Skip to content
Python

feat(dataflows): serve US statements as filed, from SEC EDGAR

Yijia-Xiaof881c4a1115d
diff --git a/.env.example b/.env.example
index 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=high
diff --git a/tests/test_sec_edgar.py b/tests/test_sec_edgar.py
new file mode 100644
index 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.py
index 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_data
from .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_data
diff --git a/tradingagents/dataflows/sec_edgar.py b/tradingagents/dataflows/sec_edgar.py
new file mode 100644
index 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")