API contracts
JSON contract between the Python engine and the Next.js web app.
The Python engine emits stable JSON under data/output/api/. The web app consumes these files with snake_case on the wire; TypeScript types mirror the same shape.
Current-run files
Top-level copies of the latest run for fast page loads:
| File | Purpose |
|---|---|
latest.json | Metadata pointer to the most recent stem |
rankings.json | Flat rankings for the latest run |
field.json | Projected CFP field for the latest run |
bracket.json | Bracket payload for the latest run |
These files update when a new run completes. They carry schema_version: 1.
Per-run files
Each completed run lives under data/output/api/runs/{stem}/:
| File | Purpose |
|---|---|
rankings.json | Full ranking table for that stem |
field.json | Projected field for that stem |
bracket.json | Bracket structure and matchups |
audit.json | Selection audit trail when exported |
team-resumes.json | Per-team resumes: schedule, score breakdown, selection case |
sensitivity.json | Selection Stability frequencies (optional; older runs omit it) |
committee.json | Model vs Committee comparison (optional; only for seasons with final committee reference data) |
Run metadata (season, week, mode, weights, timestamps) lives in the catalog entries, not in a per-run file. Scenario stems reuse the same layout with a distinct suffix so diffs stay traceable. Optional files are omitted entirely when their inputs do not exist; the UI hides the matching surfaces rather than inventing values.
Run catalog files
| File | Purpose |
|---|---|
runs.json | Catalog for the run switcher: all stems, labels, latest pointer |
validation.json | Repo-level backtest metrics from the validation harness |
The web app reads runs.json once per session (shared catalog hook) and resolves per-run payloads by stem. There is no mapping layer between Python exports and TypeScript types.
Source of truth
Pydantic v2 models in src/api_contracts/models.py define the contract. Breaking changes require a schema version bump and coordinated web updates.
Note
The full contract includes TeamSlot shapes, audit payloads, and complete JSONC examples for every file above. See the GitHub doc.