using-sports-data

name	using-sports-data
description	The Wayfinder sports data catalog — every canonical resource, its params, and which sports support it; betting (odds/props/futures) coverage per league; Lab (backtesting) specifics; id/season/category conventions.
metadata	{"tags":"wayfinder, sports, betting, props, odds, backtesting, lab"}

What you need to know (TL;DR)

All sports data flows through three MCP tools backed by the backend gateway (the provider key never leaves the backend; the surface is provider-agnostic):

• wayfinder_sports_snapshot — bounded live reads (scoreboard/odds/props/injuries/lookups/stats).
• wayfinder_sports_provider — the full façade: action="catalog" lists every callable endpoint_id with supported_leagues per data endpoint — that catalog is the runtime source of truth for "which sports support what"; action="call" invokes one.
• wayfinder_sports_backtest_state — canonical run/job monitoring for Lab backtests.

An unsupported (resource, sport) combo returns resource_unavailable_for_league with the leagues that DO support it — never guess availability, read the error or the catalog. Within one task, treat that error as a task-local unavailable-resource guard: do not retry the same (endpoint_id, sport) combo for every game/match.

Leagues: nba nfl mlb nhl wnba ncaaf ncaab ncaaw cbb epl laliga seriea bundesliga ligue1 ucl mls worldcup mma f1 atp wta pga cs2 lol dota2. Lab (backtesting) = nba/nfl/nhl/mlb only. Common wrong guesses → right slug: fifa/fiba → worldcup; soccer → a league slug (epl/laliga/ucl/...); football → nfl; tennis → atp/wta; golf → pga. An invalid slug returns a 400 listing the valid choices — read it, don't keep guessing.

Canonical resources (what each returns, key params)

Resource ids are generic and resolve per-league (e.g. competitors = players/fighters/drivers; events = games/matches/MMA events/F1 sessions/golf tournaments). Call shape: sports_provider(action="call", endpoint_id="data.<resource>.<list|get>", sport=..., query={...}, path_params={...}).

endpoint_id	Returns	Key params
data.events.list / data.event.get	schedule/fixtures + results	query: dates[], seasons[], per_page; get: path_params.id
data.teams.list / data.team.get	teams / clubs / constructors	query.per_page
data.competitors.list / .get	players / fighters / drivers	query: search, player_ids (array), per_page
data.competitors_active.list	current rosters only	as above
data.standings.list	standings / rankings / driver standings	query.season (most team sports require it)
data.team_standings.list	constructor/team standings (F1)	query.season
data.player_stats.list	per-game logs	query: player_ids (array), seasons[], dates[], per_page, postseason
data.player_season_stats.list	player season totals	query: season, player_ids where supported; NHL is per-player: path_params.player_id
data.season_averages.list	per-player season averages (NBA-family)	query: season, player_id; path_params.category + query.type for categorized
data.team_season_averages.list	team season averages	query: season, season_type (regular/playoffs), type (base/advanced); path_params.category
data.team_stats.list	team per-game stats	query: game_id/season
data.team_season_stats.list	team season stats	query.season; NHL per-team: path_params.team_id
data.player_advanced_stats.list	advanced metrics	query: seasons[], player_ids; NFL: path_params.category = rushing/passing/receiving
data.leaders.list	stat leaders	query: season, stat_type
data.injuries.list	injury/availability report	query.per_page
data.box.list / data.box.live	box scores (historical / live)	query.date / none
data.lineups.list, data.plays.list	lineups, play-by-play	query.game_id (game-scoped)
data.matchups.list	tennis head-to-head; MLB batter-vs-pitcher	tennis: query player ids; MLB versus: batter/pitcher ids
data.career_stats.list	career stats (tennis)	query.player_id
data.shots.list	soccer shot maps with xG	query.match_id/game_id depending on league
data.match_events.list	soccer goals/cards/subs	query.match_id/game_id depending on league
data.momentum.list, data.pregame_forms.list	soccer momentum / recent form where catalog-supported; not guaranteed for every soccer-family league	query.match_id/game_id depending on league
data.rosters.list	rosters; NFL depth charts	soccer: query; NFL: path_params.team_id
data.results.list	F1 session results / PGA tournament results / MMA fight results	query: season/event/fight/tournament filters
data.qualifying.list, data.pit_stops.list, data.laps.list	F1 detail (plan-gated upstream)	query session/event ids
data.venues.list	circuits / stadiums / courses	—
data.round_stats.list	PGA strokes-gained round stats	query tournament/player
data.splits.list, data.plate_appearances.list	MLB splits / plate appearances	query player/season
data.pitcher_pitch_stats.list, data.hitter_pitch_stats.list	MLB pitch-type breakdowns	query player/season
data.conferences.list, data.bracket.list	college conferences / March Madness bracket	query.season
data.player_contracts.list, data.team_contracts.list	NBA salaries/payroll (plan-gated upstream)	query
data.shot_locations.list	WNBA shooting zones	query player/season
data.odds.list	odds context	snapshot: event_id/game_id/fight_id/tournament_id OR date; façade: provider-specific ids
data.player_props.list	player prop lines + over/under odds	snapshot: event_id; façade: game_id, match_id, or tournament_id
data.futures.list	outright/futures odds	snapshot: season, optional event_id/market_type; façade: provider-specific filters

Which sports have what (highlights — catalog is authoritative)

• nba — richest: full stats family (game logs, season averages + categories general/clutch/shooting/playtype/tracking/hustle/defense/shotdashboard with type sub-param, team averages incl. pace/def_rating under type=advanced), advanced stats, box/live box, lineups, plays, leaders, injuries, contracts (plan-gated), odds + player props (the only league on the absolute v2 betting surface — handled transparently).
• nfl — game logs, season stats, team stats + team season stats, advanced rushing/passing/receiving (via category), per-team depth-chart rosters (path_params.team_id), plays, injuries, standings, odds + props.
• mlb — game logs, season stats, batter-vs-pitcher matchups, splits, plate appearances, pitch-type stats (pitcher + hitter), lineups, plays, injuries, odds + props.
• nhl — box scores, plays, injuries, standings; season stats are per-player/per-team id-scoped (no flat game-log endpoint); player/team leaders; odds + props.
• wnba — NBA-style stats + advanced + shot_locations; odds + props.
• soccer leagues (epl/laliga/seriea/bundesliga/ligue1/ucl/mls) — matches, rosters, injuries, standings, player/team match stats, xG shots, match events, momentum and pregame forms where the catalog lists support; odds + props; futures for ucl. EPL serves from its v2 API transparently.
• worldcup — matches, standings/results, odds, player props, and futures where live. Do not call data.pregame_forms.list for worldcup unless the runtime catalog explicitly lists worldcup in supported_leagues; current resource_unavailable_for_league means use standings/results plus web/news research for pregame form.
• tennis (atp/wta) — players, matches, rankings (as standings), head-to-head matchups, match stats, career stats; odds only.
• mma — fighters, events (cards), fight results (data.results.list), fight stats, rankings; odds only.
• f1 — drivers, constructors (teams), sessions (events), qualifying, results, laps, pit stops, driver + team standings, venues; futures only (no per-race odds). Much of the deep telemetry is plan-gated upstream — expect resource_unavailable_for_league if unentitled.
• pga — players, tournaments, results, strokes-gained round stats, venues (courses); futures + props, no match odds.
• college (ncaaf/ncaab/ncaaw/cbb) — teams, players, games, standings, plays, conferences, bracket (ncaab/ncaaw March Madness); odds only, no props.
• esports (cs2/lol/dota2) — teams/players/matches (cs2 deepest: match/map stats); no betting.

Betting coverage map

Markets	Leagues
odds + player props	nba, nfl, mlb, nhl, wnba, epl, laliga, seriea, bundesliga, ligue1, mls, ucl, worldcup
odds only	ncaaf, ncaab, ncaaw, cbb, mma, atp, wta
futures	ucl, worldcup, f1, pga
none	cs2, lol, dota2

Sportsbook odds/props/futures are optional context, never the executable price. Wayfinder sports views are actionable only against Polymarket or Hyperliquid prediction market books. Compute edges with wayfinder_paths.quant.sports_props.market_edge(...) or the prediction-market quant helpers against PM/HL order-book prices.

Conventions that bite

• Arrays: list-valued query params just work — query={"player_ids": [161, 1057262518]} bulk-fetches in one call (the gateway maps to the provider's key[] form). Batch a whole slate's game logs in ONE data.player_stats.list call.
• Ids are one namespace per sport: the player_id in props, game logs, and players are the same id space (newer players just have huge ids). Hydrate names via data.competitors.list with player_ids.
• Seasons: integer start-year (2025 = the 2025-26 NBA season). season_type: regular/playoffs where supported; game logs accept postseason true/false.
• Id-scoped resources: where the error or this doc says per-team/per-player, pass path_params={"team_id": ...} or {"player_id": ...} (NFL rosters, NHL season stats).
• Snapshot id convention: prefer event_id from scoreboard cards. The backend maps it to game_id for US team sports, match_id for soccer/World Cup props, fight_id/event_id for MMA odds, tournament_id for PGA props and tennis tournament odds, and event_ids[] for F1 futures. game_id remains a legacy alias.
• Provider façade id convention: use the exact provider filter requested by the endpoint (game_id, match_id, fight_id, tournament_id, event_ids[], etc.); call catalog or read errors instead of guessing.
• Caching: non-live data (stats/averages/rosters) is cached server-side for hours — repeats are cheap; odds/props/futures stay near-live (~15s). Still batch.
• Pagination: per_page (max 100) + cursor in meta.next_cursor where present.

Scripted analysis (inside core_run_script)

Betting analysis is a FUNNEL that starts from the executable boards: (1) ENUMERATE what's tradeable — the Polymarket per-game event (get_event on the {league}-{away}-{home}-{date} slug) and Hyperliquid HIP-4 outcomes — into a candidate table; (2) INFORMATION via sports data and the canned pipelines below where useful (complete fetches, model features, optional sportsbook-context market math; never pull odds from the web); (3) TRIAGE candidates by liquidity and fair-value delta (hypothesized fair probability/range minus executable PM/HL price); use PM/HL cross-venue differences as venue-noise/liquidity sanity checks, not the main objective; (4) DEEP-DIVE survivors with whatever data sharpens the number (full matchup history across seasons, comparable players vs that opponent, minutes/usage given injuries/lineups — multi-season player_stats, matchups, advanced stats), each input a weighted evidence card; (5) GATE per candidate and answer with the annotated board. MODELING is the agent's judgment: game_slate separates an INFORMATION section (facts) from a labeled REFERENCE MODEL (one opinion — adjust or replace it; --data-only for facts alone), and your own view is expressed as evidence cards gated through sports_posterior over the executable prior:

Broad prop/crossbet scans are sports-first, with novelty second. For broad "any props worth taking/selling" requests, first run cheap category discovery across real sports markets: match outcomes/game lines, visible player/team stat props, goals, points, totals/bands, exact score, more-markets, and specials. Then scan announcer-word, broadcast, entertainment, and other bespoke PM/HL props as a secondary novelty bucket, not the default center of the answer; secondary means scan after sports props, not skip. Do not stop at the first category that returns results. If search surfaces more-markets, specials, exact-score, or announcer/broadcast event groups, hydrate the top liquid/relevant event before any global prop conclusion. Hydrate discovered event ladders, inspect resolution text, and gate by spread/liquidity. It is valid to return BUY (heuristic) / SELL (heuristic) when the relative-pricing gap is obvious, but do not center word/phrase markets unless the user explicitly asked for broadcast props or they are the best surfaced board after the scan. Include categories scanned/found/hydrated /skipped/not found/unavailable. A broad NO EDGE claim is allowed only after surfaced categories are hydrated or explicitly skipped with reason; otherwise scope it to checked categories. For live sportsbook player_props, default to limit=20, page with offset=20 only when useful, and prefer prop_type/vendors filters over full-board pulls. Before final BUY/SELL/NO EDGE, the primary should run sports data and research as bounded lanes after the initial executable board/shortlist exists: sports for event state/odds/props/supported form inputs/unsupported endpoint notes, research for current news and resolution facts. If skipped or unavailable, label sports_state=not_hydrated, research_state=not_hydrated, or market/odds-only and scope the conclusion. Avoid unsupported true-prob claims.

# player props -> ACTIONABLE/WATCH/EXCLUDED EV table
poetry run python -m wayfinder_paths.quant.prop_slate \
  --sport nba --game-id <GAME_ID> --season <SEASON> --out .wayfinder_runs/sports

# game markets (moneyline/total/spread) -> data/model context and optional book context
# (PM/HL order books remain the executable price)
poetry run python -m wayfinder_paths.quant.game_slate \
  --sport nhl --game-id <GAME_ID> --season <SEASON> --date <GAME_DATE> --out .wayfinder_runs/sports

# futures fields (tournament winner / group winner / reach-final) -> optional book-context fair_p
poetry run python -m wayfinder_paths.quant.futures_slate \
  --sport worldcup --market-type outright --out .wayfinder_runs/sports

# context/model fair vs executable PM/HL disagree? -> dislocation check + gated posterior ledger
poetry run python -m wayfinder_paths.quant.sports_posterior \
  --market <PM_PRICE> --book <FAIR_P> --vendors <N> --overround <O> \
  [--card "davies_out:against:medium:news"]

Composition and autonomy rules: Every probability, edge, or EV asserted in the final answer must appear in a shown table or posterior ledger. If the sports worker returns a rendered table, paste the top rows; if it returns only dataFiles, read the artifact and show the rows. Finish the executable-venue check and top dislocation adjudication in-session instead of offering them as follow-ups.

Executable board rule: Polymarket lists a per-game EVENT (slug {league}-{away}-{home}-{YYYY-MM-DD}, e.g. mlb-lad-cws-2026-06-12) but the visible board may be split across parent and child events. Hydrate the exact event (polymarket_read get_event) and use sportsBoard, childEvents, and categorySummary as the executable coverage map; child events can hold player props, more-markets, specials, exact score, and broadcast props even when the parent event only shows match outcomes. Hydrate or inspect surfaced child categories before saying a Polymarket prop category is absent, and page candidates with offset when the category is large. game_slate emits alt_lines (model probabilities for the alt ladder) to price game lines. "No provider props" never means "nothing executable." For multi-outcome match boards (soccer/worldcup, tennis sets, MMA method, etc.), preserve the returned outcome mapping exactly. A three-way soccer board is home/draw/away; never collapse it into a binary or recommend "buy No on the favorite" unless a binary No token is explicitly listed. For Hyperliquid HIP-4, only request mids for #... assets surfaced by the market search or prior metadata; for sports/prediction-market discovery call wayfinder_hyperliquid_search_hip4(query="...", limit=15) so perps/spots are filtered out by construction, and do not derive sibling asset ids by changing the last digit.

Exact-market hydration rule: For a named match/fight/event, never conclude "no Polymarket market" from a search summary alone. If polymarket_read(action="search") returns any plausible eventSlug, candidate, or event group for the names/date/card, immediately hydrate it with get_event and inspect the candidate board. If exact-name search is empty, run bounded fallback queries for each competitor/team surname or short name independently plus the sport/card/date, then hydrate every same-card/same-date event returned before declaring absence. Broad searches such as "ufc fight" are truncation-prone discovery only; they are not negative proof unless every plausible event candidate they surface has been hydrated with get_event. Only after those hydrated checks can you say no executable PM market was found; phrase it as "not surfaced by these searches" when coverage is incomplete. Likewise, for a named game/fight/event, still search the direct matchup on PM and Hyperliquid HIP-4 before calling the analysis complete, even when provider odds are unavailable.

UTC-boundary trap: US evening games can cross the UTC date line. For scoreboard reads, pass the user's IANA timezone with the concrete date and inspect the returned dateContext before answering. Before analysis, identify the concrete game id, local/UTC start, and status; NEVER mix one game's live book odds with another game's pre-game venue board.

Odds sourcing rule: never source betting lines from web search or media pages. Executable lines come from PM/HL order books. Provider sportsbook odds are optional context only; if they are empty, unmatched, or auth-blocked, continue with PM/HL boards, sports data, and model estimates rather than checkpointing. Web research is for news and qualitative evidence, not odds.

Dislocation rule: when an optional sportsbook/context number or model estimate and the PM/HL executable price for the same outcome disagree enough that sports_posterior.dislocation flags it, never recommend the cheap side on trust — the prior is the EXECUTABLE price, the context/model number enters as one capped evidence card, and the gap must be adjudicated (research: "what explains the cheap side?" — post-line news, resolution-rules mismatch, lockup/flow, stale data, method risk) before any recommendation. An unexplained dislocation gates to WATCH with the EV shown — by design. Sub-threshold gaps are VENUE NOISE, not edge: never describe one as "X points too rich/cheap" — say the market is priced within normal venue tolerance (a directional view from evidence is "a lean within noise, not a value call"). Absence of a cross-venue arbitrage path is not a skip reason: the user cares about fair-value delta versus executable price unless they explicitly ask for arbs.

For scan questions, CLI-gate every dislocation you headline and fully adjudicate at least the largest one: ask research "what explains the cheap side?", fold evidence cards back through sports_posterior, and show the final gated verdict. Unexplained dislocations are candidates, not calls.

Path-dependent event markets

For tournament winners, group winners, playoff brackets, promotion/relegation, championship futures, season awards with staged cuts, or any field market where path matters, do not stop at prediction-market cross-venue spreads or optional book-vs-market spreads. Build a current-state probability layer; sportsbook odds are optional context, not a required input.

Default first-pass workflow:

1. Enumerate executable PM/HL boards first, then add bounded sports state/context that helps interpret the board: completed results, standings/bracket/cuts if cheap, injuries/availability, futures context, and obvious missing path fields.
2. Return the desk-analyst board and value/fade shortlist before any full path model. The first pass should include board coverage counts, state classification, and path-model status such as not_run_shortlist_first or missingPathFields.
3. After the initial executable board and tentative shortlist/evidence questions exist, run sports data and research as parallel bounded lanes when both can move fair value. wayfinder-sports returns sports state/context; wayfinder-research returns a reusable researchInfluencePack with evidence cards, researcherOpinion, influenceHints, optional contextPack / modelModifiers, or final-synthesis-only evidence when no pack is justified.
4. For shortlisted candidates, or when the user explicitly asks for full modelling first, ask wayfinder-sports for a sport-neutral eventStatePack: participants, ratings/form inputs, completed results, standings/bracket/cuts if known, upcoming path, futures_slate fair probabilities if available, and executable PM/HL markets. Sportsbook/futures auth failure must not block this pack.
5. Run event_sim validation/smoke before any full simulation: low iterations, short timeout, and fail fast on missing group slots, impossible wildcard slots, unknown participants, or unsupported target shapes. Generated custom-simulator debugging gets one repair max.
6. Run poetry run python -m wayfinder_paths.quant.event_sim --input <event_pack.json> --out .wayfinder_runs/sports or delegate the pack to wayfinder-quant.
7. Price simulated probabilities against executable order-book entries/depth and gate with sports_posterior when dislocations remain large.

The simulator is one model view, not the answer. Final synthesis must distill multiple views: executable PM/HL prior, sports/context model or rating model, path simulation, and qualitative evidence/posterior. Do not present the latest sim as final fair value by itself. If ratings come from outright winner probabilities or other market-implied prices, label the sim diagnostic_only; if the bracket/path is approximate, label approx_bracket and downgrade buy calls to WATCH unless another independent model corroborates them. Use executable entry/depth for trade math: ask/depth for buys, bid/depth for sells.

Executable sports odds should be shared as TTL'd WorkPacks, not repeatedly re-fetched by every subagent. The first agent that hydrates PM/HL boards should write a compact sports surfacePack and pass surfacePackRefs downstream. Reuse unexpired surface packs for analysis and final synthesis; refresh only shortlisted markets for exact sizing or execution. Defaults: PM/HL board ttlSeconds: 60, exact quote/depth ttlSeconds: 30, standings/results state ttlSeconds: 300. If a worker hits max steps after writing useful packs, resume from those pack refs; do not improvise a final BUY from venue spreads or qualitative reasoning alone. Missing model/fair-value work should be labeled WATCH / incomplete_fair_value.

Run the first-pass board now, even early in an event. Do not defer with "run once the group stage is 50% complete" or similar. Full path simulation is the second-stage validation step after the shortlist; if the user explicitly asks for modelling first, skip straight to the path layer. If the official bracket/path is unavailable for validation, run the best bounded approximation from known rules and label pathAssumption: "approximate"; if a path cannot be represented at all, surface missingPathFields as the blocker. If a final answer claims fair value without event_sim or a custom simulator, label it WATCH / incomplete_fair_value and state that simulation is not yet run. Before running a full path model, the event pack must pass the smoke/validation step above. If validation fails, return WATCH / incomplete_fair_value / NEEDS_MORE_STATE with the validation issues rather than spending the turn repairing a malformed bracket.

For "scan the field/market" questions, the final answer must be the annotated board before any single-candidate drilldown. It must include: board coverage counts for each executable venue, a ranked top-candidate table from the full joined field, each candidate's state classification, path-model status/artifact (or missingPathFields), and order-book depth only for shortlisted candidates. Never finish with only one or two selected order books. Under a hard tool budget, use a bounded scan plan and finish anyway: hydrate the main outright board, search the second executable venue, search group/round boards with enough candidate coverage to surface multiple event slugs, pull current standings/results using the canonical sport slug (for World Cup: worldcup, not soccer) and a generous limit so standings are not silently truncated. Do not call data.pregame_forms.list for worldcup unless the catalog explicitly supports it; after one resource_unavailable_for_league for pregame_forms + worldcup, do not retry it for later matches and use the research lane for current form/news instead. Then fetch mids for the shortlisted match boards that surfaced. Prioritize hydrating or directly using group boards for groups with current results before spending calls on novelty/entertainment match searches. Do not call mid_prices for every encoded outcome in a large field; shortlist top/ambiguous outcomes first. If group or match boards surface in search but are not fully hydrated, classify them as search_surfaced_unhydrated, not not_surfaced. If group or match boards do not surface, report the search coverage and move on rather than checkpointing or offering follow-up work. For broad multi-category scans ("most mispriced across match, group, outright", "scan the whole field"), cap primary-agent collection at sixteen external calls. Reserve one call for current state/results with a generous limit and one for match-market mids if match boards surface. After the sixteenth call, stop gathering data and write the final answer from the joined board/state you have. Missing category coverage is a finding (not_surfaced / search_surfaced_unhydrated / missingModelArtifact), not a reason to continue. Never output a progress checkpoint for these scans. Avoid progress-only headings such as Goal, Constraints, Progress, Done, In Progress, Blocked, Critical Context, and Next Steps in the answer. A partial annotated board with honest blockers is the final deliverable.

The generic pack shape is:

{
  "participants": [
    {"id": "stable-id", "name": "Display Name", "rating": 1800,
     "state": "clean_unplayed|live_conditioned|post_result_stale|dead_signal"}
  ],
  "groups": [
    {"id": "Group/Stage", "participants": ["id1", "id2"],
     "qualifiers": [{"rank": 1, "slot": "G1_1"}],
     "matches": [{"a": "id1", "b": "id2", "status": "completed", "score": [1, 0]}]}
  ],
  "wildcards": [{"source_rank": 3, "count": 2, "slot_prefix": "WC"}],
  "bracket": {"matches": [{"id": "m1", "a": {"slot": "G1_1"}, "b": {"participant": "id3"}}],
              "champion_match": "m_final"},
  "target": {"type": "champion|slot|reach_match|match_winner",
             "slots": ["PROMO1", "PROMO2"], "match": "m_final"},
  "markets": [{"participant_id": "id1", "venue": "polymarket|hyperliquid", "bid": 0.01, "ask": 0.011}],
  "modelProvenance": {"ratingSource": "team-strength source", "bracketSource": "official|approximate"}
}

Fill only what is known. If the provider/catalog lacks an official path, return missingPathFields; if you approximate from public rules, set pathAssumption: "approximate" and list assumptions. Use target to avoid winner-take-all overfitting: champion for outrights, slot for promotion/relegation or staged cuts, reach_match for reach-final/reach-playoff markets, and match_winner for a specific stage winner. If event_sim cannot represent the sport/event, a quant worker may build a custom simulator, save artifacts, and document the model and assumptions. Do not create event-specific prompt rules.

Classify every surfaced candidate:

• clean_unplayed: no relevant result has occurred yet.
• live_conditioned: current results/standings are folded into the model.
• post_result_stale: comparison still uses pre-result odds/model inputs.
• dead_signal: path is mathematically gone or economically irrelevant.

Do not call stale or dead signals value.

LLM forecasting / prediction-market notes

Use LLMs for retrieval, synthesis, evidence cards, researchInfluencePack artifacts, and model selection, not as raw uncalibrated probability oracles. A strong researcher view can be a visible desk override candidate, but the consuming agent must ledger whether it was accepted, rejected, or deferred and must show why it changed the final view. Relevant research patterns:

• Retrieval + aggregation improves LLM forecasting over zero-shot (Approaching Human-Level Forecasting with Language Models, https://arxiv.org/abs/2402.18563).
• Live prediction-market evaluation needs timestamp-locked order books, news, and execution simulation (PolyBench, https://arxiv.org/abs/2604.14199).
• Accuracy is not enough; returns depend on execution, downside when wrong, and agreement filters (Beyond Accuracy: Can LLM Forecasters Profit on Prediction Markets?, https://openreview.net/pdf?id=TSA5kRUKZv).
• LLM confidence is often miscalibrated and domain-sensitive; apply posterior gates and calibration checks instead of trusting stated confidence (KalshiBench, https://arxiv.org/abs/2512.16030).

The pipelines are multi-sport (NBA/NHL/MLB/World Cup verified live). They are context and model helpers, not gates before PM/HL pricing. MLB notes: props include one-sided "milestone" quotes (single odds, no under side) — the pipeline skips these with a visible count; do NOT model them by hand (a single quote cannot be de-vigged). MLB pitcher props project off outs recorded, batter props off plate appearances. Soccer notes: moneylines are three-way (1X2 — home/draw/away de-vigged together; never two-way over home/away); futures quotes carry the whole field's vig (de-vig across the entire field, never read one quote as a probability); a brand-new tournament has no completed-game form — game_slate flags no_form_model and shows odds-only views.

One command: fetches props + complete paginated game logs + team pace/defense + injuries, models with proper distributions and optional book-context probabilities, and prints an ACTIONABLE / WATCH (flagged) / EXCLUDED (no joinable data) table; writes prop_slate_<game>.csv/.json artifacts. Output fields per pick: model_p, book_p, book_edge, book_ev, kelly, proj, n, flags. book_* numbers are vs optional non-executable sportsbook context — informational; the executable stage is sports_props.market_edge(pick.model_p, polymarket_price) against a matching Polymarket market. Only compare a model/context probability to the same executable outcome. A player anytime-goal probability is not an edge against a team moneyline; if the matching executable prop is absent, label the model output context-only / informational-only.

For custom analysis the pipeline doesn't cover (matchup deep-dives, soccer xG, cross-game studies), write a bounded script. Fetch through SPORTS_CLIENT (same backend gateway as the MCP tools: key-safe, allowlisted, cached — never raw provider URLs), shape with pandas, model with the quant modules:

import asyncio, pandas as pd
from wayfinder_paths.core.clients.SportsClient import SPORTS_CLIENT
from wayfinder_paths.quant import sports_props as sp          # projections, EV, market_edge
# from wayfinder_paths.quant import polymarket_edge           # prediction-market math

async def main():
    logs = await SPORTS_CLIENT.provider_call(
        endpoint_id="data.player_stats.list", sport="nba",
        query={"player_ids": [161, 1057262518], "seasons": [2025], "per_page": 100})
    df = pd.DataFrame(logs["data"])
    # rolling form, hit rates vs a line, joins to team pace/def_rating, score_prop EV tables...
    df.to_csv(".wayfinder_runs/sports/analysis.csv", index=False)  # artifact -> dataFiles

asyncio.run(main())

SPORTS_CLIENT methods: snapshot(action=..., sport=..., ...), provider_call(endpoint_id=..., sport=..., path_params=..., query=..., body=..., run_id=...), provider_catalog(), backtest_state(action=..., run_id=...) — all async. Conventions: bulk arrays over per-player loops; bounded lookbacks (a season, not all history); big tables go to .wayfinder_runs/sports/ artifacts (return the paths), summaries go in the response.

Local sports scripts are optional accelerators, not blockers. If a script or direct SPORTS_CLIENT call fails with auth/config errors (401, 403, missing key/config, provider entitlement), do not retry or defer. Mark the model artifact as script_auth_unavailable, use the already gathered MCP snapshots/PM/HL boards, and produce a final answer with lower confidence plus explicit missingPathFields / missingModelArtifact. For outrights/path markets, still return an eventStatePack from known participants/current state/executable PM/HL markets even when futures_slate or sportsbook futures fail auth. Never turn a script-auth failure into a checkpoint or follow-up.

Hard rules for prop scoring scripts (learned from real runs):

• Use sports_props for the math — devig_two_way (never compare against raw vigged implied probabilities), score_prop/project_stat/prob_over (proper distributions + shrinkage), prop_value/market_edge. Don't reimplement a simpler model inline.
• per_page=100 does not hold a slate's season of logs — chunk player_ids or follow meta.next_cursor until every player has rows.
• A player with zero joined logs is a broken join/pagination, not a 0.0 average — exclude or refetch, and sanity-check stars' averages before ranking.
• Run with poetry run python (plain python3 lacks pandas and project deps).

Lab (backtesting) quick sheet — nba/nfl/nhl/mlb only

• Factors: lab.factors.list — integer factor_id, slug (pp_* = player-prop factors), typed configurable_params.
• Create: lab.models.create body {name, sport, bet_type: moneyline|spread|over_under, mode: simple|weighted, factors: [{factor_id, parameters, weight}]} — the key is parameters (not params); weighted weights sum to exactly 100; prop models need model_type: "player_prop" + prop_type + pp_* factors (game models reject pp_*).
• Update replaces (PUT semantics — send the full body). Backtest: lab.performance.run (async job) → lab.performance.get (win_rate, roi as a fraction, results_by_confidence).
• Predictions: lab.predictions.generate (model id in path) → list via query={"model_id": ...} (top-level route). Active jobs for a model: lab.jobs.active (path_params.id = model id). Models/jobs are scoped to your workspace — foreign ids 404.
• Jobs are async (pending → running → completed/failed): kick off, capture run_id/job_id, monitor via wayfinder_sports_backtest_state — never tight-loop.