docs/api_contract.md

IFRS 9 ECL Copilot — API v2 Contract

THIS FILE IS THE SINGLE SOURCE OF TRUTH. The UI author codes ONLY against the exact request/response JSON shapes documented here — never against main.py source, never against a guess. If a field the UI needs is missing from this file, that is an API bug: extend this contract first, then the endpoint, then tests/test_contract.py, in that order. (Lesson recorded from the Day-4 UI/API seam bug: the two were built in parallel against imagined shapes and drifted.)

Every example below is a REAL response captured from the running app (warm engine state, adopted 25/50/25 scenario weights), not an invented placeholder. Numbers will drift slightly only if the frozen engine/model inputs change; field names and types will not.

Conventions

• Base URL: same-origin (app/api/main.py serves both the API and the built SPA on one origin — no CORS anywhere). All paths below are relative to that origin, e.g. GET /api/ecl/summary.
• Money fields: every dollar amount in every response is a raw USD float (e.g. 34046377.82), NEVER pre-divided into millions. The response also carries "amounts_in": "USD" wherever a payload has money fields, as a machine-checkable reminder. The UI divides by 1e6 itself to render "$34.0m" — do not expect the API to do this. The one place a pre-formatted $34.0m-style string appears is inside a headline / caption / narration string, which is display-only prose, never parsed back into a number by the UI.
• Percent fields: fields named *_pct or coverage (a ratio, e.g. 0.0203 = 2.03%) — check the field name; coverage/jensen_ratio are ratios in [0, ~2], not already-multiplied-by-100 percentages, while *_pct fields (e.g. share_of_book_allowance_pct, stage2_share_pct) ARE already in the 0–100 range. This is called out per-endpoint below. When in doubt: the field's own name and the worked example settle it. This api_contract file must call it out; it does not need to be memorised because every field's convention is written next to it below.
• Errors: malformed request bodies/params → 422 with {"detail": [...]} (FastAPI/pydantic validation errors) BEFORE any engine code runs. Unknown routes → 404. One-at-a-time /api/agent/ask contention → 429. A missing prerequisite exhibit file → 503.
• Static exhibits: every PNG referenced by a png_url / image_url field is served read-only at /static/exhibits/<relative-path-under-outputs/> (e.g. /static/exhibits/hazard/age_baseline.png == outputs/hazard/age_baseline.png). Fetch it directly with <img src>.

---

1. Engine data views (existing, unchanged by this doc — reproduced here

because this file must cover EVERY endpoint the v2 UI consumes)

GET /api/health

No params. Liveness + warm-up timing.

{
  "status": "ok",
  "engine_warm": true,
  "warm_up_seconds": 4.73,
  "agent": "fallback"
}

agent is "langgraph" once the Day-4 router is resolved, else "fallback" (deterministic keyword router, offline).

GET /api/ecl/summary

No params. Headline stats + scenario table for the dashboard header (Executive Overview tab).

{
  "as_of": {"t": 60, "period": "2015Q1"},
  "n_loans": 7849,
  "balance": 1673746502.62,
  "weights": {"up": 0.25, "base": 0.5, "down": 0.25},
  "weighted_allowance": 34046377.82,
  "coverage": 0.02034141834854155,
  "allowance_at_average_path": 32886316.29,
  "jensen_ratio": 1.0352749002351027,
  "stage_mix": {
    "stage1": {"n_loans": 7803, "allowance": 27489620.86,
               "allowance_pct_of_total": 80.74169008498012},
    "stage2": {"n_loans": 3, "allowance": 486590.04,
               "allowance_pct_of_total": 1.429197669792072},
    "stage3": {"n_loans": 43, "allowance": 6070166.92,
               "allowance_pct_of_total": 17.829112245227805}
  },
  "scenarios": [
    {"name": "up", "weight": 0.25, "allowance": 27689413.56,
     "coverage": 0.01654337351589052, "zbar_13q": -0.8489346059784133,
     "uer_peak_pp": 6.388333333333333},
    {"name": "base", "weight": 0.5, "allowance": 30454080.65,
     "coverage": 0.018195157150911207, "zbar_13q": -0.8788198475771632,
     "uer_peak_pp": 6.388333333333333},
    {"name": "down", "weight": 0.25, "allowance": 47587936.42,
     "coverage": 0.02843198557645327, "zbar_13q": -1.5489269149154279,
     "uer_peak_pp": 11.2}
  ],
  "amounts_in": "USD"
}

coverage and jensen_ratio are ratios (not *_pct). stage_mix.*.allowance_pct_of_total IS already 0–100.

GET /api/ecl/waterfall?t0=20&t1=40

Query params t0, t1 (ints, 1 <= t0 < t1 <= 60; default 20, 40). Movement decomposition between two rung-1 snapshots.

{
  "tool": "decompose_waterfall",
  "t0": 20, "t1": 40,
  "period_t0": "2005Q1", "period_t1": "2010Q1",
  "opening_allowance": 24538544.76,
  "closing_allowance": 1032613371.19,
  "components": [
    {"component": "opening", "amount": 24538544.76, "n_loans": 8662, "kind": "level"},
    {"component": "stage_migration", "amount": 3879319.76, "n_loans": 498, "kind": "delta"},
    {"component": "remeasurement", "amount": 26010644.52, "n_loans": 1948, "kind": "delta"},
    {"component": "derecognitions", "amount": -21177011.65, "n_loans": 6714, "kind": "delta"},
    {"component": "new_loans", "amount": 999361873.81, "n_loans": 11915, "kind": "delta"},
    {"component": "closing", "amount": 1032613371.19, "n_loans": 13863, "kind": "level"}
  ],
  "identity_gap": 0.0,
  "amounts_in": "USD",
  "headline": "allowance waterfall t=20 (2005Q1) -> t=40 (2010Q1): opening $24.5m, stage migration +3.9m, remeasurement +26.0m, derecognitions -21.2m, new loans +999.4m, closing $1,032.6m",
  "tool_call_id": "tc-000001"
}

components where kind == "delta" sum exactly to closing_allowance - opening_allowance (identity_gap ~ 0). Bad params (inverted/out-of-range/non-int t0/t1) → 422.

GET /api/exhibits/credit_cycle

No params. The recovered credit-cycle series (Z_t) with calendar labels.

{
  "rho": 0.02270852403709047,
  "n_quarters": 60,
  "points": [
    {"t": 1, "calendar": "2000Q2", "z": 1.05067609,
     "observed_dr": 0.01060071, "ttc_pd": 0.01701426, "pit_pd": 0.0082523},
    {"t": 2, "calendar": "2000Q3", "z": 1.33658745,
     "observed_dr": 0.0094518, "ttc_pd": 0.01703656, "pit_pd": 0.0073204}
  ]
}

(60 points total, t=1..60.)

POST /api/tools/{shock_macro|reweight_scenarios|rerun_ecl|decompose_waterfall}

The four Tier-1 tools, pydantic-guarded (bad args → 422 before the engine runs; nothing bad is ever logged to the audit trail). Bodies/shapes are unchanged from Day 4 — reproduced here for completeness.

POST /api/tools/shock_macro body {"var": "UER", "shock": 2.0} (optional "shape": "parallel"|"peak_revert", default "parallel"):

{
  "tool": "shock_macro", "var": "UER", "shock": 2.0, "shape": "parallel",
  "shock_units": "percentage points on the unemployment level",
  "applied_peak_deltas_pp": {"uer": 2.0, "hpi_growth": -0.8258713077987423,
                            "gdp_growth": -0.10903259391827495},
  "baseline_allowance": 30454080.65, "shocked_allowance": 31694012.25,
  "delta": 1239931.6, "delta_pct": 4.071479338705607,
  "baseline_coverage": 0.018195157150911207, "coverage": 0.018935969214955575,
  "stage_mix": {"stage1": {"n_loans": 7803, "allowance": 25138208.67,
                           "allowance_pct_of_total": 79.31532452794009},
               "stage2": {"n_loans": 3, "allowance": 485636.66,
                         "allowance_pct_of_total": 1.532266274180116},
               "stage3": {"n_loans": 43, "allowance": 6070166.92,
                         "allowance_pct_of_total": 19.15240919787979}},
  "waterfall_vs_baseline": [ /* same 6-row shape as /api/ecl/waterfall */ ],
  "amounts_in": "USD",
  "headline": "UER +2pp (parallel) coherent shock of the base scenario: reported allowance $30.5m -> $31.7m (delta +1.2m, +4.1%), shocked coverage 1.89%",
  "tool_call_id": "tc-000002"
}

POST /api/tools/reweight_scenarios body {"w_up": 0.25, "w_base": 0.5, "w_down": 0.25} (must sum to 1 within 1e-6) → {weights, per_scenario, weighted_allowance, allowance_at_average_path, jensen_ratio, coverage, adopted_weights, adopted_weighted_allowance, delta_vs_adopted_pct, amounts_in, headline, tool_call_id} (delta_vs_adopted_pct is already 0–100-scale).

POST /api/tools/rerun_ecl body {"segment": "stage3"} (one of all, stage1, stage2, stage3, investor, high_ltv, default all) → {tool, segment, segment_definition, weights, n_loans, balance, weighted_allowance, coverage, share_of_book_allowance_pct, per_scenario_allowance, stage_mix, amounts_in, headline, tool_call_id}.

POST /api/tools/decompose_waterfall body {"t0": 20, "t1": 40} → same shape as GET /api/ecl/waterfall.

POST /api/agent/ask

Body {"question": "..."} (1–2000 chars, extra="forbid") → {"answer": str, "route": str, "mode": str, "trace": [{"node": ..., ...}, ...]}. route is one of the six tool/retriever names, "REASONED", or a refusal spelling ("REFUSE" from the live LangGraph router, "refusal" from the offline fallback router — match either, case-insensitively). 429 if another question is mid-flight (single-worker demo limit).

mode (added additively; every prior field is unchanged) is the UI's status-indicator classification of answer:

mode	when	UI status word (§5.5)
"grounded"	a numeric tool ran, or the cited docs retriever (query_model_docs) answered	GROUNDED
"reasoned"	the REASONED route — a cited, number-disciplined LLM interpretation grounded in retrieved passages + the engine's own baseline snapshot, but NOT a fresh engine computation	REASONED
"refusal"	the question was out of scope	OUT OF SCOPE

Every "reasoned" answer's answer string is ALSO prefixed with the literal marker "[REASONED — interpretation, not engine output] " — a second, redundant signal (never the UI's only one; branch on mode, treat the prefix as display text like any other narration) in case the answer is ever rendered somewhere that has only the raw string.

GET /api/agent/stream

No params. text/event-stream SSE: replays the most recent /ask trace, then streams live events as data: {...}\n\n JSON lines, with : keep-alive comments every 15s.

Trace event shape (same dicts as POST /api/agent/ask's trace array; the UI must key off node, not any other field): every event is a JSON object with a "node" string — one of "router", "narrator", "REASONED", "refusal", or a tool name ("shock_macro", "reweight_scenarios", "rerun_ecl", "decompose_waterfall", "query_model_docs", "analyze_data"; the offline fallback router emits the generic "tool") — plus node-dependent optional fields. The ones the UI may render:

field	on	meaning
ts	live router events	ISO-8601 UTC timestamp
route, args, model, detail	router	chosen route + validated args
status ("ok"/"error"), tool_call_id, headline, detail	tool nodes	execution outcome
mode, model, number_check_passed / citation_check_passed	narrator	grounding-check outcome (a PER-EVENT diagnostic — "llm" / "template_*" — distinct from the top-level response's mode field above, which classifies the whole answer for the UI status indicator)
mode, model, number_check_passed, attempts	"REASONED"	same per-event diagnostic, plus "llm_repaired" when the one regeneration attempt fixed an ungrounded number
message / answer	refusal, fallback events	display text
label, tool, answer	fallback-router events	display text
_id	every streamed event	monotonic replay-dedup id (ignore)

No event field is ever parsed back into a number by the UI — trace text is display-only.

---

2. NEW: The Model tab

GET /api/model/coefficients

Hazard-ratio families parsed from outputs/hazard/hazard_ratios.md, plus fit statistics from outputs/hazard/fit_stats.md. No params.

{
  "models": {
    "default": {
      "n_fit": 418418, "events": 11354, "mcfadden_r2": 0.0761,
      "coefficients": [
        {"variable": "Intercept", "family": "baseline", "hazard_ratio": 0.2658,
         "ci": [0.1534, 0.4608], "p": 2.35e-06, "p_display": "2.35e-06",
         "story": "Seasoning: hazard climbs over the first ~2-3 years on book, then burns out (spline coefficients are basis weights, not individually interpretable -- see age_baseline.png)."},
        {"variable": "FICO at orig. (per 100 pts)", "family": "borrower",
         "hazard_ratio": 0.6314, "ci": [0.613, 0.6505],
         "p": 1e-16, "p_display": "<1e-16",
         "story": "Borrower quality: cleaner credit at origination defaults less; investors walk away from underwater rentals faster than owner-occupiers.",
         "unit_meaning": "1 unit = 100 points of FICO score at origination (fico_s = FICO_orig_time / 100).",
         "transformation": "level, static at origination, scaled /100",
         "lag": "static (origination) -- no lag, not time-varying",
         "fred_series": null,
         "economic_channel": "Ability/willingness-to-pay channel: cleaner credit history at origination signals lower baseline default propensity, independent of the macro cycle.",
         "hazard_ratio_per_unit": 0.6314,
         "worked_example": "+100 FICO points => hazard x 0.6314 (-36.9%, a 36.9% decrease in the monthly/quarterly default hazard)."}
        /* ... 13 rows total for "default": Intercept, FICO, Updated LTV,
           Rate incentive, Investor loan, Condo, Planned urban dev.,
           Single family, Unemployment level (lag 1), Unemployment 4q
           change (lag 1), HPI growth (lag 1), GDP growth (lag 1),
           DOUBLE TRIGGER: LTV(10pp) x UER (centered) */
      ]
    },
    "prepay": {
      "n_fit": 418418, "events": 22734, "mcfadden_r2": 0.0503,
      "coefficients": [ /* same 13-row shape, prepayment-hazard values */ ]
    }
  },
  "fit_stats": {
    "default": {"n_fit": 418418, "events": 11354, "train_auc": 0.7476,
               "oot_auc": 0.6609, "mcfadden_r2": 0.0761},
    "prepay": {"n_fit": 418418, "events": 22734, "train_auc": 0.6839,
              "oot_auc": 0.5841, "mcfadden_r2": 0.0503},
    "seasoning_peak": {"fitted_q": 12, "empirical_q": 10, "tolerance_q": 8,
                       "plausible_window_q": [4, 18]},
    "net_uer_effect_note": "A 1pp labour-market shock moves the unemployment level and its 4-quarter change one-for-one, so its hazard effect at mean LTV is beta(uer_lag1) + beta(uer_chg4_lag1) = -0.3668 + +0.6135 = +0.2467 (hazard ratio 1.280 per pp) -- PD RISES in unemployment. The negative level coefficient in isolation is the level-vs-momentum decomposition under 0.94 collinearity, not an economic sign.",
    "double_trigger_note": "beta(centered ltv10 x centered uer_lag1) = -0.00597 (p = 3.75e-02, significant at 5%; identical to the uncentered x*y coefficient -- centering only reparametrises the main effects). Negative: the LTV slope flattens slightly at high unemployment -- in-sample the two triggers partially substitute (the main effects and momentum term already carry the joint stress response, and the worst-LTV loans default early in the stress window). Reported either way, per spec. Marginal LTV effect per 10pp: +0.2029 at mean UER (5.6%); +0.1766 at UER 10%."
  },
  "source_files": ["outputs/hazard/hazard_ratios.md", "outputs/hazard/fit_stats.md"]
}

Field notes:

• models.{default,prepay}.coefficients[].family is one of baseline, borrower, collateral, macro, incentive — story is that family's narrative (repeated per row for the family, so the UI never needs a second lookup to group-and-annotate).
• p is always a float: for a table cell like <1e-16 it is the numeric bound 1e-16 (use p_display — the original string, e.g. "<1e-16" or "2.35e-06" — for display; never format p yourself and claim exactness beyond the bound).
• ci is [low, high].
• hazard_ratio > 1 = risk-increasing; < 1 = risk-reducing (it is exp(coef) of a cloglog hazard).

Requirement 12 interpretation fields (every coefficient row, both default and prepay, all 13 rows) — content curated/transcribed from outputs/variable_dictionary.md + outputs/hazard/hazard_ratios.md, the two computed numbers (hazard_ratio_per_unit, worked_example) derived mechanically from the row's own hazard_ratio/coef, never hand-typed:

• unit_meaning (string) — what "1 unit" of this covariate actually is (e.g. "100 points of FICO", "10pp of updated LTV", "1pp of national UER level").
• transformation (string) — the exact source-column transform (level / delta / log-growth / static flag / spline / interaction).
• lag (string) — the lag window and, for the two documented current-period exceptions (ltv10, prepay_incentive), a note why.
• fred_series (string, always null on this endpoint) — the DCR panel's macro columns (UER, HPI, GDP) are a vendor-premerged national series on the panel's own ANONYMIZED quarterly clock (data/panel/build_panel.py: "macros pre-merged"), not a live FRED pull, so no FRED series id is claimed here. The clock's CALENDAR alignment to real quarters was independently verified via correlation against FRED UNRATE (corr 0.996) — an anchoring check, not a sourcing claim (see each macro row's transformation text for the citation). Genuinely FRED-sourced rows (state UER/HPI, live-pulled by freddie/macro.py) carry a real id on GET /api/freddie/hazard below.
• economic_channel (string) — the one-paragraph causal story (labour- income / collateral-equity / refinancing-incentive / strategic-default channel), including a stated MISS where the fit disagrees with the prior (never smoothed over).
• hazard_ratio_per_unit (float, nullable) — exp(beta · unit_delta) for the row's OWN economically-legible unit. For the two log-growth macro rows (HPI growth (lag 1) in both models) this is NOT the same number as hazard_ratio — the table's hazard_ratio is scaled to a full 1.0 log-unit (~100% quarterly growth, never observed); hazard_ratio_per_unit is the same coefficient re-expressed per 1% growth (hazard_ratio ** 0.01) — the classic 0.01-vs-1pp misread this field exists to prevent. null for the DOUBLE TRIGGER interaction row (a per-unit read of a product term is misleading — see worked_example / fit_stats.double_trigger_note instead).
• worked_example (string) — one computed sentence, e.g. "+1pp of national UER level => hazard x 0.6930 (-30.7%, a 30.7% decrease in the monthly/quarterly default hazard)." For categorical rows (Investor loan, Condo, …) it reads "A loan that is X => hazard x HR (…% higher/lower than the reference)." For the Intercept it reads as a baseline-multiplier sentence. For the DOUBLE TRIGGER interaction row a single per-unit number would mislead (it is a product term), so the string instead points at fit_stats.double_trigger_note for the marginal-effect decomposition — always a string, never null, on rows that carry a coefficient at all (see /api/model/variable_dictionary below for the 4 rows that carry none).

GET /api/model/variable_dictionary

Parsed from outputs/variable_dictionary.md. No params.

{
  "preamble": "Data window: panel quarters t=1..60 ≙ **2000Q2–2015Q1** (calendar anchoring verified vs FRED UNRATE, corr 0.996).\nTrain = t≤40 (2000Q2–2010Q1); OOT = t=41–60 (2010Q2–2015Q1, the stress aftermath). All fits on train only.\nMacro series are US **national** (state-level upgrade = Freddie rung 3). Timing convention: every macro\n*regressor* is lagged; the two deliberate current-quarter **state variables** are flagged ⚡ below.",
  "rows": [
    {"variable": "`fico_s`", "source_transformation": "`FICO_orig_time` / 100",
     "lag_window": "static (origination)",
     "economic_rationale": "Ability/willingness to pay",
     "expected_sign": "PD ↓", "fitted_verified": "✓ negative",
     "consumed_by": "default hazard; LGD cure"},
    {"variable": "`ltv10` ⚡",
     "source_transformation": "`updated_ltv`/10 = LTV_orig × (bal_t/bal_orig) × (hpi_orig/hpi_t), winsor 300",
     "lag_window": "current-quarter state (collateral indexation, documented exception)",
     "economic_rationale": "Equity cushion / strategic-default trigger; = vendor `LTV_time` to 5e-9",
     "expected_sign": "PD ↑, severity ↑, cure ↓",
     "fitted_verified": "✓ all three (sev +0.107/10pp, cure −0.764)",
     "consumed_by": "default hazard; LGD both stages; staging legs",
     "unit_meaning": "1 unit = 10 percentage points of updated LTV (ltv10 = updated_ltv / 10; updated_ltv winsorised at 300%).",
     "transformation": "updated_ltv = LTV_orig x (balance_t/balance_orig) x (hpi_orig/hpi_t) -- a documented CURRENT-period exception to the lag convention, because collateral value is a real-time state, not a forecast.",
     "lag": "current period (documented exception, flagged with a lightning-bolt in the variable dictionary)",
     "fred_series": null,
     "economic_channel": "Collateral / negative-equity channel: as updated LTV rises the borrower's equity cushion shrinks, removing both the option to sell out of trouble and (past 100% LTV) adding a strategic-default incentive.",
     "hazard_ratio_per_unit": 1.225,
     "worked_example": "+10pp of updated LTV => hazard x 1.2250 (+22.5%, a 22.5% increase in the monthly/quarterly default hazard)."}
    /* ... 13 rows total, in file order: fico_s, ltv10, loan_age,
       prepay_incentive, investor/RE-type flags, uer_lag1, uer_chg4_lag1,
       hpi_growth_lag1, gdp_lag1/gdp_growth_lag2, dt_ltv_uer,
       lgd_time (target), Z_t (recovered), Scenario paths */
  ],
  "notes": "Model equations live in the module docstrings (cloglog hazard; two-stage LGD; ECL sum; Vasicek PIT\ntransform with the Gauss-Hermite anchor proof; satellite Z = −1.694 + 13.642·hpi_growth_lag1 +\n0.730·gdp_growth_lag2, n=57, with ADF/KPSS/DW/AIC and the GFC-dummy sensitivity in\noutputs/satellite/satellite_report.md). Coefficient tables with CIs: outputs/hazard/hazard_ratios.md,\noutputs/lgd/lgd_report.md."
}

rows[].* original keys (variable, source_transformation, lag_window, economic_rationale, expected_sign, fitted_verified, consumed_by) are all strings (raw source cells, including the ✓/⚡/↑/↓ glyphs and backtick-quoted variable names — the UI renders them as-is, markdown-lite).

Requirement 12 interpretation fields, joined onto every row (same unit_meaning / transformation / lag / fred_series / economic_channel / hazard_ratio_per_unit / worked_example shape as /api/model/coefficients above, described there field-by-field — including fred_series always being null here too, for the same reason: every row on this endpoint is a DCR/national concept, never a live FRED pull): the hazard-ratio-bearing fields are reused from the DCR default-hazard table, never re-derived, so the two exhibits cannot silently disagree. Four rows have no hazard ratio at all and get hazard_ratio_per_unit: null, worked_example: null (still carry unit_meaning/transformation/economic_channel): loan_age (spline basis, not individually interpretable), `lgd_time` (target) (an LGD target, not a hazard regressor), `Z_t` (recovered) (the satellite's dependent variable, not a regressor), and Scenario paths (a set of forward paths, not one coefficient). A fifth row, `dt_ltv_uer`, DOES carry a hazard ratio but still gets hazard_ratio_per_unit: null — it is the same DOUBLE TRIGGER interaction term as /api/model/coefficients above, and a per-unit read of a product term would mislead the same way there; worked_example stays a non-null string pointing at fit_stats.double_trigger_note.

GET /api/model/macro_glossary

NEW (Requirement 12). Every macro series used anywhere in the app — DCR (national), SFLLD (state, Freddie rung 3), and the satellite Z regression — one entry per (series, model) pairing where the transformation or lag genuinely differs. Curated from outputs/variable_dictionary.md, outputs/hazard/hazard_ratios.md, outputs/freddie/hazard/hazard_report.md, outputs/satellite/satellite_report.md and freddie/macro.py's docstrings. No params.

{
  "series": [
    {"id": "dcr_uer_level", "label": "National UER -- level",
     "fred_series": null, "geography": "US national",
     "frequency": "monthly (matched to the panel's quarterly clock)",
     "transformation": "level (pp)", "lag": "1 quarter",
     "lag_rationale": "Publication-lag realism + the model's own timing convention: only past values (t-k, k>=1) are ever referenced, so scoring never looks ahead. NOT a live FRED pull -- vendor-premerged on the DCR panel's anonymized clock; only the clock's calendar alignment was verified against FRED UNRATE (corr 0.996).",
     "which_models": ["DCR default hazard"]},
    "... 9 more rows: dcr_uer_momentum, dcr_hpi_growth, dcr_gdp_growth,",
    "sflld_uer_level, sflld_uer_momentum, sflld_hpi_growth,",
    "satellite_hpi_growth, scenario_paths, coherent_shock_convention",
    "(10 rows total) ..."
  ],
  "source_files": ["outputs/variable_dictionary.md", "outputs/hazard/hazard_ratios.md",
                   "outputs/freddie/hazard/hazard_report.md", "outputs/satellite/satellite_report.md",
                   "freddie/macro.py"]
}

Field notes:

• id (string) — stable row key, e.g. dcr_uer_level, sflld_hpi_growth.
• fred_series (string, nullable) — the FRED series ID, populated ONLY for the two SFLLD/state rows that are genuinely live-pulled from FRED by freddie/macro.py: {POSTAL}UR, {POSTAL}STHPI (a literal {POSTAL} template, not a specific state — FRED mints one series per state postal code). null for every dcr_* and satellite_hpi_growth row (the DCR panel's macro columns are a vendor-premerged national series on an ANONYMIZED clock, not a live FRED pull — only the clock's calendar alignment was checked against FRED UNRATE, see each row's lag_rationale) and for the two non-series rows: scenario_paths (a DFAST supervisory-scenario CSV pull, not a FRED series) and coherent_shock_convention (a modelling-convention note, not a series at all).
• which_models (array of strings) — every consumer, e.g. ["DCR default hazard", "DCR prepayment hazard"], ["DCR default hazard", "satellite (Z regression)"] (GDP growth is the one series consumed at two different lags by two different models — lag/lag_rationale state both).
• coherent_shock_convention is the one entry with no series-level facts (fred_series/geography/frequency/lag are all n/a or null): it documents that the satellite is Z = f(hpi_growth_lag1, gdp_growth_lag2) with no unemployment term (sign-governance excluded it — every spec pairing duer with gdp_growth fit a wrong-signed, collinearity-driven duer coefficient), so shock_macro projects any univariate agent shock onto the DFAST severe-minus-base direction to still reach Z. Matches wiki/pages/agent-layer.md's "THE COHERENT-SHOCK CONVENTION" note — reported here for the UI, not duplicated logic.

GET /api/model/lgd

Key numbers + exhibit paths parsed from outputs/lgd/lgd_report.md. No params.

{
  "cure_rate": 0.122,
  "cure_auc": {"train": 0.837, "oot": 0.769},
  "excess_loss_loading": 0.0255,
  "oot_calibration": {
    "mean_realised_lgd": {"train": 0.5995, "oot": 0.6113},
    "mean_predicted_lgd": {"train": 0.599, "oot": 0.6583},
    "gap_pred_minus_real": {"train": -0.0005, "oot": 0.0471},
    "cure_rate_realised": {"train": 0.1224, "oot": 0.0716},
    "cure_rate_predicted": {"train": 0.1224, "oot": 0.0499},
    "mean_sev_noncure_realised": {"train": 0.6825, "oot": 0.6581},
    "mean_sev_noncure_predicted": {"train": 0.6825, "oot": 0.6926},
    "decile_mae_lgd": {"train": 0.0203, "oot": 0.0571}
  },
  "cure_stage_coefficients": [
    {"variable": "Intercept", "coef": 4.4489, "se": 0.3402, "z": 13.0783,
     "p": 0.0, "odds_ratio": 85.5337},
    {"variable": "ltv10", "coef": -0.764, "se": 0.0252, "z": -30.2588,
     "p": 0.0, "odds_ratio": 0.4658},
    {"variable": "uer_lag1", "coef": 0.2774, "se": 0.0334, "z": 8.3086,
     "p": 0.0, "odds_ratio": 1.3197},
    {"variable": "fico_s", "coef": -0.1402, "se": 0.0555, "z": -2.528,
     "p": 0.0115, "odds_ratio": 0.8692},
    {"variable": "loan_age", "coef": -0.0727, "se": 0.0064, "z": -11.4393,
     "p": 0.0, "odds_ratio": 0.9299}
  ],
  "severity_stage_coefficients": [
    {"variable": "Intercept", "coef": 1.4274, "se_hc1": 0.1347, "z": 10.601, "p": 0.0},
    {"variable": "ltv10", "coef": 0.1074, "se_hc1": 0.0082, "z": 13.1763, "p": 0.0},
    {"variable": "uer_lag1", "coef": -0.0416, "se_hc1": 0.0104, "z": -4.0031, "p": 0.0001},
    {"variable": "fico_s", "coef": -0.2532, "se_hc1": 0.0202, "z": -12.5228, "p": 0.0},
    {"variable": "loan_age", "coef": 0.0093, "se_hc1": 0.0036, "z": 2.5417, "p": 0.011}
  ],
  "exhibits": [
    {"id": "lgd_calibration_ltv", "png_url": "/static/exhibits/lgd/calibration_ltv.png"},
    {"id": "lgd_cure_by_ltv", "png_url": "/static/exhibits/lgd/cure_by_ltv.png"},
    {"id": "lgd_distribution", "png_url": "/static/exhibits/lgd/lgd_distribution.png"}
  ]
}

cure_rate is a ratio (0.122 = 12.2%). p here is the raw table value (already rounded to 4dp in the source; 0.0 means "< 0.00005", not literally zero).

---

3. NEW: The Policy tab

GET /api/policy/staging_sensitivity

The SICR ratio-threshold vs Stage-2-share governance curve, parsed from outputs/staging/staging_report.md. No params.

{
  "add_on_pp": 0.5,
  "thresholds": ["1.5x", "2.0x", "3.0x", "4.0x"],
  "rows": [
    {"t": 20, "period": "2005Q1",
     "stage2_share_pct": {"1.5x": 0.0, "2.0x": 0.0, "3.0x": 0.0, "4.0x": 0.0}},
    {"t": 40, "period": "2010Q1",
     "stage2_share_pct": {"1.5x": 85.1, "2.0x": 75.76, "3.0x": 30.25, "4.0x": 3.32}}
  ],
  "reading": "in the calm quarter the relative test stages (almost) nobody at any threshold -- deterioration since origination simply has not happened -- while in the stress quarter the doubling convention (2x) moves roughly three quarters of the live book to lifetime ECL, and the choice between 2x and 4x swings the Stage-2 population by tens of percentage points of the book. The threshold is the single loudest governance dial in the impairment estimate (notes section 2.2 pitfall).",
  "image_url": "/static/exhibits/staging/stage2_sensitivity.png"
}

stage2_share_pct values are already 0–100 (percent, not a ratio). The governance decision this exhibit informs (pairs "exhibit ↔ decision", per the Policy tab's design mandate): which multiple of origination PD triggers Stage 2 — the 2.0x adopted convention vs alternatives shown.

GET /api/policy/weights_table

Scenario table + the weighted allowance under 3 canned scenario-weight sets, computed by calling the real reweight_scenarios tool (reused, not re-derived). No params.

GOVERNANCE NOTE: every call to this endpoint appends three lines to outputs/agent_log/tool_calls.jsonl (one per canned weight set) — this is deliberate: the audit trail records every reweighting the app has ever shown a user, including from this Policy tab convenience table, not only from Copilot chat.

{
  "amounts_in": "USD",
  "scenario_totals": [
    {"name": "up", "allowance": 27689413.56, "coverage": 0.01654337351589052},
    {"name": "base", "allowance": 30454080.65, "coverage": 0.018195157150911207},
    {"name": "down", "allowance": 47587936.42, "coverage": 0.02843198557645327}
  ],
  "weight_sets": [
    {"id": "adopted", "label": "Adopted (25/50/25)",
     "weights": {"up": 0.25, "base": 0.5, "down": 0.25},
     "weighted_allowance": 34046377.82, "coverage": 0.02034141834854155,
     "jensen_ratio": 1.0352749002351027, "delta_vs_adopted_pct": 0.0},
    {"id": "equal_thirds", "label": "Equal-thirds (33/33/33)",
     "weights": {"up": 0.3333333333333333, "base": 0.3333333333333333, "down": 0.3333333333333333},
     "weighted_allowance": 35243810.21, "coverage": 0.021056838747751664,
     "jensen_ratio": 1.0436799985368514, "delta_vs_adopted_pct": 3.5170625123169375},
    {"id": "downside_tilt", "label": "Downside-tilted (15/35/50)",
     "weights": {"up": 0.15, "base": 0.35, "down": 0.5},
     "weighted_allowance": 38606308.47, "coverage": 0.023065803818429133,
     "jensen_ratio": 1.042572998763202, "delta_vs_adopted_pct": 13.393291574886245}
  ]
}

weight_sets[].id is a stable identifier for the UI ("adopted" is the book's actual reported basis; the other two are illustrative policy alternatives). delta_vs_adopted_pct is already 0–100-scale (percent deviation of that set's weighted allowance from the adopted basis).

GET /api/exhibits/list

id → {title, png_url, caption} for all 17 servable exhibit PNGs (the consultant-curated subset used across The Model / Policy tabs — not every PNG under outputs/). No params.

{
  "exhibits": [
    {"id": "hazard_age_baseline", "title": "Seasoning (age) baseline hazard",
     "png_url": "/static/exhibits/hazard/age_baseline.png",
     "caption": "Fitted natural-cubic-spline age baseline of the default hazard."},
    {"id": "hazard_pd_term_structure", "title": "PD term structure",
     "png_url": "/static/exhibits/hazard/pd_term_structure.png",
     "caption": "Lifetime PD term structure implied by the fitted hazards."},
    {"id": "lgd_calibration_ltv", "title": "LGD calibration by updated LTV",
     "png_url": "/static/exhibits/lgd/calibration_ltv.png",
     "caption": "Realised vs predicted LGD by updated-LTV decile, train vs OOT."},
    {"id": "lgd_cure_by_ltv", "title": "Cure rate by updated LTV",
     "png_url": "/static/exhibits/lgd/cure_by_ltv.png",
     "caption": "Realised vs predicted cure rate by updated-LTV decile."},
    {"id": "lgd_distribution", "title": "Realised LGD distribution",
     "png_url": "/static/exhibits/lgd/lgd_distribution.png",
     "caption": "Bimodal shape of realised workout LGD motivating the two-stage model."},
    {"id": "staging_stage2_sensitivity", "title": "Stage-2 share vs SICR threshold",
     "png_url": "/static/exhibits/staging/stage2_sensitivity.png",
     "caption": "Stage-2 share of the book at t=20 and t=40 across SICR ratio thresholds."},
    {"id": "staging_stage_distribution", "title": "Stage distribution over time",
     "png_url": "/static/exhibits/staging/stage_distribution.png",
     "caption": "Stage 1/2/3 population shares at each reporting snapshot."},
    {"id": "scenario_jensen_gap", "title": "Jensen gap",
     "png_url": "/static/exhibits/scenario_ecl/jensen_gap.png",
     "caption": "Weighted-scenario allowance vs allowance at the weighted-average macro path."},
    {"id": "scenario_ecl_bars", "title": "Scenario ECL comparison",
     "png_url": "/static/exhibits/scenario_ecl/scenario_ecl_bars.png",
     "caption": "Reported allowance under the up / base / down scenarios."},
    {"id": "scenario_z_paths", "title": "Scenario Z paths",
     "png_url": "/static/exhibits/scenario_ecl/z_paths.png",
     "caption": "Recovered credit-cycle factor Z under each scenario's macro path."},
    {"id": "vasicek_credit_cycle", "title": "Credit cycle (PIT vs TTC)",
     "png_url": "/static/exhibits/vasicek/credit_cycle.png",
     "caption": "Recovered systematic factor Z_t and the PIT-vs-TTC PD gap through the cycle."},
    {"id": "eda_default_rate_vs_macro", "title": "Default rate vs macro",
     "png_url": "/static/exhibits/eda/default_rate_vs_macro.png",
     "caption": "Quarterly default rate against the macro series (EDA)."},
    {"id": "eda_hazard_by_loan_age", "title": "Hazard by loan age",
     "png_url": "/static/exhibits/eda/hazard_by_loan_age.png",
     "caption": "Empirical default hazard by loan age (EDA)."},
    {"id": "eda_lgd_realised_bimodal", "title": "Realised LGD (EDA)",
     "png_url": "/static/exhibits/eda/lgd_realised_bimodal.png",
     "caption": "Raw bimodal realised-LGD histogram, before modelling."},
    {"id": "eda_origination_quality", "title": "Origination quality over vintages",
     "png_url": "/static/exhibits/eda/origination_quality.png",
     "caption": "FICO / LTV origination quality drift across vintages."},
    {"id": "eda_prepay_vs_rate_incentive", "title": "Prepayment vs rate incentive",
     "png_url": "/static/exhibits/eda/prepay_vs_rate_incentive.png",
     "caption": "Empirical prepayment rate against the note-vs-market rate incentive."},
    {"id": "eda_vintage_cumulative_default", "title": "Cumulative default by vintage",
     "png_url": "/static/exhibits/eda/vintage_cumulative_default.png",
     "caption": "Cumulative default curves by origination vintage."}
  ]
}

---

4. NEW: The 'Real Data' tab (Freddie Mac SFLLD Phase A/B)

freddie/ (read-only, FROZEN like the engine) built a second, REAL-data pipeline alongside the DCR-synthetic engine above — a champion hazard/LGD refit on the real Freddie Mac Single-Family Loan-Level Dataset (SFLLD, 17 vintages), an ALFRED-vintage backtest, and an LSTM path-dependence challenger. The four endpoints below parse outputs/freddie/**'s already-written reports/CSVs/JSON into JSON on every request — no engine state is touched and every number is read off those artifacts VERBATIM, never recomputed. Every PNG referenced by a png_url below is served at /static/freddie/<relative-path-under-outputs/freddie/> (a second, more convenient mount over the same files /static/exhibits/freddie/* already serves via the whole-outputs/ mount above).

GET /api/freddie/summary

Panel scale + the headline numbers for the tab's hero panel. No params.

{
  "panel": {
    "n_loans": 837500,
    "n_loan_months": 39522565,
    "n_vintages": 17,
    "overall_d90_rate_pct": 5.32,
    "overall_prepay_rate_pct": 58.93,
    "vintages": [
      {"vintage": "2005", "n_loans": 50000, "n_loan_months": 3588153,
       "d90_rate_pct": 10.75, "prepay_rate_pct": 87.21,
       "other_terminal_rate_pct": 0.15, "censored_rate_pct": 1.89,
       "perf_window_end": "2025-09"},
      "... 15 more rows (one per vintage: 2005-2010, 2014-2016, 2018-2025 —",
      "2011-2013/2017 are a documented coverage gap, never downloaded) ...",
      {"vintage": "2025", "n_loans": 37500, "n_loan_months": 153366,
       "d90_rate_pct": 0.04, "prepay_rate_pct": 1.79,
       "other_terminal_rate_pct": 0.03, "censored_rate_pct": 98.14,
       "perf_window_end": "2025-09"}
    ]
  },
  "hazard": {
    "train_auc": 0.8535911902958723, "oot_auc": 0.6847251436480823,
    "train_n": 17703723, "train_events": 26284,
    "oot_n": 21818842, "oot_events": 18309,
    "mcfadden_r2": 0.11966452683311235,
    "dcr_train_auc": 0.7476, "dcr_oot_auc": 0.6609
  },
  "covid": {
    "verdict": "exclude",
    "window": "2020-04..2021-09",
    "naive_oot2_auc": 0.7553126379930407,
    "additive_oot2_auc": 0.7546806708472524,
    "exclude_oot2_auc": 0.7509195241784803,
    "recommendation": "prefer **exclude** for any structural or scenario-conditional use -- it is the only treatment that preserves economically-signed macro coefficients, ... (full paragraph, verbatim from hazard_report.md section 3)"
  },
  "lgd": {
    "mean_realized_lgd_train": 0.2715010941028595,
    "mean_realized_lgd_oot": 0.0073627401143312,
    "cure_auc_train": 0.6991, "cure_auc_oot": 0.4769,
    "excess_loading_sflld": 0.0148, "excess_loading_dcr": 0.0255
  },
  "backtest_headline": {
    "worst_asof": "2007-12", "worst_miss_ratio_frozen": 9.423568161519073,
    "worst_miss_ratio_actual": 1.8965807743337444,
    "saturation_asof": "2019-12", "saturation_miss_ratio_actual": 0.06433186245201551
  },
  "lstm": {
    "oot_champion_auc": 0.6847251436480823, "oot_lstm_auc": 0.9924998553122111,
    "prior_dlq_champion_auc": 0.5698246326781929, "prior_dlq_lstm_auc": 0.9570336218094414,
    "clean_champion_auc": 0.5385541163579888, "clean_lstm_auc": 0.5287356531754855
  },
  "gate_verdict": "PASS",
  "source_files": ["outputs/freddie/gate_phaseA.md", "... 8 more"]
}

Notes: hazard.dcr_*_auc is the DCR-synthetic champion's own AUC (reused from outputs/hazard/fit_stats.md via the existing /api/model/coefficients parser — never re-derived), for the DCR-vs-SFLLD comparison stat tiles. *_pct fields are already 0–100 scale. covid.verdict is always "exclude" (the reviewed recommendation — the additive-dummy variant was overturned on review: it fits POSITIVE but fails to repair the sign-flipped structural macro terms). lgd.mean_realized_lgd_oot is COVID-cure-dominated, not a like-for-like regime comparison (see /api/freddie/summary's lgd source report). backtest_headline.worst_* is the row with the largest miss_ratio_frozen across all 5 reporting dates (currently 2007-12, the GFC); saturation_* is the row with the smallest miss_ratio_actual (currently 2019-12, the hindsight-macro saturation). gate_verdict is the Phase B gate's own PASS/FAIL line.

GET /api/freddie/hazard

Coefficients + the DCR sign comparison + AUCs + the COVID regime verdict — the same covid object as /api/freddie/summary, plus the full coefficient tables. No params.

{
  "coefficients": [
    {"term": "Intercept", "coef": -3.604265652756619, "std_err": 0.0659238765215353,
     "z": -54.67314488976103, "p_value": 0.0,
     "ci_low": -3.733474076460094, "ci_high": -3.475057229053144,
     "hazard_ratio": 0.0272074171706316,
     "unit_meaning": "reference-row hazard multiplier: owner-occupied / purchase-money / retail-channel / loan-age-spline reference, all continuous covariates at 0 on their raw scale.",
     "transformation": "model constant", "lag": "n/a", "fred_series": null,
     "economic_channel": "Not an economic channel -- the baseline hazard level the other coefficients multiply.",
     "hazard_ratio_per_unit": 0.027207,
     "worked_example": "Reference/mean-covariate baseline hazard multiplier: x0.0272 -- not a marginal per-unit effect."},
    {"term": "uer_lag1", "coef": 0.09496308546677008, "std_err": 0.003081229955925172,
     "z": 30.81986311477892, "p_value": 1.42e-208,
     "ci_low": 0.0889239857250708, "ci_high": 0.10100218520846936,
     "hazard_ratio": 1.0996182624819877,
     "unit_meaning": "1 unit = 1 percentage point of the property state's own unemployment rate LEVEL, lagged 1 month.",
     "transformation": "level (pp), state-level, lagged 1 month", "lag": "1 month",
     "fred_series": "{POSTAL}UR",
     "economic_channel": "Cash-flow / labour-income channel, same mechanism as the DCR national UER level -- state resolution replaces the national anchor with the borrower's own local labour market.",
     "hazard_ratio_per_unit": 1.099618,
     "worked_example": "+1pp of state UER level => hazard x 1.0996 (+10.0%, a 10.0% increase in the monthly/quarterly default hazard)."},
    "... 17 more rows (19 total: intercept, occupancy/purpose/channel",
    "categoricals, the 5-knot loan-age spline, fico_s, dti_s, ltv10,",
    "uer_lag1, delta_uer_lag1, hpi_growth_lag1) ..."
  ],
  "dcr_sign_comparison": [
    {"variable": "fico_s", "dcr_variable": "fico_s", "dcr_expected_sign": "-"},
    {"variable": "dti_s", "dcr_variable": null, "dcr_expected_sign": "n/a (DCR has no DTI field at this rung)"},
    {"variable": "ltv10", "dcr_variable": "ltv10", "dcr_expected_sign": "+"},
    {"variable": "uer_lag1", "dcr_variable": "uer_lag1", "dcr_expected_sign": "+ (net, level+momentum -- see DCR variable dictionary)"},
    {"variable": "delta_uer_lag1", "dcr_variable": "uer_chg4_lag1", "dcr_expected_sign": "+"},
    {"variable": "hpi_growth_lag1", "dcr_variable": "hpi_growth_lag1", "dcr_expected_sign": "-"},
    {"variable": "cr(loan_age, df=5)", "dcr_variable": "cr(loan_age, df=5)", "dcr_expected_sign": "hump (DCR peak ~12 QUARTERS ~= 36 months)"}
  ],
  "metrics": { "...": "identical shape to /api/freddie/summary's hazard object" },
  "covid": { "...": "identical shape to /api/freddie/summary's covid object" },
  "source_files": ["outputs/freddie/hazard/coefficients.csv", "... 5 more"]
}

dcr_variable is null when the SFLLD term has no DCR counterpart (only dti_s today — the DCR engine has no DTI field at this rung). dcr_sign_comparison covers the 7 continuous/structural terms only (not the categorical occupancy/purpose/channel dummies, which have no DCR counterpart at all).

Requirement 12 interpretation fields, joined onto every one of the 19 coefficients[] rows — same shape/semantics as /api/model/coefficients (unit_meaning, transformation, lag, fred_series, economic_channel, hazard_ratio_per_unit, worked_example), curated from outputs/freddie/hazard/hazard_report.md's per-variable rationale table. Two differences from the DCR endpoint, both because this endpoint carries the raw fitted coef (DCR's markdown table only ever publishes HR = exp(coef)):

• hazard_ratio_per_unit for the two log-growth macro rows (hpi_growth_lag1) is computed as exp(coef * 0.01) from the raw coef column, not derived from hazard_ratio — the tightest possible "computed mechanically, never invented" reading, and exactly what tests/test_contract.py recomputes and asserts against.
• The 8 categorical dummy rows (occupancy/purpose/channel) and the 5 loan-age spline rows get the SAME unit_kind treatment as their DCR categorical/spline counterparts, including 3 explicitly STATED misses vs the DCR sign prior (occupancy_status[T.S], loan_purpose[T.N], channel[T.C] — see economic_channel on those three rows, verbatim from hazard_report.md's "Fitted signs vs the priors" paragraph).

GET /api/freddie/backtest

The ALFRED-vintage backtest: per-reporting-date predicted-vs-realized D90

• miss ratios (the honesty exhibit), plus 3 verbatim narrative notes. No params.

{
  "rows": [
    {"asof": "2007-12", "fit_n": 86188, "fit_events": 610, "n_active_loans": 124235,
     "realized_cum_d90": 0.08749547229041735, "predicted_cum_d90_frozen": 0.009284749766834936,
     "miss_ratio_frozen": 9.423568161519073, "predicted_cum_d90_actual": 0.046133269657947416,
     "miss_ratio_actual": 1.8965807743337444},
    {"asof": "2009-12", "fit_n": 264774, "fit_events": 6843, "n_active_loans": 165978,
     "realized_cum_d90": 0.06568942871946884, "predicted_cum_d90_frozen": 0.05553775223045237,
     "miss_ratio_frozen": 1.182788753259087, "predicted_cum_d90_actual": 0.04657626110967737,
     "miss_ratio_actual": 1.4103628576966267},
    {"asof": "2015-12", "fit_n": 713027, "fit_events": 23732, "n_active_loans": 121861,
     "realized_cum_d90": 0.013974938659620387, "predicted_cum_d90_frozen": 0.01856748237465763,
     "miss_ratio_frozen": 0.752656627195429, "predicted_cum_d90_actual": 0.018546140130412742,
     "miss_ratio_actual": 0.753522757908191},
    {"asof": "2019-12", "fit_n": 1067328, "fit_events": 26491, "n_active_loans": 193308,
     "realized_cum_d90": 0.04600947710389637, "predicted_cum_d90_frozen": 0.009198148398939846,
     "miss_ratio_frozen": 5.00203683484812, "predicted_cum_d90_actual": 0.7151895709255173,
     "miss_ratio_actual": 0.06433186245201551},
    {"asof": "2021-12", "fit_n": 1298615, "fit_events": 35707, "n_active_loans": 173838,
     "realized_cum_d90": 0.011608509071664424, "predicted_cum_d90_frozen": 0.01733963868732328,
     "miss_ratio_frozen": 0.6694781408652541, "predicted_cum_d90_actual": 0.012290078358215651,
     "miss_ratio_actual": 0.944543129288056}
  ],
  "central_honesty_note": "miss ratio (frozen) = 9.42x (realized 8.750% vs predicted 0.928%) -- **UNDERPREDICTS the GFC, as expected**: a model fit on pre-2008 data with macro frozen at 2007-12 levels cannot see the crisis coming; this is the exhibit's central honesty result, not a defect.",
  "overlay_narrative": "The DCR champion (`engine/hazard.py`) is a point-in-time (PIT) hazard; IFRS-9 compliance requires pairing it with a forward-looking scenario overlay ... (full paragraph, verbatim from backtest_report.md section 1)",
  "covid_panel_note": "The 2019-12 model (fit on pre-COVID data, macro frozen at 2019-12 levels or even the hindsight-actual path) projects forward straight through the 2020-04..2021-09 forbearance window it never saw ... (full paragraph, verbatim from backtest_report.md section 3)",
  "source_files": ["outputs/freddie/backtest/all_metrics.json", "outputs/freddie/backtest/backtest_report.md"]
}

Exactly 5 rows (the 5 pseudo-reporting dates: 2007-12, 2009-12, 2015-12, 2019-12, 2021-12), always in that order. realized_cum_d90 / predicted_cum_d90_* are ratios (e.g. 0.0875 = 8.75%), not *_pct fields. miss_ratio_* is realized / predicted (>1 = the model underpredicted; <1 = overpredicted) — 2007-12's miss_ratio_frozen 9.42× is the centerpiece finding: a pre-crisis model with macro frozen at 2007-12 levels cannot see the GFC coming.

GET /api/freddie/exhibits

id → {title, png_url, caption, source} for the 13 curated Freddie SFLLD exhibit PNGs (vintage curves, roll-rate/COVID anomaly, state heterogeneity, severity cycle, hazard calibration/seasoning/COVID-regime, the backtest honesty panels, and the LSTM calibration/lift charts). No params.

{
  "exhibits": [
    {"id": "freddie_vintage_curves", "title": "Vintage curves -- cumulative D90 by months on book",
     "png_url": "/static/freddie/eda/exhibit1_vintage_curves.png",
     "caption": "2007 vintage reaches 16.26% cumulative D90 by month 225 vs 14.11% (2006) and 9.14% (2008) -- the pre-crisis-vintage hump; every 2018-2025 modern vintage tops out below 5.48%.",
     "source": "outputs/freddie/eda/eda_report.md#Exhibit 1"},
    {"id": "freddie_backtest_200712", "title": "Backtest honesty panel -- 2007-12 GFC miss",
     "png_url": "/static/freddie/backtest/predicted_vs_realized_200712.png",
     "caption": "A model refit through 2007-12 with macro frozen at then-current levels predicts 0.928% 36-month D90 vs a realized 8.750% -- a 9.42x underprediction of the GFC it could not see coming.",
     "source": "outputs/freddie/backtest/backtest_report.md#2"},
    "... 11 more (see app/api/main.py FREDDIE_EXHIBITS for the full curated list) ..."
  ]
}

source (unique to this endpoint vs /api/exhibits/list's caption-only shape) names the report/section the caption's numbers were read from.

---

5. NEW: Copilot / Scenario Lab auto-interpretation

POST /api/agent/interpret

Body: {"tool": "<one of the 5 route names>", "result": {<the exact JSON that tool/route returned>}}.

tool must be one of "shock_macro", "reweight_scenarios", "rerun_ecl", "decompose_waterfall", "query_model_docs" (422 if not). result must be the tool's own returned JSON verbatim — for the four Tier-1 tools it must at minimum contain headline and tool_call_id; for query_model_docs it must contain passages (a 422 with a "missing required field(s)" detail is returned otherwise, BEFORE any LLM call).

Request example (after a Scenario Lab run of rerun_ecl):

{
  "tool": "rerun_ecl",
  "result": {
    "tool": "rerun_ecl", "segment": "all",
    "weighted_allowance": 34046377.82,
    "headline": "segment 'all' (entire non-payoff book at the t=60 reporting date): 7,849 loans, balance $1,673.7m, scenario-weighted allowance $34.0m (100.0% of the book allowance), coverage 2.03%",
    "tool_call_id": "tc-000123"
  }
}

Response:

{
  "interpretation": "The book carries a scenario-weighted allowance of $34.0m against $1,673.7m of balance (2.03% coverage), computed across all 7,849 loans on the book. [engine-computed; audit ref tc-000123]",
  "grounded": false,
  "mode": "template_number_check_failed"
}

• interpretation (string): the narration to show under the Scenario Lab result card. Non-empty, always safe to render as plain text.
• grounded (bool): true iff the LLM's own prose passed the mechanical verbatim-number/citation check (agent/graph.py's narration_numbers_ok / docs_answer_ok, reused, not duplicated) and is being shown as-is. false means the LLM's narration either errored or invented a number outside the tool result, and interpretation therefore fell back to the engine's own deterministic text (the tool's headline for Tier-1 tools, or a cited passage listing for query_model_docs) — this is a normal, expected outcome under the project's anti-hallucination governance, not a bug the UI should surface as an error. A small "AI interpretation" vs "engine summary" badge is the recommended UI treatment of grounded.
• mode (string, informational/debug only — do not branch UI logic on its exact value beyond the grounded bool): "llm" on success, else one of "template_number_check_failed", "template_citation_check_failed", or "template_llm_error:<ExceptionType>".

For query_model_docs, result must look like the Tier-3 tool's own output shape: {"tool": "query_model_docs", "question": "...", "passages": [{"source": "wiki"|"notes", "citation": "...", "text": "..."}], "reading_list": [...], "headline": "...", "tool_call_id": "tc-..."}.

---

6. NEW: UI v3 AI-explain question-prefix conventions

Both conventions below are UI-side wire-text conventions layered on top of the existing POST /api/agent/ask (§1) — they add ZERO new endpoints and change no response shape. POST /api/agent/ask already accepts any 1–2000 char free-text question; these are simply two disciplined ways the v3 UI composes that string so an "explain" click gets the exact same tools/Tier-2/Tier-3/refusal governance as a typed question (FINAL_SPEC.md §7.5, design-judge grafts 4). The router sees ordinary text — a bracketed tag, a colon, and a trailing question — and is free to route it to any of the five paths, including REFUSE, exactly as it would any other message.

6.1 Panel/tile explain prefix

Every panel/tile heading in the UI carries a small AI-explain icon (app/ui/src/components/ExplainButton.jsx). Clicking it composes:

[explain:<panel_id> <live params>] <Exhibit label> — <panel title>: <CODE-GENERATED
recap of the exact figures the panel is showing right now> What should I take
from this?

• <panel_id> is a short stable slug (e.g. waterfall, hazard_coefficients, kpi_coverage) — never free text, always the same value for the same panel across renders.
• <live params> (when present) are key=value pairs reflecting the panel's CURRENT inputs (e.g. t0=59 t1=60), space-separated inside the same brackets.
• <Exhibit label> is omitted for un-numbered panels (KPI tiles, control panels, guides).
• The recap sentence is built from the SAME payload object that rendered the panel — never hand-typed prose — so the router/narrator always has the rendered numbers in front of it.

Example (app/ui/src/api.js's explainPanelQuestion, used by WaterfallChart.jsx):

[explain:waterfall t0=59 t1=60] Exhibit 1 — Allowance bridge: opening $X.Xm,
stage migration +$X.Xm, remeasurement +$X.Xm, derecognitions −$X.Xm, new
loans +$X.Xm, closing $X.Xm. What should I take from this?

6.2 Selection-explain prefix

Highlighting any text in the main app area (outside inputs and both chat surfaces) shows a floating "Explain with AI" chip (app/ui/src/components/SelectionExplain.jsx); clicking it composes:

Explain, in the context of the <tab label> tab: "<selected text, trimmed, <=300 chars>"

<tab label> is one of the five tab names (Executive Overview, The Model, Scenario Lab, Policy, Copilot). The selected text is quoted verbatim (truncated, never paraphrased) so the router sees exactly what the user highlighted.

Both builders live in app/ui/src/api.js (explainPanelQuestion, explainSelectionQuestion) as the single source of the exact wire text, so the UI and tests/test_contract.py's router-wiring test stay byte-identical with this doc.

---

Summary table (every endpoint the v2 UI may call)

Method	Path	Purpose
GET	/api/health	liveness + warm-up timing
GET	/api/ecl/summary	headline stats + scenario table
GET	/api/ecl/waterfall	movement decomposition between two snapshots
GET	/api/exhibits/credit_cycle	recovered Z_t series
POST	/api/tools/shock_macro	Tier-1 tool
POST	/api/tools/reweight_scenarios	Tier-1 tool
POST	/api/tools/rerun_ecl	Tier-1 tool
POST	/api/tools/decompose_waterfall	Tier-1 tool
POST	/api/agent/ask	route a free-text question through the copilot
GET	/api/agent/stream	SSE trace feed of the latest /ask
GET	/api/model/coefficients	hazard-ratio families + fit stats (The Model)
GET	/api/model/variable_dictionary	every modelled variable (The Model)
GET	/api/model/macro_glossary	every macro series across DCR+SFLLD+satellite (The Model)
GET	/api/model/lgd	LGD key numbers + exhibits (The Model)
GET	/api/policy/staging_sensitivity	SICR threshold governance curve (Policy)
GET	/api/policy/weights_table	scenario weights sensitivity (Policy)
GET	/api/exhibits/list	every servable exhibit PNG, with captions
GET	/api/freddie/summary	SFLLD panel scale + headline numbers (Real Data hero)
GET	/api/freddie/hazard	SFLLD hazard coefficients + DCR sign comparison + AUCs
GET	/api/freddie/backtest	ALFRED-vintage predicted-vs-realized table (Real Data)
GET	/api/freddie/exhibits	every servable Freddie SFLLD exhibit PNG, with captions
POST	/api/agent/interpret	auto-interpretation of an already-run tool result
GET	/static/exhibits/*	the exhibit PNGs themselves (read-only static mount)
GET	/static/freddie/*	the Freddie SFLLD exhibit PNGs (read-only static mount)
GET	/static/mdd/MDD.html	the Model Development Document (read-only static mount)