--- description: Access and analyze SEC EDGAR filings with smart lookup by ticker, fund name, or investor name. Fetch 13F-HR institutional holdings and 10-K/10-Q financial statements. Retrieve XBRL data, track portfolio changes, and analyze 12,000+ companies and 50+ top hedge funds including Berkshire Hathaway, Citadel, Bridgewater, and more. Also covers the edgartools API (company search, filing retrieval, 8-K and other forms) and direct XBRL / XML processing. metadata: default_prompt: 'Get the latest 13F holdings for Berkshire Hathaway (CIK: 0001067983)' display_name: SEC EDGAR icon_path: assets/icon.png short_description: 'Fetch and analyze SEC filings: 13F holdings, 10-K/10-Q financials, and XBRL data' name: sec-edgar --- # SEC EDGAR ## Overview This skill provides comprehensive access to SEC EDGAR database for retrieving and analyzing: - **13F-HR Filings**: Institutional investment holdings reports (quarterly) - **10-K/10-Q Filings**: Annual and quarterly financial statements with XBRL data - **CUSIP-to-Ticker Mapping**: Automatic ticker symbol resolution for holdings - **Financial Statement Extraction**: Income statements, balance sheets, and cash flow statements - **Section Extraction**: Systematically extracts Item 1 (Business), Item 1A (Risk Factors), Item 7 (MD&A), and Item 8 (Financials) Use this skill when you need to: - Analyze institutional investor portfolios and holdings - Track changes in investment positions over time - Extract financial statements and metrics from company filings - Perform fundamental analysis using official SEC data - Research holdings across multiple quarters or years ## Prerequisites The skill uses the `edgartools` Python library and requires: - A user agent identifier ("Name (email)") for SEC API compliance - resolved as described in **SEC Identity (Required)** below - Company/fund identifier (ticker, fund name, investor name, or CIK) - CUSIP_Ticker.csv mapping file (included in skill package) **NEW: Smart CIK Lookup System** You can reference companies and funds using natural identifiers: - **Ticker symbols**: "AAPL", "MSFT", "BRK-B" (12,000+ mappings) - **Fund names**: "Berkshire", "Citadel", "Bridgewater" (50+ top funds) - **Investor names**: "Warren Buffett", "Ray Dalio", "Ken Griffin" - **Direct CIKs**: "0001067983" (automatic padding if needed) No need to remember CIK numbers! See `references/cik_lookup_guide.md` for complete lookup documentation. ## Validation & Testing ✅ **Production Ready**: This skill has been comprehensively tested and validated on real SEC filings. **Test Coverage**: - ✅ 10-K extraction: Apple (AAPL), Tesla (TSLA) - 100% success rate - ✅ 10-Q extraction: Microsoft (MSFT) - Risk factors extracted - ✅ Section extraction: Items 1, 1A, 7, 8 systematically isolated - ✅ Smart CIK lookup: Tickers, fund names, and pension plans resolved correctly - ✅ XBRL data: Financial statements extracted to CSV format See `examples/test_section_extraction.py` for the complete validation suite. ## How to Use The user invokes: ``` /sec-edgar [options] ``` **Interpret the input as:** - Filing type: "13F", "10-K", "10-Q", or "holdings analysis" - Identifier: CIK (for 13F) or ticker symbol (for 10-K/10-Q) - Options: Number of periods, specific quarters, bulk operations **Examples:** - `/sec-edgar 13F holdings for Berkshire Hathaway` - `/sec-edgar Get latest 4 quarters of 10-Q for AAPL` - `/sec-edgar Analyze 13F filings for CIK 0001067983` - `/sec-edgar Extract Item 1A from latest TSLA 10-K` - `/sec-edgar Get CalPERS 13F holdings` ## SEC Identity (Required) The SEC requires every request to identify the requester ("Name (email)"). Resolve the identity in this order, and stop at the first that works: 1. **Provided in the request** - the user gave a name and/or email in their message or earlier in the session. 2. **`SEC_USER_AGENT` environment variable** - use its value as-is (format: `Your Name (you@yourcompany.com)`). 3. **Ask the user** - if neither is available, stop and ask before making any SEC call, for example: "The SEC requires a contact name and email for EDGAR requests. What name and email should I use? (It is sent only to the SEC as a user-agent string.)" Rules: - Never invent an identity or fall back to a placeholder such as `your.email@example.com` or `contact@example.com`. - If the user gives only an email, use it with a generic name such as "SEC EDGAR User (email)". - Reuse the identity for the rest of the session; do not ask again. - Pass it to `EdgarLibrary("")`, or to `set_identity("")` when using the scripts in `scripts/edgartools/`. - Do not echo the email back in reports or write it to output files. ## Steps (STRICT) ### For 13F-HR Holdings 1. **Parse Request**: Extract identifier (ticker, fund name, investor name, or CIK) from user input 2. **Smart CIK Lookup**: Use `cik_lookup.smart_cik_lookup()` to resolve identifier to 10-digit CIK 3. **Confirm Match**: Show user the matched fund/company name for verification 4. **Initialize Library**: Resolve the SEC identity (see **SEC Identity (Required)**), then create the EdgarLibrary instance with it 5. **Fetch Filings**: Call `get_13f_filings(cik, num_latest)` 6. **Process Data**: Library automatically aggregates, adjusts values, calculates prices, and maps tickers 7. **Save Output**: Write holdings to CSV file named `_13f_holdings.csv` 8. **Report Results**: Summarize key holdings, total value, and top positions ### For 10-K/10-Q Financials 1. **Parse and Validate**: Extract ticker symbol and form type from user input 2. **Initialize Library**: Resolve the SEC identity (see **SEC Identity (Required)**), then create the EdgarLibrary instance with it 3. **Fetch Filings**: Call `get_10kq_filings(ticker, form_name, num_latest)` 4. **Extract Statements**: Library retrieves income statement, balance sheet, and cash flow via XBRL 5. **Extract Sections**: Use `section_extractor.extract_sections()` to systematically isolate: - **Item 1: Business** - Company operations, products, and strategy - **Item 1A: Risk Factors** - Comprehensive risk analysis - **Item 7: Management's Discussion and Analysis** - Performance and outlook - **Item 8: Financial Statements** - Audited financials with notes 6. **Save Output**: Results saved to `/` directory: - Full filing markdown: `__.md` - Extracted sections: `__item_
.txt` - Financial statements: `___.csv` 7. **Report Results**: Summarize key financial metrics, filing dates, and sections extracted with character counts ### For Combined Analysis 1. **Fetch 13F Holdings**: Get institutional positions using CIK 2. **Extract Tickers**: Get unique ticker list from holdings (excluding "Not Found") 3. **Batch Fetch Financials**: Call `get_13f_filings_and_10q_for_holdings(cik, num_latest)` 4. **Save All Data**: Holdings CSV + individual 10-Q files per ticker 5. **Generate Summary**: Cross-reference holdings with financial performance ## Output Format (STRICT) ### 13F Holdings Output **File**: `_13f_holdings.csv` **Columns**: - `FundName`: Institution name - `as_of_date`: Report date (YYYY-MM-DD) - `Cusip`: 9-character CUSIP identifier - `Ticker`: Stock symbol or "Not Found" - `Issuer`: Company name - `Shares`: Number of shares held - `Value`: Position value in USD - `SharePrice`: Calculated share price - `Class`, `Type`, `InvestmentDiscretion`, `PutCall` - `SoleVoting`, `SharedVoting`, `NonVoting`: Voting authority **Summary Report**: - Total portfolio value - Number of positions - Top 10 holdings by value - Sector breakdown (if available) - Quarter-over-quarter changes ### 10-K/10-Q Output **Files Created**: 1. `/__.md` - Full filing text in markdown 2. `/__item_1_business.txt` - Item 1: Business (operations, products, strategy) 3. `/__item_1a_risk.txt` - Item 1A: Risk Factors (comprehensive risk analysis) 4. `/__item_7_mda.txt` - Item 7: MD&A (performance analysis and outlook) 5. `/__item_8_financials.txt` - Item 8: Financial Statements (audited data with notes) 6. `/___.csv` - XBRL financial statements (Income, Balance, CashFlow) **Section File Format**: Each extracted section includes: - Header with company name, ticker, and filing type - Character count for length awareness - Clean markdown formatting with preserved tables and structure - Section-specific content (typically 15-100KB per section) **CSV Structure** (XBRL Financial Data): - Line item names (e.g., "Revenue", "Net Income", "Total Assets") - `end_value`: Most recent period value - `begin_value`: Previous period value - `end_date`: End date of reporting period - `begin_date`: Start date of reporting period - `Ticker`: Stock symbol **Summary Report**: - Filing metadata (date, form type, period covered) - Section extraction results with character counts - Revenue and earnings trends from XBRL data - Key balance sheet metrics - Cash flow highlights - Year-over-year or quarter-over-quarter changes ## edgartools API & XBRL Reference Beyond the `EdgarLibrary` workflows above (13F holdings, 10-K/10-Q bulk extraction, CIK lookup), this skill includes general `edgartools` coverage for any form type (10-K, 10-Q, 8-K, proxy, Form 4, etc.) and direct XBRL processing. Read the relevant guide before using these features. **Guides** (`references/edgartools/`): - `common-api-usage.md` - **Read first.** Correct `latest()`, `Company()` and filing-method usage. - `core-api.md` - identity setup, company search and CIK lookup, retrieving and downloading filings, date-range queries, XML parsing, pandas analysis, common gotchas and a quick reference. - `extracting-financial-statements.md` - balance sheet, income statement and cash flow from any filing via `xbrl().statements`. - `financial-statements.md` - advanced statement analysis and parsing techniques. - `xbrl-processing.md` - direct XBRL processing (instance documents, taxonomies, facts) for advanced use. **Scripts** (`scripts/edgartools/`): `search_company.py`, `retrieve_filings.py`, `download_filing.py`, `parse_filing.py`, `xml_parsing_helper.py`, `financial_analysis.py`, `safe_financial_analysis.py`, `safe_numeric_formatting.py`, `get_10q_financials.py`. These call `set_identity(...)` with a placeholder contact; always replace it with the identity resolved per **SEC Identity (Required)**. **Which to use:** for 13F holdings, ticker/fund-name lookup, CUSIP mapping and 10-K section extraction, use `EdgarLibrary` (above). For other form types, ad-hoc filings or raw XBRL, use the edgartools guides. ## Constraints - **CIK Lookup Coverage**: 12,000+ ticker mappings, 50+ top institutional investors, 20+ pension plans - **CIK Format**: Automatically padded to 10 digits if needed (e.g., "1067983" → "0001067983") - **Rate Limiting**: SEC limits to 10 requests/second - batch operations handle automatically - **User Agent Required**: The SEC requires a real name and email on every request. Never use a placeholder; resolve it per **SEC Identity (Required)** - **Ticker Validation**: 1-5 uppercase alphanumeric characters (supports symbols like "BRK-B") - **Historical Coverage**: Not all companies have complete filing history - **CUSIP Mapping**: ~65,000 mappings included; some securities may show "Not Found" - **Directory Creation**: Skill creates `10-K/` and `10-Q/` directories for output - **Memory Usage**: Large bulk operations (100+ tickers) may require significant memory - **Form Types**: Only supports "10-K" and "10-Q" (case-insensitive) - **Value Adjustment**: Pre-Q3 2022 values automatically multiplied by 1000 - **Section Extraction**: Optimized for 10-K filings; 10-Q structure differs (see references) - **Section Size Limits**: Each extracted section capped at 100KB to manage memory - **Lookup Limitations**: Not all companies/funds are in lookup tables - provide CIK directly if not found - **Fuzzy Matching**: Pension plan lookups use fuzzy matching with 80% similarity threshold ## Error Handling **Invalid CIK**: - Check format: digits only, max 10 characters - Add leading zeros if needed: "1067983" → "0001067983" - Raise `InvalidCIKError` with helpful message **Invalid Ticker**: - Validate 1-5 alphanumeric pattern - Convert to uppercase automatically - Raise `InvalidTickerError` if format wrong **Filing Not Found**: - Verify company exists in SEC database - Check CIK/ticker spelling - Suggest using SEC company search - Raise `FilingNotFoundError` with clear message **Missing XBRL Data**: - Log warning for incomplete statements - Continue processing available data - Note missing sections in report **Data Processing Failures**: - Catch and log all exceptions - Provide partial results when possible - Include error details in summary ## Examples **Example 1: Recent Berkshire Hathaway 13F Holdings (Using Fund Name)** User: `/sec-edgar Get the last 4 quarters of 13F holdings for Berkshire Hathaway` Expected workflow: 1. Smart Lookup: "Berkshire Hathaway" → Found: CIK 0001067983 (Warren Buffett) 2. Confirm: "Analyzing Berkshire Hathaway Inc. (Warren Buffett)" 3. Call `edgar.get_13f_filings("0001067983", 4)` 4. Save to `BERKSHIRE HATHAWAY INC_13f_holdings.csv` 5. Report: "Retrieved 4 quarters of holdings (Q4 2023 - Q3 2024). Portfolio contains 45 positions worth $350B. Top holdings: Apple ($150B), Bank of America ($35B), Coca-Cola ($25B)." **Alternative using investor name:** User: `/sec-edgar Show me Warren Buffett's latest holdings` → Same result via person name lookup **Example 2: Apple 10-Q Financials** User: `/sec-edgar Fetch latest 10-Q financial statements for AAPL` Expected workflow: 1. Validate ticker: "AAPL" 2. Call `edgar.get_10kq_filings("AAPL", form_name='10-Q', num_latest=1)` 3. Save markdown and CSV to `10-Q/` directory 4. Report: "Retrieved Q1 2024 10-Q for Apple Inc. Revenue: $119.6B (+4.3% YoY), Net Income: $33.9B, EPS: $2.18." **Example 3: Section Extraction from 10-K** User: `/sec-edgar Extract risk factors and business description from Tesla's latest 10-K` Expected workflow: 1. Call `edgar.get_10kq_filings("TSLA", form_name='10-K', num_latest=1)` 2. Filing fetched and sections automatically extracted 3. Save 4 section files to `10-K/` directory: - `TSLA_10-K_item_1_business.txt` (45KB - products, operations, strategy) - `TSLA_10-K_item_1a_risk.txt` (84KB - comprehensive risk analysis) - `TSLA_10-K_item_7_mda.txt` (64KB - management discussion) - `TSLA_10-K_item_8_financials.txt` (100KB - audited statements) 4. Report: "Retrieved 2025 10-K for Tesla Inc. Extracted 4 sections totaling 293KB. Key risks include AI development, production ramp, supply chain." **Example 4: Combined Holdings Analysis** User: `/sec-edgar Analyze Berkshire's holdings and get financials for all portfolio companies` Expected workflow: 1. Call `edgar.get_13f_filings_and_10q_for_holdings("0001067983", 1)` 2. Fetch 13F holdings 3. Extract 43 valid tickers (2 show "Not Found") 4. Batch fetch 10-Q for all 43 tickers 5. Report: "Analyzed 45 holdings. Retrieved financials for 43 companies. 2 tickers not found: [CUSIP list]. Files saved to workspace." ## Available Functions Use the `EdgarLibrary.py` script in `scripts/` directory. Key functions: ### `get_13f_filings(cik: str, num_latest: int) -> pd.DataFrame` Retrieves institutional holdings from 13F-HR filings. ### `get_10kq_filings(ticker: str, form_name: str, num_latest: int) -> pd.DataFrame` Retrieves financial statements from 10-K or 10-Q filings. ### `get_10kq_filings_bulk(tickers: Union[Set[str], List[str]], form_name: str, num_latest: int) -> pd.DataFrame` Batch fetch financials for multiple tickers. ### `get_13f_filings_and_10q_for_holdings(cik: str, num_latest: int) -> None` Combined workflow: fetch 13F holdings + 10-Q financials for all positions. See `references/api_reference.md` for complete function documentation.