MLB Desk Construction Spec

Status: IN PROGRESS Started: April 6, 2026 Last Updated: April 9, 2026

1. Data Sources

Game-Day Markets (6/8/10/2/6 ET + 1 min before close)

Futures Markets (adaptive schedule)

Stats (9 AM ET daily — 3 staggered groups)

Edge Detection (fires :10 past hour, after data collection)

Player Props (separate desk — MLB Player Props)

2. Databases (16 files)

Game-Day Odds

• kalshi-mlb-prices.db — Kalshi game-level contracts. Columns: scan_type, game_date, game_time, market_type, game_id, away/home team, threshold, yes_bid, yes_ask, exec_price, spread, volume. Same-day only, no settled prices, scan window gated.
• pinnacle-mlb.db — Pinnacle sharp odds. Tables: pinnacle_mlb_odds, pinnacle_mlb_f5, pinnacle_mlb_team_totals. Columns: scan_type, game_date, game_time, game_number (doubleheaders).
• sbr-mlb.db — SBR 6-sportsbook consensus. Table: sbr_book_odds (MLB filtered).

Futures

• kalshi-mlb-futures.db — Season-long Kalshi futures. Filtered to: world_series, pennant, playoff, best_record, worst_record, teams_in_ws. Expiry: 2026-09-27.
• kalshi-mlb-win-totals.db — Per-team win totals. Columns: team, threshold (wins needed), yes/no bid/ask/exec/spread. Expiry: 2026-09-27.
• kalshi-mlb-divisions.db — Division winners. Columns: division, team, yes/no bid/ask/exec/spread. Expiry: 2026-09-27.
• pinnacle-mlb-futures.db — Pinnacle sharp anchor for futures. Columns: market_name, selection, decimal odds, american odds, market_type. Expiry: 2026-09-27.

Stats

• mlb-stats.db — Schedule, lineups, standings, transactions, pitchers, stadiums (6 tables).
• mlb-pitching.db — SP game logs, baselines, priors, bullpen x4, opener flags, xFIP (9 tables).
• mlb-batting.db — Batter game logs, baselines, platoons, career stats, crosswalk (5 tables).
• mlb-weather.db — Game weather + stadiums (2 tables).
• mlb-model.db — Derived metrics, quality composite, adjusted rates, blended rates, team priors, model daily, park factors x3, variance, fatigue, inning scoring, game innings, ABS challenges, platoon splits (16 tables).

Props (Player Props desk)

• kalshi-mlb-props.db — Kalshi player prop contracts.
• mlb-prop-lines.db — FD/DK prop lines from Odds API.
• mlb-prop-edges.db — Prop edge scanner results, steam detection, matchup context.

Edge Detection

• mlb-edges.db — Edge scanner results (sports_edges MLB filtered), implied curves, edge summary, F5 probability curves (mlb_probability_curves table, market_type = f5_spread/f5_total/f5_moneyline).

3. Schedules

Game-Day Timeline (6 AM, 8 AM, 10 AM, 2 PM, 6 PM ET)

Futures Adaptive Schedule

Stats (9 AM ET daily — 3 staggered groups)

Each group runs sequentially within itself. Groups are staggered 5 minutes apart so raw data finishes before computation starts. If one group fails, the others still run.

4. Edge Detection

Game-Day Edges

The edge scanner compares Kalshi alt-line prices against Pinnacle sharp odds:

1. Pinnacle provides the fair value (moneyline, spread, total)
2. A probability curve is built from Pinnacle's line using Poisson (totals) or Normal (spreads) distribution
3. Each Kalshi alt-line rung is compared: if Kalshi's price diverges from the model probability by more than the fee (7%), it's flagged as an edge
4. Edges are tagged with scan_type, confidence, steam detection, and closing line value (CLV)

Team Totals

The edge scanner implies team totals from Pinnacle's game total + spread:

• Home team total = (game total - spread) / 2
• Away team total = (game total + spread) / 2 These implied totals are compared against Kalshi's team total alt-line prices.

Implied Probability Curves

Built from Kalshi's alt-line ladders. Each game gets a curve showing the market-implied probability at each threshold. Per-team curves for spreads, game-level for totals. Pinned contracts (bid ≤5 and ask ≥90) are filtered out.

F5 (First 5 Innings) Probability Curves

F5 lines are derived from Pinnacle's full-game line, not scraped directly (Pinnacle's F5 scraper is unreliable). The model engine provides per-game SP quality ratios to scale full-game lines to F5.

F5 Spreads — Normal distribution, sigma 2.7 (tighter than full-game 4.0 because 5 innings = less variance). Per-game ratio: model_f5Spread / model_fullSpread applied to Pinnacle's spread. Fallback: flat 0.55 scale when no SP data.

F5 Totals — Poisson distribution. Per-game ratio: model_f5Total / model_fullTotal applied to Pinnacle's total. Produces F5 totals in the ~4-5 run range (vs 7-9 full game). SP quality dominates — an ace matchup gets a lower ratio than two bad starters.

F5 Moneyline (3-way) — Home win / Away win / Tie. Poisson tie model: P(tie) = Σ P(Home=k) × P(Away=k) using SP-scaled team lambdas. Pinnacle's 2-way ML de-vigged to conditional probabilities, then multiplied by (1 - P(tie)) for unconditional. 3 rows per game in the database. F5 ML edge scanner deferred until historical tie rate data validates the Poisson model (~2 weeks of settlements needed). Tie rate tracked passively through Kalshi F5 TIE contract settlements.

All F5 curves stored in mlb-edges.db → mlb_probability_curves table with market_type = f5_spread / f5_total / f5_moneyline.

Dashboard views: /data-status/view/mlb-f5-spread-curves, /data-status/view/mlb-f5-total-curves, /data-status/view/mlb-f5-ml-curves.

F5 Edge Scanner

F5 spread and total edges are live. The edge scanner detects F5 tickers (contains "F5" in Kalshi ticker), looks up precomputed SP-scaled probabilities from the mlb_probability_curves table, and compares against Kalshi prices. Falls back to on-the-fly curve building with sigma 2.7 if precomputed curve is unavailable. F5 edges tagged with sub_market = 'f5' in sports_edges.

Dashboard views: /data-status/view/edge-scanner-mlb-f5-spreads, /data-status/view/edge-scanner-mlb-f5-totals.

Futures Edge Detection (not yet built)

Compare Kalshi futures prices against Pinnacle sharp odds. WS winner, pennant, division odds from Pinnacle serve as the anchor. Gap between Kalshi and Pinnacle = the edge.

5. Dashboard

MLB Desk Groups

• Edge Detection — Edge scanner results (ML, spread, total, F5, team total), F5 probability curves (spreads, totals, 3-way ML), implied curves
• Kalshi Game-Day — Kalshi game lines, Pinnacle odds, Pinnacle F5, SBR, Pregame
• Kalshi Futures — Kalshi futures, win totals, divisions, Pinnacle futures (sharp anchor)
• Ratings & Predictions — DRatings, Dimers, GameSim
• Pitching — SP game logs, baselines, bullpen, xFIP
• Batting & Matchups — Batter logs, baselines, platoons, lineups, standings
• Game Context — Park factors, weather, umpires
• Computed Analytics — Derived metrics, quality composite, team variance, fatigue, inning scoring

MLB Player Props Desk Groups

• Edge Detection — Prop edge scanner (K, hits, HR, TB, HRR), steam detection
• Odds & Prices — Kalshi props, FD+DK prop lines, Pinnacle (game context)
• Pitcher Data — SP logs, baselines, bullpen, roster
• Batter Data — Batter logs, baselines, platoon splits
• Game Context — Lineups, schedule, park factors
• Computed Analytics — Blended rates, adjusted rates, matchup context

6. Freshness Rules

Freshness Tracker

Passive poller runs every 5 minutes. Checks MAX(timestamp) per table across all databases. No scraper cooperation needed.

Thresholds

Alerts

Telegram alert after 2 consecutive misses (10 min of staleness). Consolidated message with color-coded status. Dead-man's switch on the poller itself.

7. Data Quality Rules

1. No live/in-game data — Only pre-game prices. Games that have started are skipped.
2. No settled prices — Bid ≤5 or bid ≥95 filtered out for game-day data.
3. Same-day only — Game-day database only stores prices for today's games.
4. Scan window tagging — Every row tagged with scan_type (6am/8am/10am/2pm/6pm/close).
5. Doubleheader handling — game_number column (1 or 2), G1/G2 detected from Pinnacle game_id.
6. Pinned contract filter — Implied curves skip contracts where bid ≤5 and ask ≥90 (dead markets).
7. Rate limiting — 500ms-2s delay between Kalshi API calls to avoid 429 errors.
8. Closing snapshots — Fire 1 minute before game start, not at game start.
9. Expiry dates — Futures databases have expiry_date column (2026-09-27). Scanning stops after expiry.

8. Isolation Checklist Status

Document Control

This spec will be updated as the desk is built. Final version when all checklist items pass.