a CFP selection simulator
A transparent, reproducible decision-support simulator for College Football Playoff ranking, selection, seeding, and bracket analysis.
The simulator runs from sample data in under a minute, generates a 12-team playoff field, explains why teams made or missed the bracket, and compares model outputs against CFP-style selection rules.
Note
v1 beta. The web app is the primary way to explore results: run make web.
The Python CLI and CSV/JSON exports are the engine underneath. The two runtime modes
(local OSS and hosted) are compared in Operating modes below.
Engine
- Composite rankings (resume, predictive, SOR, SOS)
- 12-team field selection under 2024 or 2025+ CFP rules
- Format-aware seeding and bracket generation
- Structured audit trail and reproducibility manifest
- Historical validation against published CFP rankings
Selection Room web app
- Projected field, rankings, and bubble/cut-line views with per-team resume drawers
- In-browser Run Analysis: launch a season/week run from sample or live CFBD data
- Scenario Lab: reweight the pillars and diff the resulting field, seeds, and bubble
- Validation Dashboard: committee alignment, field accuracy, and predictive-signal tracks across seasons
- Export / share: rankings CSV, bracket share image, and per-team resume cards
Note
No API key is required for make demo. Sample fixtures include conference champions so auto-bids and byes look realistic.
git clone https://github.com/XavierAgostino/cfp-selection-simulator.git
cd cfp-selection-simulator
make setup # Python engine (.venv)
make demo # first sample run (no API key needed)
make web # Selection Room site at http://localhost:3000The site walks you through setup if you open it first, and new analyses can be launched from the run bar (Run Analysis): season, week, sample or live CFBD data.
One-shot script: ./scripts/demo.sh · Web app docs: docs/web-app.md
Two runtime modes share the same JSON contract and Python engine. Browsing is open in both; the difference is how runs get launched.
| Local OSS | Hosted (Vercel + Supabase + Trigger) | |
|---|---|---|
| Data | make demo or your own runs, read from data/output/ |
Seeded official catalog in Supabase Storage + Postgres |
| Browsing | Open, no setup beyond make demo |
Open to everyone, no account |
| Run Analysis | Optional subprocess jobs (SELECTION_ROOM_ENABLE_RUN_JOBS=1) |
GitHub sign-in with a per-user daily quota; Trigger.dev worker |
| CFBD key | Required for live runs | Server/worker only |
| Setup | make setup && make demo && make web |
Hosted Runs v1 |
On the hosted deployment, browsing the catalog needs no account; launching a run requires a GitHub sign-in with a per-user daily quota (a legacy access code still works as an optional bypass). No billing in v1.
Important
Live runs need a free College Football Data API key in .env as CFBD_API_KEY.
cp .env.example .env # put your CFBD_API_KEY in .env
make run YEAR=2025 WEEK=15
# or: ./bin/sroom run --year 2025 --week 15
# or: the Run Analysis button on the siteUse make or ./bin/sroom from the repo root. Bare sroom requires source .venv/bin/activate.
| Goal | Command |
|---|---|
| Environment check | ./bin/sroom doctor |
| Sample demo | make demo |
| Full pipeline | make run YEAR=2025 WEEK=15 |
| Web app | make web |
| Bracket HTML | make bracket YEAR=2025 WEEK=15 |
| Latest outputs | ./bin/sroom outputs --latest |
| Validation (all tracks) | make validate |
| Field validation only | make validate-selection |
| Predictive metrics only | make validate-predictive |
| DuckDB store status | ./bin/sroom store status |
| Query run store | ./bin/sroom store query "SELECT * FROM runs LIMIT 5" |
| Dev verification | make verify |
See CLI Reference for all options.
After make demo:
| File | Description |
|---|---|
data/output/rankings/2025_week15_rankings.csv |
Composite rankings |
data/output/fields/2025_week15_field.csv |
12-team playoff field |
data/output/brackets/2025_week15_bracket.csv |
Seeded bracket |
data/output/brackets/2025_week15_bracket.html |
Interactive bracket |
data/output/audits/2025_week15_audit.json |
Selection audit |
data/output/runs/2025_week15_manifest.json |
Reproducibility manifest |
Details: Output Files
Data contracts: JSON under data/output/api/ powers the web app. Each export also writes a local DuckDB store at data/output/selection_room.duckdb for analytical queries (sroom store). See Development Guide.
Note
Selection Room is a decision-support simulator, not a claim to replicate closed-door committee deliberations.
One composite pipeline with explainable components.
Documentation home: docs/index.md · Research methodology: docs/research/index.md
| Topic | Doc |
|---|---|
| CFP format rules | Format History |
| Committee alignment | CFP Committee Alignment |
| Ranking model | Model Methodology |
| Metrics | Metric Definitions |
| Backtests | Historical Validation |
| Stability | Sensitivity Analysis |
| Scope | Limitations & Ethics |
| Era | Field | Seeding / byes |
|---|---|---|
| 2014–2023 | 4 teams | Use validation modules only |
| 2024 | 12 teams (5 auto + 7 at-large) | Top 4 conference champions get byes |
| 2025+ | 12 teams (5 auto + 7 at-large) | Straight seeding; top 4 overall get byes |
Start here
Research
Contributors
- Contributing
- Development Guide
- Project Structure
- Hosted Runs v1: deploy the hosted app
- Supabase setup
- Trigger worker setup
make setup
make verifyv1 beta (now): local OSS and hosted.
- Local OSS: full engine plus optional Run Analysis subprocess jobs.
- Hosted: Vercel + Supabase + Trigger.dev. Open browsing of the seeded catalog; run launch behind GitHub sign-in with a per-user daily quota (Hosted Runs v1).
Future (v1.1+), documented but not implemented:
- Shareable scenario URLs: deep-link a Scenario Lab diff.
- Billing and shareable authenticated links: not in v1.
Research track: V2 experiments (through V2.4) are implemented but intentionally do not change v1 production defaults; full historical evaluation and V2.5 are deferred. See research methodology.
Adapter design history: docs/architecture/hosted-production.md.
MIT License. See LICENSE.
Game data via College Football Data API. Team logos may load from ESPN CDN fallbacks when a local asset is missing.
Author: Xavier Agostino