walrusquant/sports-analytic-skills/sports-ds-bridge

Sports DS Bridge

Overview

sports_ds is an optional data and workflow accelerator that lives in the same repository as this skill pack. It is not required by the other skills.

This bridge is the only skill allowed to talk about sports_ds setup, imports, CLI commands, caches, and pipeline outputs. Its job is narrow:

1. decide whether the toolkit is actually needed;
2. set it up only with authorization;
3. use the narrowest toolkit surface that satisfies the request;
4. materialize a portable CSV / Parquet / JSON artifact;
5. validate that artifact against the downstream skill's own contract;
6. hand off to a standalone skill and stop.

The bridge is an integration boundary, not a second modeling stack. After the handoff, generic skills must not call back into sports_ds.

Read references/toolkit-map.md for concrete imports and CLI routes. Read references/handoff-contracts.md before writing an artifact for another skill.

When to Use This Skill

Use this skill when:

• the user explicitly names sports_ds, sports-ds, or this repository's toolkit;
• the user wants the optional public-data loaders / normalized panels for

NFL, NBA, or MLB;

• the user wants toolkit CLI reference pipelines or feature-registry output;
• the user needs setup, install, import, cache, or CLI troubleshooting for the toolkit;
• the user already has toolkit output and needs it translated into a portable

artifact another skill can consume.

Do not use this skill when:

• the user already has usable CSV / Parquet / JSON and just wants EDA, features,

models, validation, calibration, or reporting;

• a public loader skill (nflreadpy, sportsdataverse-py, pybaseball,

data-sources) is enough and the user did not ask for the toolkit;

• you are tempted to make a generic skill "easier" by smuggling in a

sports_ds dependency;

• the request is custom betting-market construction, pick selling, or claimed edge.

Installation

The toolkit is optional. Confirm it is missing before suggesting install, and get authorization before cloning or installing.

Check first

python -c "import sports_ds; print(sports_ds.__version__)"
sports-ds --help

If import works, do not reinstall. Record the version and continue.

Authorized install from the public repo

git clone https://github.com/WalrusQuant/sports-analytic-skills.git
cd sports-analytic-skills
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .

Optional multi-sport loaders (NBA/MLB via sportsdataverse / pybaseball):

python -m pip install -e ".[multi]"

Optional developer/test extras:

python -m pip install -e ".[dev]"

Compatibility notes:

• Python 3.10+ required.
• Base install covers NFL (nflreadpy) and the scientific stack.
• NBA/MLB team and player loaders need .[multi].
• On macOS only, XGBoost pulled by sportsdataverse may need OpenMP:

brew install libomp. Not required for skill-only installs and usually unnecessary on Linux.

• Keep installs inside a project venv. Do not modify system Python.
• Large public-data pulls and caches need explicit user authorization.

Decision workflow

Every bridge task follows this arc. Do not skip.

1. Name the downstream skill and its contract.

• What skill will consume the artifact?
• What grain, keys, and required fields does that skill document?
• If the contract is unknown, stop and open that skill first.

1. Decide whether `sports_ds` is necessary.

• User already has the table → skip the toolkit; hand the path to the skill.
• User wants public data only → prefer loader skills unless they asked for the toolkit.
• User asked for sports_ds / reference pipelines / normalized panels → continue.

1. Check importability before setup.

• Import + sports-ds --help first.
• Install only with authorization when missing.

1. Choose the narrowest surface.

• Loader/core API for data or one transform.
• CLI pipeline only when the user wants an end-to-end reference benchmark.
• Never default to the heaviest pipeline "to be helpful."

1. Materialize a portable artifact in the user's project.

• CSV / Parquet / JSON owned by the user.
• Stable path under their workspace (data/, artifacts/, etc.).
• No reliance on repo-relative paths or pipeline provenance.

1. Validate before handoff.

• Required columns present.
• Grain correct (team-game doubled? one row per decision? unique game ids?).
• Time fields usable for walk-forward.
• Missingness and row counts sane for the claimed window.

1. Hand off and stop.

• Tell the agent which standalone skill to run next.
• Do not keep modeling inside the bridge.
• Do not tell the next skill to import sports_ds.

Choose the narrowest toolkit surface

Loader-first pattern (preferred)

from pathlib import Path
from sports_ds.data.nfl import load_team_game_panel
panel = load_team_game_panel([2022, 2023, 2024])
required = {
    "season", "game_id", "gameday", "team", "opponent", "is_home",
    "points_for", "points_against", "point_diff", "won",
}
missing = sorted(required.difference(panel.columns))
if missing:
    raise ValueError(f"team-game panel missing columns: {missing}")
out = Path("data/nfl_team_games.parquet")
out.parent.mkdir(parents=True, exist_ok=True)
panel.to_parquet(out, index=False)
print(out)

Then:

Use eda-sports on data/nfl_team_games.parquet. Confirm grain, coverage,
missingness, target balance, and modeling red flags.

CLI reference pattern (only when asked)

Discover the live surface; do not memorize a stale subset:

sports-ds --help
sports-ds feature-registry

Common reference commands:

# Team EDA
sports-ds nfl-eda --seasons 2023-2024
sports-ds nba-eda --seasons 2023-2024
sports-ds mlb-eda --seasons 2023-2024
 
# Team walk-forward benchmarks
sports-ds nfl-win-pipeline --seasons 2018-2024 --json-out artifacts/nfl_win.json
sports-ds nfl-margin-pipeline --seasons 2018-2024 --json-out artifacts/nfl_margin.json
sports-ds nfl-elo --seasons 2018-2024 --json-out artifacts/nfl_elo.json
sports-ds nfl-win-rich --seasons 2018-2024 --json-out artifacts/nfl_win_rich.json
 
sports-ds nba-win-pipeline --seasons 2023-2024 --json-out artifacts/nba_win.json
sports-ds mlb-win-pipeline --seasons 2023-2024 --json-out artifacts/mlb_win.json
 
# Player paths
sports-ds nfl-player-eda --seasons 2023-2024
sports-ds nfl-player-pipeline --seasons 2022-2024 --target fantasy_points_ppr --json-out artifacts/nfl_player.json
sports-ds nba-player-pipeline --seasons 2023-2024 --json-out artifacts/nba_player.json
sports-ds mlb-player-pipeline --seasons 2023-2024 --max-games 50 --json-out artifacts/mlb_player.json
 
# Trust checks inside the toolkit (still optional)
sports-ds calibrate --sport nfl --seasons 2018-2024 --json-out artifacts/cal.json
sports-ds leakage-audit --sport nfl --seasons 2023-2024 --json-out artifacts/leak.json

Pipeline JSON is a reference benchmark, not a silent schema for results-reporting or model-card. Translate keys explicitly or keep the benchmark self-contained and summarize it in plain language.

NHL note: historical sportsdataverse dumps have been unreliable. Prefer NFL/NBA/MLB unless the user explicitly accepts NHL limitations.

Handoff contracts

Bridge defaults live in references/handoff-contracts.md. The downstream skill remains the source of truth.

Minimum checks before handoff:

Team-game panel

• one row per team per game (usually two complementary rows per game_id);
• required fields present: season, game_id, gameday, team, opponent,

is_home, points_for, points_against, point_diff, won;

• won is binary from the focal team's view;
• include week or another within-season order field when available.

Prediction table

• one row per evaluated decision;
• stable keys + y_true + y_pred or p_pred;
• time/fold field such as season;
• no silent renames.

Fold-metrics JSON

• task, validation design, primary metric, per-fold n and scores;
• baseline comparison included when the benchmark claims improvement;
• map toolkit-specific keys before a reporting skill consumes them.

Elo / simulation schedule

• one row per remaining matchup (not a doubled team panel);
• unique game_id;
• team, opponent, is_home, and either win_probability or documented

ratings sufficient to compute it.

If validation fails, fix or rebuild the artifact. Do not hand garbage downstream and hope the next skill invents columns.

Troubleshooting

Capture command, environment, package versions, and the exact error before changing dependencies.

Anti-patterns