foryourhealth111-pixel/Vibe-Skills / bundled/skills/edgartools
edgartools
VerifiedPython library for accessing, analyzing, and extracting data from SEC EDGAR filings. Use when working with SEC filings, financial statements (income statement, balance sheet, cash flow), XBRL financial data, insider trading (Form 4), institutional holdings (13F), company financials, annual/quarterly reports (10-K, 10-Q), proxy statements (DEF 14A), 8-K current events, company screening by ticker/CIK/industry, multi-period financial analysis, or any SEC regulatory filings.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/ai-integration.md | markdown | 6.7 KB |
| references/companies.md | markdown | 6.0 KB |
| references/data-objects.md | markdown | 5.4 KB |
| references/entity-facts.md | markdown | 8.1 KB |
| references/filings.md | markdown | 8.9 KB |
| references/financial-data.md | markdown | 6.9 KB |
| references/xbrl.md | markdown | 9.2 KB |
references/entity-facts.md
View on GitHub# edgartools — EntityFacts Reference
Structured access to SEC company financial facts with AI-ready features, querying, and professional formatting.
## Table of Contents
- [EntityFacts Class](#entityfacts-class)
- [FactQuery — Fluent Query Builder](#factquery--fluent-query-builder)
- [FinancialStatement Class](#financialstatement-class)
- [FinancialFact Class](#financialfact-class)
- [Common Patterns](#common-patterns)
---
## EntityFacts Class
### Getting EntityFacts
```python
from edgar import Company
company = Company("AAPL")
facts = company.get_facts() # Returns EntityFacts object
```
### Core Properties
```python
facts.cik # 320193
facts.name # "Apple Inc."
len(facts) # total number of facts
# DEI properties (from SEC filings)
facts.shares_outstanding # float or None
facts.public_float # float or None
facts.shares_outstanding_fact # FinancialFact with full metadata
facts.public_float_fact # FinancialFact with full metadata
```
### Financial Statement Methods
```python
# Income statement
stmt = facts.income_statement() # FinancialStatement (4 annual periods)
stmt = facts.income_statement(periods=8) # 8 periods
stmt = facts.income_statement(annual=False) # quarterly
df = facts.income_statement(as_dataframe=True) # return DataFrame directly
# Balance sheet
stmt = facts.balance_sheet()
stmt = facts.balance_sheet(periods=4)
stmt = facts.balance_sheet(as_of=date(2024, 12, 31)) # point-in-time
# Cash flow
stmt = facts.cash_flow()
stmt = facts.cashflow_statement(periods=5, annual=True)
# Parameters:
# periods (int): number of periods (default: 4)
# annual (bool): True=annual, False=quarterly (default: True)
# period_length (int): months — 3=quarterly, 12=annual
# as_dataframe (bool): return DataFrame instead of FinancialStatement
# as_of (date): balance sheet only — point-in-time snapshot
```
### Query Interface
```python
query = facts.query()
# Returns FactQuery builder — see FactQuery section
```
### Get Single Fact
```python
revenue_fact = facts.get_fact('Revenue')
q1_revenue = facts.get_fact('Revenue', '2024-Q1')
# Returns FinancialFact or None
```
### Time Series
```python
revenue_ts = facts.time_series('Revenue', periods=8) # DataFrame
```
### DEI / Entity Info
```python
# DEI facts DataFrame
dei_df = facts.dei_facts()
dei_df = facts.dei_facts(as_of=date(2024, 12, 31))
# Entity info dict
info = facts.entity_info()
print(info['entity_name'])
print(info['shares_outstanding'])
```
### AI / LLM Methods
```python
# Comprehensive LLM context
context = facts.to_llm_context(
focus_areas=['profitability', 'growth'], # or 'liquidity'
time_period='5Y' # 'recent', '5Y', '10Y', 'all'
)
# MCP-compatible tool definitions
tools = facts.to_agent_tools()
```
### Iteration
```python
for fact in facts:
print(f"{fact.concept}: {fact.numeric_value}")
```
---
## FactQuery — Fluent Query Builder
Create via `facts.query()`. All filter methods return `self` for chaining.
### Concept Filtering
```python
query = facts.query()
# Fuzzy matching (default)
q = query.by_concept('Revenue')
# Exact matching
q = query.by_concept('us-gaap:Revenue', exact=True)
# By human-readable label
q = query.by_label('Total Revenue', fuzzy=True)
q = query.by_label('Revenue', fuzzy=False)
```
### Time-Based Filtering
```python
# Fiscal year
q = query.by_fiscal_year(2024)
# Fiscal period
q = query.by_fiscal_period('FY') # 'FY', 'Q1', 'Q2', 'Q3', 'Q4'
q = query.by_fiscal_period('Q1')
# Period length in months
q = query.by_period_length(3) # quarterly
q = query.by_period_length(12) # annual
# Date range
q = query.date_range(start=date(2023, 1, 1), end=date(2024, 12, 31))
# Point-in-time
q = query.as_of(date(2024, 6, 30))
# Latest n periods
q = query.latest_periods(4, annual=True)
q = query.latest_instant() # most recent balance sheet items
```
### Statement / Form Filtering
```python
q = query.by_statement_type('IncomeStatement')
q = query.by_statement_type('BalanceSheet')
q = query.by_statement_type('CashFlow')
q = query.by_form_type('10-K')
q = query.by_form_type(['10-K', '10-Q'])
```
### Quality Filtering
```python
q = query.high_quality_only() # audited facts only
q = query.min_confidence(0.9) # confidence score 0.0-1.0
```
### Sorting
```python
q = query.sort_by('filing_date', ascending=False)
q = query.sort_by('fiscal_year')
```
### Execution
```python
# Execute and return facts
facts_list = query.execute() # List[FinancialFact]
count = query.count() # int (no fetch)
latest_n = query.latest(5) # List[FinancialFact] (most recent)
# Convert to DataFrame
df = query.to_dataframe()
df = query.to_dataframe('label', 'numeric_value', 'fiscal_period')
# Pivot by period
stmt = query.pivot_by_period() # FinancialStatement
df = query.pivot_by_period(return_statement=False) # DataFrame
# LLM context
llm_data = query.to_llm_context()
```
### Full Chaining Example
```python
results = facts.query()\
.by_concept('Revenue')\
.by_fiscal_year(2024)\
.by_form_type('10-K')\
.sort_by('filing_date')\
.execute()
```
---
## FinancialStatement Class
Wrapper around DataFrame with intelligent formatting and display.
### Properties
```python
stmt = company.income_statement()
stmt.shape # (10, 4) — rows x periods
stmt.columns # period labels: ['FY 2024', 'FY 2023', ...]
stmt.index # concept names: ['Revenue', 'Cost of Revenue', ...]
stmt.empty # bool
```
### Methods
```python
# Get numeric DataFrame for calculations
numeric_df = stmt.to_numeric()
growth_rates = numeric_df.pct_change(axis=1)
# Get specific concept across periods
revenue_series = stmt.get_concept('Revenue') # pd.Series or None
# Calculate period-over-period growth
growth = stmt.calculate_growth('Revenue', periods=1) # pd.Series
# Format a value
formatted = stmt.format_value(1234567, 'Revenue') # "$1,234,567"
# LLM context
context = stmt.to_llm_context()
```
### Display
- Jupyter: automatic HTML rendering with professional styling
- Console: formatted text with proper alignment
- Compatible with Rich library
---
## FinancialFact Class
Individual fact with full metadata.
### Core Attributes
```python
fact = facts.get_fact('Revenue')
fact.concept # "us-gaap:Revenue"
fact.taxonomy # "us-gaap"
fact.label # "Revenue"
fact.value # raw value
fact.numeric_value # float for calculations
fact.unit # "USD", "shares", etc.
fact.scale # 1000, 1000000, etc.
```
### Temporal Attributes
```python
fact.period_start # date (for duration facts)
fact.period_end # date
fact.period_type # "instant" or "duration"
fact.fiscal_year # int
fact.fiscal_period # "FY", "Q1", "Q2", "Q3", "Q4"
```
### Filing Context
```python
fact.filing_date # date filed
fact.form_type # "10-K", "10-Q", etc.
fact.accession # SEC accession number
```
### Quality
```python
fact.data_quality # DataQuality.HIGH / MEDIUM / LOW
fact.is_audited # bool
fact.confidence_score # float 0.0-1.0
```
### AI Attributes
```python
fact.semantic_tags # List[str]
fact.business_context # str description
```
### Methods
```python
context = fact.to_llm_context() # dict for LLM
formatted = fact.get_formatted_value() # "365,817,000,000"
period_key = fact.get_display_period_key() # "Q1 2024", "FY 2023"
```
---
## Common Patterns
### Multi-Period Income Analysis
```python
from edgar import Company
company = Company("AAPL")
facts = company.get_facts()
# 4 annual periods
stmt = facts.income_statement(periods=4, annual=True)
print(stmt)
# Convert to numeric for calculations
numeric = stmt.to_numeric()
revenue_growth = numeric.loc['Revenue'].pct_change()
print(revenue_growth)
```
### Query Latest Revenue Facts
```python
latest_revenue = facts.query()\
.by_concept('Revenue')\
.latest_periods(4, annual=True)\
.to_dataframe()
```
### Error Handling
```python
from edgar.entity.core import NoCompanyFactsFound
try:
facts = company.get_facts()
except NoCompanyFactsFound:
print("No facts available")
# Methods return None gracefully
stmt = facts.income_statement() # None if no data
if stmt and not stmt.empty:
# process
pass
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |