Python
feat(dataflows): serve US statements as filed, from SEC EDGAR
Yijia-Xiaof881c4a1115d
diff --git a/.env.example b/.env.exampleindex b6f14ed41..42c17f68c 100644--- a/.env.example+++ b/.env.example@@ -16,57 +16,43 @@ MOONSHOT_API_KEY=GROQ_API_KEY=NVIDIA_API_KEY=-# FRED (Federal Reserve macro data: rates, inflation, labor, growth). Free key: https://fred.stlouisfed.org/docs/api/api_key.html+# SEC EDGAR (US company filings, point-in-time). No key; a contact address SEC can reach you at.+#SEC_EDGAR_USER_AGENT=Your Name [email protected]++# FRED (Federal Reserve macro data). Free key: https://fred.stlouisfed.org/docs/api/api_key.html#FRED_API_KEY=-# Optional: a custom OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp,-# relay). Select provider "openai_compatible" and set the base URL; the key is-# optional (local servers need none).+# Custom OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp). Local servers need no key.#OPENAI_COMPATIBLE_API_KEY=-# AWS Bedrock (provider "bedrock", install with: pip install ".[bedrock]").-# Auth: either a Bedrock API key (bearer token, no AWS access keys) OR the AWS-# credential chain (env keys / ~/.aws/credentials / IAM role / AWS_PROFILE). Set-# the region either way; a bearer token takes precedence when both are present.+# AWS Bedrock (pip install ".[bedrock]"). Bearer token, or the AWS credential chain; set the region either way.#AWS_BEARER_TOKEN_BEDROCK=#AWS_DEFAULT_REGION=us-west-2#AWS_PROFILE=-# Optional: point at a remote Ollama server. When unset, defaults to-# the local instance at http://localhost:11434/v1. Convention follows-# the broader Ollama ecosystem; both the CLI dropdown and programmatic-# client pick this up.+# Remote Ollama server. Unset uses http://localhost:11434/v1.#OLLAMA_BASE_URL=http://your-ollama-host:11434/v1-# Optional: override DEFAULT_CONFIG without editing code.-# Any TRADINGAGENTS_* variable below, when set, replaces the matching key-# in tradingagents/default_config.py. Values are coerced to the type of-# the existing default (bool / int / str), so "true"/"3" work as expected.-# In the CLI, setting the LLM provider / models / backend URL / language-# also skips the matching interactive selection step (useful for-# OpenAI-compatible endpoints like opencode or LM Studio, and unattended runs).+# Override any DEFAULT_CONFIG key. In the CLI, a value set here skips its prompt.#TRADINGAGENTS_LLM_PROVIDER=openai-#TRADINGAGENTS_DEEP_THINK_LLM=gpt-5.4-#TRADINGAGENTS_QUICK_THINK_LLM=gpt-5.4-mini+#TRADINGAGENTS_DEEP_THINK_LLM=gpt-5.6+#TRADINGAGENTS_QUICK_THINK_LLM=gpt-5.6-luna#TRADINGAGENTS_LLM_BACKEND_URL=#TRADINGAGENTS_OUTPUT_LANGUAGE=English#TRADINGAGENTS_MAX_DEBATE_ROUNDS=1#TRADINGAGENTS_MAX_RISK_ROUNDS=1#TRADINGAGENTS_CHECKPOINT_ENABLED=false-# Sampling temperature (lower = less run-to-run variation on models that-# honor it). Unset leaves each provider at its default. See the README-# "Reproducibility" note — no setting makes LLM output fully deterministic.++# Lower temperature means less run-to-run variation on models that honor it.#TRADINGAGENTS_TEMPERATURE=0.0-# LLM SDK retry budget forwarded to every provider. Unset leaves each SDK at its-# own default (usually 2). Raise it to ride out bursty 429 rate-limit throttling-# on rate-limited deployments (e.g. Azure OpenAI) instead of aborting the run.++# Retry budget for every LLM SDK. Raise it to ride out 429 throttling.#TRADINGAGENTS_LLM_MAX_RETRIES=6-# Cap on output tokens forwarded to every provider (Gemini's max_output_tokens-# too). Unset leaves each provider at its default. Set it to bound a model that-# emits unbounded reasoning/output and hangs or trips a gateway idle timeout.++# Cap output tokens to bound a model that runs long and trips a timeout.#TRADINGAGENTS_MAX_TOKENS=8192-# Provider-specific reasoning/thinking depth (optional; unset = provider-# default). Setting one also skips the matching interactive prompt.++# Reasoning depth per provider; setting one skips its prompt.#TRADINGAGENTS_OPENAI_REASONING_EFFORT=medium#TRADINGAGENTS_GOOGLE_THINKING_LEVEL=high#TRADINGAGENTS_ANTHROPIC_EFFORT=highdiff --git a/tests/test_sec_edgar.py b/tests/test_sec_edgar.pynew file mode 100644index 000000000..79f205357--- /dev/null+++ b/tests/test_sec_edgar.py@@ -0,0 +1,239 @@+"""SEC EDGAR fundamentals: statements as they were filed, not as they read today.++Every other fundamentals vendor serves the current value of a past period and+cuts on the fiscal period end, so a run sees figures the company had not yet+filed, and later restatements replace what was actually published. EDGAR carries+the filing date of every fact, so a run can be limited to what was on file by its+own date.+"""++from __future__ import annotations++from unittest import mock++import pytest++from tradingagents.dataflows import sec_edgar+from tradingagents.dataflows.errors import NoMarketDataError++_REAL_FETCH = sec_edgar._fetch_json++TICKER_MAP = {"0": {"cik_str": 320193, "ticker": "AAPL", "title": "Apple Inc."}}+++def _fact(end, val, filed, form="10-K", fp="FY", start=None):+ fact = {"end": end, "val": val, "filed": filed, "form": form, "fy": int(end[:4]), "fp": fp}+ if start:+ fact["start"] = start+ return fact+++FACTS = {+ "cik": 320193,+ "entityName": "Apple Inc.",+ "facts": {"us-gaap": {+ "Assets": {"units": {"USD": [+ _fact("2008-09-27", 39_572_000_000, "2008-11-05"),+ _fact("2008-09-27", 36_171_000_000, "2010-01-25", form="10-K/A"),+ _fact("2022-03-26", 350_662_000_000, "2022-04-29", form="10-Q", fp="Q2"),+ _fact("2024-09-28", 364_980_000_000, "2024-11-01"),+ ]}},+ "Liabilities": {"units": {"USD": [_fact("2024-09-28", 308_030_000_000, "2024-11-01")]}},+ "EarningsPerShareDiluted": {"units": {"USD/shares": [+ _fact("2024-09-28", 6.08, "2024-11-01", start="2023-09-30"),+ ]}},+ "RevenueFromContractWithCustomerExcludingAssessedTax": {"units": {"USD": [+ # One filing reports the quarter and the year to date under one end date.+ _fact("2025-12-31", 81_300_000_000, "2026-01-29", form="10-Q", fp="Q2", start="2025-10-01"),+ _fact("2025-12-31", 158_900_000_000, "2026-01-29", form="10-Q", fp="Q2", start="2025-07-01"),+ _fact("2024-09-28", 391_035_000_000, "2024-11-01", start="2023-09-30"),+ ]}},+ }},+}++[email protected](autouse=True)+def _no_network_or_cache(tmp_path, monkeypatch):+ monkeypatch.setattr(sec_edgar, "get_config", lambda: {"data_cache_dir": str(tmp_path)})+ monkeypatch.setattr(sec_edgar, "_fetch_json", lambda url: TICKER_MAP if "company_tickers" in url else FACTS)+++def test_a_us_filer_resolves_to_its_cik():+ assert sec_edgar.cik_for("AAPL") == "0000320193"+ assert sec_edgar.cik_for("aapl") == "0000320193"+++def test_a_non_filer_is_reported_as_such_not_as_missing_data():+ with pytest.raises(NoMarketDataError, match="not a US SEC filer"):+ sec_edgar.get_balance_sheet("0700.HK", "annual", "2026-01-01")+++def test_a_restated_figure_reads_as_it_did_at_the_time():+ """The value published then, not the correction filed later."""+ as_filed = sec_edgar.get_balance_sheet("AAPL", "annual", "2009-06-30")+ restated = sec_edgar.get_balance_sheet("AAPL", "annual", "2011-01-01")+ assert "39572" in as_filed and "36171" not in as_filed+ assert "36171" in restated+++def test_a_period_that_ended_but_was_not_filed_yet_is_not_served():+ """The fiscal year ended 2024-09-28; it reached the public on 2024-11-01."""+ before = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-10-15")+ after = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")+ assert "2024-09-28" not in before+ assert "2024-09-28" in after and "364980" in after+++def test_the_quarter_is_not_confused_with_the_year_to_date():+ """One filing carries both spans under the same end date (#MSFT-shaped)."""+ out = sec_edgar.get_income_statement("AAPL", "quarterly", "2026-06-01")+ assert "81300" in out+ assert "158900" not in out+++def test_a_line_the_filer_does_not_tag_is_named_unavailable():+ out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")+ assert "Stockholders Equity" in out and "unavailable" in out+ assert "364980" in out # the rest of the statement still returns+++def test_the_report_states_the_vintage_rule():+ out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")+ assert "filed on or before 2024-11-15" in out+++def test_a_filer_with_no_usable_facts_reads_differently_from_a_non_filer(monkeypatch):+ monkeypatch.setattr(sec_edgar, "_fetch_json",+ lambda url: TICKER_MAP if "company_tickers" in url else {"facts": {}})+ with pytest.raises(NoMarketDataError, match="no us-gaap facts"):+ sec_edgar.get_balance_sheet("AAPL", "annual", "2026-01-01")+++def test_company_facts_are_fetched_once_per_company_not_once_per_date(tmp_path, monkeypatch):+ """A sweep asks for many dates; the filing history is the same file."""+ calls = []+ monkeypatch.setattr(sec_edgar, "_fetch_json",+ lambda url: calls.append(url) or (TICKER_MAP if "company_tickers" in url else FACTS))+ for date in ("2024-11-15", "2025-01-15", "2025-06-15"):+ sec_edgar.get_balance_sheet("AAPL", "annual", date)+ assert len([u for u in calls if "companyfacts" in u]) == 1+++def test_it_works_unconfigured_and_takes_the_caller_s_own_contact(monkeypatch):+ """SEC returns 403 for a User-Agent with no contact address, so the default+ carries one; a caller who sets their own replaces it."""+ monkeypatch.delenv("SEC_EDGAR_USER_AGENT", raising=False)+ assert "@" in sec_edgar._user_agent()++ monkeypatch.setenv("SEC_EDGAR_USER_AGENT", "MyDesk [email protected]")+ assert sec_edgar._user_agent() == "MyDesk [email protected]"+++def test_a_throttle_lets_the_next_vendor_try(monkeypatch):+ """SEC throttles by refusing the request; the router then tries yfinance."""+ import requests++ from tradingagents.dataflows.errors import VendorRateLimitError++ def _throttled(*a, **k):+ raise requests.HTTPError(response=mock.Mock(status_code=429))++ monkeypatch.setattr(sec_edgar.requests, "get", _throttled)+ with pytest.raises(VendorRateLimitError):+ _REAL_FETCH("https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json")+++def test_values_do_not_break_the_columns():+ """Figures run to the billions; a thousands separator would split the field."""+ out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")+ body = [row for row in out.splitlines() if row.startswith("Total Assets")][0]+ assert body.count(",") == out.splitlines()[3].count(",")+++def test_a_per_share_figure_keeps_its_own_unit():+ """Statements are reported in millions, but EPS is dollars per share: scaling+ it the same way prints a real figure as zero."""+ out = sec_edgar.get_income_statement("AAPL", "annual", "2024-11-15")+ row = [r for r in out.splitlines() if r.startswith("Diluted EPS")][0]+ assert "6.08" in row+ assert "USD/shares" in row or "per share" in row+++def test_every_row_has_one_cell_per_period():+ """An untagged line still has to line up with the columns, or the table is+ misread by position."""+ out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")+ table = [r for r in out.splitlines() if r and not r.startswith("#")]+ widths = {row.count(",") for row in table}+ assert len(widths) == 1, table+++def test_a_server_error_lets_the_next_vendor_try(monkeypatch):+ import requests++ from tradingagents.dataflows.errors import VendorError++ def _server_error(*a, **k):+ raise requests.HTTPError(response=mock.Mock(status_code=503))++ monkeypatch.setattr(sec_edgar.requests, "get", _server_error)+ with pytest.raises(VendorError): # not a bare HTTPError+ _REAL_FETCH("https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json")+++def test_older_periods_fall_back_to_the_tag_the_filer_used_then():+ """Filers renamed lines when the revenue standard changed, so one tag covers+ only recent years. Each period takes one tag, never a sum of two."""+ facts = {"Revenues": {"units": {"USD": [_fact("2015-09-26", 233_715_000_000, "2015-10-28",+ start="2014-09-28")]}},+ "RevenueFromContractWithCustomerExcludingAssessedTax": {"units": {"USD": [+ _fact("2024-09-28", 391_035_000_000, "2024-11-01", start="2023-09-30")]}}}+ values, unit = sec_edgar._as_of(facts, ("RevenueFromContractWithCustomerExcludingAssessedTax",+ "Revenues"), "2026-01-01", (300, 400))+ assert values == {"2015-09-26": 233_715_000_000, "2024-09-28": 391_035_000_000}+ assert unit == "USD"+++def test_a_period_reported_under_two_tags_takes_the_preferred_one_not_both():+ facts = {"Revenues": {"units": {"USD": [_fact("2024-09-28", 111, "2024-11-01", start="2023-09-30")]}},+ "RevenueFromContractWithCustomerExcludingAssessedTax": {"units": {"USD": [+ _fact("2024-09-28", 999, "2024-11-01", start="2023-09-30")]}}}+ values, _ = sec_edgar._as_of(facts, ("RevenueFromContractWithCustomerExcludingAssessedTax",+ "Revenues"), "2026-01-01", (300, 400))+ assert values == {"2024-09-28": 999}+++def test_the_default_identification_tracks_the_installed_version(monkeypatch):+ """A release should identify itself, not a version frozen in the source."""+ monkeypatch.delenv("SEC_EDGAR_USER_AGENT", raising=False)+ monkeypatch.setattr(sec_edgar.metadata, "version", lambda name: "9.9.9")+ assert sec_edgar._user_agent() == "TradingAgents/9.9.9 ([email protected])"+++def test_an_uninstalled_checkout_still_identifies_itself(monkeypatch):+ monkeypatch.delenv("SEC_EDGAR_USER_AGENT", raising=False)++ def _missing(name):+ raise sec_edgar.metadata.PackageNotFoundError(name)++ monkeypatch.setattr(sec_edgar.metadata, "version", _missing)+ assert "@" in sec_edgar._user_agent()diff --git a/tradingagents/dataflows/interface.py b/tradingagents/dataflows/interface.pyindex 281c83747..6fc80462d 100644--- a/tradingagents/dataflows/interface.py+++ b/tradingagents/dataflows/interface.py@@ -19,6 +19,11 @@ from .errors import ()from .fred import get_macro_data as get_fred_macro_datafrom .polymarket import get_prediction_markets as get_polymarket_prediction_markets+from .sec_edgar import (+ get_balance_sheet as get_sec_edgar_balance_sheet,+ get_cashflow as get_sec_edgar_cashflow,+ get_income_statement as get_sec_edgar_income_statement,+)from .y_finance import (get_balance_sheet as get_yfinance_balance_sheet,get_cashflow as get_yfinance_cashflow,@@ -79,6 +84,7 @@ TOOLS_CATEGORIES = {VENDOR_LIST = ["yfinance",+ "sec_edgar","fred","polymarket","alpha_vantage",@@ -110,14 +116,17 @@ VENDOR_METHODS = {},"get_balance_sheet": {"alpha_vantage": get_alpha_vantage_balance_sheet,+ "sec_edgar": get_sec_edgar_balance_sheet,"yfinance": get_yfinance_balance_sheet,},"get_cashflow": {"alpha_vantage": get_alpha_vantage_cashflow,+ "sec_edgar": get_sec_edgar_cashflow,"yfinance": get_yfinance_cashflow,},"get_income_statement": {"alpha_vantage": get_alpha_vantage_income_statement,+ "sec_edgar": get_sec_edgar_income_statement,"yfinance": get_yfinance_income_statement,},# news_datadiff --git a/tradingagents/dataflows/sec_edgar.py b/tradingagents/dataflows/sec_edgar.pynew file mode 100644index 000000000..245ec0241--- /dev/null+++ b/tradingagents/dataflows/sec_edgar.py@@ -0,0 +1,229 @@+"""Company statements as they were filed, from SEC EDGAR.++Every other fundamentals vendor serves a period's current value and cuts the+statement at the fiscal period end. That is two claims a run should not make: a+period that has ended is not public until the company files, weeks later, and a+figure that was later restated is not what investors saw at the time.++EDGAR reports every fact with the date it was filed, so a run dated ``curr_date``+serves exactly what was on file by then, restatements included at the vintage+that was current. Apple's 2008 total assets read as 39.6B until the 2010+amendment; a 2009 run should see 39.6B, and does.++Access needs no key or account, only a User-Agent identifying the caller, which+SEC requires and refuses requests without. US filers only: anything absent from+EDGAR's ticker map falls through to the next configured vendor.+"""++from __future__ import annotations++import json+import logging+import os+import time+from datetime import date, datetime+from importlib import metadata+from pathlib import Path++import requests++from .config import get_config+from .errors import NoMarketDataError, VendorRateLimitError++logger = logging.getLogger(__name__)++_TICKERS_URL = "https://www.sec.gov/files/company_tickers.json"+_FACTS_URL = "https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json"++# A filing history only changes when something new is filed, so one fetch per+# company per day serves every date a run asks about.+_CACHE_TTL_SECONDS = 24 * 60 * 60++# Line items, each with the tags filers use for it, best first. First match wins+# and values are never summed across tags: a company reporting revenue under two+# tags would otherwise be counted twice.+_STATEMENTS: dict[str, list[tuple[str, tuple[str, ...]]]] = {+ "balance_sheet": [+ ("Total Assets", ("Assets",)),+ ("Current Assets", ("AssetsCurrent",)),+ ("Cash and Equivalents", ("CashAndCashEquivalentsAtCarryingValue",)),+ ("Total Liabilities", ("Liabilities",)),+ ("Current Liabilities", ("LiabilitiesCurrent",)),+ ("Stockholders Equity", ("StockholdersEquity",+ "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest")),+ ],+ "income_statement": [+ ("Revenue", ("RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues",+ "SalesRevenueNet")),+ ("Cost of Revenue", ("CostOfRevenue", "CostOfGoodsAndServicesSold")),+ ("Gross Profit", ("GrossProfit",)),+ ("Operating Income", ("OperatingIncomeLoss",)),+ ("Net Income", ("NetIncomeLoss",)),+ ("Diluted EPS", ("EarningsPerShareDiluted",)),+ ],+ "cashflow": [+ ("Operating Cash Flow", ("NetCashProvidedByUsedInOperatingActivities",+ "NetCashProvidedByUsedInOperatingActivitiesContinuingOperations")),+ ("Investing Cash Flow", ("NetCashProvidedByUsedInInvestingActivities",)),+ ("Financing Cash Flow", ("NetCashProvidedByUsedInFinancingActivities",)),+ ("Capital Expenditure", ("PaymentsToAcquirePropertyPlantAndEquipment",)),+ ],+}++# A statement's figures cover a span: a quarter is about 90 days, a year about+# 365. One filing reports both the quarter and the year to date under the same+# end date, so a match on the end date alone can report half a year as a quarter.+_SPANS = {"quarterly": (60, 115), "annual": (300, 400)}+++def _user_agent() -> str:+ """Who SEC sees. No account or key exists; callers identify themselves.++ www.sec.gov, which serves the ticker map, refuses a User-Agent carrying no+ contact address: a client name alone or with a project URL gets 403, one+ with an address gets 200. So the default carries a placeholder address and+ the package version. Set SEC_EDGAR_USER_AGENT to your own name and address+ so SEC can reach you about your traffic rather than the project.+ """+ configured = os.getenv("SEC_EDGAR_USER_AGENT", "").strip()+ return configured or f"TradingAgents/{_version()} ([email protected])"+++def _version() -> str:+ """The installed package version, so a release identifies itself correctly."""+ try:+ return metadata.version("tradingagents")+ except metadata.PackageNotFoundError:+ return "dev"+++def _fetch_json(url: str) -> dict:+ """Read a public EDGAR document, respecting SEC's identification rule."""+ try:+ response = requests.get(url, headers={"User-Agent": _user_agent()}, timeout=30)+ response.raise_for_status()+ return response.json()+ except requests.RequestException as exc:+ status = getattr(getattr(exc, "response", None), "status_code", None)+ # Every failure here is "this vendor cannot serve it now", so the router+ # moves on instead of seeing a transport exception it has no rule for.+ raise VendorRateLimitError(f"SEC EDGAR request failed ({status or type(exc).__name__})") from exc+ except ValueError as exc:+ raise VendorRateLimitError("SEC EDGAR returned an unreadable response") from exc+++def _cached_json(url: str, name: str) -> dict:+ path = Path(get_config()["data_cache_dir"]) / "sec_edgar" / name+ if path.exists() and time.time() - path.stat().st_mtime < _CACHE_TTL_SECONDS:+ try:+ return json.loads(path.read_text(encoding="utf-8"))+ except ValueError:+ pass # a truncated file is a miss, not a failure+ data = _fetch_json(url)+ path.parent.mkdir(parents=True, exist_ok=True)+ temp = path.with_suffix(".tmp")+ temp.write_text(json.dumps(data), encoding="utf-8")+ os.replace(temp, path)+ return data+++def cik_for(ticker: str) -> str | None:+ """The filer's CIK, or None when the ticker is not a US filer."""+ table = _cached_json(_TICKERS_URL, "company_tickers.json")+ wanted = ticker.strip().upper()+ for entry in table.values():+ if entry.get("ticker", "").upper() == wanted:+ return f"{int(entry['cik_str']):010d}"+ return None+++def _as_of(facts: dict, tags: tuple[str, ...], curr_date: str, span: tuple[int, int]) -> tuple[dict, str]:+ """({period end: value}, unit) for the first tag the filer reports, as known then.++ A period reported more than once takes its latest filing on or before the+ date, so an amendment counts from the day it was filed and not before. The+ unit comes from the filing: most lines are USD, earnings per share are+ USD/shares, and scaling those alike would print a real figure as zero.+ """+ low, high = span+ values: dict[str, float] = {}+ chosen_unit = "USD"+ # Tags are tried in order and a period keeps the first one that reports it:+ # filers renamed lines over the years, so one tag covers only part of the+ # history. Values are never added across tags, which would double count.+ for tag in tags:+ for unit, unit_values in ((facts.get(tag) or {}).get("units", {})).items():+ latest: dict[str, dict] = {}+ for fact in unit_values:+ if fact["filed"] > curr_date or fact["end"] in values:+ continue+ # A duration fact (revenue, cash flow) must cover the span asked+ # for. An instant fact (a balance) has no span and serves both.+ if "start" in fact:+ days = (date.fromisoformat(fact["end"]) - date.fromisoformat(fact["start"])).days+ if not low <= days <= high:+ continue+ seen = latest.get(fact["end"])+ if seen is None or fact["filed"] >= seen["filed"]:+ latest[fact["end"]] = fact+ if latest:+ chosen_unit = unit+ values.update({end: fact["val"] for end, fact in latest.items()})+ return dict(sorted(values.items())), chosen_unit+++def _statement(kind: str, ticker: str, freq: str, curr_date: str, title: str) -> str:+ curr_date = curr_date or datetime.now().strftime("%Y-%m-%d")+ cik = cik_for(ticker)+ if cik is None:+ raise NoMarketDataError(ticker, ticker, "not a US SEC filer")++ facts = _cached_json(_FACTS_URL.format(cik=cik), f"CIK{cik}.json")+ us_gaap = (facts.get("facts") or {}).get("us-gaap")+ if not us_gaap:+ raise NoMarketDataError(ticker, ticker, "US filer with no us-gaap facts")++ span = _SPANS["quarterly" if freq.lower() == "quarterly" else "annual"]+ lines = {label: _as_of(us_gaap, tags, curr_date, span) for label, tags in _STATEMENTS[kind]}+ periods = sorted({end for values, _ in lines.values() for end in values})+ if not periods:+ raise NoMarketDataError(ticker, ticker, f"no {freq} {title.lower()} filed by {curr_date}")++ header = (+ f"# {title} for {ticker.upper()} ({freq}), USD in millions unless the row says otherwise\n"+ f"# SEC EDGAR facts filed on or before {curr_date}, at the values filed then\n\n"+ )+ rows = [",".join([""] + periods)]+ for label, (values, unit) in lines.items():+ # Every row spans the same columns, or a reader lines the table up wrong.+ if not values:+ rows.append(",".join([label] + ["unavailable (not tagged by this filer)"] * len(periods)))+ continue+ name = label if unit == "USD" else f"{label} ({unit})"+ # Plain numbers: a thousands separator would split the CSV field.+ cells = [+ (f"{values[p] / 1e6:.0f}" if unit == "USD" else f"{values[p]:.2f}")+ if p in values else "" for p in periods+ ]+ rows.append(",".join([name] + cells))+ return header + "\n".join(rows) + "\n"+++def get_balance_sheet(ticker: str, freq: str = "quarterly", curr_date: str | None = None) -> str:+ """Balance sheet as filed on or before ``curr_date``."""+ return _statement("balance_sheet", ticker, freq, curr_date, "Balance Sheet")+++def get_income_statement(ticker: str, freq: str = "quarterly", curr_date: str | None = None) -> str:+ """Income statement as filed on or before ``curr_date``.++ A fourth quarter is never derived: filers report it only inside the annual+ figure, and subtracting three separately filed quarters would invent a number+ with no filing date behind it.+ """+ return _statement("income_statement", ticker, freq, curr_date, "Income Statement")+++def get_cashflow(ticker: str, freq: str = "quarterly", curr_date: str | None = None) -> str:+ """Cash flow statement as filed on or before ``curr_date``."""+ return _statement("cashflow", ticker, freq, curr_date, "Cash Flow Statement")