fix(research): [PR2] get_balance_sheet → fundamentals S3 (R3)

[cipher813]

yfinance-centralization arc — PR 2 (balance-sheet tool → fundamentals S3)

Plan doc: alpha-engine-docs/private/yfinance-centralization-260516.md (item R3, PR 2 — the last HOT research yfinance socket).

Exact change

Rewrote agents/sector_teams/quant_tools.py::get_balance_sheet to read alpha-engine-data's weekly Finnhub fundamentals snapshot from S3 instead of yfinance.Ticker().info; removed the import yfinance as yf from that path (it was the only yfinance ref in the module — quant_tools.py is now yfinance-free for PR2's scope).

• New module-level read_fundamentals_from_s3() — reads archive/fundamentals/{date}.json; with no run_date, scans the prefix and reads the most-recent snapshot. Mirrors the predictor's inference/stages/fetch_alt_data.py read + date-resolution pattern and the in-repo read_factor_profiles_from_s3 S3 helper style.
• Cached once at tool-creation time (one S3 read per sector team per Saturday SF run — same pattern/budget as factor_profiles) via a new fundamentals_data context key (also test-injectable → no S3/network in tests).

Schema-mapping correction (vs the plan doc)

The plan assumed raw Finnhub keys (peTTM, totalDebt/totalEquityAnnual, …) are present in the S3 JSON. They are not — alpha-engine-data/collectors/fundamentals.py persists a normalized/clipped per-ticker schema: {pe_ratio, pb_ratio, debt_to_equity, revenue_growth_yoy, fcf_yield, gross_margin, roe, current_ratio}. I followed the plan's intent (consume the exact S3 key the predictor already reads) and mapped the actual schema onto the tool's existing output keys:

tool output	← data-module key	note
debt_to_equity	debt_to_equity	already a ratio — NO yfinance %/100 scaling (per plan)
current_ratio	current_ratio
pe_ratio	pe_ratio
price_to_book	pb_ratio
revenue_growth	revenue_growth_yoy
gross_margins	gross_margin
forward_pe	— → None	not persisted by the collector
market_cap	— → None	computed transiently for fcf_yield, not persisted

The agent consumes these as soft directional context, not a hard gate (the hard D/E gate R2 is deleted in PR1), so the normalized-scale / trailing-vs-TTM delta is tolerable per the plan's risk note.

Graceful-degrade preserved

Exact return-schema keys unchanged. A ticker absent from the snapshot (or an empty/missing snapshot) returns {"error": ...} per the existing contract — never raises under all-agents-strict (#195). The read_* helper returns None on any S3 failure so the tool degrades rather than propagating. No read that degraded before now raises.

Tests

Added tests/test_get_balance_sheet_s3.py — 8 tests, monkeypatch/fakes, no unittest.mock.patch (per the documented full-suite bleed; mirrors tests/test_held_thesis_strict.py style): mapped schema from a faked fundamentals JSON, D/E not %/100-rescaled, {"error":...} on missing ticker + empty snapshot (no raise), no-yfinance-import assertion, S3-reader scan-for-latest + None-on-failure. Full suite: 1329 passed (1321 baseline + 8 new), 1 pre-existing acceptable failure — tests/test_scoring.py::TestRSIScoring::test_bull_overbought_matches_neutral_post_revert (stale-local-config; passes on CI). Zero new failures.

Deferred

None. Independent of PR1 and PR3 (off origin/main).

---

DEPLOY HELD — research auto-deploys on merge; do not merge until user directs. Part of the yfinance-centralization arc (plan doc alpha-engine-docs/private/yfinance-centralization-260516.md); intended to land before the held Research re-run.

🤖 Generated with Claude Code