sportsdata-agents

Documentation: Architecture & system design ·
Repo structure · Agent roster ·
Operating it · Security & cost controls ·
Updating the app · Next steps ·
Releasing. These are kept current by the
docs_keeper ops agent.

An agentic platform that turns the sportsdata-mcp
tool catalogue into whatever desk you need — a cross-bookmaker trading desk, a
sports-analytics / coaching team, a fantasy desk, or a custom mix. It's one composable
team of LLM agents over a shared data backbone: they gather and analyse sports data, model
outcomes, compare odds, optimise fantasy lineups, and track performance — you turn on the
agents and modules that fit your purpose. A separate engineering team of agents maintains the
codebase via CI-gated PRs.

You assemble a workspace from modules we build and you select — Match Analytics, Fantasy,
Racing, Trading/Betting, and more. Nothing is privileged: a Trading module and a Coaching module
are equal citizens of the catalogue. Trading/Betting is just one module (and jurisdiction-gated),
so a workspace without it is a pure analytics tool (bigger market, lower compliance surface).

Advisory only — no agent ever places a bet or moves money.

The platform informs. It surfaces recommendations, the statistics you asked for,
and the bets you may choose to place (with stakes, books, and reasoning). You
always take the action. This is a research and analytics tool, not a betting operator.

Design

🛠️ BUILD_PLAN.md — the technical, phase-by-phase implementation
checklist to tick off while coding (P0 → P4, milestones, exit gates).

🖥️ P4_DESKTOP_PLAN.md — the P4 replan: a downloadable
desktop app (the Cursor-style harness on the user's machine) instead of hosted SaaS —
shell options, process/storage/secrets architecture, trade-offs, revised milestones.

📐 PLAN.md — the full architecture: the two-plane design, the agent
roster, the user-customizable agent-spec format, the data model, orchestration & model
selection, sandboxing, interfaces (CLI → Slack → web), multi-tenancy / SaaS-readiness,
the self-improvement loop, the delivery roadmap, and a decision register with the
pros and cons of every choice.

What's built (P0–P4 complete — a downloadable desktop app)

The agent team (27 specs in src/sportsdata_agents/specs/ — 20 product, 7 ops): an orchestrator that
routes and delegates; odds/stats specialists over the live data plane; a racing
analyst (racecards, results, cross-book win/place) and a prediction-market
analyst (Kalshi/Polymarket + the exchange-vs-book edge); a modelling agent
(general model development — features, calibration, Brier/log-loss, logistic regression,
XGBoost skills); a value scout (vig removal, +EV detection, cross-book best price); a
backtester (entry-at-prediction-time discipline, CLV vs close); bankroll manager, bet
tracker and bet notifier (advisory only); a market steward that maintains the market
dictionary as data; an arb hunter (deterministic cross-book arbitrage incl.
exchange-vs-book); a news scout over X/official feeds; a fantasy advisor; Slack manager;
data-analysis agent (sandboxed run_python); a generalist catch-all that grows the
platform (writes reusable skills, builds new agents as it learns your needs); concierge
— plus seven ops agents (health, improver, reviewer, evals, triage, site manager,
docs keeper) on the separate operations plane.
Every answer is grounded (numbers must come from tool results — a deterministic
verifier checks), sourced (provenance per tool call), budgeted (one cost ceiling
per team run) and audited (runs/tool-calls/costs land in the DB when configured).

The odds warehouse (agents ingest): discovery-driven, capture-everything ingestion
across 10 bookmakers — Sportsbet, TAB, Unibet/Kambi, Entain (Ladbrokes/Neds),
Pinnacle, PointsBet, BetR, FanDuel (US sportsbook + racing) — plus two prediction
markets (Kalshi, Polymarket) — in five tiers:

hot (5–30 min): every provider's own discovery route → all sports, all
competitions, primary + inline markets — nothing hardcoded, new comps/sports appear
automatically;
full-book (60 min): every market of every fixture (rotating windows over the
megabyte-scale per-fixture firehoses);
racing (~3 min): win+place cards from TAB, Sportsbet, BetR, PointsBet, Unibet,
FanDuel, soonest races first;
racing futures (60 min): ante-post Cup/carnival outrights from TAB, Sportsbet,
PointsBet, Unibet;
prediction markets (15 min): Kalshi and Polymarket exchange quotes captured as
decimal odds (1/price) — event contracts read like any book's board (Polymarket's
Gamma edge is geo-gated; the feed runs wherever the edge answers).

Sports futures (premiership winners, Brownlow, NFL/MLB futures, …) ride the hot tier:
Kambi competitions.json, Sportsbet's Outrights route, Entain/BetR/TAB inline.
Normalizers never filter by market name — canonical_market() only renames onto shared
keys (h2h/spread/total/win/place), driven by a market dictionary that is data
(packaged seed + steward-maintained local overrides; merge safety enforced in the tools:
qualifier markets can never alias into base families). Raw observations land in
odds_snapshots (prunable; carries the parsed advertised start time); the
change-point-only prices series is what models and backtests read.

Event resolution (agents resolve): deterministic, LLM-free mapping of every book's
private event ids onto shared fixtures (fuzzy-subset team-token matching, swap-tolerant,
windowed on the event's advertised start so futures join months ahead; ambiguity is
counted and skipped, never guessed). That join powers cross_book_prices (best price per
selection across every mapped book), resolution-aware backtest settlement (a result
recorded under any book settles every book's series, with side-orientation translated
between books' listing orders), and the find_fixture / best_prices agent tools.

The quant loop: save_model refuses uncalibrated models → record_predictions
(backdatable predicted_at; side-relative selections must name their book) →
run_backtest (flat-stake replay, no lookahead: entry is the prevailing price at
prediction time; CLV vs close, or vs a sharp benchmark via clv_book="Pinnacle") →
agents results settles from racing placings + official NBA/AFL/NRL scoreboards →
agents eval gates golden metrics (calibration, CLV backtest, grounding, event
resolution) against a committed baseline.

Quickstart

# 1) The data plane (sibling checkout, its own venv)
git clone https://github.com/DanielTomaro13/sportsdata-mcp.git
cd sportsdata-mcp && python -m venv .venv && .venv/bin/pip install -e . && cd ..

# 2) The agent plane
git clone https://github.com/DanielTomaro13/sportsdata-agents.git
cd sportsdata-agents && python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# 3) Configure (.env — see .env.example)
#    - ONE model key: ANTHROPIC_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY /
#      GROQ_API_KEY / OPENAI_API_KEY  (Gemini + Groq have free tiers)
#    - point at the data plane binary:
#      SPORTSDATA_AGENTS_MCP_COMMAND=["/abs/path/to/sportsdata-mcp/.venv/bin/sportsdata-mcp"]

# 4) Database (audit rows + the odds warehouse). SQLite works out of the box:
#      SPORTSDATA_AGENTS_DATABASE_URL="sqlite+aiosqlite:////path/to/warehouse.db"
#    or Postgres via docker compose up -d; then:
.venv/bin/alembic upgrade head

# 5) Talk to the team
.venv/bin/agents run "Using MLB data: which team does Aaron Judge play for?"
.venv/bin/agents chat                       # interactive REPL (/exit to quit)
.venv/bin/agents run "..." --agent value_scout        # one agent instead of the team
.venv/bin/agents list && .venv/bin/agents lint        # spec catalogue + validation

The data loop

.venv/bin/agents ingest --once              # one capture cycle across all due feeds
.venv/bin/agents ingest --once --feed tab_racing_futures   # a single feed
.venv/bin/agents ingest --loop              # scheduled loop (per-feed cadence)
.venv/bin/agents schedule --cron 60         # THE CONDUCTOR: one cron line runs everything
.venv/bin/agents schedule --status          #   per-job state, failures, pacing
.venv/bin/agents schedule --dry-run         #   what this tick would run
.venv/bin/agents ingest --once --prune 90   # retention for raw snapshots
.venv/bin/agents resolve                    # map book events -> shared fixtures
.venv/bin/agents resolve --dry-run          # count without writing
.venv/bin/agents results                    # settle: racing placings + league finals (cron daily)
                                            #   first-party NBA/AFL/NRL/MLB; ESPN scoreboard for the rest
.venv/bin/agents steward                    # market_steward dictionary audit (cron weekly)
.venv/bin/agents dictionary-promote --write # promote steward overrides into the committed seed
.venv/bin/agents movement --event <id>      # change-point series for one event
.venv/bin/agents eval --baseline src/sportsdata_agents/evals/baseline.json
.venv/bin/agents refresh-books              # weekly: re-verify bookmaker ids

The ingest worker runs the MCP as a scoped subprocess per provider group and tolerates
per-feed failures (one book down never sinks the cycle). Known exclusions, by policy or
upstream fault: NBA CDN (aggregator — books of record only), Betfair (public key returns
no prices from AU; code ready for an authed key), Entain racing GraphQL (upstream
persisted-query drift; Entain sports REST — including its outrights — is unaffected).

Testing

.venv/bin/pytest                  # offline suite (default: not live, not eval) — CI runs this
.venv/bin/pytest -m live          # real MCP + real model (needs a key; ~cents or free tier)
.venv/bin/pytest -m eval          # golden eval cases, graded for factual accuracy
.venv/bin/ruff check . && .venv/bin/mypy src   # the other two gates

Status

P4 complete — code-ready to ship. The platform is a downloadable desktop app
(the "Cursor for sports data" model): agents app runs the gateway + the conductor
in one supervised process on the user's machine — their compute, their warehouse,
their own odds capture, BYO model key. On top of P0–P3 (the operations plane and
its merged self-improvement PRs, the line monitor + cross-book arbitrage watch
with honesty re-measurement, prediction markets beside the bookmakers, fantasy +
agent-builder + Discord), P4 added: the web chat UI with the
learned-skills panel (everything is free and open source — the old tier/licensing
machinery is dormant, see docs/SECURITY.md); the
macOS packaging + signing pipeline (tag → notarized DMG, pending only the Apple
Developer ID); a signed OTA data feed; daemon hardening (DNS-rebind guard,
crash-restart supervision); the generalist growth loop; and the operator
console (agents config|costs|ops status + the in-app operator panel, gated by a
signed operator licence claim — on a release build the SPORTSDATA_OPERATOR env
var is ignored; see docs/SECURITY.md). The chat UI has since
grown into a full agentic workbench: provider on/off toggles, expandable
per-reply reasoning traces, agent activity views, a live monitors pane
(arb / line-move / value alerts), per-agent model pins, per-conversation model +
data-provider scope, and an in-app marketplace that hands checkout off to the
browser (no payment logic in the app). What remains to go live is account
setup, not code — see docs/NEXT_STEPS.md, the milestone log
in docs/history/BUILD_PLAN.md, and
POST_DEV.md for everything built-but-switched-off.

Support this project

sportsdata-agents is free and MIT-licensed, with no paid tier and nothing gated.
If it's useful to you, you can support the work at
ko-fi.com/danieltomaro — optional, and a
star or a good bug report helps just as much.