v2: SEC 10-K pipeline - schema + section chunker + EDGAR downloader

README.md

@@ -72,7 +72,7 @@ JSON summary, markdown) land in `evaluation/reports/<timestamp>/` after each run
 |----------|-------------------|-----------|-----------|-----------|------------|--------------|
 | Receipts | SROIE (5)         | **0.938** | **1.000** | 0.20      | **$0.012** | 6.3 s        |
 | Receipts | CORD (5)          | **0.914** | 0.839     | **0.80**  | **$0.012** | 8.2 s        |
-| Filings  | SEC 10-K sample   | _v2 in progress_ | _v2_ | _v2_ | _v2_    | _v2_         |
+| Filings  | SEC 10-K (n=5)    | _v2 pipeline built — live numbers pending_ | | | | |
 
 **Read the numbers:**
 - **Micro F1 ≈ 0.92** across both datasets — the model gets ~92% of individual
@@ -159,6 +159,17 @@ number, then the SEC 10-K schema for the long-doc / dual-domain story.
                     └────────────────┘
 ```
 
+**Long-document handling (10-K path).** SEC filings are 50-250 pages and would
+cost ~$0.60/doc if we shipped the whole thing to the model on every call. So
+the filing path runs the document through a section chunker
+(`src/extractors/section_chunker.py`) that finds each `Item 1.`, `Item 1A.`,
+`Item 7.`, `Item 8.` heading via regex, deduplicates against the Table of
+Contents (keeping the last occurrence — the real section), and slices the
+plaintext into named chunks. Only the cover, Item 8 (financials), and Item 1A
+(risk factors) are stitched into the prompt — everything else is skipped.
+Result: ~30–40K prompt tokens per 10-K instead of ~150K, on the same
+gpt-5-nano @ minimal reasoning-effort configuration.
+
 ## Tech stack
 
 | Layer | Choice | Why |
@@ -208,6 +219,28 @@ python scripts/run_eval.py --dataset evaluation/ground_truth/sroie.jsonl \
 Reports (per-record CSV + summary JSON + resume-ready markdown) land in
 `evaluation/reports/<UTC-timestamp>/`.
 
+### 10-K (SEC filings) quick start
+
+```bash
+# 1. Download the 5-issuer watchlist (Apple, JPM, ExxonMobil, Pfizer, Walmart).
+#    Files land in data/raw/10k/ — plaintext, sidecar JSON, and XBRL companyfacts.
+python scripts/download_edgar.py
+
+# 2. Build a ground-truth JSONL from the sidecars + XBRL.
+python scripts/build_filings_gt.py
+
+# 3. Run the eval against a real model.
+python scripts/run_eval.py \
+    --dataset evaluation/smoke_filings_sample.jsonl \
+    --doc-type filing \
+    --mode live \
+    --model gpt-5-nano \
+    --reasoning-effort minimal
+```
+
+The filing extractor uses section-based chunking to keep per-doc cost around
+$0.05–0.15 instead of $0.60+ at whole-document context.
+
 ## Project structure
 
 ```
@@ -240,8 +273,8 @@ Reports (per-record CSV + summary JSON + resume-ready markdown) land in
 
 ## Roadmap
 
-- [x] **v1 — Invoices & Receipts pipeline + multi-model benchmark** _(in progress)_
-- [ ] v2 — SEC Filings pipeline (10-K / 10-Q, long-doc handling)
+- [x] **v1 — Invoices & Receipts pipeline + multi-model benchmark**
+- [x] **v2 — SEC 10-K pipeline** (schema + section chunker + EDGAR downloader, live eval pending)
 - [ ] v3 — Streaming extraction + async batch API
 - [ ] v4 — Fine-tuning experiment vs. base GPT-5 nano
 

scripts/build_filings_gt.py

@@ -0,0 +1,169 @@
+"""Build filings ground-truth JSONL from downloaded EDGAR data.
+
+Reads the sidecars + XBRL companyfacts written by `download_edgar.py` and
+produces `evaluation/smoke_filings_sample.jsonl` — the file the eval CLI
+reads in `--mode live --doc-type filing` runs.
+
+Each JSONL row has:
+    id, source, text (full 10-K plaintext), ground_truth (Filing schema dict)
+
+Cover fields come from the sidecar (auto). Financials come from XBRL
+companyfacts using the most-common US-GAAP concepts (see FIN_MAP below).
+Risk factors are left EMPTY in the auto-generated ground truth — they're
+free text and there's no canonical source. Backfill by hand for a stricter
+qualitative eval.
+
+Usage
+-----
+    python scripts/build_filings_gt.py
+    python scripts/build_filings_gt.py --raw-dir data/raw/10k --out evaluation/smoke_filings_sample.jsonl
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+# US-GAAP concept name -> our schema field.
+# Values are lists of candidate concept names in order of preference — real
+# filers use different names for the same line ("Revenues", "SalesRevenueNet",
+# "RevenueFromContractWithCustomerExcludingAssessedTax"...).
+FIN_MAP = {
+    "revenue": [
+        "Revenues",
+        "RevenueFromContractWithCustomerExcludingAssessedTax",
+        "SalesRevenueNet",
+    ],
+    "cost_of_revenue": ["CostOfRevenue", "CostOfGoodsAndServicesSold", "CostOfGoodsSold"],
+    "gross_profit": ["GrossProfit"],
+    "operating_income": ["OperatingIncomeLoss"],
+    "net_income": ["NetIncomeLoss"],
+    "eps_basic":   ["EarningsPerShareBasic"],
+    "eps_diluted": ["EarningsPerShareDiluted"],
+    "cash_and_equivalents": ["CashAndCashEquivalentsAtCarryingValue", "CashCashEquivalentsAndShortTermInvestments"],
+    "total_assets": ["Assets"],
+    "total_equity": ["StockholdersEquity", "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"],
+    "total_debt": [  # sum of short-term + long-term where separately reported
+        "LongTermDebt",
+        "LongTermDebtNoncurrent",
+    ],
+    "operating_cash_flow": ["NetCashProvidedByUsedInOperatingActivities"],
+}
+
+
+def _pick_fy_value(concept_data: dict, fy_end: str) -> float | None:
+    """Return the concept value for the fiscal year ending `fy_end` (ISO date).
+
+    XBRL companyfacts nests values by unit (USD, USD/shares, pure). We take
+    the first unit that produces a match. Match rule: same `end` date + form
+    starting with '10-K' + `fp == 'FY'`.
+    """
+    units = concept_data.get("units", {})
+    for _unit, entries in units.items():
+        for e in entries:
+            if e.get("end") == fy_end and e.get("form", "").startswith("10-K") and e.get("fp") == "FY":
+                try:
+                    return float(e["val"])
+                except (KeyError, ValueError, TypeError):
+                    continue
+    return None
+
+
+def build_financials(facts: dict, fy_end: str) -> dict:
+    """Populate as many FilingFinancials fields as possible from XBRL."""
+    us_gaap = (facts.get("facts", {}) or {}).get("us-gaap", {}) or {}
+    fin: dict = {"currency": "USD", "fiscal_year": int(fy_end[:4])}
+
+    for field, candidates in FIN_MAP.items():
+        val = None
+        collected: list[float] = []
+        for concept in candidates:
+            data = us_gaap.get(concept)
+            if not data:
+                continue
+            v = _pick_fy_value(data, fy_end)
+            if v is None:
+                continue
+            if field == "total_debt":
+                # Sum across all matching debt concepts (short-term + long-term).
+                collected.append(v)
+            else:
+                val = v
+                break
+        if field == "total_debt" and collected:
+            val = sum(collected)
+        if val is not None:
+            fin[field] = val
+
+    return fin
+
+
+def build_row(txt_path: Path) -> dict | None:
+    """Produce one ground-truth row for the JSONL, or None if metadata is missing."""
+    stem = txt_path.name[:-len(".txt")]
+    meta_path = txt_path.parent / f"{stem}.meta.json"
+    facts_path = txt_path.parent / f"{stem}.facts.json"
+    if not meta_path.exists():
+        print(f"[!] no sidecar for {txt_path.name} — skipping")
+        return None
+
+    meta = json.loads(meta_path.read_text(encoding="utf-8"))
+    facts = json.loads(facts_path.read_text(encoding="utf-8")) if facts_path.exists() else None
+
+    fy_end = meta["reporting_period_end"]
+    cover = {
+        "company_name": meta["company_name"],
+        "cik": meta["cik10"],
+        "ticker": meta["ticker"],
+        "form_type": meta["form"],
+        "fiscal_year_end": fy_end,
+        "filing_date": meta["filing_date"],
+    }
+    financials = build_financials(facts, fy_end) if facts else {"currency": "USD", "fiscal_year": int(fy_end[:4])}
+
+    return {
+        "id": f"filing_{meta['ticker']}_{fy_end}",
+        "source": "sec_edgar",
+        "text": txt_path.read_text(encoding="utf-8"),
+        "ground_truth": {
+            "cover": cover,
+            "financials": financials,
+            "top_risk_factors": [],   # backfill by hand for qualitative eval
+        },
+    }
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--raw-dir", default="data/raw/10k")
+    ap.add_argument("--out", default="evaluation/smoke_filings_sample.jsonl")
+    args = ap.parse_args(argv)
+
+    raw = ROOT / args.raw_dir
+    out = ROOT / args.out
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    txts = sorted(raw.glob("*_10k.txt"))
+    if not txts:
+        print(f"[!] no *_10k.txt files under {raw} — run download_edgar.py first.")
+        return 2
+
+    n_written = 0
+    with out.open("w", encoding="utf-8") as f:
+        for p in txts:
+            row = build_row(p)
+            if not row:
+                continue
+            f.write(json.dumps(row) + "\n")
+            n_written += 1
+            fin = row["ground_truth"]["financials"]
+            print(f"  {row['id']:36s} revenue={fin.get('revenue')} net_income={fin.get('net_income')}")
+
+    print(f"\n-> {out}  ({n_written} rows)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/download_edgar.py

@@ -0,0 +1,211 @@
+"""Download the most recent 10-K for a small watchlist of large-cap issuers.
+
+Purpose
+-------
+Give the eval pipeline five real 10-K filings to run against, with
+auto-scrapable ground-truth metadata already pulled from SEC EDGAR's
+structured feeds. Filings are saved as plaintext under `data/raw/10k/`
+so `src/eval/cli.py --mode live` can read them via the loader's `.txt` path.
+
+Approach
+--------
+SEC EDGAR exposes a JSON submissions feed per issuer at
+    https://data.sec.gov/submissions/CIK{cik10}.json
+which lists every filing (form, accession, date, primary document). We:
+    1. For each ticker in WATCHLIST, resolve ticker -> CIK via the tickers file.
+    2. Fetch the submissions feed and pick the most recent 10-K.
+    3. Download the primary document (HTML).
+    4. Strip HTML -> plaintext (via BeautifulSoup) and save.
+    5. Also fetch companyfacts.json for XBRL-driven ground truth.
+
+SEC's rules
+-----------
+- Identify yourself in the User-Agent header (they rate-limit anonymous UAs).
+- Cap traffic at <= 10 req/s. A 250 ms sleep between requests is well under.
+
+Usage
+-----
+    python scripts/download_edgar.py                    # default watchlist
+    python scripts/download_edgar.py AAPL MSFT NVDA     # custom tickers
+    python scripts/download_edgar.py --dry-run          # print plan only
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+import requests
+from bs4 import BeautifulSoup
+
+ROOT = Path(__file__).resolve().parents[1]
+RAW_DIR = ROOT / "data" / "raw" / "10k"
+
+# One large-cap per sector — diverse writing styles, real ground truth.
+WATCHLIST_DEFAULT = ["AAPL", "JPM", "XOM", "PFE", "WMT"]
+
+# SEC requires an identifying User-Agent. Change the email if you fork.
+USER_AGENT = "structured-data-extractor (Aditya Patel, adityapatel1801@gmail.com)"
+HEADERS = {"User-Agent": USER_AGENT, "Accept-Encoding": "gzip, deflate"}
+SLEEP_SEC = 0.25   # <= 10 req/s per SEC's fair-use policy
+
+
+def _get(url: str, timeout: int = 30) -> requests.Response:
+    """Throttled GET with SEC-mandated headers."""
+    r = requests.get(url, headers=HEADERS, timeout=timeout)
+    r.raise_for_status()
+    time.sleep(SLEEP_SEC)
+    return r
+
+
+def load_ticker_index() -> dict:
+    """Return a dict of TICKER -> 10-digit CIK, downloaded from SEC."""
+    r = _get("https://www.sec.gov/files/company_tickers.json")
+    payload = r.json()
+    out = {}
+    for row in payload.values():
+        out[str(row["ticker"]).upper()] = str(row["cik_str"]).zfill(10)
+    return out
+
+
+def latest_10k_metadata(cik10: str) -> dict:
+    """Return { accession, primary_doc, filing_date, ... } for the most recent 10-K."""
+    r = _get(f"https://data.sec.gov/submissions/CIK{cik10}.json")
+    payload = r.json()
+    recent = payload["filings"]["recent"]
+    for i, form in enumerate(recent["form"]):
+        if form == "10-K":
+            return {
+                "cik10": cik10,
+                "company_name": payload.get("name", ""),
+                "form": form,
+                "accession": recent["accessionNumber"][i],
+                "filing_date": recent["filingDate"][i],
+                "reporting_period_end": recent["reportDate"][i],
+                "primary_doc": recent["primaryDocument"][i],
+            }
+    raise RuntimeError(f"No 10-K found in recent filings for CIK {cik10}")
+
+
+def download_10k_html(meta: dict) -> str:
+    accession_nodash = meta["accession"].replace("-", "")
+    cik_nozero = str(int(meta["cik10"]))
+    url = (
+        f"https://www.sec.gov/Archives/edgar/data/{cik_nozero}/"
+        f"{accession_nodash}/{meta['primary_doc']}"
+    )
+    r = _get(url, timeout=60)
+    return r.text
+
+
+def html_to_text(html: str) -> str:
+    """Strip HTML -> plaintext, preserving section headings so the chunker can find them."""
+    soup = BeautifulSoup(html, "html.parser")
+    for tag in soup(["script", "style", "nav", "footer", "header"]):
+        tag.decompose()
+    text = soup.get_text(separator="\n")
+    lines = [ln.rstrip() for ln in text.splitlines()]
+    out = []
+    blank = 0
+    for ln in lines:
+        if ln.strip() == "":
+            blank += 1
+            if blank <= 1:
+                out.append("")
+        else:
+            blank = 0
+            out.append(ln)
+    return "\n".join(out).strip() + "\n"
+
+
+def download_companyfacts(cik10: str) -> dict:
+    """Return the XBRL companyfacts JSON — used for auto-ground-truth."""
+    r = _get(f"https://data.sec.gov/api/xbrl/companyfacts/CIK{cik10}.json")
+    return r.json()
+
+
+def save_filing(ticker: str, meta: dict, text: str, facts: dict | None) -> Path:
+    RAW_DIR.mkdir(parents=True, exist_ok=True)
+    stem = f"{ticker.upper()}_{meta['reporting_period_end']}_10k"
+    txt_path = RAW_DIR / f"{stem}.txt"
+    meta_path = RAW_DIR / f"{stem}.meta.json"
+
+    txt_path.write_text(text, encoding="utf-8")
+
+    sidecar = {
+        "ticker": ticker.upper(),
+        "cik10": meta["cik10"],
+        "company_name": meta["company_name"],
+        "form": meta["form"],
+        "accession": meta["accession"],
+        "filing_date": meta["filing_date"],
+        "reporting_period_end": meta["reporting_period_end"],
+        "primary_doc": meta["primary_doc"],
+        "source_url": (
+            f"https://www.sec.gov/Archives/edgar/data/{int(meta['cik10'])}/"
+            f"{meta['accession'].replace('-', '')}/{meta['primary_doc']}"
+        ),
+        "text_bytes": len(text),
+        "has_companyfacts": facts is not None,
+    }
+    meta_path.write_text(json.dumps(sidecar, indent=2), encoding="utf-8")
+
+    if facts is not None:
+        (RAW_DIR / f"{stem}.facts.json").write_text(
+            json.dumps(facts, separators=(",", ":")), encoding="utf-8"
+        )
+    return txt_path
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("tickers", nargs="*", default=WATCHLIST_DEFAULT,
+                    help=f"Ticker symbols. Default: {' '.join(WATCHLIST_DEFAULT)}")
+    ap.add_argument("--dry-run", action="store_true", help="Print plan + exit.")
+    ap.add_argument("--skip-facts", action="store_true",
+                    help="Skip companyfacts.json download (faster, loses auto-GT).")
+    args = ap.parse_args(argv)
+
+    tickers = [t.upper() for t in args.tickers]
+    print(f"Watchlist:  {tickers}")
+    print(f"Output dir: {RAW_DIR}")
+    if args.dry_run:
+        return 0
+
+    print("Loading SEC ticker index ...", flush=True)
+    ticker_index = load_ticker_index()
+
+    for ticker in tickers:
+        try:
+            cik10 = ticker_index[ticker]
+        except KeyError:
+            print(f"[!] {ticker} not in SEC ticker index — skipping.")
+            continue
+
+        print(f"\n=== {ticker}  (CIK {cik10}) ===")
+        try:
+            meta = latest_10k_metadata(cik10)
+            print(f"    latest 10-K: accession={meta['accession']} filed {meta['filing_date']}")
+            html = download_10k_html(meta)
+            print(f"    primary doc: {meta['primary_doc']}  ({len(html):,} HTML bytes)")
+            text = html_to_text(html)
+            print(f"    plaintext:   {len(text):,} chars")
+            facts = None
+            if not args.skip_facts:
+                facts = download_companyfacts(cik10)
+                print(f"    companyfacts: {len(facts.get('facts', {}))} taxonomies")
+            path = save_filing(ticker, meta, text, facts)
+            print(f"    -> {path.relative_to(ROOT)}")
+        except requests.HTTPError as e:
+            print(f"[!] {ticker} HTTP error: {e}")
+        except Exception as e:
+            print(f"[!] {ticker} failed: {type(e).__name__}: {e}")
+
+    print(f"\nDone. Files in {RAW_DIR.relative_to(ROOT)}/")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/extractors/extractor.py

@@ -14,6 +14,7 @@ from src.extractors.document_loader import LoadedDocument, load_document
 from src.extractors.envelope import compute_overall_confidence, make_envelope
 from src.extractors.openai_client import OpenAIExtractionClient
 from src.extractors.prompts import get_prompt
+from src.extractors.section_chunker import chunk_filing
 from src.schemas import ExtractionResult
 from src.schemas.registry import get_schema
 from src.utils.cost_tracker import ExtractionMetrics
@@ -62,8 +63,13 @@ class DocumentExtractor:
         if loaded.source_type == "empty":
             raise ValueError(f"Could not load document {filename!r} (unknown or corrupt format).")
 
-        # 3. Build the messages.
-        messages = self._build_messages(system_prompt, loaded)
+        # 3. Build the messages. Filings use a section-aware path — a full 10-K
+        #    is ~150K tokens; we ship only cover + Item 8 + Item 1A to keep
+        #    per-call cost + latency reasonable and reduce distractor text.
+        if doc_type.strip().lower() == "filing":
+            messages = self._build_filing_messages(system_prompt, loaded)
+        else:
+            messages = self._build_messages(system_prompt, loaded)
 
         # 4. Call the model.
         envelope, metrics = self._client.parse_structured(
@@ -136,3 +142,64 @@ class DocumentExtractor:
             {"role": "system", "content": system_prompt},
             {"role": "user", "content": user_content},
         ]
+
+    # ------------------------------------------------------------------
+    # Filing path
+    # ------------------------------------------------------------------
+
+    # Per-section byte caps. Real 10-K sections rarely exceed ~40 KB; 60 KB
+    # gives us headroom for verbose filers (JPM's Item 1A runs long) while
+    # keeping total prompt size ~30-40K tokens — well inside gpt-5-nano's cost
+    # sweet spot.
+    _FILING_COVER_BYTES = 6_000
+    _FILING_ITEM_1A_BYTES = 60_000
+    _FILING_ITEM_8_BYTES = 60_000
+
+    def _build_filing_messages(
+        self,
+        system_prompt: str,
+        loaded: LoadedDocument,
+    ) -> list[dict[str, Any]]:
+        """Message builder for the 10-K path.
+
+        Slices the loaded text into cover + Item 8 (financials) + Item 1A
+        (risk factors) and hands each to the model as a clearly-labeled block.
+        Filings are text-first — vision isn't used here (10-K images are
+        usually chart infographics, not extraction targets).
+        """
+        text = loaded.text or ""
+        chunked = chunk_filing(text, cover_bytes=self._FILING_COVER_BYTES)
+
+        cover = chunked.cover[: self._FILING_COVER_BYTES]
+        item_8 = chunked.get_text("8", default="(Item 8 not found in this filing.)")[
+            : self._FILING_ITEM_8_BYTES
+        ]
+        item_1a = chunked.get_text("1A", default="(Item 1A not found in this filing.)")[
+            : self._FILING_ITEM_1A_BYTES
+        ]
+
+        logger.info(
+            f"[filing] chunked: cover={len(cover)}B, "
+            f"item_8={len(item_8)}B (present={chunked.has('8')}), "
+            f"item_1a={len(item_1a)}B (present={chunked.has('1A')}), "
+            f"total_items={len(chunked.item_ids)}"
+        )
+
+        user_text = (
+            "Extract the structured filing data. Three relevant sections of the "
+            "10-K are provided below. Do NOT hallucinate values from other "
+            "sections not shown.\n\n"
+            "---COVER SECTION---\n"
+            f"{cover}\n"
+            "---END COVER SECTION---\n\n"
+            "---FINANCIAL SECTION (Item 8)---\n"
+            f"{item_8}\n"
+            "---END FINANCIAL SECTION---\n\n"
+            "---RISK FACTORS SECTION (Item 1A)---\n"
+            f"{item_1a}\n"
+            "---END RISK FACTORS SECTION---"
+        )
+        return [
+            {"role": "system", "content": system_prompt},
+            {"role": "user",   "content": [{"type": "text", "text": user_text}]},
+        ]

src/extractors/prompts.py

@@ -80,10 +80,60 @@ RECEIPT-SPECIFIC NOTES:
 """
 
 
+SYSTEM_PROMPT_FILING = f"""You are a specialized data extraction engine for U.S. SEC 10-K annual reports.
+
+You will receive selected sections of a 10-K filing:
+  * COVER SECTION       — the first pages: registrant name, CIK, ticker, exchange, fiscal-year end.
+  * FINANCIAL SECTION   — Item 8 (Financial Statements): income statement, balance sheet, cash flows.
+  * RISK FACTORS SECTION — Item 1A (Risk Factors): the enumerated risks the registrant discloses.
+
+Your job is to output the structured filing data per the provided Pydantic schema.
+
+{_COMMON_RULES}
+
+10-K-SPECIFIC NOTES:
+
+Cover page:
+- `company_name` is the full legal name as printed on the cover (e.g. "Apple Inc.").
+- `cik` is a 10-digit numeric string. If you see fewer than 10 digits, left-pad with zeros.
+- `ticker` is the trading symbol (uppercase). If multiple share classes are listed, pick the
+  primary one (usually the first row of the "Securities registered pursuant to Section 12(b)" table).
+- `exchange` should be verbatim — e.g. "NASDAQ Global Select Market", NOT abbreviated to "NASDAQ".
+- `fiscal_year_end` is the LAST day of the fiscal period being reported (not the filing date).
+
+Financials (Item 8 — this is the trickiest part):
+- All monetary values must be in **ABSOLUTE currency units**. Real 10-Ks report "in millions"
+  or "in thousands" — YOU must multiply back up. Examples:
+    * If Apple's income statement says "Net sales ... 391,035" with a header "(In millions)",
+      output revenue = 391035000000 (=$391.035B).
+    * If the header says "(In thousands)", multiply by 1000.
+    * If the header says nothing about scaling, values are already in absolute dollars.
+- Read column headers carefully — 10-Ks usually show multiple fiscal years side-by-side.
+  Extract the values from the **most recent completed fiscal year** column (usually the leftmost
+  or the one matching `fiscal_year_end`).
+- `total_debt` = short-term borrowings + long-term borrowings (including the current portion).
+  If the filing separates them, SUM them. Do NOT include operating leases or accounts payable.
+- If `free_cash_flow` is not explicitly reported in the filing, leave it null. Do NOT compute
+  (operating_cash_flow − capex) yourself — that's an analyst step, not an extraction step.
+- `currency` is the reporting currency, typically "USD". Some ADRs report in EUR / GBP / JPY.
+
+Risk factors (Item 1A):
+- Return at most FIVE risks in `top_risk_factors`, ranked by materiality (most significant first).
+- Real 10-Ks have 20-80 individual risks. You are TL;DR-ing them. Group related risks under a
+  single theme when the disclosure is fragmented (e.g. combine "supply concentration" and
+  "single-source components" under "supply-chain concentration").
+- `theme` is a short 2-6 word label. `summary` is 1-3 sentences using the filer's own language
+  where possible — do not editorialize or add outside knowledge.
+- If Item 1A is absent, empty, or points elsewhere ("see Item 1A of our 20xx 10-K"), return an
+  empty list and add a warning.
+"""
+
+
 # Registry so the extractor can look up a prompt by doc_type
 PROMPTS: dict[str, str] = {
     "invoice": SYSTEM_PROMPT_INVOICE,
     "receipt": SYSTEM_PROMPT_RECEIPT,
+    "filing":  SYSTEM_PROMPT_FILING,
 }
 
 

src/extractors/section_chunker.py

@@ -0,0 +1,177 @@
+"""Section-aware chunker for SEC 10-K annual reports.
+
+Why this exists
+---------------
+A 10-K is 50-250 pages. Even at gpt-5's 400K-token context, feeding the whole
+thing on every extraction is wasteful — a filing weighs ~150K tokens and each
+call costs ~$0.60. Worse, the model has to skim past long stretches of
+irrelevant text to find the fields you asked for.
+
+The 10-K format is our friend: every filing structures its content into
+numbered Items. The three we care about for v2:
+
+    Item 1     — Business (skipped for now)
+    Item 1A    — Risk Factors            → RiskFactor extraction
+    Item 7     — MD&A                    → macroeconomic + strategy context
+    Item 8     — Financial Statements    → FilingFinancials extraction
+
+The cover page (registrant name, CIK, fiscal year, ticker, exchange) lives in
+the first ~2 KB before Item 1 kicks in, so we grab it as an implicit
+"cover" chunk.
+
+Method
+------
+Regex over the plaintext for headings that look like `ITEM 1A.` /
+`Item 1A.` / `Item 1A —` / `ITEM 1A — RISK FACTORS`. We build a list of
+(item_id, start_offset) hits, sort them, and slice the text into (item_id →
+text) chunks. The last item runs to end-of-document.
+
+We match generously (case-insensitive; Roman-numeral or "PART II" prefixes
+tolerated) because real 10-K formatting is inconsistent across filers and
+years. Downstream code should never assume every item is present — a filer
+might omit Item 1A when it's not material.
+
+Not in scope for v2
+-------------------
+- HTML-to-text (already handled upstream by pdfplumber / bs4 in the loader).
+- Table-of-contents skipping: the TOC often lists all items, and our regex
+  will match them. We mitigate this by keeping only the *last* occurrence of
+  each item id — which is the actual section, not the TOC entry.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Ordered list of items we recognize. Order matters — the chunker returns
+# sections in filing order for humans reading a report side-by-side.
+KNOWN_ITEMS: tuple[str, ...] = (
+    "1",   "1A",  "1B",  "1C",
+    "2",   "3",   "4",
+    "5",   "6",   "7",   "7A",
+    "8",   "9",   "9A",  "9B",
+    "10",  "11",  "12",  "13",  "14",  "15",
+)
+
+
+# The regex allows:
+#   ITEM 1A.  |  Item 1A —  |  ITEM 1A -  |  Item 1A:
+# case-insensitive, with optional PART header prefix stripped by callers.
+_ITEM_ID_ALT = "|".join(re.escape(x) for x in KNOWN_ITEMS)
+_ITEM_HEADING = re.compile(
+    rf"""
+    (?:^|\n)                          # anchor to start of line (permissive)
+    \s{{0,6}}                         # a few leading spaces okay
+    ITEM\s+                           # the word ITEM
+    (?P<item>{_ITEM_ID_ALT})          # captures 1, 1A, 7, 8, ...
+    \b                                # word boundary
+    \s*[\.\-–—:\)]?         # optional punctuation: . - – — : )
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+
+
+@dataclass
+class SectionChunk:
+    """One chunk of a 10-K aligned to a specific Item heading."""
+    item: str          # normalized item id, e.g. "1A", "7", "8"
+    heading: str       # the raw matched heading text, e.g. "Item 1A. RISK FACTORS"
+    text: str          # the chunk body (from just after the heading to the next heading or EOF)
+    start: int         # byte offset in the original document
+    end: int
+
+
+@dataclass
+class ChunkedFiling:
+    """A 10-K sliced into cover + Item chunks. Access via `.get('1A')` etc."""
+    cover: str
+    sections: list[SectionChunk]
+
+    def get(self, item: str) -> SectionChunk | None:
+        """Return the section for a given item id, or None if absent."""
+        want = item.upper().strip()
+        for s in self.sections:
+            if s.item == want:
+                return s
+        return None
+
+    def get_text(self, item: str, default: str = "") -> str:
+        s = self.get(item)
+        return s.text if s else default
+
+    def has(self, item: str) -> bool:
+        return self.get(item) is not None
+
+    @property
+    def item_ids(self) -> list[str]:
+        return [s.item for s in self.sections]
+
+
+# --- API -------------------------------------------------------------------
+
+def chunk_filing(text: str, cover_bytes: int = 4000) -> ChunkedFiling:
+    """Slice a 10-K text into cover + per-Item chunks.
+
+    Args:
+        text: The full 10-K plaintext (from pdfplumber, bs4, or similar).
+        cover_bytes: How much of the doc to treat as the cover chunk. Cover
+            pages are usually ~1-3 KB; 4000 is a safe upper bound.
+
+    Returns:
+        A ChunkedFiling. If no Item headings are found (rare — malformed doc
+        or non-10-K input), returns a single "sections" entry with the whole
+        text under item="0".
+    """
+    if not text or not text.strip():
+        return ChunkedFiling(cover="", sections=[])
+
+    hits = _find_all_item_headings(text)
+
+    # No Item headings — return everything as one blob and let the caller decide.
+    if not hits:
+        return ChunkedFiling(
+            cover=text[:cover_bytes],
+            sections=[SectionChunk(item="0", heading="(no headings)", text=text, start=0, end=len(text))],
+        )
+
+    # Deduplicate: keep only the LAST occurrence of each item id — the earlier
+    # ones are almost always the Table of Contents entries.
+    last_by_item: dict[str, tuple[str, str, int, int]] = {}
+    for m in hits:
+        item = m["item"]
+        last_by_item[item] = (item, m["heading"], m["start"], m["heading_end"])
+
+    # Now order by start offset (filing order).
+    ordered = sorted(last_by_item.values(), key=lambda x: x[2])
+
+    # Compute end offsets — each section ends where the next one starts.
+    sections: list[SectionChunk] = []
+    for i, (item, heading, start, heading_end) in enumerate(ordered):
+        end = ordered[i + 1][2] if i + 1 < len(ordered) else len(text)
+        sections.append(
+            SectionChunk(item=item, heading=heading, text=text[heading_end:end], start=start, end=end)
+        )
+
+    cover_end = min(cover_bytes, ordered[0][2])
+    return ChunkedFiling(cover=text[:cover_end], sections=sections)
+
+
+# --- Internals -------------------------------------------------------------
+
+def _find_all_item_headings(text: str) -> list[dict]:
+    """Return every regex match as a dict, normalized item id + offsets."""
+    out: list[dict] = []
+    for m in _ITEM_HEADING.finditer(text):
+        item = m.group("item").upper()
+        # Grab the rest of the line as the "heading" for debugging.
+        line_end = text.find("\n", m.end())
+        if line_end == -1:
+            line_end = min(m.end() + 120, len(text))
+        heading = text[m.start(): line_end].strip()
+        out.append({
+            "item": item,
+            "heading": heading,
+            "start": m.start(),
+            "heading_end": line_end,
+        })
+    return out

src/schemas/__init__.py

@@ -6,6 +6,7 @@ from src.schemas.base import (
     StrictModel,
 )
 from src.schemas.common import Address, Party
+from src.schemas.filing import Filing, FilingCover, FilingFinancials, RiskFactor
 from src.schemas.invoice import Invoice, LineItem
 from src.schemas.receipt import Receipt, ReceiptLineItem
 from src.schemas.registry import get_json_schema, get_schema, list_doc_types
@@ -17,6 +18,10 @@ __all__ = [
     "ExtractionWarning",
     "Address",
     "Party",
+    "Filing",
+    "FilingCover",
+    "FilingFinancials",
+    "RiskFactor",
     "Invoice",
     "LineItem",
     "Receipt",

src/schemas/filing.py

@@ -0,0 +1,265 @@
+"""SEC filing schema — for 10-K annual reports (v2).
+
+Design intent
+-------------
+A 10-K is a very different beast from a receipt: 50-250 pages, structured into
+Items (1, 1A, 7, 8, ...), with a mix of long-form narrative (business
+description, risk factors) and dense financial tables (income statement,
+balance sheet, cash flow).
+
+Rather than model the whole document, we extract the three highest-signal
+slices for downstream analysis and evaluation:
+
+    1. **Cover page**    — identity + registration metadata (CIK, fiscal year,
+       ticker, exchange). These are canonical, auto-scrapable from EDGAR, and
+       make excellent ground-truth targets.
+    2. **Financials**    — the top-line income statement + balance-sheet
+       figures a human analyst would extract for a quick take: revenue, net
+       income, EPS, cash, debt, equity. All in the filing's reporting currency
+       (almost always USD), normalized to *absolute* dollars (i.e. the
+       extractor must undo "in millions"/"in thousands" scaling).
+    3. **Top risk factors** — the extractor summarizes Item 1A into up to 5
+       themed risk factors. This is the qualitative story a portfolio project
+       needs — it shows the LLM doing unstructured → structured reduction, not
+       just field-picking.
+
+Conventions kept in line with receipt/invoice schemas
+------------------------------------------------------
+- `StrictModel` base (extra="forbid" for OpenAI structured-outputs strict mode).
+- `MoneyAmount = float` (never Decimal — see common.py for the tradeoff).
+- All fields on the sub-models are Optional except a small "required core"
+  (company name, form type). Real 10-Ks omit fields; we shouldn't fail on that.
+"""
+from __future__ import annotations
+
+from datetime import date
+
+from pydantic import Field, field_validator
+
+from src.schemas.base import StrictModel
+from src.schemas.common import Address, MoneyAmount, normalize_currency, round_money
+
+
+# ---------------------------------------------------------------------------
+# 1) COVER PAGE
+# ---------------------------------------------------------------------------
+
+class FilingCover(StrictModel):
+    """Registrant + filing metadata from the 10-K cover page.
+
+    All of this is scrapable from EDGAR's structured header, so it's a strong
+    ground-truth target for evaluation. A well-tuned extractor should hit
+    ~100% F1 on this section — the interesting question is whether it does.
+    """
+
+    company_name: str = Field(description="Full legal name of the registrant as it appears on the cover.")
+
+    cik: str | None = Field(
+        default=None,
+        description=(
+            "SEC Central Index Key — 10-digit numeric string with leading zeros preserved "
+            "(e.g. '0000320193' for Apple). Extract as printed if visible; else null."
+        ),
+    )
+    ticker: str | None = Field(
+        default=None, description="Primary trading symbol, e.g. 'AAPL'. Uppercase."
+    )
+    exchange: str | None = Field(
+        default=None,
+        description=(
+            "Registered exchange (e.g. 'NASDAQ Global Select Market', 'New York Stock Exchange'). "
+            "Verbatim from the cover — do NOT abbreviate 'NASDAQ Global Select Market' to 'NASDAQ'."
+        ),
+    )
+
+    form_type: str = Field(
+        default="10-K",
+        description="Filing form (10-K, 10-K/A, 10-Q, etc.) as printed on the cover.",
+    )
+
+    fiscal_year_end: date | None = Field(
+        default=None,
+        description=(
+            "Last day of the fiscal year the filing covers (ISO 8601). "
+            "Not the filing date — the *reporting period end* date."
+        ),
+    )
+    filing_date: date | None = Field(
+        default=None,
+        description=(
+            "Date the 10-K was filed with the SEC (ISO 8601). Sometimes only "
+            "the report date is on the cover; this may need to be inferred from the header."
+        ),
+    )
+
+    state_of_incorporation: str | None = Field(
+        default=None,
+        description="US state (two-letter) or country of incorporation. Uppercase.",
+    )
+    address: Address | None = Field(
+        default=None,
+        description="Principal executive offices address if listed on the cover.",
+    )
+
+    @field_validator("ticker", "state_of_incorporation", mode="before")
+    @classmethod
+    def _upper(cls, v: str | None) -> str | None:
+        return v.strip().upper() if isinstance(v, str) and v.strip() else None
+
+    @field_validator("cik", mode="before")
+    @classmethod
+    def _cik(cls, v):
+        """Left-pad CIK to 10 digits if the model returns 320193 not 0000320193."""
+        if v is None:
+            return None
+        s = str(v).strip()
+        return s.zfill(10) if s.isdigit() else s
+
+
+# ---------------------------------------------------------------------------
+# 2) FINANCIALS
+# ---------------------------------------------------------------------------
+
+class FilingFinancials(StrictModel):
+    """Top-line financial figures from the income statement, balance sheet,
+    and cash-flow statement (Item 8).
+
+    Every monetary field is in **absolute** currency units (dollars, not
+    millions). The extraction prompt instructs the model to multiply back
+    up when the source states "(in millions)" or "(in thousands)". Getting
+    the units right is one of the harder eval targets — a factor-of-1000
+    error is easy to make and easy to catch.
+    """
+
+    currency: str = Field(
+        default="USD",
+        description="ISO 4217 code for the reporting currency (almost always USD).",
+    )
+    fiscal_year: int | None = Field(
+        default=None,
+        ge=1900,
+        le=2100,
+        description="The 4-digit fiscal year these financials correspond to (e.g. 2025).",
+    )
+
+    # --- Income statement -----------------------------------------------
+    revenue: MoneyAmount | None = Field(
+        default=None,
+        description=(
+            "Total net revenue (top line) in absolute currency units. "
+            "For Apple FY2024 this would be 391_035_000_000 (=$391.035B), NOT 391035."
+        ),
+    )
+    cost_of_revenue: MoneyAmount | None = Field(
+        default=None, description="Cost of goods/services sold. Absolute units."
+    )
+    gross_profit: MoneyAmount | None = Field(default=None)
+    operating_income: MoneyAmount | None = Field(default=None)
+    net_income: MoneyAmount | None = Field(
+        default=None, description="Net income attributable to the parent company."
+    )
+
+    # --- Per-share ------------------------------------------------------
+    eps_basic: float | None = Field(
+        default=None, description="Basic earnings per share (e.g. 6.11 for $6.11)."
+    )
+    eps_diluted: float | None = Field(default=None, description="Diluted EPS.")
+
+    # --- Balance sheet ---------------------------------------------------
+    cash_and_equivalents: MoneyAmount | None = Field(
+        default=None,
+        description="Cash and cash equivalents (excluding marketable securities).",
+    )
+    total_debt: MoneyAmount | None = Field(
+        default=None,
+        description=(
+            "Total debt = short-term + long-term borrowings. If the filing separates "
+            "'current portion of long-term debt' from long-term debt, sum them."
+        ),
+    )
+    total_assets: MoneyAmount | None = Field(default=None)
+    total_equity: MoneyAmount | None = Field(
+        default=None, description="Total stockholders' equity attributable to the parent."
+    )
+
+    # --- Cash flow -------------------------------------------------------
+    operating_cash_flow: MoneyAmount | None = Field(
+        default=None, description="Net cash provided by operating activities."
+    )
+    free_cash_flow: MoneyAmount | None = Field(
+        default=None,
+        description=(
+            "Free cash flow = operating_cash_flow - capex. If not explicitly reported, "
+            "leave null rather than compute it — many 10-Ks don't state it."
+        ),
+    )
+
+    @field_validator("currency", mode="before")
+    @classmethod
+    def _currency(cls, v):
+        return normalize_currency(v) or "USD"
+
+    @field_validator(
+        "revenue", "cost_of_revenue", "gross_profit", "operating_income",
+        "net_income", "cash_and_equivalents", "total_debt",
+        "total_assets", "total_equity",
+        "operating_cash_flow", "free_cash_flow",
+        mode="before",
+    )
+    @classmethod
+    def _money(cls, v):
+        return round_money(v) if v is not None else v
+
+
+# ---------------------------------------------------------------------------
+# 3) RISK FACTORS (Item 1A)
+# ---------------------------------------------------------------------------
+
+class RiskFactor(StrictModel):
+    """A single themed risk distilled from Item 1A.
+
+    Item 1A in a real 10-K is 20-80 pages of prose. The model reduces it to
+    at most ~5 named themes with 1-3 sentence summaries — the "TL;DR" a
+    quant would want on a first pass. `theme` is fuzzy-matchable (eval uses
+    rapidfuzz); `summary` is scored more leniently.
+    """
+
+    theme: str = Field(
+        description=(
+            "Short (2-6 word) label for the risk — e.g. 'supply chain concentration', "
+            "'foreign-exchange exposure', 'regulatory / antitrust'."
+        ),
+    )
+    summary: str = Field(
+        description=(
+            "1-3 sentence plain-English summary of the risk. Use the filer's own language "
+            "where possible; do not editorialize."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# TOP-LEVEL FILING
+# ---------------------------------------------------------------------------
+
+class Filing(StrictModel):
+    """A structured extract of a single SEC 10-K annual report.
+
+    Composed of the three sub-schemas above. The top-level model stays flat
+    to keep the JSON output easy to consume in a downstream analytics
+    pipeline (Snowflake, DuckDB, a dashboard).
+    """
+
+    cover: FilingCover = Field(description="Registrant identity + filing metadata.")
+    financials: FilingFinancials = Field(
+        description="Top-line income statement, balance sheet, and cash flow figures."
+    )
+    top_risk_factors: list[RiskFactor] = Field(
+        default_factory=list,
+        max_length=5,
+        description=(
+            "Up to 5 themed risk factors distilled from Item 1A. "
+            "Order = the extractor's ranking of importance. Empty list allowed for filings "
+            "with unusually short or missing risk sections."
+        ),
+    )

src/schemas/registry.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 from pydantic import BaseModel
 
+from src.schemas.filing import Filing
 from src.schemas.invoice import Invoice
 from src.schemas.receipt import Receipt
 
@@ -15,9 +16,7 @@ from src.schemas.receipt import Receipt
 _REGISTRY: dict[str, type[BaseModel]] = {
     "invoice": Invoice,
     "receipt": Receipt,
-    # v2 additions will land here:
-    # "sec_10k": Filing10K,
-    # "sec_10q": Filing10Q,
+    "filing":  Filing,   # SEC 10-K (v2). Same key handles 10-K and 10-K/A.
 }
 
 

tests/unit/test_filing_schema.py

@@ -0,0 +1,163 @@
+"""Filing schema tests — pure Python, no OpenAI. Covers the required-field,
+validator, currency, and CIK-padding contracts."""
+from __future__ import annotations
+
+from datetime import date
+
+import pytest
+from pydantic import ValidationError
+
+from src.schemas import Filing, FilingCover, FilingFinancials, RiskFactor
+from src.schemas.registry import get_schema, list_doc_types
+
+
+def _cover(**overrides) -> FilingCover:
+    return FilingCover(company_name="Apple Inc.", **overrides)
+
+
+def _fin(**overrides) -> FilingFinancials:
+    return FilingFinancials(**overrides)
+
+
+# --- Cover ----------------------------------------------------------------
+
+def test_cover_requires_company_name_only():
+    c = FilingCover(company_name="Northwind Software, Inc.")
+    assert c.company_name == "Northwind Software, Inc."
+    assert c.form_type == "10-K"
+    assert c.cik is None
+    assert c.ticker is None
+
+
+def test_cover_ticker_uppercased_and_stripped():
+    c = _cover(ticker="aapl")
+    assert c.ticker == "AAPL"
+    c2 = _cover(ticker="  msft  ")
+    assert c2.ticker == "MSFT"
+
+
+def test_cover_ticker_blank_becomes_none():
+    c = _cover(ticker="   ")
+    assert c.ticker is None
+
+
+def test_cik_gets_zero_padded_from_str_int():
+    assert _cover(cik="320193").cik == "0000320193"
+    assert _cover(cik=320193).cik == "0000320193"
+    # A CIK already at 10 digits stays the same.
+    assert _cover(cik="0000320193").cik == "0000320193"
+
+
+def test_cik_non_numeric_passes_through_untouched():
+    # Belt-and-suspenders: if the LLM returns something weird, don't crash.
+    assert _cover(cik="CIK-320193").cik == "CIK-320193"
+
+
+def test_cover_dates_parsed_from_iso_strings():
+    c = _cover(fiscal_year_end="2024-09-28", filing_date="2024-11-01")
+    assert c.fiscal_year_end == date(2024, 9, 28)
+    assert c.filing_date == date(2024, 11, 1)
+
+
+# --- Financials -----------------------------------------------------------
+
+def test_financials_defaults_currency_to_usd():
+    assert FilingFinancials().currency == "USD"
+
+
+def test_financials_currency_normalized():
+    assert _fin(currency="usd").currency == "USD"
+    assert _fin(currency="  eur  ").currency == "EUR"
+
+
+def test_financials_currency_blank_falls_back_to_usd():
+    # Model returning "" or spaces shouldn't produce an invalid currency.
+    assert _fin(currency="").currency == "USD"
+    assert _fin(currency="   ").currency == "USD"
+
+
+def test_financials_money_rounds_to_two_decimals():
+    f = _fin(revenue=391035000000.123456, net_income=93736000000.789)
+    assert f.revenue == 391035000000.12
+    assert f.net_income == 93736000000.79
+
+
+def test_financials_fiscal_year_range_enforced():
+    _fin(fiscal_year=2024)  # OK
+    with pytest.raises(ValidationError):
+        _fin(fiscal_year=1500)
+    with pytest.raises(ValidationError):
+        _fin(fiscal_year=2200)
+
+
+def test_financials_all_money_fields_optional():
+    # Building with no fields shouldn't raise — 10-K may omit any of them.
+    f = FilingFinancials()
+    assert f.revenue is None
+    assert f.total_debt is None
+    assert f.free_cash_flow is None
+
+
+# --- Risk factors + top-level Filing -------------------------------------
+
+def test_risk_factor_requires_both_theme_and_summary():
+    RiskFactor(theme="supply chain", summary="Depends on China manufacturing.")
+    with pytest.raises(ValidationError):
+        RiskFactor(theme="supply chain")  # missing summary
+
+
+def test_filing_composes_all_three_subschemas():
+    f = Filing(
+        cover=_cover(cik="0000320193", ticker="AAPL", fiscal_year_end="2024-09-28"),
+        financials=_fin(fiscal_year=2024, revenue=391035000000, net_income=93736000000, eps_diluted=6.11),
+        top_risk_factors=[
+            RiskFactor(theme="supply chain concentration", summary="China dependency."),
+            RiskFactor(theme="FX exposure",                 summary="Non-US sales volatility."),
+        ],
+    )
+    assert f.cover.ticker == "AAPL"
+    assert f.financials.revenue == 391035000000.0
+    assert len(f.top_risk_factors) == 2
+
+
+def test_top_risk_factors_capped_at_five():
+    with pytest.raises(ValidationError):
+        Filing(
+            cover=_cover(),
+            financials=_fin(),
+            top_risk_factors=[
+                RiskFactor(theme=str(i), summary="x") for i in range(6)  # 6 > max_length=5
+            ],
+        )
+
+
+def test_top_risk_factors_default_empty_list():
+    # A 10-K with no risk section shouldn't fail extraction.
+    f = Filing(cover=_cover(), financials=_fin())
+    assert f.top_risk_factors == []
+
+
+def test_filing_forbids_extra_fields():
+    with pytest.raises(ValidationError):
+        Filing.model_validate({
+            "cover": {"company_name": "X"},
+            "financials": {},
+            "top_risk_factors": [],
+            "extra_field": "nope",  # extra="forbid" should reject this
+        })
+
+
+# --- Registry hookup ------------------------------------------------------
+
+def test_filing_registered_and_returned_by_get_schema():
+    assert get_schema("filing") is Filing
+
+
+def test_list_doc_types_includes_filing():
+    assert "filing" in list_doc_types()
+
+
+def test_filing_case_insensitive_lookup():
+    # get_schema lowercases the input.
+    assert get_schema("FILING") is Filing
+    assert get_schema("Filing") is Filing

tests/unit/test_section_chunker.py

@@ -0,0 +1,138 @@
+"""Tests for the 10-K section chunker."""
+from __future__ import annotations
+
+import textwrap
+
+import pytest
+
+from src.extractors.section_chunker import chunk_filing
+
+
+SYNTHETIC_10K = textwrap.dedent("""\
+    APPLE INC.
+    FORM 10-K
+    Annual Report Pursuant to Section 13 or 15(d) of the Securities Exchange Act of 1934
+
+    Common Stock, $0.00001 par value per share
+    NASDAQ Global Select Market
+    Central Index Key: 0000320193
+    State of Incorporation: California
+
+    TABLE OF CONTENTS
+    Item 1.  Business ..................... 3
+    Item 1A. Risk Factors ................. 12
+    Item 7.  MD&A ......................... 34
+    Item 8.  Financial Statements ......... 42
+
+    PART I
+
+    Item 1. Business
+
+    Apple Inc. designs, manufactures, and markets smartphones, personal
+    computers, tablets, wearables, and accessories.
+
+    Item 1A. Risk Factors
+
+    The company faces intense competition and the following risks could
+    materially affect the business.
+
+    Supply chain — heavy dependence on manufacturing in China.
+    Foreign exchange — a substantial portion of net sales from non-US markets.
+
+    PART II
+
+    Item 7. Management's Discussion and Analysis of Financial Condition
+
+    Net sales grew 3% year over year, driven by Services growth.
+
+    Item 8. Financial Statements and Supplementary Data
+
+    Revenue: $391,035 million
+    Net income: $93,736 million
+    Diluted EPS: $6.11
+    Cash and cash equivalents: $29,943 million
+    Total assets: $364,980 million
+""")
+
+
+def test_finds_the_four_headline_items_in_order():
+    c = chunk_filing(SYNTHETIC_10K)
+    assert c.item_ids == ["1", "1A", "7", "8"]
+
+
+def test_toc_entries_deduped_last_wins():
+    """A synthetic 10-K has each Item mentioned twice (TOC + real section).
+    We keep the LAST occurrence — the real section, not the TOC entry.
+    """
+    c = chunk_filing(SYNTHETIC_10K)
+    # If we'd kept the TOC entry, Item 1A's text would start with '. Risk Factors'
+    # from the TOC. Real section starts with actual body.
+    body = c.get_text("1A").lstrip()
+    assert body.startswith("The company faces intense competition"), body[:80]
+
+
+def test_cover_captured_before_first_item():
+    c = chunk_filing(SYNTHETIC_10K)
+    assert "APPLE INC." in c.cover
+    assert "Central Index Key: 0000320193" in c.cover
+    # The cover ends where the FIRST Item heading starts — so the actual
+    # "Item 1. Business" section body must NOT be in it.
+    assert "Apple Inc. designs, manufactures" not in c.cover
+
+
+def test_section_bodies_do_not_leak_into_neighbors():
+    c = chunk_filing(SYNTHETIC_10K)
+    # Item 1A's chunk should have risk-factor content, not Item 7 MD&A content.
+    body_1a = c.get_text("1A")
+    assert "Supply chain" in body_1a
+    assert "Net sales grew 3%" not in body_1a
+    # Item 8's chunk holds financials, not MD&A.
+    body_8 = c.get_text("8")
+    assert "Revenue: $391,035" in body_8
+    assert "Net sales grew 3%" not in body_8
+
+
+def test_has_and_get_are_case_insensitive():
+    c = chunk_filing(SYNTHETIC_10K)
+    assert c.has("1a") is True   # lowercase input
+    assert c.has("1A") is True
+    assert c.get("1a") is not None
+
+
+def test_missing_item_returns_none():
+    c = chunk_filing(SYNTHETIC_10K)
+    assert c.get("15") is None
+    assert c.get_text("15", default="—") == "—"
+
+
+def test_empty_input_returns_empty_result():
+    c = chunk_filing("")
+    assert c.cover == ""
+    assert c.sections == []
+    c2 = chunk_filing("   \n\n   ")
+    assert c2.sections == []
+
+
+def test_no_headings_returns_single_blob():
+    """A plain document with no Item headings shouldn't crash — degrades gracefully."""
+    text = "This document does not follow SEC 10-K structure."
+    c = chunk_filing(text)
+    assert len(c.sections) == 1
+    assert c.sections[0].item == "0"
+    assert c.sections[0].text == text
+
+
+def test_variant_heading_punctuation_still_matches():
+    # 10-Ks in the wild use "Item 1A -", "Item 1A —", "Item 1A:"
+    for sep in [". ", " - ", " — ", ": "]:
+        text = f"cover\n\nItem 1A{sep}Risk Factors\n\nThe risks are as follows."
+        c = chunk_filing(text)
+        assert c.has("1A"), f"failed on separator {sep!r}"
+
+
+def test_case_variants_in_source_still_match():
+    # ITEM 1A. and item 1a. are both valid in real filings.
+    for form in ["Item 1A.", "ITEM 1A.", "item 1a."]:
+        text = f"cover\n\n{form} Risk Factors\n\nRisks."
+        c = chunk_filing(text)
+        assert c.has("1A"), f"failed on form {form!r}"

ui/src/components/Dropzone.tsx

@@ -13,7 +13,7 @@ import { useCallback, useRef, useState } from "react";
 import type { DocType } from "@/types";
 import { SAMPLE_DOCS, loadSampleAsFile, type SampleDoc } from "@/lib/samples";
 
-const ACCEPT = "application/pdf,image/png,image/jpeg,image/webp,image/tiff,image/bmp";
+const ACCEPT = "application/pdf,image/png,image/jpeg,image/webp,image/tiff,image/bmp,text/plain,text/html,.txt,.htm,.html";
 
 interface Props {
   file: File | null;
@@ -206,6 +206,7 @@ function DocTypePicker({
   const opts: { key: DocType; label: string }[] = [
     { key: "receipt", label: "Receipt" },
     { key: "invoice", label: "Invoice" },
+    { key: "filing",  label: "10-K"    },
   ];
   return (
     <div className="relative z-10 flex items-center gap-2">

ui/src/types.ts

@@ -3,7 +3,7 @@
  * Kept minimal — Pydantic v2 on the server is the source of truth.
  */
 
-export type DocType = "invoice" | "receipt";
+export type DocType = "invoice" | "receipt" | "filing";
 
 export interface FieldConfidence {
   field: string;