Quickstart¶
The whole pipeline on synthetic data, with the real commands: install, build a demo store, backtest, forecast, run a live private book and price a sportsbook's lines. About 5 minutes once Postgres is up.
Every command below is a normal racinglines command with --demo added. --demo switches the data source to a
demo store (a separate database and data folder filled from a data pack) and changes nothing else.
The default pack, kart, is a synthetic Formula 1 world with a Mario Kart grid: every pace, result and price is
invented; play money, nothing is traded anywhere.
What you need
Python 3.11 or newer and a PostgreSQL 16+ server. No API key, no account and no network access are needed for the demo. The hosted way in needs only Python and a racinglines.bet account with MCP access (in testing).
Installing from PyPI?
pip install "racinglines[db]" is the shortest way in: the
package README walks through the same demo from the installed package, with
the database in one docker run. The package is F1, the downhill sim, the kart demo and the web app;
[db] runs every command, pip install "racinglines[mcp]" adds the MCP server and the hosted way in (--remote,
racinglines remote, data pull), and pip install "racinglines[web]" adds the web app. The NASCAR, MotoGP, road cycling and weather commands on this page are not in it.
Prefer to watch first? The same commands, recorded, play in the browser at racinglines.bet/docs/quickstart/term, no sign-in needed.
Which way in?¶
Everything runs on your machine. The demo store is built on first use (about a minute) and every command works on it.
Setup (5 min)¶
Step 1: Install¶
# LOCAL (Mac), or any machine with Python 3.11+ and Docker
python3 -m venv ~/rl && source ~/rl/bin/activate
pip install "racinglines[db]" # or, in a clone of racinglines-public: pip install -e ".[web]"
Step 2: Start Postgres¶
# LOCAL (Mac): PostgreSQL 17 on localhost:5433, data in the Docker volume racinglines-pgdata
docker run -d --name racinglines-db -p 5433:5432 -e POSTGRES_USER=racinglines -e POSTGRES_PASSWORD=racinglines \
-e POSTGRES_DB=racinglines -v racinglines-pgdata:/var/lib/postgresql/data postgres:17
In a clone of the full development repository, docker compose up -d starts the same server
(docker-compose.yml).
Without Docker, any Postgres 16+ works: point DATABASE_URL at it (Database). The demo
database is created next to the configured one (racinglines_demo_kart on the same server), so the user in the
URL needs the right to create databases (the container's user has it).
Step 3: Check the install¶
racinglines check runs the pipelines on synthetic data, probes every data source and checks the database
(about 10 seconds). --offline skips the endpoint probes; --no-db skips the database.
code (synthetic data)
✓ f1 code load + measurements 0.3s 6 events, 7,485 laps, 360 practice rows
✓ f1 code as-of leakage guard 0.0s sessions only usable after they end
✓ f1 code training history 0.6s 120 training rows
✓ f1 code race pricing 1.2s favourite Driver 01 36%
✓ f1 code backtest 0.6s 6 race x mode rows, mean win Brier 0.032
✓ f1 code season forecast 0.3s leader Driver 01 71%
✓ markets code maker replay 0.0s 172 fills, P&L +72.56
✓ markets code weekend taker 0.0s 46 trades, P&L +300.15
✓ markets code season strategy 0.2s 39 trades, P&L -93.55
✓ mtb_dh code parse results tables 0.1s 1920 rows, 60 riders, rounds ['final', 'practice', 'qual1']
✓ mtb_dh code season model 0.2s sigma 0.0096, 60 riders
✓ mtb_dh code season forecast 0.2s leader 69%
✓ mtb_dh code backtest 0.2s 1 held-out round(s) scored
database
✓ database Postgres 0.2s localhost:5433/racinglines, schema up to date
14/14 checks passed
Step 4: Choose where the data comes from¶
The first command that needs a database, when none is configured (no DATABASE_URL, no db or source in
~/.config/racinglines/cli.toml), asks once and saves the answer as source in that file. Answer 1:
racinglines needs a database, and none is configured (no DATABASE_URL, no `db` or `source` in ~/.config/racinglines/cli.toml).
1) local: the Postgres of docker-compose.yml on localhost:5433; start it with one command, `docker compose up -d`
(then every command works; add --demo for the synthetic demo store, docs/quickstart.md)
2) remote: sign in to racinglines.bet (the browser opens on first use) and run `racinglines book map|price|settle`
on the hosted server, like `racinglines remote ...` and `--remote` on a Lab-job command (in testing);
other commands still need a local database
Choose 1 or 2 [1]:
With no terminal to ask on (a script, CI), it prints the same two options and exits with code 2: set
DATABASE_URL, or run racinglines book config source local (or remote). The same command changes the answer
later. One resolver makes this choice and the --demo one (racinglines/cli/source.py).
Now run the quickstart.
#aintcare mode
racinglines.bet remote access is in testing (#aintcare mode). A review of venue and data-feed terms is pending, so data served here is for testing only. Every command that connects to the hosted server prints this warning on stderr.
Sign up on racinglines.bet first
Every --remote command needs a racinglines.bet token, which comes from your sign-in on the site:
sign up before Step 2. The hosted demo store (--demo --remote) may let you
try a few calls without a token first, then asks you to sign up. The local tab needs no account.
From PyPI, these commands need the MCP extra: pip install "racinglines[mcp]".
Nothing to install but the CLI itself, no Postgres: --remote sends the commands the hosted server runs to
racinglines.bet, and --demo --remote sends them to the pack's hosted demo store (racinglines mcp --http
--demo on the VM, over its own database built from the pack: synthetic data only, never production's). The
outputs below are not shown because these commands need the hosted server, which the docs build cannot reach.
Setup (2 min)¶
Step 1: Install the CLI¶
# LOCAL (Mac), or any machine with Python 3.11+: no Postgres needed
git clone https://github.com/racinglines/racinglines.git && cd racinglines # the development repository
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pip install -e .
Step 2: Sign in¶
The first --remote command opens the browser to sign in with your racinglines.bet account (one with MCP
access: Pro or admin, MCP: Hosted) and waits for Allow. The login is kept in
~/.config/racinglines/mcp-login.json and refreshed on its own; racinglines book logout forgets it. On a
machine with no browser, an rl_ token from Settings > Connect Claude (MCP) in RACINGLINES_MCP_TOKEN skips
the sign-in.
# LOCAL (Mac): the pack's book, priced on the hosted demo store (the browser opens once)
racinglines book price --demo --remote
Step 3: Run the model as a hosted job¶
On the hosted store the model commands run as the server's Lab jobs (run_job, followed with get_job), the
log printed as it arrives, and the run is saved there. They take the job's options only (--races, --sims,
--track, --half-life, --scenario; --half-life-days, --junior-weight for mtb_dh).
# LOCAL (Mac)
racinglines model backtest kart --demo --remote --races 10 # the backtest as a hosted job
racinglines model forecast kart --demo --remote # a forecast scenario on the hosted demo store
db stats, live run and live report need a local store. The pack names its server ([remote] mcp_url in
pack.toml; RACINGLINES_DEMO_MCP_URL overrides it); it answers once the owner has built it on the VM
(scripts/vm/demo_store.sh, Demo data packs). With source = "remote" saved
in ~/.config/racinglines/cli.toml, --demo alone goes to the hosted store too.
Step 4: Pull real data into your own database (optional)¶
The same sign-in reaches more of the hosted server (MCP: More commands on the hosted
server): --remote on any command that has a Lab job,
racinglines remote tools | call | job, and racinglines data pull SPORT, which copies one sport's shared data
(race data, model runs, exchange prices, trades and books; never accounts or positions) into a local database:
Run the quickstart (the kart pack)¶
The steps come from the pack's manifest (racinglines/demo/packs/kart/pack.toml, [[quickstart]], rendered by
python3 scripts/build_quickstart.py), and every Output tab is what the command printed on the pack, captured
by scripts/docs/capture_examples.py (never typed by hand). The browser replay
records the same list. Run them in order.
Step 1: 📦 Install racinglines¶
In a virtualenv with Python 3.11+: the package with its database extra (from a clone of racinglines-public, pip install -e ".[web]").
Step 2: 🍄 Build and look at the demo store¶
The first --demo command builds the store (a few minutes, with a progress bar): the database, the synthetic files, the real ingest and the exchange links. Later commands reuse it.
demo: building the kart pack's store (no database): database racinglines_demo_kart, folder
/home/user/racinglines-public/data/demo/kart. Synthetic data, made once (a few minutes).
🔧 demo store 0/7 creating the database
🔧 demo store 1/7 schema and reference data (alembic upgrade head, seed)
🔧 demo store 2/7 the pack's data files
🔧 demo store generating: 2024 R01 Mario Kart Stadium
🔧 demo store generating: 2025 R01 Mario Kart Stadium
🔧 demo store generating: 2026 R01 Mario Kart Stadium
🔧 demo store generating: files written
🔧 demo store generating: exchange odds 2026-09
🔧 demo store generating: exchange odds 2026-10
🔧 demo store generating: exchange odds 2026-11
🔧 demo store 3/7 racinglines data ingest f1 --years 2024-2026
🔧 demo store 4/7 racinglines model forecast f1 --save --sims 2000
🔧 demo store 5/7 racinglines data pm-links-import f1
🔧 demo store 6/7 racinglines data pm-links-import f1 --exchange kalshi
🔧 demo store 7/7 ready
demo: the kart store is ready (f1 data; `racinglines db stats --demo kart`) Let's-a go! 🍄
╭─ 📦 database racinglines_demo_kart ──────────────────────────────────────────╮
│ 📅 calendar 🏁 results 🔮 model │
│ sports 8 athletes 20 model runs 1 │
│ leagues 8 athlete identifiers 20 race predictions 60 │
│ competitions 8 results 3,300 standings predictions 20 │
│ categories 11 splits 0 │
│ venues 27 source files 33 │
│ events 36 │
│ races 36 │
│ rounds 165 │
╰──────────────────────────────────────────────────────────────────────────────╯
coverage
competition year category events rounds results
───────────────────────────────────────────────────────────
f1_wdc 2024 DRV 12 60 1,200
f1_wdc 2025 DRV 12 60 1,200
f1_wdc 2026 DRV 9 45 900
Step 3: 📊 Backtest the model¶
Every past race priced as of before the weekend, before qualifying and before the race, with track features on and off, scored against the results and against uniform and grid baselines.
progress 0/1 building history (track features on)
📊 backtest, track features on
progress 10/33 2024 R10 rainbow-road
progress 20/33 2025 R08 mount-wario
progress 30/33 2026 R06 thwomp-ruins
progress 33/33 2026 R09 bowser-s-castle
📊 Track features ON: mean over 32 races
╭────────┬─────────────┬─────────────┬─────────┬────────┬──────────────────┬──────────╮
│ market │ stage │ model Brier │ uniform │ grid │ skill vs uniform │ log loss │
├────────┼─────────────┼─────────────┼─────────┼────────┼──────────────────┼──────────┤
│ win │ pre weekend │ 0.0431 │ 0.0475 │ – │ ▉ +9% │ 0.1518 │
│ │ pre quali │ 0.0405 │ 0.0475 │ – │ █▍ +15% │ 0.1388 │
│ │ pre race │ 0.0381 │ 0.0475 │ 0.0410 │ █▉ +20% │ 0.1266 │
├────────┼─────────────┼─────────────┼─────────┼────────┼──────────────────┼──────────┤
│ podium │ pre weekend │ 0.0988 │ 0.1275 │ – │ ██▎ +23% │ 0.3155 │
│ │ pre quali │ 0.0913 │ 0.1275 │ – │ ██▊ +28% │ 0.3058 │
│ │ pre race │ 0.0772 │ 0.1275 │ 0.0824 │ ███▉ +39% │ 0.2699 │
├────────┼─────────────┼─────────────┼─────────┼────────┼──────────────────┼──────────┤
│ top10 │ pre weekend │ 0.1662 │ 0.2500 │ – │ ███▎ +34% │ 0.5105 │
│ │ pre quali │ 0.1543 │ 0.2500 │ – │ ███▊ +38% │ 0.4897 │
│ │ pre race │ 0.1295 │ 0.2500 │ 0.1345 │ ████▊ +48% │ 0.4353 │
╰────────┴─────────────┴─────────────┴─────────┴────────┴──────────────────┴──────────╯
🏁 favourite won 34% of 32 races · rank correlation 0.83 · mean winner probability 22.7%
best call 2024 R04 Royal Raceway: Donkey Kong won at 48.6%
upset 2024 R08 Mount Wario: Donkey Kong won at 1.7% (favourite Peach)
progress 0/1 building history (track features off)
📊 backtest, track features off
progress 10/33 2024 R10 rainbow-road
progress 20/33 2025 R08 mount-wario
progress 30/33 2026 R06 thwomp-ruins
progress 33/33 2026 R09 bowser-s-castle
📊 Track features OFF: mean over 32 races
╭────────┬─────────────┬─────────────┬─────────┬────────┬──────────────────┬──────────╮
│ market │ stage │ model Brier │ uniform │ grid │ skill vs uniform │ log loss │
├────────┼─────────────┼─────────────┼─────────┼────────┼──────────────────┼──────────┤
│ win │ pre weekend │ 0.0437 │ 0.0475 │ – │ ▊ +8% │ 0.1629 │
│ │ pre quali │ 0.0407 │ 0.0475 │ – │ █▍ +14% │ 0.1391 │
│ │ pre race │ 0.0377 │ 0.0475 │ 0.0410 │ ██ +21% │ 0.1240 │
├────────┼─────────────┼─────────────┼─────────┼────────┼──────────────────┼──────────┤
│ podium │ pre weekend │ 0.1033 │ 0.1275 │ – │ █▉ +19% │ 0.3356 │
│ │ pre quali │ 0.0915 │ 0.1275 │ – │ ██▊ +28% │ 0.3104 │
│ │ pre race │ 0.0768 │ 0.1275 │ 0.0824 │ ███▉ +40% │ 0.2650 │
├────────┼─────────────┼─────────────┼─────────┼────────┼──────────────────┼──────────┤
│ top10 │ pre weekend │ 0.1879 │ 0.2500 │ – │ ██▍ +25% │ 0.5659 │
│ │ pre quali │ 0.1573 │ 0.2500 │ – │ ███▋ +37% │ 0.4944 │
│ │ pre race │ 0.1296 │ 0.2500 │ 0.1345 │ ████▊ +48% │ 0.4326 │
╰────────┴─────────────┴─────────────┴─────────┴────────┴──────────────────┴──────────╯
🏁 favourite won 38% of 32 races · rank correlation 0.83 · mean winner probability 23.1%
best call 2024 R04 Royal Raceway: Donkey Kong won at 52.3%
upset 2024 R08 Mount Wario: Donkey Kong won at 1.6% (favourite Peach)
Per-race rows -> /home/user/racinglines-public/data/demo/kart/runs/f1/backtests/backtest_20261014_0506.csv
Step 4: 🔮 Forecast the rest of the season¶
The next races (Rainbow Road is a sprint weekend) and both championships; --save stores the run the book and the web app read.
🔮 forecast 2026 · cutoff 2026-10-14 05:06 UTC · latest results 2026-10-04 14:00
🏁 R10 Rainbow Road Grand Prix (18 Oct)
╭─────────────┬──────────┬───────┬──────────────┬────────┬──────────────┬────────┬───────┬─────────╮
│ driver │ team │ win │ │ podium │ │ top 10 │ DNF │ exp pts │
├─────────────┼──────────┼───────┼──────────────┼────────┼──────────────┼────────┼───────┼─────────┤
│ Mario │ mushroom │ 26.4% │ ███▋ │ 58.7% │ ████████▏ │ 95.0% │ 3.2% │ 15.1 │
│ Luigi │ mushroom │ 18.8% │ ██▋ │ 49.7% │ ██████▉ │ 93.8% │ 3.1% │ 13.4 │
│ Bowser │ koopa │ 14.4% │ ██ │ 40.2% │ █████▋ │ 82.2% │ 13.9% │ 11.2 │
│ Peach │ royal │ 9.9% │ █▍ │ 33.1% │ ████▋ │ 86.7% │ 5.5% │ 10.2 │
│ Daisy │ royal │ 8.3% │ █▏ │ 29.6% │ ████▏ │ 84.4% │ 5.9% │ 9.5 │
│ Donkey Kong │ kong │ 8.0% │ █ │ 27.4% │ ███▊ │ 85.8% │ 3.5% │ 9.3 │
│ Bowser Jr. │ koopa │ 6.7% │ ▉ │ 23.6% │ ███▎ │ 75.2% │ 13.7% │ 8.1 │
│ Diddy Kong │ kong │ 2.8% │ ▍ │ 12.3% │ █▋ │ 72.9% │ 3.3% │ 5.8 │
│ Yoshi │ yoshi │ 1.6% │ ▏ │ 7.7% │ █ │ 60.1% │ 7.3% │ 4.2 │
│ Rosalina │ comet │ 1.2% │ ▏ │ 5.9% │ ▊ │ 55.5% │ 5.6% │ 3.6 │
╰─────────────┴──────────┴───────┴──────────────┴────────┴──────────────┴────────┴───────┴─────────╯
🏁 R11 Wario Stadium Grand Prix (01 Nov)
╭─────────────┬──────────┬───────┬──────────────┬────────┬──────────────┬────────┬───────┬─────────╮
│ driver │ team │ win │ │ podium │ │ top 10 │ DNF │ exp pts │
├─────────────┼──────────┼───────┼──────────────┼────────┼──────────────┼────────┼───────┼─────────┤
│ Mario │ mushroom │ 24.4% │ ███▍ │ 59.3% │ ████████▎ │ 95.4% │ 3.0% │ 15.0 │
│ Luigi │ mushroom │ 20.7% │ ██▉ │ 52.9% │ ███████▍ │ 94.8% │ 3.0% │ 14.0 │
│ Peach │ royal │ 15.6% │ ██▏ │ 44.2% │ ██████▏ │ 90.8% │ 5.9% │ 12.4 │
│ Bowser │ koopa │ 12.9% │ █▊ │ 37.3% │ █████▏ │ 82.2% │ 14.0% │ 10.8 │
│ Daisy │ royal │ 12.1% │ █▋ │ 36.9% │ █████▏ │ 89.1% │ 5.7% │ 11.2 │
│ Bowser Jr. │ koopa │ 4.6% │ ▋ │ 19.1% │ ██▋ │ 75.1% │ 13.7% │ 7.3 │
│ Donkey Kong │ kong │ 4.2% │ ▌ │ 18.4% │ ██▌ │ 82.0% │ 3.1% │ 7.6 │
│ Yoshi │ yoshi │ 2.1% │ ▎ │ 11.0% │ █▌ │ 69.3% │ 7.4% │ 5.4 │
│ Diddy Kong │ kong │ 1.0% │ ▏ │ 6.1% │ ▊ │ 61.1% │ 3.6% │ 4.0 │
│ Birdo │ yoshi │ 0.9% │ ▏ │ 5.3% │ ▋ │ 56.3% │ 7.3% │ 3.6 │
╰─────────────┴──────────┴───────┴──────────────┴────────┴──────────────┴────────┴───────┴─────────╯
🏆 2026 drivers' championship
╭──────────────┬────────┬──────────┬──────────┬────────────────┬────────╮
│ driver │ points │ expected │ champion │ │ top 3 │
├──────────────┼────────┼──────────┼──────────┼────────────────┼────────┤
│ Luigi │ 191 │ 234 │ 99.8% │ █████████████▉ │ 100.0% │
│ Mario │ 134 │ 182 │ 0.2% │ │ 99.1% │
│ Peach │ 106 │ 141 │ 0.0% │ │ 60.5% │
│ Bowser │ 99 │ 135 │ 0.0% │ │ 39.9% │
│ Daisy │ 62 │ 95 │ 0.0% │ │ 0.2% │
│ Donkey Kong │ 57 │ 85 │ 0.0% │ │ 0.2% │
│ Bowser Jr. │ 60 │ 85 │ 0.0% │ │ 0.1% │
│ Koopa Troopa │ 55 │ 58 │ 0.0% │ │ 0.0% │
│ Birdo │ 36 │ 48 │ 0.0% │ │ 0.0% │
│ Diddy Kong │ 28 │ 46 │ 0.0% │ │ 0.0% │
╰──────────────┴────────┴──────────┴──────────┴────────────────┴────────╯
constructors
team points expected champion
────────────────────────────────────────────────────────────────────
Mushroom Racing 325 416 100.0% ██████████████
Royal Racing 168 236 0.0%
Koopa Kart Works 159 220 0.0%
Kong Jungle Racing 85 132 0.0%
Yoshi Island GP 62 91 0.0%
finishing model coef {'g': 0.527, 'g_ease': -0.149, 'rp_rel': 0.041, 'rp_ease': 0.051, 'qp_rel':
0.08, 'street_g': 0.0} sigma 0.155; season drift (as-of) {'team_sd': 0.002652025069557153,
'driver_sd': 0.0005339299639313828}
Saved forecast run 2.
Step 5: 🏁 Run a live private book¶
Bowser's Castle (round 9) replayed on a simulated clock: the maker's book opens before practice, reprices after each session from the model's stage runs, 100 simulated takers trade against it, the book closes at lights out and settles from the results.
pre-weekend: priced (run #3)
2026-10-02T10:30:00+00:00 2026-09 pre-weekend: 80 markets, 54 quoted, 0 crowd fills, maker P&L +24.73
╭─ 🚦 Bowser's Castle Grand Prix 2026 (synthetic) · pre-weekend (1 of 7 · 2026-10-02T10:30 UTC) ─╮
│ │
│ driver fair move bid ask Polymarket Kalshi inventory │
│ ──────────────────────────────────────────────────────────────────────────────────────────── │
│ Mario 27.6% ███▎ 24.0% 31.0% 32.5% 36.0% -81 │
│ Luigi 21.4% ██▌ 18.0% 25.0% 11.1% 8.0% – │
│ Daisy 20.5% ██▍ 17.0% 24.0% 6.1% 5.7% – │
│ Peach 18.2% ██▏ 15.0% 22.0% 10.4% 11.2% – │
│ Bowser 3.6% ▍ 1.0% 8.0% 10.2% 10.5% -357 │
│ Bowser Jr. 2.1% ▎ – 6.0% 1.8% 2.1% – │
│ Yoshi 1.6% ▏ – 5.0% 1.6% 1.9% – │
│ Koopa Troopa 1.2% ▏ – 5.0% 7.2% 11.2% – │
│ │
│ 👥 crowd: 0 fills this update · 0 in all · $0 traded · 0 of 100 takers still betting │
│ 💰 maker P&L +24.73 (crowd +0.00, picks +24.73) │
│ next: after FP1 at 2026-10-02T13:00 UTC │
╰────────────────────────────────────────────────────────────────────────────────────────────────╯
after FP1: priced (run #4)
2026-10-02T13:00:00+00:00 2026-09 after FP1: 80 markets, 44 quoted, 4 crowd fills, maker P&L -75.09
╭─ 🔄 Bowser's Castle Grand Prix 2026 (synthetic) · after FP1 (2 of 7 · 2026-10-02T13:00 UTC) ─────╮
│ │
│ driver fair move bid ask Polymarket Kalshi inventory │
│ ────────────────────────────────────────────────────────────────────────────────────────────── │
│ Mario 29.1% ███▍ ▲ 1.5 26.0% 32.0% 32.5% 36.0% -66 │
│ Bowser 20.1% ██▍ ▲ 16.4 17.0% 23.0% 10.2% 10.5% -357 │
│ Luigi 19.3% ██▎ ▼ 2.1 16.0% 22.0% 11.1% 8.0% – │
│ Peach 16.0% █▉ ▼ 2.2 13.0% 19.0% 10.4% 11.2% – │
│ Daisy 11.1% █▎ ▼ 9.5 8.0% 14.0% 6.1% 5.7% – │
│ Koopa Troopa 1.9% ▏ ▲ 0.6 – 5.0% 7.2% 11.2% – │
│ Yoshi 0.7% ▼ 0.9 – 4.0% 1.6% 1.9% – │
│ King Boo 0.5% ▼ 0.6 – 4.0% 2.3% 1.8% – │
│ │
│ 👥 crowd: 4 fills this update · 4 in all · $294 traded · 4 of 100 takers still betting │
│ 💰 maker P&L -75.09 (crowd -51.91, picks -23.17) │
│ 🏁 fp1: P1 Mario · P2 Bowser · P3 Luigi │
│ next: after FP2 at 2026-10-02T16:30 UTC │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
… 79 lines cut (showing the first 39 and last 28 of 146) …
2026-10-04T17:00:00+00:00 2026-09 results: 80 markets, 0 quoted, 0 crowd fills, maker P&L -222.25
╭─ 🏁 Bowser's Castle Grand Prix 2026 (synthetic) · results (7 of 7 · 2026-10-04T17:00 UTC) ──────╮
│ │
│ driver fair move bid ask Polymarket Kalshi inventory │
│ ───────────────────────────────────────────────────────────────────────────────────────────── │
│ Luigi ✅ 31.4% ███▊ ▲ 4.5 – – 11.1% 8.0% -13 │
│ Daisy ❌ 20.5% ██▍ ▲ 8.5 – – 6.1% 5.7% -66 │
│ Mario ❌ 20.4% ██▍ ▼ 2.2 – – 32.5% 36.0% -66 │
│ Bowser ❌ 20.0% ██▍ ▲ 5.3 – – 10.2% 10.5% -1,058 │
│ Peach ❌ 6.5% ▊ ▼ 12.8 – – 10.4% 11.2% -132 │
│ King Boo ❌ 0.5% ▼ 0.3 – – 2.3% 1.8% -2,338 │
│ Koopa Troopa ❌ 0.4% ▼ 1.4 – – 7.2% 11.2% – │
│ Donkey Kong ❌ 0.2% = – – 0.8% – – │
│ │
│ 👥 crowd: 0 fills this update · 176 in all · $6,048 traded · 52 of 100 takers still betting │
│ 💰 maker P&L -222.25 (crowd -72.25, picks -150.00) │
│ 🏁 race: P1 Luigi · P2 Daisy · P3 Donkey Kong │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
simulated 2026-09 to 2026-10-04 17:00:00: 7 updates
╭─ 🏁 Bowser's Castle Grand Prix 2026 (synthetic) ─────────────────────╮
│ opened 2026-10-02T10:30 UTC │
│ settled 2026-10-04T17:00 UTC │
│ 💰 maker P&L -222.25 │
│ from the crowd -72.25 │
│ from the picks -150.00 │
│ 👥 fills 176 ($6,048 traded) │
│ bettors 83: 31 up, 52 down, best +1,297.32, worst -184.03 │
╰──────────────────────────────────────────────────────────────────────╯
Rich output, or plain
db stats, model backtest, model forecast, live run, live report and book map|price|settle print Rich
output (colour, tables, probability bars), also when piped. --plain on any command gives the plain text;
NO_COLOR=1 keeps the layout and drops the colour codes, which is how these outputs were captured
(CLI: Output).
Measured on a cloud container (one CPU, 2026-10-14, the capture's own timings): the store build 56 s, the backtest 45 s, the forecast 10 s, the live run 36 s, the book 2 s.
After the live run¶
The rehearsal left a settled event in the store. live status lists it, and live report writes the event report
(Markdown, charts and, with --pdf, a PDF, which needs weasyprint or a headless Chrome) under
data/demo/kart/runs/live/demo-2026-09/report/.
The report, with its own summary of the event and the files it wrote:
╭─ 🏁 Bowser's Castle Grand Prix 2026 (synthetic) ─────────────────────╮
│ opened 2026-10-02T10:30 UTC │
│ settled 2026-10-04T17:00 UTC │
│ 💰 maker P&L -222.25 │
│ from the crowd -72.25 │
│ from the picks -150.00 │
│ 👥 fills 176 ($6,048 traded) │
│ bettors 83: 31 up, 52 down, best +1,297.32, worst -184.03 │
╰──────────────────────────────────────────────────────────────────────╯
📄 report files
what file
─────────────────────────────────────────────────────────────
md runs/live/demo-2026-09/report/report.md
html runs/live/demo-2026-09/report/report.html
pnl.svg runs/live/demo-2026-09/report/pnl.svg
scorecard.svg runs/live/demo-2026-09/report/scorecard.svg
Price a sportsbook's lines¶
The pack carries a generic sportsbook's lines on rounds 10 and 11 (racinglines/demo/packs/kart/book.toml), one
per F1 pricing feature. book map resolves every leg to a race, athletes and a market kind by exact keys; book
price adds the model's fair, the linked exchange price, the book's implied probability and the EV against each;
book settle adds each leg's result and payout once the race is in. --json on any of them prints the same result
as JSON (Sportsbook slips).
demo: the demo store's synthetic data (made-up names, results and prices); nothing is traded
book map
id selection kind status race reason
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
win Super Mario race_win mapped 34
win-no Luigi not to win race_win mapped 34
podium Peach race_podium mapped 34
top5 Daisy race_top5 mapped 34
top10 Bowser race_top10 mapped 34
p2 Luigi race_p2 mapped 34
pole Mario race_pole mapped 34
fl Luigi race_fastest_lap mapped 34
h2h Daisy v Peach race_h2h mapped 34
mover Yoshi race_biggest_mover mapped 34
spr-win Mario race_sprint_win mapped 34
spr-pole Luigi race_sprint_pole mapped 34
red No race_red_flag mapped 34
sgp-joint Mario win + Luigi combo mapped 34
podium
└ 14.1 race_win Mario (f1 mapped 34
2026-10)
└ 14.2 race_podium Luigi mapped 34
(f1 2026-10)
sgp-product Peach podium + combo mapped 34
Daisy top 10
└ 15.1 race_podium Peach mapped 34
(f1 2026-10)
└ 15.2 race_top10 Daisy mapped 34
(f1 2026-10)
parlay Mario wins Rainbow combo mapped 34, 35
Road and Wario
Stadium
└ 16.1 race_win Mario (f1 mapped 34
2026-10)
└ 16.2 race_win Mario (f1 mapped 35
2026-11)
typo Maryo race_win unmapped 34 leg 17: driver
'Maryo' is not an
exact name in race
34's field
└ 17 race_win (f1 unmapped 34 driver 'Maryo' is
2026-10) not an exact name
in race 34's field
book_demo · event 2026-10 · f1 · captured 2026-10-15T09:00Z · odds decimal · USD
╭────────────────── unmapped lines ───────────────────╮
│ typo │
│ exact keys only: fix the book file or its [aliases] │
╰─────────────────────────────────────────────────────╯
Every leg mapped by its exact keys. Now the prices:
demo: the demo store's synthetic data (made-up names, results and prices); nothing is traded
book price
model
id selection odds book model market EV model EV market method
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
win Super 3.20 31.2% 26.4% 65.4% -15.6% +109.3% single
Mario
win-no Luigi not 1.30 76.9% 81.2% 87.2% +5.6% +13.4% single
to win
podium Peach 2.40 41.7% 33.1% 11.6% -20.5% -72.2% single
top5 Daisy 1.90 52.6% 50.2% – -4.6% – single
top10 Bowser 1.25 80.0% 82.2% – +2.7% – single
p2 Luigi 4.50 22.2% – 32.8% – +47.6% single
pole Mario 2.75 36.4% 35.0% 66.3% -3.9% +82.3% single
fl Luigi 5.00 20.0% – – – – single
h2h Daisy v 2.10 47.6% 47.0% 41.5% -1.4% -12.8% single
Peach
mover Yoshi 6.00 16.7% 8.6% – -48.5% – single
spr-win Mario 2.90 34.5% 24.8% – -28.0% – single
spr-pole Luigi 4.00 25.0% 16.1% – -35.6% – single
red No 1.45 69.0% – – – – single
sgp-joint Mario win 4.20 23.8% 13.1% 40.0% -44.9% +68.1% product
+ Luigi
podium
└ 14.1 race_win – 26.4% 65.4%
Mario (f1 polymarket
2026-10)
└ 14.2 race_podi… – 49.7% 61.2%
Luigi (f1 polymarket
2026-10)
sgp-product Peach 2.50 40.0% 28.0% – -30.1% – product
podium +
Daisy top
10
└ 15.1 race_podi… – 33.1% 11.6%
Peach (f1 polymarket
2026-10)
└ 15.2 race_top10 – 84.4% –
Daisy (f1
2026-10)
parlay Mario wins 9.60 10.4% 6.4% 35.9% -38.2% +244.7% single x
Rainbow single
Road and
Wario
Stadium
└ 16.1 race_win 3.2 31.2% 26.4% 65.4%
Mario (f1 polymarket
2026-10)
└ 16.2 race_win 3.0 33.3% 24.4% 54.9%
Mario (f1 polymarket
2026-11)
typo Maryo – – – – – –
book_demo · event 2026-10 · f1 · captured 2026-10-15T09:00Z · odds decimal · USD
╭───────────────────────────────────── flags ──────────────────────────────────────╮
│ sgp-joint: race 34: 2 legs on one race, correlated: EV approximate │
│ sgp-joint: market: product of leg prices on one race, correlated: EV approximate │
│ sgp-product: race 34: 2 legs on one race, correlated: EV approximate │
│ parlay: legs on 2 races: independent across races (product) │
╰──────────────────────────────────────────────────────────────────────────────────╯
╭────────────────── unmapped lines ───────────────────╮
│ typo │
│ exact keys only: fix the book file or its [aliases] │
╰─────────────────────────────────────────────────────╯
╭────────────────────────────────────────── assumptions ───────────────────────────────────────────╮
│ • EV is per unit staked: probability x decimal payout - 1; decimal payout = 1 / the book's │
│ implied probability. │
│ • Legs on different races are independent: the slip probability is the product of their │
│ probabilities. │
│ • Legs on the same race are priced jointly from simulations when they are available (passed in, │
│ or a stored combo run with exactly these legs); otherwise the product of the marginals, flagged │
│ 'correlated: EV approximate'. │
│ • The market's slip probability is the product of its legs' prices: no exchange lists the slip │
│ itself. │
│ • Model and market are shown side by side, never blended (owner, 2026-10-07). │
│ • The market price is the freshest linked exchange's mid (bid/ask midpoint, else its last price, │
│ else the tape's). │
│ blend: none (owner, 2026-10-07; docs/sportsbook/slips.md) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
And the settlement:
demo: the demo store's synthetic data (made-up names, results and prices); nothing is traded
book settle
id selection odds result payout profit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
win Super Mario 3.20 pending – –
win-no Luigi not to win 1.30 pending – –
podium Peach 2.40 pending – –
top5 Daisy 1.90 pending – –
top10 Bowser 1.25 pending – –
p2 Luigi 4.50 pending – –
pole Mario 2.75 pending – –
fl Luigi 5.00 manual – –
h2h Daisy v Peach 2.10 pending – –
mover Yoshi 6.00 pending – –
spr-win Mario 2.90 pending – –
spr-pole Luigi 4.00 pending – –
red No 1.45 manual – –
sgp-joint Mario win + Luigi podium 4.20 pending – –
└ 14.1 race_win Mario (f1 2026-10) pending
└ 14.2 race_podium Luigi (f1 2026-10) pending
sgp-product Peach podium + Daisy top 10 2.50 pending – –
└ 15.1 race_podium Peach (f1 2026-10) pending
└ 15.2 race_top10 Daisy (f1 2026-10) pending
parlay Mario wins Rainbow Road and Wario Stadium 9.60 pending – –
└ 16.1 race_win Mario (f1 2026-10) pending
└ 16.2 race_win Mario (f1 2026-11) pending
typo Maryo – – – –
book_demo · event 2026-10 · f1 · captured 2026-10-15T09:00Z · odds decimal · USD
╭────────────────── unmapped lines ───────────────────╮
│ typo │
│ exact keys only: fix the book file or its [aliases] │
╰─────────────────────────────────────────────────────╯
Rounds 10 and 11 have not been raced in the pack, so every line settles as pending.
Where things go¶
| What | Where | Notes |
|---|---|---|
| The demo database | racinglines_demo_kart, on the same server as DATABASE_URL |
RACINGLINES_DEMO_DATABASE_URL moves it |
| The demo data folder | data/demo/kart/ (gitignored) |
the generated FastF1 files under raw/, the exchange links under archive/, run outputs under runs/, the live spec under live/; RACINGLINES_DEMO_DATA moves it |
| The build marker | data/demo/kart/demo-store.json |
a fingerprint of the pack and its generator: both the database and the folder are rebuilt when the pack changes; delete the marker (or drop the database) to rebuild by hand |
Not in the quickstart yet: strategy replay f1 (the maker replay needs a recorded exchange tape of price history and
trades per market; the kart pack carries quotes only, not a tape).
Rebuild the data yourself¶
The demo is synthetic. To rebuild the real history locally, every source the code ingests is fetched with your own machine's network access, and with your own key where one is needed. Keys are never typed on the command line or committed: put them in your environment, or in a gitignored env file you fill with a hidden prompt, e.g.
# LOCAL (Mac): store a key without echoing it or leaving it in the shell history
read -rs -p "WUNDERGROUND_API_KEY: " k && printf 'export WUNDERGROUND_API_KEY=%s\n' "$k" >> .env.local && unset k
chmod 600 .env.local && source .env.local # .env.local: add it to .git/info/exclude if it isn't ignored
| Source | What | Your own key? | Commands | Code |
|---|---|---|---|---|
| F1 live-timing archive (via FastF1) | F1 sessions: results, laps, schedule | No | racinglines data fetch f1 --years 2020-2026, then racinglines data ingest f1 |
racinglines/sources/fastf1/fetch.py, ingest.py |
| ChronoRace | UCI downhill results | No (the results key comes from ChronoRace's public page data) | racinglines data download mtb_dh, then racinglines data ingest mtb_dh |
racinglines/sources/chronorace/download.py, ingest.py |
| NASCAR content feeds (cf.nascar.com) | NASCAR Cup results and laps | No | racinglines data fetch nascar, then racinglines data ingest nascar |
racinglines/sources/nascar/fetch.py |
| MotoGP results API (api.motogp.pulselive.com) | MotoGP classifications | No | racinglines data fetch motogp, then racinglines data ingest motogp |
racinglines/sources/motogp/fetch.py |
| ProCyclingStats | road cycling results | No key; needs pip install cloudscraper selectolax, and runs from a home connection |
racinglines data fetch cycling (see racinglines data fetch cycling -h) |
racinglines/sources/pcs.py, racinglines/cli/cycling.py |
| Polymarket (Gamma API) | market links, prices, trades | No (public market data) | racinglines markets sync, racinglines markets history, racinglines markets trades |
racinglines/markets/polymarket/sync.py |
| Kalshi (Trade API v2, market data) | market links, prices, trades | No for market data; a key (KALSHI_API_KEY_ID, KALSHI_PRIVATE_KEY_PATH, from your Kalshi account's API keys page) only for the portfolio and order endpoints, which a rebuild doesn't use |
racinglines markets --exchange kalshi sync (then history, trades) |
racinglines/markets/kalshi/client.py, trade.py |
| Open-Meteo | weather forecasts per event | No | racinglines weather fetch |
racinglines/weather/open_meteo.py |
| Weather Underground | weather forecasts (optional source) | Yes: WUNDERGROUND_API_KEY, the key a Weather Underground personal weather station owner gets; untested (no key has been probed) |
racinglines weather probe, racinglines weather fetch |
racinglines/weather/wunderground.py |
| IndyCar, WEC, SailGP | results (sources present, not wired into an ingest) | unknown | none yet | racinglines/sources/indycar/, wec/, sailgp/ |
Recorded exchange history older than what the exchanges still serve exists only on the VM: a rebuild has whatever
the exchanges return today. Respect each source's terms of use (e.g. sports/motogp.toml [results].terms) and its
rate limits; the fetchers pace themselves and are safe to re-run.
Next steps¶
-
CLI reference
Every group and command, with its
-houtput and a real run where one is captured. -
Demo data packs
What
--demodoes, what a pack is, the kart pack, and how to add one of your own. -
Ask Claude instead
The MCP server: the same data and simulations as typed tools for Claude Code, Claude Desktop or the CLI.
-
The web app
Markets, Trade, History and Lab at racinglines.bet, and how to run the app yourself.