F1 ML Project

Point-in-time Formula 1 race and championship predictions. Every prediction uses only information that was public before its cutoff, and every training race is audited from official FIA documents.

Status (6 November 2026): development predictions are published for each 2026 race weekend, trained on 99 audited Gold races (2022 to the 2026 Mexico City GP). No model has passed the formal selection gate yet, so every output is labelled development_only, not a validated forecast. Candidate improvements (weather, wet-weather skill, tyre and pit strategy, a sharper winner draw) run as shadow predictions next to the official one and are scored on new races.

Start with the pipeline overview: it has diagrams of the data flow, trust rules, model, shadows, and the race-weekend and post-race checklists.

flowchart LR
    S["FIA, formula1.com,<br/>Jolpica, OpenF1, Open-Meteo"] --> A["Audits<br/>(hash-bound evidence)"]
    A --> G["Gold races and<br/>contract datasets"]
    G --> E["evaluate-cutoffs<br/>(protocol v3)"]
    E --> P["predict-next-race<br/>official + shadows"]
    P --> W["export-web<br/>React app"]
    P --> C["score-shadows.py<br/>after the race"]

Loading

Setup

Python 3.11 or newer, from the repository root:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pip install -e ".[xgboost,catboost,lightgbm,audit]"

Checks (all must pass before a commit):

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m ruff format --check .
.\.venv\Scripts\python.exe -m mypy
cd web; npm run typecheck; npm run lint; npm run test

Tests use mocks and need no network access.

On a race weekend

# Any time before qualifying: pre-weekend prediction
.\.venv\Scripts\python.exe -m f1_ml_predictor predict-next-race

# After qualifying, before the race: post-qualifying prediction plus shadows
.\.venv\Scripts\python.exe -m f1_ml_predictor predict-next-race

predict-next-race runs one collector tick, picks the contract for the current cutoff (pre-weekend, sprint, post-qualifying or pre-race), fits the models on Gold races before the cutoff and publishes race probabilities, a season simulation and report.md under data/predictions/development/next_race/. After a post-qualifying or pre-race run it also freezes the shadow predictions and prints them under the report (--no-shadows skips them). The Windows scheduled collector is disabled, so these runs are made by hand. Details: development predictions.

After a race

A fixed chain of audits brings the new race into Gold, refreshes the weather, strategy and results data, and scores the shadows. The ordered checklist with every command is in the pipeline overview.

Web frontend

.\.venv\Scripts\python.exe -m f1_ml_predictor export-web
cd web
npm install
npm run dev

export-web verifies every run's hashes and probability contracts and writes display-ready JSON to web/public/data/. The React app shows the predicted order, race probabilities, both championships, the actual result against the prediction, the shadow predictions and model details; it never computes predictions. Stop the dev server before re-exporting on Windows. See web frontend.

Documentation

Document	What it covers
Pipeline overview	Diagrams, trust rules, contracts, shadows, weekend and post-race checklists
Data trust	Evidence classes, tiers, publication rules for every source
Gold workflow	How races are audited into Gold
Feature dictionary	Every predictor and its availability rule
Protocol v3	The frozen evaluation, calibration and selection method
Modeling	Candidate models, calibration, joint simulation
Development predictions	predict-next-race, sprints, shadows, outputs
Simulation	Championship simulation
Scoring ledger	Audited championship points
Web frontend	Export contract and React app
Project plan	Milestones, decisions, open risks

Dated reports record individual results and are not edited afterwards: weather addendum, strategy addendum, provisional-grid cohort, historical enrichment, scoring evaluation, DNF audit status, baseline regression audit and the Gold recovery and expansion reports.

Lower-level commands

Command	Purpose
ingest-season <season>	Jolpica schedules, results and standings into data/normalized (--refresh for an older season)
list-openf1-sessions, ingest-openf1-session, ingest-fastf1-session	Session enrichment (FastF1 needs .[fastf1])
capture-forecast <season> <round>	Live Open-Meteo forecast for an event in the next seven days
collect-next-race, collection-status	One prospective collector tick, and its state
build-benchmarks, backtest, compare-models	Tiered benchmarks and earlier model comparisons
evaluate-cutoffs [--contracts ...]	Protocol v3 evaluation per contract, cached by exact inputs
build-gold-enrichment, build-gold-scoring, build-gold-sprints	Gold rebuild steps
model-hardware	CPU/GPU probe for the boosting backends
export-web	Frontend data

Run python -m f1_ml_predictor <command> --help for options.

Graphify

A git post-commit hook updates the local knowledge graph in graphify-out/ after each commit.