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

bashCopy code
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

bashCopy code
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):

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

Optional developer/test extras:

bashCopy code
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.

2. 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.

3. Check importability before setup.

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

4. 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."

5. 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.

6. 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.

7. 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)

pythonCopy code
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:

textCopy code
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:

bashCopy code
sports-ds --help
sports-ds feature-registry

Common reference commands:

bashCopy code
# 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

Hard constraints

1. Never imply sports_ds is installed merely because this skill exists.
2. Never tell a generic skill to import sports_ds or call sports-ds.
3. Never present pipeline-specific field names as a universal schema.
4. Do not install packages, download large datasets, or overwrite artifacts without authorization.
5. Preserve decision-time integrity on pre-game features: every value must be knowable at or before the declared prediction time.
6. Prefer user-owned artifact paths over repository-internal paths.
7. NHL remains second-class until data quality is explicitly accepted.
8. No odds/EV/arbitrage product claims. This bridge does not sell picks.

Worked paths

A. User wants NFL team-game data, then EDA

1. Confirm they asked for toolkit or accept it as the data path.
2. Check import; install only if missing and approved.
3. Load panel for a bounded season window.
4. Validate team-game required columns and 2 rows per game.
5. Write data/nfl_team_games.parquet.
6. Hand off to eda-sports.

B. User wants a reference NFL win benchmark

1. Confirm they want the reference pipeline, not just data.
2. Run sports-ds nfl-win-pipeline --seasons ... --json-out artifacts/nfl_win.json.
3. Summarize fold metrics, baseline comparison, n, and limits in plain language.
4. If they want deeper interpretation, translate metrics into a portable JSON and open results-reporting / model-card with explicit schema notes.
5. Do not pretend the benchmark is a production betting model.

C. User already has toolkit output and wants calibration help

1. Inspect the artifact columns.
2. Map to y_true, p_pred, and a fold/time column.
3. Write a clean predictions table.
4. Hand off to calibration-check.
5. Keep all sports_ds talk inside this bridge.

Output contract

Finish every bridge task with:

• whether sports_ds was needed and why;
• toolkit version / env notes when used;
• the exact surface used (module import vs CLI command);
• artifact path, format, grain, and time window;
• required-column validation result (pass/fail + missing fields);
• row counts and any provenance/cache limitations;
• the standalone skill that should run next;
• what was not done (no silent modeling, no edge claim).

If the toolkit was not used, say so explicitly and point to the correct skill.