Waterboy

Every league. Any matchup. One auditable simulation engine.

Waterboy is a technical-preview sports intelligence command center for current-week score projections and hypothetical games. It combines source-backed history, deterministic Monte Carlo, visible uncertainty, exact replay, and seven isolated league packs behind one fast interface.

Built to make simulation powerful, legible, and falsifiable.

Product truth

Contract	Current public state
Portfolio role	Deterministic Sports Simulation Engine — auditable projections, hypothetical matchups, exact replay, and seven isolated league packs.
Maturity	Technical preview
Engineering evidence baseline	7c0999ad · configured quality workflow
Proved now	The public release implements query-only intake, provenance storage, seven league packs, deterministic Monte Carlo, semantic replay, API/CLI/UI surfaces, and a 74-test automated quality result.
Authority ceiling	Simulation only. Waterboy has no wagering, sportsbook, brokerage, capital, or real-world action authority.
Clean demonstration	Follow the quick start, refresh the seven-day board, then build a hypothetical matchup with a retained seed and evidence envelope.
Known limit	League calibration is provisional and data-dependent. Internal reference anchors and historical replay do not establish predictive supremacy, profitability, or current real-time completeness.

Designed for: sports-data, media, simulation, and product teams that need one replayable engine without hiding league semantics, uncertainty, or source quality.

Explore the ObtuseAI portfolio · Inspect the simulation pipeline · Start a technical conversation

The product presentation

Waterboy opens with a complete, evidence-backed explanation of the working system before handing control to the current-week board and Matchup Lab:

Presentation surface	What it explains
Live engine pulse	Database integrity, current source, model identity, remote-write boundary, and the complete projection output shape
Platform capabilities	Counterfactual depth, deterministic replay, payload provenance, visible uncertainty, winner semantics, and execution isolation
Six-stage pipeline	Capture, normalize, remember, estimate, simulate, and publish contracts
Architecture stack	Dashboard/API/CLI, application services, team intelligence, seven league packs, and the immutable event kernel
Projection anatomy	Why scores are decimals, how the ✓ is selected, what probabilities and 80% intervals mean, and how evidence labels constrain the claim
League intelligence	Sport-specific rules, periods, overtime behavior, recency half-lives, and current-window game counts for all seven leagues
Evidence and fidelity	Automated quality results, F0–F3 readiness boundaries, semantic RNG, event-chain identity, and exact replay
Working product	The live seven-day schedule, organized league filters, and the fully interactive hypothetical matchup studio
Evidence boundary	Missing real-time inputs, provisional calibration status, and the explicit absence of wagering or execution authority

The presentation is responsive, keyboard navigable, CSP-compatible, and uses the same versioned API as every other Waterboy client. It does not substitute decorative claims for evidence: illustrative values are labeled, current counts are loaded from the live application, and unsupported fidelity remains gated.

What Waterboy does

Surface	Capability
Current-week command center	Organizes scheduled, live, and final games across seven leagues
Score projections	Decimal team scores, totals, margins, win/tie probabilities, and 80% intervals
Winner signal	Places an accessible ✓ immediately beside the higher-probability team
Matchup Lab	Simulates any two teams at home or a neutral site with 5K–50K draws
Team intelligence	Recency weighting, opponent adjustment, prior shrinkage, and freshness penalties
Evidence	Source URL, observation time, payload hash, sample size, data-through time, and limitations
Replay	Same model, state, inputs, and seed reproduce the same simulated world
Operations	Versioned API, CLI, SQLite provenance store, security headers, and non-root container

The Waterboy pipeline

flowchart LR
    A["Read-only schedules<br/>and historical scores"] --> B["Normalized game contract<br/>timestamp + source + SHA-256"]
    B --> C["Provenance SQLite<br/>isolated target-owned store"]
    C --> D["Team-state intelligence<br/>recency + opponent adjustment"]
    D --> E["Posterior parameter worlds<br/>shrinkage + uncertainty"]
    E --> F{"Fidelity router"}
    F -->|"F0"| G["Mass analytical simulation"]
    F -->|"F1"| H["Event-level game paths"]
    G --> I["Decimal projections<br/>probabilities + intervals"]
    H --> J["Replayable event chain<br/>result-envelope hash"]
    I --> K["Current Week + Matchup Lab"]
    J --> K

Loading

Waterboy does not hide source quality behind a confidence color. Sparse or stale history is explicitly labeled and shrunk toward transparent league priors. In-progress scores remain observations; the pregame model is withheld instead of being mislabeled as a live forecast.

Showcase snapshot

Dimension	Verified local evidence
Historical bootstrap	179,383 valid games copied query-only from the retained source corpus
Current seven-day board	107 games: 92 MLB and 15 WNBA on 2026-07-26
Scheduled pregame projections	94
League packs	7
Hypothetical simulation depth	Up to 50,000 draws
Current-board latency	Approximately 1.1 seconds at 500 draws/game
Automated tests	74 passed, zero warnings
Negative/mechanism controls	49 passed, zero failures
Reference validation	7/7 provisional league anchors
Browser validation	Desktop + mobile, zero console errors/warnings

This snapshot demonstrates working software and operational data flow. It does not establish predictive supremacy or profitability; those require independently governed prospective, point-in-time evaluation.

Seven leagues, one engine

UI category	Internal pack	Family
MLB	mlb	Bat and ball
NFL	nfl	Gridiron
NCAAF	ncaaf	Gridiron
NBA	nba	Court invasion
WNBA / WBA	wnba	Court invasion
NCAAM	ncaambb	Court invasion
NHL	nhl	Ice invasion

Each pack owns its rules, clocks, phases, scoring, stochastic transitions, and reference anchors. Sport semantics never leak into the domain-neutral event core.

Quick start

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

# Refresh the rolling seven-day board.
.\.venv\Scripts\waterboy.exe refresh-data --days 7

# Start Waterboy.
.\.venv\Scripts\waterboy.exe serve

Open http://127.0.0.1:8765.

The legacy sports-engine command and universal_sports_engine Python namespace remain supported for replay and integration compatibility. New integrations should use the waterboy command or python -m waterboy.

Build any matchup

.\.venv\Scripts\waterboy.exe simulate-matchup `
  --league nfl `
  --home KC `
  --away PHI `
  --simulations 50000 `
  --seed 20260726

{
  "projected_home_score": 24.8,
  "projected_away_score": 22.1,
  "home_win_probability": 0.557,
  "away_win_probability": 0.431,
  "tie_probability": 0.012,
  "confidence_label": "HIGH_DATA_COVERAGE"
}

The example shape illustrates the API contract; actual values depend on the selected teams, point-in-time history, model version, and seed.

API

Method	Path	Purpose
GET	/api/v1/health	Engine and database integrity
GET	/api/v1/leagues	League catalog and aliases
GET	/api/v1/leagues/{league}/teams	Current team picker
GET	/api/v1/week	Rolling current-week projection board
POST	/api/v1/simulations/hypothetical	Reproducible matchup simulation
POST	/api/v1/data/refresh	Bounded public schedule refresh

OpenAPI is available at /docs.

Determinism and governance

flowchart TD
    T["Point-in-time training"] --> S["Bounded population search"]
    S --> C["Chronological calibration"]
    C --> W["Expert weights + interval adaptation"]
    W --> G{"All promotion gates pass?"}
    G -->|"Yes"| P["Freeze content-addressed champion"]
    G -->|"No"| R["Retain incumbent + record failure"]
    P --> O["Prospective shadow outcomes"]
    R --> O
    O --> D{"Drift detected?"}
    D -->|"No"| W
    D -->|"Yes"| Q["Quarantine, recalibrate, or roll back"]

Loading

Event streams are immutable and hash-chained. Result envelopes commit to league, score, seed, event chain, and evidence metadata. Search cannot mutate rules, evaluators, split boundaries, tests, or quality gates.

Container

docker build -t waterboy:0.4.0 .
docker run --read-only --tmpfs /tmp `
  -p 127.0.0.1:8765:8765 `
  -v waterboy-data:/data `
  waterboy:0.4.0

The image runs as a non-root user. Remote binding is explicit and must sit behind an authenticated TLS reverse proxy with rate limits and network policy.

Documentation

Document	Purpose
Architecture	Kernel, application, data, and fidelity boundaries
Production runbook	Bootstrap, deployment, refresh, backup, and incident response
Pipeline lineage	Exact source-corpus reuse and exclusion boundary
Data rights and provenance	Source, caching, and permitted-use responsibilities
Known limitations	What Waterboy does not currently model or prove
Version 0.4 evidence	Current release and browser verification
Autonomous improvement	Search, weighting, drift, promotion, and rollback

Evidence boundary

Waterboy is a sophisticated, working simulation platform—not a magic oracle. Its current projections omit live roster, injury, starting-lineup, probable-pitcher, coaching, travel, official, and forecast-weather inputs. F2 spatial calibration and F3 physics remain blocked pending licensed evidence rather than being fabricated.

No wagering, sportsbook, brokerage, order, or capital-execution interface exists.

Waterboy

Carry the data. Run the worlds. Show the evidence.