Auto-generated. This article is rebuilt from FastAPI route introspection by scripts/build_api_kb.py. Edit the route docstring in app/ and re-run the script — do not edit this file directly.

GET /api/v1/screener/calibration

Handler: app.screener.routes.get_screener_calibration_route
Methods: GET

Description

Per-archetype screener calibration summary.

Wraps app.signals.screener_predictions.get_screener_calibration(db). Returns per-archetype hit-rate, CI, and sample size for matured screener_predictions rows.

Headline filters (W1-1, schema 2026.07). Every displayed number is computed from the HEADLINE cohort only: rows flagged on/after calibration_start_date (post-flood era, screener_config § calibration) whose engine state at flag time was headline_state (‘primed’). Flood-era (2026-06-14..21 whole-universe flood) and off-state rows are excluded from hit-rates, the calibrated flag, and the trust surfaces, and appear ONLY in the labeled diagnostics block — contamination diagnostics, never a track record. Expect headline numbers to be smaller and honest — that is the contamination leaving, not a regression.

Episode dedup (W1-8/F7, schema 2026.07.1). The headline cohort is additionally deduped to the FIRST flag per (ticker, archetype, horizon)- episode — a gap of more than 10 calendar days to the prior flag starts a new episode — so a daily re-firing candidacy counts once per EPISODE, not once per fire-day (the F7 pseudo-replication that inflated n and artificially tightened CIs). Each entry carries episode_dedup: {raw_rows, deduped_rows} as the audit trail. Expect n to DROP vs the row-level read — that is replication leaving, not data loss.

Honesty contract (DOCTRINE P0): Every archetype is labeled calibrated: False until it accumulates min_matured_samples (from screener_config.json, default 30) matured rows. Maturation requires 30–45 REAL calendar days. Empty / immature data returns HTTP 200 with honest labels — NEVER a 404 and NEVER a fabricated hit-rate.

The label field carries a human-readable summary:

• "calibrated" — min samples met; hit_rate is meaningful.
• "uncalibrated (N/min)" — shows current sample size and the floor.

Accrual visibility (PR-S, additive). Each by_archetype entry — accruing AND calibrated — carries pending_predictions (recorded rows still unmatured) and next_maturation_eta (the earliest trading-day-add maturation date over those rows, YYYY-MM-DD or null). The top-level response carries total_recorded_predictions (sum across archetypes) and earliest_maturation_eta (min ETA across archetypes, or null) so the widget can show accrual as visible motion before the first cohort matures.

Dial diagnostic (#66, additive, EXPERIMENTAL — not validated, watched forward). Each CALIBRATED by_archetype entry additionally carries by_dial — the screener’s own confidence dials (engine state, confluence_count, score_norm) vs the intent-aware excess hit-rate, bucketed. It rides ONE representative horizon (by_dial.horizon_days, the 5-day read) so a multi-horizon archetype-day isn’t counted once per horizon. Each dial is a list of {bucket, hit_rate_excess, mean_excess, n} — empty buckets are emitted with n: 0 and null rates, never dropped. Accruing entries have no matured rows and omit by_dial. This is a forward-watched diagnostic, NOT a validated edge: a Phase-1 recompute saw confluence + score_norm inverted (higher → worse) on a 2-week substrate, but that read is hypothesis-grade and the buckets are reported factually for OOS grading.

Curl

curl -s https://bigclawd.com/api/v1/screener/calibration