Skip to content

"Vibe-Trading: Your Personal Trading Agent"

35.1 KB
Raw Blame
"""Read-only financial-statements tool: three statements + key indicators.

Pulls a single stock's balance sheet, income statement, cash-flow statement, or
key per-period indicators from a market-appropriate public source:

* **A-share** (``.SH`` / ``.SZ`` / ``.BJ``) — Eastmoney's A-share F10 report
  datasets (``RPT_F10_FINANCE_*``), filtered on the dotted ``SECUCODE`` (e.g.
  ``600519.SH``). The legacy Sina ``quotes.sina.cn`` company-finance openapi
  returned a graceful-empty masking an upstream failure, so the A-share path now
  shares the Eastmoney transport with HK.
* **US** (``.US``) — SEC EDGAR companyfacts XBRL, resolved by ticker->CIK.
* **Hong Kong** (``.HK``) — Eastmoney's HK F10 financial-report datasets,
  filtered on the bare ``SECURITY_CODE``; ``indicators`` reads the
  main-indicator dataset.

Eastmoney requests go through :func:`backtest.loaders.eastmoney_client.get_json`
(``host_key="eastmoney"``); SEC requests go through the shared EDGAR client
(``host_key="sec"``).

The tool is read-only and self-contained: ``execute`` returns a JSON-string
envelope and never raises for a recoverable per-request failure — a bad symbol
or a transient HTTP error is reported inside the envelope.
"""

from __future__ import annotations

import json
import logging
from typing import Any

from backtest.loaders import sec_frames
from backtest.loaders import yahoo_client
from backtest.loaders.eastmoney_client import datacenter_rejection, get_json, resolve_secid
from backtest.loaders.sec_edgar_client import cik_for, get_company_facts
from src.agent.tools import BaseTool
from src.tools._result_paging import fit_records

logger = logging.getLogger(__name__)

# --- Eastmoney datacenter report API --------------------------------------

# Eastmoney datacenter report API. The three statements and the main-indicator
# dataset are addressed by report name, which differs by market (A / HK).
_EM_REPORT_URL = "https://datacenter.eastmoney.com/securities/api/data/v1/get"

# (market_prefix_group, statement) -> Eastmoney report name. ``a`` covers the
# mainland exchanges (markets 0/1); ``hk`` covers 116.
_EM_REPORT_NAME: dict[str, dict[str, str]] = {
    "a": {
        "balance": "RPT_F10_FINANCE_GBALANCE",
        "income": "RPT_F10_FINANCE_GINCOME",
        "cashflow": "RPT_F10_FINANCE_GCASHFLOW",
        "indicators": "RPT_F10_FINANCE_MAINFINADATA",
    },
    "hk": {
        "balance": "RPT_HKF10_FN_BALANCE",
        "income": "RPT_HKF10_FN_INCOME",
        "cashflow": "RPT_HKF10_FN_CASHFLOW",
        "indicators": "RPT_HKF10_FN_GMAININDICATOR",
    },
}

# Eastmoney mainland A-share markets (SZ/BJ = 0, SH = 1) and the HK market.
_EM_A_MARKETS = ("0", "1")
_EM_HK_MARKET = "116"

_SEC_CONCEPTS: dict[str, tuple[str, ...]] = {
    "balance": (
        "Assets",
        "AssetsCurrent",
        "CashAndCashEquivalentsAtCarryingValue",
        "Liabilities",
        "LiabilitiesCurrent",
        "LongTermDebtAndFinanceLeaseObligationsCurrentAndNoncurrent",
        "StockholdersEquity",
    ),
    "income": (
        "Revenues",
        "RevenueFromContractWithCustomerExcludingAssessedTax",
        "GrossProfit",
        "OperatingIncomeLoss",
        "NetIncomeLoss",
        "EarningsPerShareBasic",
        "EarningsPerShareDiluted",
    ),
    "cashflow": (
        "NetCashProvidedByUsedInOperatingActivities",
        "NetCashProvidedByUsedInInvestingActivities",
        "NetCashProvidedByUsedInFinancingActivities",
        "PaymentsToAcquirePropertyPlantAndEquipment",
        "CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalentsPeriodIncreaseDecreaseIncludingExchangeRateEffect",
    ),
    "indicators": (
        "Revenues",
        "RevenueFromContractWithCustomerExcludingAssessedTax",
        "NetIncomeLoss",
        "Assets",
        "Liabilities",
        "StockholdersEquity",
        "EarningsPerShareDiluted",
        "WeightedAverageNumberOfDilutedSharesOutstanding",
    ),
}

# --- Shared limits / validation ------------------------------------------

_VALID_STATEMENTS = ("balance", "income", "cashflow", "indicators")
_VALID_PERIODS = ("annual", "quarter")

# Defensive caps so a payload can never blow up the LLM context.
_MAX_PERIODS = 40
_MAX_FIELDS_PER_PERIOD = 200


def _error(message: str) -> str:
    """Build the failure envelope as a JSON string.

    Args:
        message: Human-readable error description.

    Returns:
        A ``{"ok": false, "error": ...}`` JSON string.
    """
    return json.dumps({"ok": False, "error": message}, ensure_ascii=False)


def _truncate_period(record: dict[str, Any]) -> dict[str, Any]:
    """Cap one period's field count so a single record stays context-safe.

    Args:
        record: A flat period dict (field name -> value).

    Returns:
        A new dict with at most :data:`_MAX_FIELDS_PER_PERIOD` items, preserving
        insertion order. The original is never mutated.
    """
    items = list(record.items())
    if len(items) <= _MAX_FIELDS_PER_PERIOD:
        return dict(items)
    return dict(items[:_MAX_FIELDS_PER_PERIOD])


def _cap_periods(periods: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """Cap each period's field count, keeping every period.

    The record count is no longer clipped here: ``execute`` pages whole periods
    against the result-size budget, so clipping at the parser would put the
    older history permanently out of reach of any ``offset``.

    Args:
        periods: Period records as returned by the provider parser.

    Returns:
        A new list of field-capped records, one per input period.
    """
    return [_truncate_period(record) for record in periods]


def _eastmoney_market_group(secid: str) -> str | None:
    """Classify an Eastmoney secid into the ``a`` or ``hk`` report group.

    Args:
        secid: Eastmoney secid (e.g. ``"1.600519"`` or ``"116.00700"``).

    Returns:
        ``"a"``, ``"hk"``, or ``None`` when the market prefix is unrecognized.
    """
    market = secid.split(".", 1)[0]
    if market in _EM_A_MARKETS:
        return "a"
    if market == _EM_HK_MARKET:
        return "hk"
    return None


def _parse_eastmoney_periods(payload: Any) -> list[dict[str, Any]]:
    """Extract period records from an Eastmoney datacenter report payload.

    Eastmoney nests report rows under ``result.data`` as a list of flat dicts.
    Any other shape yields an empty list rather than raising.

    Args:
        payload: Decoded JSON from the datacenter report API.

    Returns:
        A list of flat period dicts (possibly empty).
    """
    if not isinstance(payload, dict):
        return []
    result = payload.get("result")
    data = result.get("data") if isinstance(result, dict) else None
    if not isinstance(data, list):
        return []
    return [row for row in data if isinstance(row, dict)]


def _eastmoney_filter(group: str, code: str, secid: str) -> str:
    """Build the datacenter ``filter`` clause for one market group.

    The A-share F10 datasets key on the dotted ``SECUCODE`` (e.g.
    ``600519.SH``), whereas the HK datasets key on the bare ``SECURITY_CODE``
    carried in the secid (e.g. ``00700``). No ``REPORT_TYPE`` clause
    is emitted: Eastmoney stores ``REPORT_TYPE`` as locale text (年报 / 一季报)
    or a ``2026/Q1`` string that differs by market and report, so a numeric
    filter matched zero rows. Period selection is done client-side instead
    (see :func:`_filter_by_period`).

    Args:
        group: Market group from :func:`_eastmoney_market_group`.
        code: Original Vibe-Trading symbol (e.g. ``"600519.SH"``).
        secid: Resolved Eastmoney secid (e.g. ``"1.600519"``).

    Returns:
        The Eastmoney ``filter`` query-parameter string.
    """
    if group == "a":
        return f'(SECUCODE="{code.upper()}")'
    bare_code = secid.split(".", 1)[1]
    return f'(SECURITY_CODE="{bare_code}")'


def _filter_by_period(
    periods: list[dict[str, Any]], period: str
) -> list[dict[str, Any]]:
    """Best-effort client-side period selection by report date.

    Eastmoney returns a mixed newest-first series (annual + interim reports).
    For ``annual`` we keep only fiscal-year-end rows (``REPORT_DATE`` ending
    ``-12-31``); if none match — e.g. an issuer whose fiscal year does not end
    in December — we fall back to the full series rather than drop all data.
    ``quarter`` returns the full newest-first series unchanged.

    Args:
        periods: Period records (newest-first) from the report parser.
        period: ``"annual"`` or ``"quarter"``.

    Returns:
        The filtered list; never empty when ``periods`` is non-empty.
    """
    if period != "annual":
        return periods
    annual = [
        row
        for row in periods
        if str(row.get("REPORT_DATE", ""))[:10].endswith("-12-31")
    ]
    return annual or periods


def _fetch_eastmoney_statement(
    code: str, *, statement: str, period: str
) -> dict[str, Any]:
    """Fetch one A-share/HK statement from Eastmoney, shaped into a result dict.

    Args:
        code: Symbol (e.g. ``"600519.SH"`` or ``"00700.HK"``).
        statement: One of :data:`_VALID_STATEMENTS`.
        period: ``"annual"`` or ``"quarter"``.

    Returns:
        ``{"periods": [...]}`` on success or ``{"error": ...}`` on failure;
        never raises.
    """
    secid = resolve_secid(code)
    if secid is None:
        return {"error": "unresolvable symbol"}

    group = _eastmoney_market_group(secid)
    if group is None:
        return {"error": "symbol is not an A-share or Hong Kong instrument"}

    params = {
        "reportName": _EM_REPORT_NAME[group][statement],
        "columns": "ALL",
        "filter": _eastmoney_filter(group, code, secid),
        "sortColumns": "REPORT_DATE",
        "sortTypes": "-1",
        "pageNumber": "1",
        "pageSize": str(_MAX_PERIODS),
        "source": "F10",
        "client": "PC",
    }
    try:
        payload = get_json(_EM_REPORT_URL, params=params)
    except Exception as exc:  # noqa: BLE001 - one bad fetch must not kill the call
        logger.warning("eastmoney statement fetch failed for %s: %s", code, exc)
        return {"error": str(exc)}

    rejection = datacenter_rejection(payload)
    if rejection is not None:
        # A stale report or column reads as a rejection, not as no filings (#1502).
        return {"error": f"eastmoney rejected the request: {rejection}"}
    periods = _filter_by_period(_parse_eastmoney_periods(payload), period)
    return {"periods": _cap_periods(periods)}


# Yahoo quoteSummary module + result-key per (statement, cadence). UK
# (.L) names have no Eastmoney or SEC filing pipeline; Yahoo's
# crumb-gated quoteSummary serves annual and quarterly histories for
# LSE tickers (UK parity, #1206).
_YAHOO_STATEMENT_MODULES: dict[tuple[str, str], tuple[str, str]] = {
    ("balance", "annual"): ("balanceSheetHistory", "balanceSheetStatements"),
    ("balance", "quarter"): ("balanceSheetHistoryQuarterly", "balanceSheetStatements"),
    ("income", "annual"): ("incomeStatementHistory", "incomeStatementHistory"),
    ("income", "quarter"): ("incomeStatementHistoryQuarterly", "incomeStatementHistory"),
    ("cashflow", "annual"): ("cashflowStatementHistory", "cashflowStatements"),
    ("cashflow", "quarter"): ("cashflowStatementHistoryQuarterly", "cashflowStatements"),
}
_YAHOO_INDICATOR_MODULES = ["financialData", "defaultKeyStatistics"]
# {raw, fmt, longFmt} value shapes; keep the numeric raw only.
_YAHOO_NUMERIC_KEYS = {"raw", "longFmt", "fmt"}


def _yahoo_value(value: Any) -> Any:
    """Flatten a Yahoo ``{raw, fmt, ...}`` value to plain numbers/integers.

    Args:
        value: A Yahoo quoteSummary value (``{raw, fmt, longFmt}``) or a
            scalar (``str``/``int``/``float``/``bool``/``None``).

    Returns:
        The numeric ``raw`` when present (``None`` when raw is missing), or the
        scalar itself. Text values like ``"2026-08-24"`` pass through.
    """
    if isinstance(value, dict):
        if "raw" in value:
            return value.get("raw")
        return {k: _yahoo_value(v) for k, v in value.items() if k not in _YAHOO_NUMERIC_KEYS}
    return value


def _fetch_yahoo_statement(
    code: str, *, statement: str, period: str
) -> dict[str, Any]:
    """Fetch one UK (.L) statement/indicators from Yahoo quoteSummary.

    Args:
        code: UK symbol (e.g. ``"VOD.L"``).
        statement: One of :data:`_VALID_STATEMENTS`.
        period: ``"annual"`` or ``"quarter"`` — selects the corresponding
            history module; both exist for LSE tickers.

    Returns:
        ``{"periods": [...]}`` on success or ``{"error": ...}`` on failure;
        never raises.
    """
    if statement == "indicators":
        modules = _YAHOO_INDICATOR_MODULES
    else:
        module, key = _YAHOO_STATEMENT_MODULES[(statement, period)]
        modules = [module]
    try:
        result = yahoo_client.get_quote_summary(code, modules)
    except Exception as exc:  # noqa: BLE001 - one bad fetch must not kill the call
        logger.warning("yahoo statement fetch failed for %s: %s", code, exc)
        return {"error": str(exc)}

    if statement == "indicators":
        record: dict[str, Any] = {}
        for module in modules:
            block = result.get(module) or {}
            for field, value in block.items():
                if field == "maxAge":
                    continue
                record[field] = _yahoo_value(value)
        return {"periods": [record]} if record else {"error": "no indicator data"}

    block = result.get(module) or {}
    rows = block.get(key) or []
    periods = []
    for row in rows:
        if not isinstance(row, dict):
            continue
        flat: dict[str, Any] = {}
        for field, value in row.items():
            if field in ("maxAge",):
                continue
            flat[field] = _yahoo_value(value)
        if flat:
            periods.append(flat)
    if not periods:
        return {"error": f"Yahoo returned no {statement} history for {code}"}
    periods.sort(key=lambda row: str(row.get("endDate") or ""), reverse=True)
    return {"periods": _cap_periods(periods)}


# CVM statement codes per requested statement, consolidated first. CVM files
# carry no ratio/indicator block, so "indicators" always comes from Yahoo.
_CVM_STATEMENTS: dict[str, tuple[str, ...]] = {
    "balance": ("BPA", "BPP"),
    "income": ("DRE",),
    "cashflow": ("DFC_MI", "DFC_MD"),
}


def _fetch_cvm_statement(code: str, *, statement: str, period: str) -> dict[str, Any] | None:
    """Read a B3 company's filed statement from the local CVM store.

    The store is filled by ``python -m src.br_data sync`` (DFP annual, ITR
    quarterly). Consolidated statements are preferred; parent-only (``_ind``)
    ones are used when a company files no consolidated set.

    Args:
        code: B3 symbol, e.g. ``"PETR4.SA"``.
        statement: ``balance``, ``income`` or ``cashflow``.
        period: ``"annual"`` (DFP) or ``"quarter"`` (ITR).

    Returns:
        ``{"periods": [...]}`` newest first, each period a flat
        ``{"period_end", "period_start", "<account> <description>": value}``
        record in BRL, or ``None`` when the store, the ticker or the rows are
        missing, so the caller can fall back to Yahoo.
    """
    statements = _CVM_STATEMENTS.get(statement)
    if not statements:
        return None
    try:
        from src.br_data.store import connect

        ticker = code.rpartition(".")[0].strip().upper()
        doc = "DFP" if period == "annual" else "ITR"
        with connect() as conn:
            row = conn.execute(
                "SELECT cnpj FROM cvm_company_tickers WHERE ticker = ?", (ticker,)
            ).fetchone()
            if row is None:
                return None
            rows: list[Any] = []
            for suffix in ("", "_ind"):
                names = [name + suffix for name in statements]
                marks = ",".join("?" for _ in names)
                rows = conn.execute(
                    "SELECT period_end, period_start, account, description, value "
                    f"FROM cvm_statements WHERE cnpj = ? AND doc = ? AND statement IN ({marks}) "
                    "ORDER BY period_end DESC, period_start, account",
                    (row["cnpj"], doc, *names),
                ).fetchall()
                if rows:
                    break
    except Exception as exc:  # noqa: BLE001 - missing store or schema: fall back to Yahoo
        logger.info("cvm statement unavailable for %s: %s", code, exc)
        return None
    if not rows:
        return None
    periods: dict[tuple[str, str], dict[str, Any]] = {}
    for r in rows:
        key = (r["period_end"], r["period_start"])
        record = periods.setdefault(
            key, {"period_end": r["period_end"], "period_start": r["period_start"] or None}
        )
        record[f"{r['account']} {r['description'] or ''}".strip()] = r["value"]
    ordered = sorted(
        periods.values(),
        key=lambda rec: (rec["period_end"], rec["period_start"] or ""),
        reverse=True,
    )
    return {"periods": _cap_periods(ordered), "point_in_time": False,
            "basis": "latest stored CVM revisions"}


def _to_number(value: Any) -> float | None:
    """Coerce a numeric provider cell to float, preserving missing values."""
    if value in (None, "", "-"):
        return None
    try:
        return float(value)
    except (TypeError, ValueError):
        return None


def _pick_sec_unit(units: dict[str, Any]) -> tuple[str, list[Any]]:
    """Pick the SEC XBRL unit bucket with the most reported rows."""
    best_key = ""
    best_rows: list[Any] = []
    for key, rows in units.items():
        if isinstance(rows, list) and len(rows) >= len(best_rows):
            best_key, best_rows = str(key), rows
    return best_key, best_rows


def _sec_instant_matches(row: dict[str, Any], period: str) -> bool:
    """Return whether an instant (balance-sheet) fact belongs in the cadence.

    Instant facts carry no span, so their cadence can only be read off the
    filing they came from: a fiscal-year-end balance sheet is the one reported
    on a 10-K.

    Args:
        row: One SEC ``companyfacts`` unit row with no ``start``.
        period: ``"annual"`` or ``"quarter"``.

    Returns:
        ``True`` when the fact should be kept.
    """
    if period != "annual":
        return True
    fp = str(row.get("fp") or "").upper()
    form = str(row.get("form") or "").upper()
    return fp == "FY" or form == "10-K"


def _record_sec_fact(
    bucket: dict[tuple[Any, Any], dict[str, Any]],
    row: dict[str, Any],
    concept_name: str,
    value: float,
    unit_key: str,
) -> None:
    """Merge one fact into the period record identified by its ``(start, end)``.

    A period is filed once as the primary period and then repeated as a
    comparative in later filings, which may restate it. The earliest filing
    carries the correct fiscal label, the latest carries the current value, so
    both are kept and both dates are surfaced.

    Args:
        bucket: Period records keyed by :func:`sec_frames.frame_key`.
        row: One SEC ``companyfacts`` unit row.
        concept_name: The us-gaap concept this value belongs to.
        value: The parsed numeric value.
        unit_key: The unit bucket the value came from (e.g. ``"USD"``).
    """
    key = sec_frames.frame_key(row)
    filed = str(row.get("filed") or "")
    record = bucket.get(key)
    if record is None:
        days = sec_frames.span_days(row)
        record = bucket[key] = {
            "REPORT_DATE": row.get("end"),
            "PERIOD_START": row.get("start"),
            "PERIOD_DAYS": days,
            "PERIOD_TYPE": sec_frames.classify_span(days),
            "FISCAL_YEAR": row.get("fy"),
            "FISCAL_PERIOD": row.get("fp"),
            "FORM": row.get("form"),
            "ACCESSION": row.get("accn"),
            "FILED": filed or None,
            "LAST_FILED": filed or None,
            "_units": {},
            "_filed": {},
        }
    if filed and filed < (record["FILED"] or filed):
        record["FISCAL_YEAR"] = row.get("fy")
        record["FISCAL_PERIOD"] = row.get("fp")
        record["FORM"] = row.get("form")
        record["ACCESSION"] = row.get("accn")
        record["FILED"] = filed
    if filed > (record["LAST_FILED"] or ""):
        record["LAST_FILED"] = filed
    if filed >= record["_filed"].get(concept_name, ""):
        record["_filed"][concept_name] = filed
        record[concept_name] = value
        record["_units"][concept_name] = unit_key


def _is_additive_unit(unit: Any) -> bool:
    """Whether a fact in ``unit`` sums across quarters to the full year.

    Currency flows do. A weighted-average share count (``shares``) is an
    average over its own period, and a per-share figure (``USD/shares``) is a
    ratio; quarterly EPS need not sum to the annual EPS. Subtracting three
    quarters from the year is meaningless for both, so they are not derived.

    Args:
        unit: SEC XBRL unit bucket; currency flows use three-letter codes.

    Returns:
        Whether the unit has the currency-code shape, excluding dimensionless,
        share-count, per-share and unknown compound units.
    """
    return (isinstance(unit, str) and len(unit) == 3
            and unit.isascii() and unit.isalpha() and unit.isupper())


def _synthesize_fiscal_q4(
    frames: dict[tuple[Any, Any], dict[str, Any]],
    annual_frames: dict[tuple[Any, Any], dict[str, Any]],
) -> None:
    """Derive fiscal Q4 rows, which issuers report only inside the 10-K.

    Flow concepts are never filed as a standalone Q4 duration frame, so without
    this the fourth quarter simply vanishes from a quarterly series. It is
    derived as ``FY - (Q1 + Q2 + Q3)``, the same way
    :mod:`backtest.loaders.fundamentals_loader` derives it for the PIT panel,
    and marked ``DERIVED`` so a computed figure is never mistaken for a filed
    one.

    Args:
        frames: True-quarter period records; synthesized rows are added here.
        annual_frames: Full-year period records used as the raw material.
    """
    quarter_ends = {
        record["REPORT_DATE"]
        for record in frames.values()
        if record["PERIOD_TYPE"] == sec_frames.QUARTER
    }
    for (start, end), annual in annual_frames.items():
        if not start or end in quarter_ends:
            continue
        inside = [
            record
            for record in frames.values()
            if record["PERIOD_TYPE"] == sec_frames.QUARTER
            and record["PERIOD_START"]
            and record["PERIOD_START"] >= start
            and record["REPORT_DATE"] < end
        ]
        if len(inside) != 3:
            continue
        values = {
            concept: annual[concept] - sum(quarter[concept] for quarter in inside)
            for concept, unit in annual["_units"].items()
            if _is_additive_unit(unit) and all(
                concept in quarter and quarter["_units"].get(concept) == unit
                for quarter in inside
            )
        }
        if not values:
            continue
        q4_start = max(quarter["REPORT_DATE"] for quarter in inside)
        filed = max(
            [annual["FILED"] or ""] + [quarter["FILED"] or "" for quarter in inside]
        )
        record = {
            "REPORT_DATE": end,
            "PERIOD_START": q4_start,
            "PERIOD_DAYS": sec_frames.span_days({"start": q4_start, "end": end}),
            "PERIOD_TYPE": sec_frames.QUARTER,
            "FISCAL_YEAR": annual["FISCAL_YEAR"],
            "FISCAL_PERIOD": "Q4",
            "FORM": annual["FORM"],
            "ACCESSION": annual["ACCESSION"],
            "FILED": filed or None,
            "LAST_FILED": filed or None,
            "DERIVED": "FY - (Q1 + Q2 + Q3)",
            "_units": {concept: annual["_units"][concept] for concept in values},
            "_filed": {},
        }
        record.update(values)
        frames[(q4_start, end)] = record


def _merge_sec_instants(
    frames: dict[tuple[Any, Any], dict[str, Any]],
) -> list[dict[str, Any]]:
    """Fold instant facts into the duration period ending on the same day.

    ``indicators`` mixes balance-sheet concepts (instant) with income-statement
    concepts (duration); without merging, one reporting period would come back
    as two half-populated rows.

    Args:
        frames: All period records for the requested cadence.

    Returns:
        One record per reporting period.
    """
    durations = [
        record
        for record in frames.values()
        if record["PERIOD_TYPE"] != sec_frames.INSTANT
    ]
    instants = {
        record["REPORT_DATE"]: record
        for record in frames.values()
        if record["PERIOD_TYPE"] == sec_frames.INSTANT
    }
    if not durations:
        return list(instants.values())
    for record in durations:
        instant = instants.get(record["REPORT_DATE"])
        if instant is None:
            continue
        for concept, unit_key in instant["_units"].items():
            record.setdefault(concept, instant[concept])
            record["_units"].setdefault(concept, unit_key)
    covered = {record["REPORT_DATE"] for record in durations}
    return durations + [
        record for end, record in instants.items() if end not in covered
    ]


def _fetch_sec_statement(code: str, *, statement: str, period: str) -> dict[str, Any]:
    """Fetch one US statement from SEC companyfacts, shaped as flat periods.

    Args:
        code: US symbol with ``.US`` suffix, e.g. ``"AAPL.US"``.
        statement: One of :data:`_VALID_STATEMENTS`.
        period: ``"annual"`` or ``"quarter"``.

    Returns:
        ``{"periods": [...]}`` on success or ``{"error": ...}`` on failure.
    """
    ticker = code.rsplit(".", 1)[0].strip().upper()
    try:
        cik = cik_for(ticker)
    except Exception as exc:  # noqa: BLE001 - surface provider failures as envelope
        logger.warning("SEC ticker lookup failed for %s: %s", code, exc)
        return {"error": f"SEC ticker lookup failed: {exc}"}
    if not cik:
        return {"error": "ticker not found in SEC company table"}

    try:
        facts = get_company_facts(cik)
    except Exception as exc:  # noqa: BLE001 - one bad fetch must not kill the call
        logger.warning("SEC companyfacts fetch failed for %s: %s", code, exc)
        return {"error": f"SEC companyfacts request failed: {exc}"}

    gaap = (facts.get("facts") or {}).get("us-gaap") if isinstance(facts, dict) else None
    if not isinstance(gaap, dict):
        return {"periods": []}

    # Keyed on the ``(start, end)`` span, never on ``end`` alone: a 10-Q files
    # the true quarter and the year-to-date frame under the same end date, and
    # the same fy/fp/form/accn, so any narrower key silently lets one overwrite
    # the other.
    frames: dict[tuple[Any, Any], dict[str, Any]] = {}
    annual_frames: dict[tuple[Any, Any], dict[str, Any]] = {}
    for concept_name in _SEC_CONCEPTS[statement]:
        concept = gaap.get(concept_name)
        units = concept.get("units") if isinstance(concept, dict) else None
        if not isinstance(units, dict):
            continue
        unit_key, rows = _pick_sec_unit(units)
        for row in rows:
            if not isinstance(row, dict):
                continue
            value = _to_number(row.get("val"))
            if not row.get("end") or value is None:
                continue
            kind = sec_frames.classify_span(sec_frames.span_days(row))
            if kind == sec_frames.YTD:
                continue
            if kind == sec_frames.INSTANT:
                if not _sec_instant_matches(row, period):
                    continue
                bucket = frames
            elif kind == sec_frames.ANNUAL:
                # A full year is the annual cadence, and the raw material for a
                # synthesized fiscal Q4 when the cadence is quarterly.
                bucket = frames if period == "annual" else annual_frames
            else:
                if period == "annual":
                    continue
                bucket = frames
            _record_sec_fact(bucket, row, concept_name, value, unit_key)

    if period == "quarter":
        _synthesize_fiscal_q4(frames, annual_frames)

    periods = sorted(
        _merge_sec_instants(frames),
        key=lambda row: str(row.get("REPORT_DATE") or ""),
        reverse=True,
    )
    for record in periods:
        record.pop("_filed", None)
    return {"periods": _cap_periods(periods)}


def _classify_market(code: str) -> str | None:
    """Classify a symbol's suffix into ``a_share``, ``us``, ``hk``, ``uk``, or ``None``.

    Args:
        code: Symbol with a market suffix (e.g. ``"600519.SH"``, ``"AAPL.US"``).

    Returns:
        The market label, or ``None`` when the suffix is unrecognized.
    """
    suffix = code.rpartition(".")[2].strip().upper()
    if suffix in ("SH", "SZ", "BJ", "SS"):
        return "a_share"
    if suffix == "US":
        return "us"
    if suffix == "HK":
        return "hk"
    if suffix == "L":
        # London Stock Exchange (#1206).
        return "uk"
    if suffix == "SA":
        # B3 (Brazil).
        return "br"
    return None


class FinancialStatementsTool(BaseTool):
    """Fetch a stock's three financial statements or key per-period indicators."""

    name = "get_financial_statements"
    description = (
        "Fetch a single stock's financial statements: balance sheet, income "
        "statement, cash-flow statement, or key per-period indicators (margins, "
        "ROE, EPS, etc.). Markets: A-share (.SH/.SZ/.BJ), US (.US), "
        "Hong Kong (.HK), UK LSE (.L) and Brazil B3 (.SA). US uses SEC EDGAR "
        "companyfacts; A-share and HK use Eastmoney; UK uses Yahoo quoteSummary "
        "(annual history); Brazil uses the official CVM DFP/ITR filings from the "
        "local br-data store (values in BRL), falling back to Yahoo. Reports come back newest-first as flat per-period rows. Use "
        'this to read fundamentals before building a valuation or screen. Example: '
        '{"code": "600519.SH", "statement": "income", "period": "annual"}.'
    )
    parameters = {
        "type": "object",
        "properties": {
            "code": {
                "type": "string",
                "description": (
                    "Single symbol with a market suffix, e.g. '600519.SH', "
                    "'000001.SZ', 'AAPL.US', '00700.HK', 'VOD.L', or 'PETR4.SA'."
                ),
            },
            "statement": {
                "type": "string",
                "enum": list(_VALID_STATEMENTS),
                "description": (
                    "Which report to fetch: 'balance' (balance sheet), 'income' "
                    "(income statement), 'cashflow' (cash-flow statement), or "
                    "'indicators' (key per-period indicators)."
                ),
                "default": "indicators",
            },
            "period": {
                "type": "string",
                "enum": list(_VALID_PERIODS),
                "description": (
                    "Reporting cadence: 'annual' (annual reports) or 'quarter' "
                    "(quarterly reports)."
                ),
                "default": "annual",
            },
            "offset": {
                "type": "integer",
                "description": (
                    "Index of the first period to return, newest first; "
                    "defaults to 0. Periods are returned whole and only as many "
                    "as fit one result — read paging.total and paging.next_offset "
                    "in the response and call again to continue."
                ),
            },
        },
        "required": ["code"],
    }

    def execute(self, **kwargs: Any) -> str:
        """Validate inputs, dispatch by market, and return a JSON envelope.

        Args:
            **kwargs: ``code`` (str, required), ``statement`` (one of balance|
                income|cashflow|indicators, default 'indicators'), ``period``
                (annual|quarter, default 'annual').

        Returns:
            A JSON string ``{"ok": true, "market": str, "source": str,
            "statement": str, "period": str, "data": {...}}`` when the fetch
            yields data, ``{"ok": false, "error": ...}`` when validation fails,
            or the same envelope with ``ok: false`` plus a top-level ``error``
            when the per-market fetch failed for every requested code (so a
            nested fetch error is never masked by a top-level ``ok: true``).
        """
        code = kwargs.get("code")
        if not isinstance(code, str) or not code.strip():
            return _error("code must be a non-empty symbol string")
        code = code.strip()

        statement = kwargs.get("statement", "indicators")
        if statement not in _VALID_STATEMENTS:
            return _error(f"statement must be one of {list(_VALID_STATEMENTS)}")

        period = kwargs.get("period", "annual")
        if period not in _VALID_PERIODS:
            return _error(f"period must be one of {list(_VALID_PERIODS)}")

        market = _classify_market(code)
        if market is None:
            return _error(
                "code must carry a supported suffix: .SH/.SZ/.BJ, .US, .HK, .L, or .SA"
            )

        if market == "us":
            result = _fetch_sec_statement(code, statement=statement, period=period)
            source = "sec_edgar"
        elif market == "uk":
            result = _fetch_yahoo_statement(code, statement=statement, period=period)
            source = "yahoo"
        elif market == "br":
            # Official CVM filings (local store) first; Yahoo when not synced
            # yet and for the indicator block CVM does not publish.
            cvm = _fetch_cvm_statement(code, statement=statement, period=period)
            if cvm is not None:
                result, source = cvm, "cvm"
            else:
                result = _fetch_yahoo_statement(code, statement=statement, period=period)
                source = "yahoo"
        else:
            result = _fetch_eastmoney_statement(
                code, statement=statement, period=period
            )
            source = "eastmoney"

        # The fetch failed for every requested code (here, the single ``code``)
        # iff its result carries an ``error``. Surface that as a top-level
        # ``ok: false`` so a nested failure is never masked by ``ok: true``.
        if "error" in result:
            return json.dumps(
                {
                    "ok": False,
                    "market": market,
                    "source": source,
                    "statement": statement,
                    "period": period,
                    "data": {code: result},
                    "error": result["error"],
                },
                ensure_ascii=False,
            )

        try:
            offset = max(int(kwargs.get("offset") or 0), 0)
        except (TypeError, ValueError):
            return _error("offset must be an integer")

        # Page whole periods. A raw character cut lands mid-record, and the
        # model reads the periods that survived as the issuer's full history.
        periods = result.get("periods") or []

        def _build(page: list[dict[str, Any]], paging: dict[str, Any]) -> dict[str, Any]:
            return {
                "ok": True,
                "market": market,
                "source": source,
                "statement": statement,
                "period": period,
                "paging": paging,
                "data": {code: dict(result, periods=page)},
            }

        return fit_records(periods, offset, _build, max_records=_MAX_PERIODS)