sec-analyzer 0.1.0__py3-none-any.whl

sec_analyzer/__init__.py

@@ -0,0 +1,5 @@
+"""SEC-Analyzer: Extract structured data from SEC filings using LLM + Pydantic presets."""
+
+from .engine import extract, extract_xbrl
+
+__all__ = ["extract", "extract_xbrl"]

sec_analyzer/cli.py

@@ -0,0 +1,61 @@
+"""CLI entry point for sec-analyzer."""
+
+import argparse
+import json
+import sys
+
+
+_PRESET_MAP = {
+    "supply-chain": "sec_analyzer.presets.supply_chain:SupplyChain",
+}
+
+
+def _load_preset(name: str):
+    """Load a preset class by name."""
+    if name not in _PRESET_MAP:
+        print(f"Unknown preset: {name}", file=sys.stderr)
+        print(f"Available presets: {', '.join(_PRESET_MAP)}", file=sys.stderr)
+        sys.exit(1)
+
+    module_path, class_name = _PRESET_MAP[name].rsplit(":", 1)
+    import importlib
+    mod = importlib.import_module(module_path)
+    return getattr(mod, class_name)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Extract structured data from SEC filings"
+    )
+    parser.add_argument("symbol", help="Ticker symbol (e.g., NVDA, AAPL, TSM)")
+    parser.add_argument(
+        "--preset", default="supply-chain",
+        help=f"Extraction preset ({', '.join(_PRESET_MAP)})",
+    )
+    parser.add_argument("--form", default="10-K", help="Filing form type (default: 10-K)")
+    parser.add_argument("--filing-date", default=None, help="Specific filing date (YYYY-MM-DD)")
+    parser.add_argument("--json", action="store_true", dest="compact", help="Compact JSON output")
+
+    args = parser.parse_args()
+
+    preset_cls = _load_preset(args.preset)
+
+    from .engine import extract
+
+    try:
+        result = extract(
+            symbol=args.symbol,
+            preset=preset_cls,
+            form=args.form,
+            filing_date=args.filing_date,
+        )
+    except Exception as e:
+        print(json.dumps({"error": str(e)}), file=sys.stderr)
+        sys.exit(1)
+
+    indent = None if args.compact else 2
+    print(json.dumps(result, indent=indent, default=str))
+
+
+if __name__ == "__main__":
+    main()

sec_analyzer/engine.py

@@ -0,0 +1,430 @@
+"""Core extraction engine: edgartools filing load + Gemini structured output."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+_MAX_MARKDOWN_CHARS = 2_000_000
+
+
+def _init_edgar(identity: str | None = None):
+    """Initialize edgartools SEC identity."""
+    from edgar import set_identity
+
+    identity = identity or os.environ.get(
+        "EDGAR_IDENTITY", "SECAnalyzer/1.0 user@example.com"
+    )
+    set_identity(identity)
+
+
+def _get_filing(symbol: str, form: str = "10-K", filing_date: str | None = None):
+    """Search latest filing via edgartools. Auto-fallback 10-K -> 20-F.
+
+    Returns:
+        tuple: (filing, metadata_dict, company_name)
+    """
+    from edgar import Company
+
+    _init_edgar()
+    company = Company(symbol)
+
+    retries = 3
+    last_error = None
+    for attempt in range(1, retries + 1):
+        try:
+            filings = company.get_filings(form=form)
+            if len(filings) == 0 and form == "10-K":
+                filings = company.get_filings(form="20-F")
+                form = "20-F"
+            if len(filings) == 0:
+                raise ValueError(f"No {form} filing found for {symbol}")
+
+            if filing_date:
+                for f in filings:
+                    if str(f.filing_date) == filing_date:
+                        filing = f
+                        break
+                else:
+                    filing = filings[0]
+            else:
+                filing = filings[0]
+
+            metadata = {
+                "form": form,
+                "filing_date": str(filing.filing_date),
+                "accession_number": filing.accession_number,
+                "filing_url": filing.filing_url,
+            }
+            return filing, metadata, company.name
+        except ValueError:
+            raise
+        except Exception as e:
+            last_error = e
+            if attempt < retries:
+                time.sleep(2**attempt)
+                continue
+    raise RuntimeError(f"edgartools failed after {retries} attempts: {last_error}")
+
+
+def _get_markdown(filing, max_chars: int = _MAX_MARKDOWN_CHARS) -> str:
+    """Convert filing to markdown with safe truncation."""
+    md = filing.markdown()
+    if len(md) > max_chars:
+        md = md[:max_chars]
+    return md
+
+
+def _build_default_prompt(preset_cls: type[BaseModel], company_name: str) -> str:
+    """Build a default extraction prompt from Pydantic field descriptions."""
+    schema = preset_cls.model_json_schema()
+    fields_desc = []
+    for name, prop in schema.get("properties", {}).items():
+        desc = prop.get("description", name)
+        fields_desc.append(f"- {name}: {desc}")
+
+    return f"""\
+You are a financial analyst extracting structured data from SEC filings.
+Extract entities and data exactly as stated in the filing text.
+
+Filing company: {company_name}
+
+Extract the following fields:
+{chr(10).join(fields_desc)}
+
+Rules:
+1. Use exact names and figures from the filing — do not paraphrase or invent.
+2. For context fields, copy 1-3 relevant sentences verbatim from the filing.
+3. If a field has no relevant data, return an empty list or null.
+
+Extract from this SEC filing text:
+
+{{filing_text}}
+"""
+
+
+def _extract_with_llm(
+    filing_text: str,
+    preset_cls: type[BaseModel],
+    company_name: str = "",
+    api_key: str | None = None,
+    model: str | None = None,
+) -> BaseModel | None:
+    """Extract structured data using Gemini structured output + Pydantic.
+
+    Returns:
+        Pydantic model instance, or None on failure.
+    """
+    from google import genai
+
+    api_key = api_key or os.environ.get("GOOGLE_API_KEY")
+    if not api_key:
+        raise ValueError(
+            "GOOGLE_API_KEY not set. Pass api_key parameter or set the environment variable."
+        )
+
+    model_id = model or os.environ.get("GOOGLE_MODEL", "gemini-2.5-flash")
+
+    # Build prompt: use preset's __prompt__ if available, else generate default
+    custom_prompt = getattr(preset_cls, "__prompt__", None)
+    if custom_prompt:
+        prompt = custom_prompt.format(
+            company_name=company_name or "Unknown",
+            filing_text=filing_text,
+        )
+    else:
+        template = _build_default_prompt(preset_cls, company_name or "Unknown")
+        prompt = template.format(filing_text=filing_text)
+
+    gen_config = {
+        "response_mime_type": "application/json",
+        "response_json_schema": preset_cls.model_json_schema(),
+        "temperature": 0.1,
+    }
+
+    thinking_level = os.environ.get("GOOGLE_THINKING_LEVEL", "low")
+    if thinking_level and thinking_level.lower() in ("low", "medium", "high", "minimal"):
+        from google.genai import types
+        gen_config["thinking_config"] = types.ThinkingConfig(
+            thinking_level=thinking_level.lower()
+        )
+
+    client = genai.Client(api_key=api_key)
+    retries = 3
+
+    for attempt in range(1, retries + 1):
+        try:
+            response = client.models.generate_content(
+                model=model_id,
+                contents=prompt,
+                config=gen_config,
+            )
+            return preset_cls.model_validate_json(response.text)
+        except Exception as e:
+            print(
+                f"[sec-analyzer] LLM attempt {attempt}/{retries} failed: {e}",
+                file=sys.stderr,
+            )
+            if attempt < retries:
+                time.sleep(2**attempt)
+                continue
+            return None
+
+
+def extract(
+    symbol: str,
+    preset: type[BaseModel],
+    form: str = "10-K",
+    filing_date: str | None = None,
+    max_chars: int = _MAX_MARKDOWN_CHARS,
+    api_key: str | None = None,
+    model: str | None = None,
+) -> dict:
+    """Extract structured data from an SEC filing using a Pydantic preset.
+
+    Args:
+        symbol: Ticker symbol (e.g., "NVDA", "AAPL", "TSM").
+        preset: Pydantic BaseModel class defining the extraction schema.
+            Optionally include a `__prompt__` class variable with a custom
+            extraction prompt (use {company_name} and {filing_text} placeholders).
+        form: Filing form type ("10-K", "10-Q", "20-F", "DEF 14A", etc.).
+            Auto-fallback from 10-K to 20-F for foreign issuers.
+        filing_date: Specific filing date (YYYY-MM-DD). None for latest.
+        max_chars: Maximum filing markdown length.
+        api_key: Google API key. Falls back to GOOGLE_API_KEY env var.
+        model: Gemini model ID. Falls back to GOOGLE_MODEL env var.
+
+    Returns:
+        dict with "filing" (metadata) and "data" (extracted fields).
+    """
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+    filing, metadata, company_name = _get_filing(symbol, form, filing_date)
+    markdown = _get_markdown(filing, max_chars)
+
+    result = _extract_with_llm(
+        filing_text=markdown,
+        preset_cls=preset,
+        company_name=company_name,
+        api_key=api_key,
+        model=model,
+    )
+
+    if result is None:
+        raise RuntimeError(f"LLM extraction failed for {symbol} ({metadata['form']})")
+
+    return {
+        "filing": metadata,
+        "data": result.model_dump(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# XBRL structured data extraction
+# ---------------------------------------------------------------------------
+
+def extract_xbrl(symbol: str, form: str = "10-K") -> dict:
+    """Extract structured quantitative data from XBRL tags.
+
+    Extracts 4 categories using standardized US-GAAP XBRL tags:
+    - revenue_concentration: Customer/segment revenue % (ConcentrationRiskPercentage)
+    - geographic_revenue: Revenue by country/region
+    - inventory_composition: Raw materials / WIP / finished goods
+    - purchase_obligations: Unconditional purchase commitments
+
+    Args:
+        symbol: Ticker symbol.
+        form: Filing form type.
+
+    Returns:
+        dict with "filing" metadata and "data" containing available categories.
+        Empty categories are omitted.
+    """
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    filing, metadata, _ = _get_filing(symbol, form)
+
+    try:
+        xbrl = filing.xbrl()
+        if xbrl is None:
+            return {"filing": metadata, "data": {}, "xbrl_available": False}
+    except Exception:
+        return {"filing": metadata, "data": {}, "xbrl_available": False}
+
+    try:
+        import pandas as pd
+        df = xbrl.instance.facts.reset_index()
+    except Exception:
+        return {"filing": metadata, "data": {}, "xbrl_available": False}
+
+    supplements = {}
+
+    # --- Revenue Concentration ---
+    conc = df[df["concept"].astype(str).str.contains(
+        "ConcentrationRiskPercentage", case=False, na=False)]
+    if len(conc) > 0:
+        benchmark_col = "us-gaap:ConcentrationRiskByBenchmarkAxis"
+        if benchmark_col in conc.columns:
+            conc = conc[conc[benchmark_col].astype(str).str.contains(
+                "Revenue", case=False, na=False)]
+        if "end_date" in conc.columns and len(conc) > 0:
+            latest_date = conc["end_date"].max()
+            conc = conc[conc["end_date"] == latest_date]
+
+        entries = []
+        seen = set()
+        for _, row in conc.iterrows():
+            customer = str(row.get("srt:MajorCustomersAxis", ""))
+            if not customer or customer == "nan":
+                continue
+            name = customer.split(":")[-1].replace("Member", "")
+            name = re.sub(r"([a-z])([A-Z])", r"\1 \2", name)
+            _GEO = ("Based End Customers", "Region", "Country", "Americas",
+                    "Europe", "Asia", "Pacific", "United States", "China", "Japan")
+            if any(kw.lower() in name.lower() for kw in _GEO):
+                continue
+            if name in seen:
+                continue
+            seen.add(name)
+            try:
+                pct = round(float(row["value"]) * 100, 2)
+            except (ValueError, TypeError):
+                pct = None
+            entries.append({"entity": name, "revenue_pct": pct,
+                           "source": "xbrl", "end_date": str(row.get("end_date", ""))})
+        if entries:
+            supplements["revenue_concentration"] = entries
+
+    # --- Geographic Revenue ---
+    geo_col = "srt:StatementGeographicalAxis"
+    if geo_col in df.columns:
+        geo = df[(df[geo_col].notna()) &
+                 (df["concept"].astype(str).str.contains("Revenue", case=False, na=False))]
+        if len(geo) > 0:
+            _rev_patterns = ["RevenueFromContractWithCustomer", r"^us-gaap:Revenues$"]
+            total_rev = None
+            for pat in _rev_patterns:
+                rows = df[
+                    (df["concept"].astype(str).str.contains(pat, case=False, na=False)) &
+                    (~df["concept"].astype(str).str.contains(
+                        "TextBlock|Policy|Description|Percentage|Cost", case=False, na=False)) &
+                    (df[geo_col].isna()) & (df["period_type"] == "duration")
+                ].copy()
+                if len(rows) > 0:
+                    try:
+                        rows["_val"] = pd.to_numeric(rows["value"], errors="coerce")
+                        rows = rows.dropna(subset=["_val"])
+                        if len(rows) > 0:
+                            latest = rows[rows["end_date"] == rows["end_date"].max()]
+                            total_rev = float(latest["_val"].max())
+                            break
+                    except Exception:
+                        continue
+
+            entries = []
+            seen = set()
+            _COUNTRY_MAP = {"US": "United States", "CN": "China", "JP": "Japan",
+                           "TW": "Taiwan", "KR": "South Korea", "DE": "Germany",
+                           "GB": "United Kingdom", "IN": "India"}
+            for _, row in geo.iterrows():
+                region = str(row[geo_col]).split(":")[-1].replace("Member", "")
+                region = re.sub(r"([a-z])([A-Z])", r"\1 \2", region)
+                region = _COUNTRY_MAP.get(region, region)
+                try:
+                    amount = float(row["value"])
+                except (ValueError, TypeError):
+                    continue
+                end_date = str(row.get("end_date", ""))
+                key = f"{region}_{end_date}"
+                if key in seen:
+                    continue
+                seen.add(key)
+                pct = round(amount / total_rev * 100, 2) if total_rev else None
+                amt_str = f"${amount/1e9:.1f}B" if amount >= 1e9 else f"${amount/1e6:.0f}M"
+                entries.append({"region": region, "revenue_pct": pct,
+                               "revenue_amount": amt_str, "source": "xbrl", "end_date": end_date})
+            if entries:
+                entries.sort(key=lambda x: x["end_date"], reverse=True)
+                if entries:
+                    first_period = entries[0]["end_date"]
+                    entries = [e for e in entries if e["end_date"] == first_period]
+                supplements["geographic_revenue"] = entries
+
+    # --- Inventory Composition ---
+    inv_concepts = {
+        "InventoryRawMaterialsAndSupplies": "raw_materials",
+        "InventoryRawMaterials": "raw_materials",
+        "InventoryWorkInProcess": "work_in_progress",
+        "InventoryFinishedGoods": "finished_goods",
+        "InventoryFinishedGoodsAndWorkInProcess": "finished_goods",
+    }
+    inv_total_row = df[df["concept"].astype(str).str.contains(
+        r"^us-gaap:InventoryNet$", case=False, na=False)]
+    inv_total = None
+    if len(inv_total_row) > 0:
+        try:
+            inv_total = float(inv_total_row.iloc[0]["value"])
+        except (ValueError, TypeError):
+            pass
+
+    inv_entries = []
+    comp_total = 0.0
+    for suffix, category in inv_concepts.items():
+        rows = df[df["concept"].astype(str).str.contains(suffix, case=False, na=False)]
+        if len(rows) > 0:
+            try:
+                amount = float(rows.iloc[0]["value"])
+            except (ValueError, TypeError):
+                continue
+            comp_total += amount
+            amt_str = f"${amount/1e9:.1f}B" if amount >= 1e9 else f"${amount/1e6:.0f}M"
+            inv_entries.append({"category": category, "amount": amt_str,
+                               "_raw": amount, "source": "xbrl"})
+    if inv_entries:
+        denom = inv_total if inv_total and comp_total <= inv_total * 1.05 else comp_total
+        for e in inv_entries:
+            raw = e.pop("_raw")
+            e["pct_of_total"] = round(raw / denom * 100, 2) if denom else None
+        supplements["inventory_composition"] = inv_entries
+
+    # --- Purchase Obligations ---
+    po_rows = df[df["concept"].astype(str).str.contains(
+        "UnrecordedUnconditionalPurchaseObligation", case=False, na=False)]
+    po_rows = po_rows[~po_rows["concept"].astype(str).str.contains(
+        "TextBlock|Policy", case=False, na=False)]
+    if len(po_rows) > 0:
+        po_entries = []
+        for _, row in po_rows.iterrows():
+            concept = str(row["concept"])
+            try:
+                amount = float(row["value"])
+            except (ValueError, TypeError):
+                continue
+            amt_str = f"${amount/1e9:.1f}B" if amount >= 1e9 else f"${amount/1e6:.0f}M"
+            timeframe = ""
+            for label, tf in [("BalanceSheetAmount", "total"),
+                              ("FirstAnniversary", "year 1"), ("SecondAnniversary", "year 2"),
+                              ("ThirdAnniversary", "year 3"), ("FourthAnniversary", "year 4"),
+                              ("FifthAnniversary", "year 5"), ("AfterFiveYears", "after year 5")]:
+                if label in concept:
+                    timeframe = tf
+                    break
+            po_entries.append({"obligation_type": "unconditional purchase obligation",
+                              "amount": amt_str, "timeframe": timeframe, "source": "xbrl"})
+        if po_entries:
+            supplements["purchase_obligations"] = po_entries
+
+    return {
+        "filing": metadata,
+        "data": supplements,
+        "xbrl_available": True,
+    }

sec_analyzer/presets/__init__.py

@@ -0,0 +1,5 @@
+"""Built-in extraction presets."""
+
+from .supply_chain import SupplyChain
+
+__all__ = ["SupplyChain"]

sec_analyzer/presets/supply_chain.py

@@ -0,0 +1,145 @@
+"""Supply chain intelligence preset for SEC filings.
+
+Extracts suppliers, customers, single-source dependencies, geographic
+concentration, capacity constraints, supply chain risks, revenue concentration,
+geographic revenue, purchase obligations, market risk disclosures, and
+inventory composition from 10-K/10-Q/20-F filings.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SupplierEntry(BaseModel):
+    entity: str = Field(description="Name of the supplier company. Use exact name from the filing.")
+    relationship: str = Field(default="", description="Nature of the supply relationship (e.g., 'sole source supplier', 'key component vendor').")
+    context: str = Field(default="", description="Brief relevant excerpt (1-3 sentences) from the filing that supports this supplier relationship.")
+
+
+class CustomerEntry(BaseModel):
+    entity: str = Field(description="Name of the customer company. Use exact name from the filing.")
+    relationship: str = Field(default="", description="Nature of the customer relationship (e.g., 'major customer', 'accounted for 35% of revenue').")
+    context: str = Field(default="", description="Brief relevant excerpt (1-3 sentences) from the filing that supports this customer relationship.")
+
+
+class SingleSourceEntry(BaseModel):
+    component: str = Field(default="", description="Component or material with single-source dependency (e.g., 'DRAM memory chips').")
+    supplier: str = Field(description="Name of the sole-source or single-source supplier.")
+    context: str = Field(default="", description="Brief relevant excerpt (1-3 sentences) from the filing describing this dependency.")
+
+
+class GeographicEntry(BaseModel):
+    location: str = Field(description="Country or region name (e.g., 'Taiwan', 'South Korea').")
+    activity: str = Field(default="", description="Type of activity at this location (e.g., 'manufacturing', 'assembly').")
+    context: str = Field(default="", description="Brief relevant excerpt (1-3 sentences) from the filing describing geographic concentration.")
+
+
+class CapacityConstraintEntry(BaseModel):
+    constraint: str = Field(description="Type of capacity constraint (e.g., 'extended lead times', 'production capacity limitation').")
+    context: str = Field(default="", description="Brief relevant excerpt (1-3 sentences) from the filing describing the constraint.")
+
+
+class SupplyChainRiskEntry(BaseModel):
+    risk: str = Field(description="Type of supply chain risk (e.g., 'tariff impact', 'raw material shortage').")
+    context: str = Field(default="", description="Brief relevant excerpt (1-3 sentences) from the filing describing this risk.")
+
+
+class RevenueConcentrationEntry(BaseModel):
+    entity: str = Field(description="Customer or segment name from filing.")
+    revenue_pct: float | None = Field(default=None, description="% of total revenue (e.g., 35.2).")
+    revenue_amount: str = Field(default="", description="Amount if disclosed (e.g., '$5.2 billion').")
+    context: str = Field(default="", description="1-3 sentences from Notes.")
+
+
+class GeographicRevenueEntry(BaseModel):
+    region: str = Field(description="Country or region (e.g., 'United States', 'China').")
+    revenue_pct: float | None = Field(default=None, description="% of total revenue.")
+    revenue_amount: str = Field(default="", description="Amount if disclosed.")
+    context: str = Field(default="", description="1-3 sentences from Notes.")
+
+
+class PurchaseObligationEntry(BaseModel):
+    counterparty: str = Field(default="", description="Supplier name if disclosed.")
+    obligation_type: str = Field(description="Type (e.g., 'inventory commitment', 'capacity reservation').")
+    amount: str = Field(default="", description="Dollar amount (e.g., '$2.5 billion').")
+    timeframe: str = Field(default="", description="Duration (e.g., 'through fiscal 2027').")
+    context: str = Field(default="", description="1-3 sentences from Notes.")
+
+
+class MarketRiskEntry(BaseModel):
+    risk_type: Literal["commodity", "fx", "interest_rate"] = Field(description="Type: 'commodity', 'fx', or 'interest_rate'.")
+    exposure: str = Field(default="", description="Specific exposure (e.g., 'gold price', 'EUR/USD').")
+    sensitivity: str = Field(default="", description="Quantitative impact if disclosed (e.g., '10% increase = $50M COGS impact').")
+    hedging: str = Field(default="", description="Hedging strategy if disclosed.")
+    context: str = Field(default="", description="1-3 sentences from filing.")
+
+
+class InventoryCompositionEntry(BaseModel):
+    category: Literal["raw_materials", "work_in_progress", "finished_goods"] = Field(description="Category: 'raw_materials', 'work_in_progress', or 'finished_goods'.")
+    amount: str = Field(default="", description="Dollar amount if disclosed (e.g., '$1.2 billion').")
+    pct_of_total: float | None = Field(default=None, description="% of total inventory.")
+    context: str = Field(default="", description="1-3 sentences from Notes (valuation, aging, obsolescence).")
+
+
+class SupplyChain(BaseModel):
+    """Supply chain intelligence extraction from SEC filings."""
+
+    __prompt__: ClassVar[str] = """\
+You are a financial analyst extracting supply chain intelligence from SEC filings.
+Extract entities and relationships exactly as stated in the filing text.
+
+The filing text below is the complete SEC filing in markdown format.
+Identify relevant sections by their natural headings:
+- Item 1 (Business): suppliers, customers, single-source dependencies
+- Item 1A (Risk Factors): supply chain risks, geographic concentration
+- Item 7 (MD&A): capacity constraints, operating discussion
+- Item 7A (Market Risk): commodity/FX/interest rate exposures
+- Item 8 Notes: revenue segments, inventory, commitments, concentration
+For 20-F filings, look for equivalent items (Item 4, 3D, 5, 11, 18/19).
+
+Rules:
+1. Use exact company names from the filing — do not paraphrase or invent.
+2. For context fields, copy 1-3 relevant sentences verbatim from the filing.
+3. If a category has no relevant data, return an empty list.
+4. Do NOT extract the filing company itself as its own supplier or customer.
+5. Focus on factual supply chain relationships — skip generic boilerplate.
+6. De facto single-source: If a supplier is described as the PRIMARY or ONLY provider
+   for a critical component category and NO alternative supplier is mentioned for that
+   same category, classify it as single_source_dependencies.
+7. Customer extraction: Look for revenue concentration disclosures, named buyers,
+   and "accounted for X% of revenue" language.
+8. Relationship specificity: Use precise descriptions such as "sole foundry for
+   leading-edge GPUs", "memory supplier (HBM)", "anchor customer >10% revenue".
+9. Only infer relationships where the filing text provides contextual support.
+10. Revenue concentration: From Notes, extract customers/segments with specific % of
+    revenue. Include exact percentage as revenue_pct.
+11. Geographic revenue: From Notes, extract revenue by country/region with exact
+    percentages. Use standardized country names.
+12. Purchase obligations: From Notes (Commitments and Contingencies), extract purchase
+    commitments, capacity reservations, take-or-pay contracts.
+13. Market risk disclosures: From Item 7A, extract commodity/FX/interest rate exposures.
+    Classify risk_type as "commodity", "fx", or "interest_rate".
+14. Inventory composition: From Notes, extract raw materials, work-in-progress, and
+    finished goods amounts and percentages.
+
+Filing company: {company_name}
+
+Extract all supply chain entities from this SEC filing text:
+
+{filing_text}
+"""
+
+    suppliers: list[SupplierEntry] = Field(default_factory=list, description="Companies that supply products, materials, or services to the filing company.")
+    customers: list[CustomerEntry] = Field(default_factory=list, description="Companies that purchase products or services from the filing company.")
+    single_source_dependencies: list[SingleSourceEntry] = Field(default_factory=list, description="Components with sole-source or single-source supplier dependencies.")
+    geographic_concentration: list[GeographicEntry] = Field(default_factory=list, description="Locations where manufacturing, production, or sourcing is concentrated.")
+    capacity_constraints: list[CapacityConstraintEntry] = Field(default_factory=list, description="Production capacity limitations, extended lead times, or backlogs.")
+    supply_chain_risks: list[SupplyChainRiskEntry] = Field(default_factory=list, description="Supply disruption risks including tariffs, shortages, geopolitical risks.")
+    revenue_concentration: list[RevenueConcentrationEntry] = Field(default_factory=list, description="Customer/segment revenue concentration from Notes.")
+    geographic_revenue: list[GeographicRevenueEntry] = Field(default_factory=list, description="Revenue breakdown by country/region from Notes.")
+    purchase_obligations: list[PurchaseObligationEntry] = Field(default_factory=list, description="Purchase commitments, capacity reservations from Notes.")
+    market_risk_disclosures: list[MarketRiskEntry] = Field(default_factory=list, description="Market risk exposures from Item 7A.")
+    inventory_composition: list[InventoryCompositionEntry] = Field(default_factory=list, description="Inventory breakdown from Notes.")

sec_analyzer-0.1.0.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: sec-analyzer
+Version: 0.1.0
+Summary: Extract structured data from SEC filings using LLM + Pydantic presets
+Project-URL: Homepage, https://github.com/tjdwls101010/SEC-Analyzer
+Author: Seongjin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edgar,finance,llm,pydantic,sec,structured-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: edgartools>=3.0
+Requires-Dist: google-genai>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://i.namu.wiki/i/HbVpHEsWi0aG30L2PEWRL9FEA0P7Vf-iLYm0QPbH1iOGJabk3vYcDQz1Uxo1DX3OaujOJWX62rs6QgqXFOybLw.svg" width="120" alt="SEC">
+
+# SEC-Analyzer
+
+**Extract structured data from SEC filings using LLM + Pydantic presets.**
+
+Turn any SEC filing (10-K, 10-Q, 20-F, DEF 14A, ...) into structured JSON — define a Pydantic model, and the library does the rest.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#)
+[![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](#)
+
+[Installation](#installation) · [Quick Start](#quick-start) · [Custom Presets](#custom-presets) · [API Reference](#api-reference) · [CLI](#cli)
+
+</div>
+
+![](https://github.com/tjdwls101010/DUMOK/blob/main/Images/gemini-3-pro-1774265890176ioxhdiv1w.png?raw=true)
+
+---
+
+## Why This Library?
+
+SEC filings contain invaluable data — supply chains, revenue concentration, executive compensation, risk factors — but every filing has a different format. Traditional parsing breaks constantly.
+
+This library uses **LLM structured output** (Gemini) to extract exactly the data you define in a **Pydantic model**. The LLM reads the filing and fills in your schema. No regex, no HTML parsing, no breakage.
+
+```python
+from sec_analyzer import extract
+from sec_analyzer.presets import SupplyChain
+
+result = extract("NVDA", preset=SupplyChain)
+print(result["data"]["suppliers"])
+# [{'entity': 'Taiwan Semiconductor Manufacturing Company Limited',
+#   'relationship': 'foundry for semiconductor wafers',
+#   'context': 'We utilize foundries, such as TSMC and Samsung...'}, ...]
+```
+
+---
+
+## Installation
+
+```bash
+pip install sec-analyzer
+```
+
+Requires Python 3.10+ and a [Google AI API key](https://ai.google.dev/).
+
+---
+
+## Quick Start
+
+### 1. Set your API key
+
+```bash
+export GOOGLE_API_KEY="your-key-here"
+export EDGAR_IDENTITY="YourApp/1.0 your@email.com"
+```
+
+Or create a `.env` file:
+```
+GOOGLE_API_KEY=your-key-here
+EDGAR_IDENTITY=YourApp/1.0 your@email.com
+```
+
+### 2. Extract data
+
+```python
+from sec_analyzer import extract
+from sec_analyzer.presets import SupplyChain
+
+# Latest 10-K
+result = extract("NVDA", preset=SupplyChain)
+
+# Specific form
+result = extract("TSM", preset=SupplyChain, form="20-F")
+
+# Specific filing date
+result = extract("AAPL", preset=SupplyChain, filing_date="2025-10-30")
+```
+
+### 3. Use the result
+
+```python
+filing = result["filing"]
+# {'form': '10-K', 'filing_date': '2026-02-25', 'accession_number': '...', 'filing_url': '...'}
+
+data = result["data"]
+print(f"Suppliers: {len(data['suppliers'])}")
+print(f"Customers: {len(data['customers'])}")
+print(f"Single-source deps: {len(data['single_source_dependencies'])}")
+```
+
+---
+
+## Custom Presets
+
+The real power: **define your own Pydantic model** to extract anything.
+
+### Basic custom preset
+
+```python
+from pydantic import BaseModel, Field
+from sec_analyzer import extract
+
+class RiskFactors(BaseModel):
+    regulatory_risks: list[dict] = Field(
+        default_factory=list,
+        description="Government regulations that could impact the business"
+    )
+    litigation: list[dict] = Field(
+        default_factory=list,
+        description="Pending lawsuits and legal proceedings"
+    )
+    cybersecurity_risks: list[dict] = Field(
+        default_factory=list,
+        description="Data breach and cybersecurity threats"
+    )
+
+result = extract("META", preset=RiskFactors)
+```
+
+When no `__prompt__` is defined, the library auto-generates a prompt from your field descriptions.
+
+### Advanced: custom prompt
+
+For expert-level control, add a `__prompt__` class variable:
+
+```python
+from typing import ClassVar
+from pydantic import BaseModel, Field
+
+class ExecutiveComp(BaseModel):
+    __prompt__: ClassVar[str] = """\
+You are analyzing a DEF 14A proxy statement for {company_name}.
+Extract executive compensation data from the Summary Compensation Table
+and related disclosure sections.
+
+Rules:
+1. Include only Named Executive Officers (NEOs)
+2. All dollar amounts in exact figures from the filing
+3. Include stock awards, option awards, and non-equity incentive plan separately
+
+Filing text:
+{filing_text}
+"""
+
+    executives: list[dict] = Field(description="NEO compensation details")
+    equity_awards: list[dict] = Field(description="Stock and option grant details")
+
+result = extract("AAPL", preset=ExecutiveComp, form="DEF 14A")
+```
+
+The `{company_name}` and `{filing_text}` placeholders are filled automatically.
+
+---
+
+## Built-in Presets
+
+### `SupplyChain`
+
+Extracts 11 categories of supply chain intelligence from 10-K/10-Q/20-F filings:
+
+| Category | Description |
+|----------|-------------|
+| `suppliers` | Companies supplying products/materials/services |
+| `customers` | Companies purchasing products/services |
+| `single_source_dependencies` | Components with sole-source suppliers |
+| `geographic_concentration` | Manufacturing/sourcing location concentration |
+| `capacity_constraints` | Production limitations and lead times |
+| `supply_chain_risks` | Disruption risks (tariffs, shortages, geopolitical) |
+| `revenue_concentration` | Customer/segment revenue % from Notes |
+| `geographic_revenue` | Revenue by country/region from Notes |
+| `purchase_obligations` | Commitments and take-or-pay contracts |
+| `market_risk_disclosures` | Commodity/FX/interest rate exposures (Item 7A) |
+| `inventory_composition` | Raw materials/WIP/finished goods breakdown |
+
+---
+
+## API Reference
+
+### `extract(symbol, preset, form="10-K", filing_date=None, max_chars=2_000_000, api_key=None, model=None)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `symbol` | str | Ticker symbol (e.g., "NVDA") |
+| `preset` | BaseModel class | Pydantic model defining extraction schema |
+| `form` | str | Filing type. Auto-fallback 10-K → 20-F |
+| `filing_date` | str | Specific date (YYYY-MM-DD). None = latest |
+| `max_chars` | int | Max filing markdown length |
+| `api_key` | str | Google API key (fallback: `GOOGLE_API_KEY` env) |
+| `model` | str | Gemini model (fallback: `GOOGLE_MODEL` env, default: `gemini-2.5-flash`) |
+
+**Returns** `{"filing": {...}, "data": {...}}`
+
+---
+
+## CLI
+
+```bash
+# Supply chain extraction (default)
+sec-analyzer NVDA
+
+# Specific form
+sec-analyzer TSM --form 20-F
+
+# Compact JSON
+sec-analyzer NVDA --json
+
+# Specific filing date
+sec-analyzer AAPL --filing-date 2025-10-30
+```
+
+---
+
+## How It Works
+
+```
+1. edgartools finds the filing on SEC EDGAR
+2. Filing converted to markdown (tables preserved)
+3. Full markdown + Pydantic schema sent to Gemini
+4. Gemini returns structured JSON matching the schema
+5. Pydantic validates and returns typed data
+```
+
+The key insight: Gemini's **structured output** mode forces the response to match your Pydantic schema exactly. No post-processing, no regex, no parsing.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GOOGLE_API_KEY` | Yes | - | Google AI API key |
+| `EDGAR_IDENTITY` | No | `SECAnalyzer/1.0 user@example.com` | SEC EDGAR User-Agent |
+| `GOOGLE_MODEL` | No | `gemini-2.5-flash` | Gemini model ID |
+
+---
+
+## Disclaimer
+
+This project is **not affiliated with the SEC, EDGAR, or Google**. Filing data comes from SEC EDGAR (public). LLM extraction may contain errors — always verify critical data against the original filing.
+
+This tool is for **research and educational purposes only**. It is not financial advice.
+
+---
+
+## License
+
+MIT

sec_analyzer-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sec_analyzer/__init__.py,sha256=eO_j8ok9YZ3FTrmkGkMFTZlMNRhuCzXv4YBEpJKVCoo,173
+sec_analyzer/cli.py,sha256=XcWhp-onokVCmdTUFdWLThMA1UOBShpDlChuEFmUOI4,1758
+sec_analyzer/engine.py,sha256=5LTbvKkvKI2NqKP-8Mj1sEd1qZCTFBeIMhoXUgR7v9w,16094
+sec_analyzer/presets/__init__.py,sha256=EXY1wa66qYKonFEUx1xtGThS5jFpUF3IPN45AIbKPpY,101
+sec_analyzer/presets/supply_chain.py,sha256=oiBg0LKJBBZtjUrNQ2_qmc4_repQQAbBvl_CwUAsK1g,9392
+sec_analyzer-0.1.0.dist-info/METADATA,sha256=ceFL6fQHdK-CT8fLIuNKLGxQJHDOsyvOR97qHP3vUE0,8216
+sec_analyzer-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sec_analyzer-0.1.0.dist-info/entry_points.txt,sha256=2iYSZHJ9pQCKz2oaMyAWlAZu1k3gveR4G6tZrqo5La8,55
+sec_analyzer-0.1.0.dist-info/licenses/LICENSE,sha256=TcoeGh2YiCuQikmHXW5evYQ74WkVQzZAgNzGodYHhIA,1065
+sec_analyzer-0.1.0.dist-info/RECORD,,

sec_analyzer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sec_analyzer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sec-analyzer = sec_analyzer.cli:main

sec_analyzer-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seongjin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.