wraith-tdf-predictor 0.8.0

Tour de France race outcome prediction: rider archetypes, a top-10 model, and Tissot fantasy team picks by exact knapsack.

wraith-tdf-predictor 🚴💨

Who cracks the top 10 in July? Six seasons of ProCyclingStats results, a from-scratch model, and a Tissot fantasy team picked by exact knapsack — all in pure Python. No torch, no sklearn, no 200 MB wheel for a model with nine weights.

The 2026 hot take so far: Pogačar. Groundbreaking stuff.

What it does

• Scrapes grand tours, one-week stage races, monuments and top classics (men's elite, 2021–2026) into SQLite
• Clusters riders into archetypes with hand-rolled k-means
• Predicts top-10 finishes with class-weighted logistic regression (test AUC ~0.89 — form really is everything in cycling)
• Picks a 10-rider, 120-star Tissot fantasy team via 0/1 knapsack with cardinality, backtested leave-one-year-out against the hindsight-optimal team
• Publishes a static predictions page (data.json) with per-stage teams, jersey picks, and pred-vs-actual grading during the Tour

Install

pip install wraith-tdf-predictor    # or: uv add wraith-tdf-predictor

Runtime dependencies: procyclingstats and cloudscraper. That's it. Python 3.12+.

Run it

From a clone:

git clone https://git.thomaspeoples.com/thomaspeoples/wraith-tdf-predictor.git
cd wraith-tdf-predictor
uv run poe setup      # deps, hooks, .env from template — once

uv run poe ingest     # scrape PCS -> data/raw/*.json (polite, cached)
uv run poe db         # load -> data/races.db (SQLite)
uv run poe model      # archetypes + top-10 model
uv run poe fantasy    # backtest + 2026 team pick
uv run poe publish    # data.json for the static predictions page
docker compose up -d  # browse the DB at :8080

uv run poe update     # daily during the Tour: ingest new stage if
                       # raced, retrain, republish -- no-op otherwise

Outputs land in data/: archetypes.json, model.json, and a printed team that will absolutely not win your league.

Configuration

Everything configurable lives in .env (copied from .env.example by poe setup, never committed):

Variable	Default	Purpose
DATA_DIR	./data	Scraped data, SQLite DB, model outputs
WWW_DIR	$DATA_DIR/www	Where poe publish writes data.json
TISSOT_USER / TISSOT_PASS	—	Only for scraping the Tissot game yourself

Poe tasks load .env automatically; direct python -m runs want uv run --env-file .env ....

Where the data comes from (and how politely it's scraped): docs/SOURCES.md.

Hacking on it

uv run poe test         # pytest, coverage >80% enforced
uv run poe tidy         # ruff lint + format
uv run poe docs-serve   # MkDocs on :8000
uv run cz commit        # commits go through commitizen, no exceptions

Full workflow in CONTRIBUTING.md.

License

MIT — see LICENSE.