pi-autocontext-sports

Pi package for sports roster-impact analysis using sports-impact-core.

Install from npm:

pi install npm:[email protected]

For a project-local install:

pi install npm:[email protected] -l

It adds:

• a consolidated sports_impact tool
• CSV/JSON basketball baseline import, including user-provided approved WNBA roster/minutes exports via league: "WNBA"
• deterministic run bundle summaries via summarize_run
• manifest-driven scenario bundles via validate_scenario_bundle, run_scenario_bundle, and bundle comparison via compare_scenario_bundles
• dataset-derived injury and trade scenario creation
• deterministic front-office trade-feasibility guardrails for salary matching, luxury-tax/apron thresholds, hard caps, aggregation restrictions, roster limits, and optional required salary/payroll/apron source-license provenance
• BALLDONTLIE-primary internal-demo trade scenario search with objective presets, roster-building constraints, deterministic feasibility/simulation, ranked JSON/Markdown, and runnable top-candidate artifacts
• fixture-backed draft candidate fit evaluation plus sensitivity/robustness analysis, model-vs-scout reconciliation, availability/contingency planning, live war-room state updates, manifest-driven full draft workflow runs, combined draft workflow smoke evidence, draft workflow artifact gating, and front-office decision briefs with board tiers, archetype picks, risk register, opportunity costs, analyst appendix, and next-review questions
• shared availability constraints and coaches lineup matchup ranking via rank_coaches_lineup_matchups
• historical absence/outcome fixture generation for injury backtests
• historical trade/outcome fixture generation for trade backtests
• multi-suite injury and trade calibration reporting
• deterministic trade model parameter tuning and profile comparison
• trade fixture quality validation, case-level provenance, historical fixture-pack audits, input-hash evidence, reproducibility and deterministic rerun verification with drift grouping, configurable regression gates, maturity-aware benchmarks, benchmark comparisons, train/validation/test split generation, readiness gates, holdout scoring, unified audits, and residual diagnostics
• precomputed NBA game-footage tracking analysis for player/ball tracks, quality audit warnings, possession segments/estimates, and court-zone summaries without raw video inference
• deterministic external handoff validation reports for schema/version, metadata, source-system provenance, bbox format, pixel-scale, raw-video boundary, coordinate completeness, detection completeness, and confidence checks
• deterministic external handoff normalization into game-footage-analysis-input/v1, including direct court_feet coordinates and explicit-scale pixel/bbox-center conversion
• reusable invalid external handoff fixture gates that require stable failed check IDs and normalization rejection before downstream analysis
• downstream external handoff fixture-gate CI adoption plans, adoption verification, and adoption registries that generate/verify deterministic GitHub Actions YAML for both valid fixture-pack gates and invalid-fixture gates across projects
• deterministic SVG/Markdown court visualizations for selected precomputed frames and track paths
• precomputed Roboflow/YOLO-style, CSV, ByteTrack/Supervision-style detection/tracking, and valid external handoff normalization for game-footage analysis inputs
• game-footage fixture-pack audit/rerun verification with adapter source files including external handoffs, input hashes, validation evidence, normalized-output comparisons, visualization artifact hashes, lifecycle policy scaffolds/conformance checks/run audits/CI adoption generators/adoption verifiers/trend reports/CI-hardened trend gates/trend registries/dashboard aggregation/dashboard adoption checks/dashboard adoption registries, materialized, verified, compared, gated, baseline-checked, promotion-evidenced, promotion-verified, suite-checked, ledger-verified, registry-verified, registry-gated, registry-compared, and registry-comparison-gated SVG/Markdown artifact bundles, and golden quality/possession checks
• deterministic injury/trade simulation and fixture-backed injury/trade backtest actions
• a sports-impact analysis skill
• an NBA roster-impact prompt template

The package is designed to assist analysis runs while keeping numeric projections and salary/apron feasibility checks deterministic and inspectable. Feasibility inputs can require source/license provenance for salary, payroll, apron-threshold, and rule-profile values, either embedded in the JSON input or ingested from CSV/JSON fixture files. Feasibility reports are preflights, not legal advice or authoritative CBA rulings.

Boundaries and external handoff

Follow the package-local boundary document BOUNDARIES.md, the machine-readable handoff schema schemas/game-footage-external-handoff.schema.json, and the canonical repository boundary contract in docs/BOUNDARIES.md. Game-footage tools accept precomputed court-coordinate tracking/detection outputs only. Use validate_game_footage_external_handoff to report contract readiness, source-system provenance, bbox format, pixel-scale, and raw-video boundary alignment, normalize_external_handoff_game_footage to bridge valid handoffs into the existing analysis input schema before analysis, audit_game_footage_fixture_pack with normalization.adapter: "external_handoff" plus files.externalHandoffInput when that bridge must be audited as fixture-pack evidence, gate_game_footage_external_handoff_fixture_pack when CI needs a hard pass/fail gate for validation, normalized-input matching, and raw-video boundary checks, and gate_game_footage_external_handoff_invalid_fixtures when CI needs manifest-backed negative validation coverage with stable failed check IDs. The package does not perform raw video inference, object detection, segmentation, homography estimation, or jersey OCR, and it does not provide betting/gambling recommendations, medical advice, legal advice, authoritative CBA rulings, or guaranteed-performance claims.

After install, ask Pi to use sports_impact to initialize a run, import NBA/WNBA baseline data with import_baseline_dataset (league: "WNBA" requires user-provided approved WNBA roster/minutes paths and source metadata), summarize run artifacts with summarize_run, validate manifest paths with validate_scenario_bundle, run manifest-driven trade/draft/lineup bundles with run_scenario_bundle, compare bundle manifests with compare_scenario_bundles, create create_injury_scenario / create_trade_scenario artifacts, verify explicit front-office salary/apron inputs and optional strict financial provenance with verify_trade_feasibility, rank BALLDONTLIE demo trade candidates with optimize_balldontlie_demo_trades from a generated demo pack, rank coaches lineup matchup candidates with rank_coaches_lineup_matchups, evaluate source-agnostic draft candidate fit fixtures with evaluate_draft_candidate_fit, test draft board robustness with analyze_draft_board_sensitivity, reconcile model and scout boards with reconcile_draft_board, plan pick-slot availability/contingencies with plan_draft_availability, update draft-night board state with update_draft_war_room_state, run manifest-driven full workflows with run_draft_workflow, run combined draft workflow smoke evidence with run_draft_workflow_smoke, gate draft workflow artifacts with gate_draft_workflow, build a GM/data-analyst decision-room artifact with build_draft_decision_brief, tune trade model parameters with calibrate_trade_model, validate fixtures with validate_fixtures, audit historical fixture packs with audit_trade_fixture_pack, benchmark fixture packs with benchmark_trade_fixture_pack, inspect input hashes, verify benchmark reproducibility with verify_trade_fixture_pack_benchmark, rerun deterministic benchmark verification by adding rerunBenchmark: true, compare benchmark artifacts with compare_trade_fixture_pack_benchmarks, normalize precomputed detections with normalize_roboflow_game_footage, normalize_csv_game_footage, or normalize_tracking_game_footage, and validate external handoff contracts with validate_game_footage_external_handoff.

Example draft fit action parameters:

{
  "action": "evaluate_draft_candidate_fit",
  "runDir": "runs/draft-fit-demo",
  "draftProspectsPath": "/tmp/sports-impact-draft/prospects.json",
  "draftTeamNeedsPath": "/tmp/sports-impact-draft/team-needs.json",
  "draftTargetTeam": "LAL",
  "draftTopCandidates": 10
}

This writes draft/draft-candidate-fit.json and .md under the run directory with deterministic fit evidence only; it is not a draft recommendation. Then test whether the board is robust under alternate assumptions:

{
  "action": "analyze_draft_board_sensitivity",
  "runDir": "runs/draft-fit-demo",
  "draftFitReportPath": "runs/draft-fit-demo/draft/draft-candidate-fit.json",
  "draftBoardSensitivityTopCandidates": 10
}

The sensitivity report writes draft/draft-board-sensitivity.json and .md with default, win-now, upside, low-risk, minutes-pathway, skill-heavy, and source-confidence-penalty boards plus consensus/volatile/mover groups. When scout-board JSON/CSV is available, reconcile model and scout views:

{
  "action": "reconcile_draft_board",
  "runDir": "runs/draft-fit-demo",
  "draftFitReportPath": "runs/draft-fit-demo/draft/draft-candidate-fit.json",
  "draftBoardSensitivityPath": "runs/draft-fit-demo/draft/draft-board-sensitivity.json",
  "draftScoutBoardPath": "/tmp/sports-impact-draft/scout-board.json"
}

The reconciliation report writes draft/draft-board-reconciliation.json and .md with model/scout consensus, model-high/scouts-low, scouts-high/model-low, high-upside disagreement, source/data-gap disagreement, film-review, provenance-blocker, and meeting-agenda evidence. When market/mock-board JSON/CSV and pick slots are available, plan realistic paths through the board:

{
  "action": "plan_draft_availability",
  "runDir": "runs/draft-fit-demo",
  "draftFitReportPath": "runs/draft-fit-demo/draft/draft-candidate-fit.json",
  "draftBoardSensitivityPath": "runs/draft-fit-demo/draft/draft-board-sensitivity.json",
  "draftReconciliationPath": "runs/draft-fit-demo/draft/draft-board-reconciliation.json",
  "draftMarketBoardPath": "/tmp/sports-impact-draft/market-board.json",
  "draftPickSlots": [17, 47]
}

The availability plan writes draft/draft-availability-plan.json and .md with likely/maybe/unlikely availability, reach/value flags, contingency paths, and trade-up/down evidence only. During draft-night updates, remove selected players and refresh the live state:

{
  "action": "update_draft_war_room_state",
  "runDir": "runs/draft-fit-demo",
  "draftAvailabilityPath": "runs/draft-fit-demo/draft/draft-availability-plan.json",
  "draftSelectedPicksPath": "/tmp/sports-impact-draft/selected-picks.json",
  "draftCurrentPick": 14,
  "draftPickSlots": [17, 47]
}

The war-room state writes draft/draft-war-room-state.json and .md with unavailable candidates, remaining board, pick-slot target stacks, contingency changes, active/archived trade evidence, decision pressure, and a clock-ready briefing. To run the whole workflow from a manifest of actual/demo fixture paths, use:

{
  "action": "run_draft_workflow",
  "runDir": "runs/draft-workflow-demo",
  "draftWorkflowManifestPath": "runs/draft-workflow-demo/draft-workflow-manifest.json",
  "gateDraftWorkflow": true
}

The manifest schema is sports-impact-core/draft-workflow-manifest/v1 and includes targetTeam, currentPick, pickSlots, and input paths for prospects, teamNeeds, scoutBoard, marketBoard, and selectedPicks. The action writes all stage artifacts, draft/draft-workflow-run.json/.md, and optional draft-workflow-gate.json/.md; outputs remain evidence, not draft recommendations. For CI/demo evidence that the whole draft package still fits together, run the synthetic smoke workflow:

{
  "action": "run_draft_workflow_smoke",
  "runDir": "runs/draft-workflow-smoke-demo",
  "draftCurrentPick": 14,
  "draftPickSlots": [17, 47]
}

The smoke action generates deterministic draft fixtures, runs fit → sensitivity → reconciliation → availability → war-room → brief, and writes draft/draft-workflow-ci-smoke-summary.json plus .md with stage status, output paths, and hashes. To gate real/demo workflow artifacts, validate the emitted files:

{
  "action": "gate_draft_workflow",
  "runDir": "runs/draft-workflow-smoke-demo",
  "draftFitReportPath": "runs/draft-workflow-smoke-demo/draft-workflow-smoke/draft/draft-candidate-fit.json",
  "draftBoardSensitivityPath": "runs/draft-workflow-smoke-demo/draft-workflow-smoke/draft/draft-board-sensitivity.json",
  "draftReconciliationPath": "runs/draft-workflow-smoke-demo/draft-workflow-smoke/draft/draft-board-reconciliation.json",
  "draftAvailabilityPath": "runs/draft-workflow-smoke-demo/draft-workflow-smoke/draft/draft-availability-plan.json",
  "draftWarRoomStatePath": "runs/draft-workflow-smoke-demo/draft-workflow-smoke/draft/draft-war-room-state.json",
  "draftDecisionBriefPath": "runs/draft-workflow-smoke-demo/draft-workflow-smoke/draft/front-office-draft-decision-brief.json"
}

The gate checks schemas, linked source paths/hashes, candidate/team consistency, Markdown caveats, and not-a-draft-recommendation language. Then convert the fit evidence into a decision-room brief:

{
  "action": "build_draft_decision_brief",
  "runDir": "runs/draft-fit-demo",
  "draftFitReportPath": "runs/draft-fit-demo/draft/draft-candidate-fit.json",
  "draftDecisionBriefTopCandidates": 10
}

The brief writes draft/front-office-draft-decision-brief.json and .md with tiers, archetype picks, risk register, opportunity costs, analyst appendix, and next-review questions; it is still not a draft recommendation.

Example optimizer action parameters:

{
  "action": "optimize_balldontlie_demo_trades",
  "runDir": "runs/lal-balldontlie-search",
  "balldontliePackDir": "/tmp/sports-impact-balldontlie-nba-demo-pack",
  "targetTeam": "LAL",
  "partnerTeams": ["BKN", "ATL", "DAL"],
  "objectivePreset": "production_preserving",
  "maxOutgoing": 8,
  "maxIncomingPerTeam": 8,
  "tradeFamilies": ["1-for-1", "1-for-2", "2-for-1", "2-for-2"],
  "maxCandidateCount": 500,
  "topCandidates": 10,
  "protectTopNMinutes": 3,
  "maxOutgoingSalaryUsd": 20000000,
  "minFantasyDelta": -12,
  "excludePlayers": ["LeBron James", "Luka Doncic"]
}

Use this as internal demo/source-fit scenario search only: BALLDONTLIE is third-party aggregated best-effort data, derived payroll is known-contract salary only, and output rankings are deterministic objective scores rather than official recommendations. If tradeFamilies is omitted, the optimizer preserves the original 1-for-1 search behavior; add 1-for-2, 2-for-1, or 2-for-2 explicitly for aggregate-salary multi-player exploration.

Example explicit multi-team impact action parameters:

{
  "action": "evaluate_balldontlie_multi_team_demo_trade",
  "runDir": "runs/lal-bkn-atl-balldontlie-trade",
  "balldontliePackDir": "/tmp/sports-impact-balldontlie-nba-demo-pack",
  "multiTeamTradeLegs": [
    { "fromTeam": "LAL", "toTeam": "BKN", "player": "Rui Hachimura" },
    { "fromTeam": "BKN", "toTeam": "ATL", "player": "Day'Ron Sharpe" },
    { "fromTeam": "ATL", "toTeam": "LAL", "player": "ATL Player" }
  ]
}

Use this only for explicit supplied legs; it evaluates per-team salary/apron feasibility and target-team-perspective impact for every participating team, not a legal/CBA ruling or transaction recommendation.

Example generated three-team search action parameters:

{
  "action": "optimize_balldontlie_three_team_demo_trades",
  "runDir": "runs/lal-three-team-balldontlie-search",
  "balldontliePackDir": "/tmp/sports-impact-balldontlie-nba-demo-pack",
  "targetTeam": "LAL",
  "partnerTeams": ["BKN", "ATL", "DAL"],
  "maxPlayersPerTeam": 4,
  "maxCandidateCount": 250,
  "topCandidates": 10,
  "objectivePreset": "balanced_multi_team",
  "threeTeamTradeFamilies": ["1-for-1-for-1", "2-for-1-for-1"],
  "protectTopNMinutes": 3,
  "maxTargetOutgoingSalaryUsd": 30000000,
  "minTargetFantasyDelta": -15,
  "minAllTeamFantasyDelta": 0,
  "minTeamFantasyDelta": -8,
  "maxTeamNetSalaryIncreaseUsd": 5000000,
  "maxTeamIncomingSalaryUsd": 30000000,
  "requireNoTeamFantasyLossBelow": -12,
  "requireAllTeamsFeasible": true,
  "dedupeByTargetSwap": true,
  "maxCandidatesPerTargetOutgoingPlayer": 3,
  "maxCandidatesPerTargetIncomingPlayer": 3,
  "excludePlayers": ["LeBron James", "Luka Doncic"],
  "generateCandidateComparison": true,
  "candidateComparisonRetainedLimit": 5,
  "candidateComparisonAlternativesPerCandidate": 3,
  "targetSalaryReliefWeight": 1,
  "targetFantasyDeltaWeight": 1,
  "targetNetRatingWeight": 10,
  "allTeamFantasyDeltaWeight": 0.25
}

Use this as generated scenario search only; it enumerates bounded one- or multi-player three-team cycles, applies explicit player/protection/salary/impact guardrails (including top-minute protection across every participating team's outgoing pool), applies partner-team fairness constraints and candidate diversity controls to reduce one-sided or near-duplicate target swaps, writes guardrail audit artifacts with protected-player/exclusion/fairness/filter counts plus verification status, evaluates every participating team, emits source-fit confidence, per-top-candidate explanation artifacts with filtered alternatives grouped by failure reason plus closest guardrail-boundary details, and filtered-candidates/ near-miss artifacts grouped by failed guardrail, then ranks by transparent objective weights rather than making recommendations. Set generateCandidateComparison: true to also emit retained-vs-filtered candidate-comparison.json / .md artifacts during optimization without changing ranking. Use inspect_balldontlie_three_team_filtered_candidates with inputPath or filteredCandidateIndexPath plus optional filteredCandidateReason, filteredCandidateTeam, and filteredCandidateLimit to summarize top failure reasons, closest near misses, and by-team guardrail gaps. Use compare_balldontlie_three_team_candidates with inputPath, optional filteredCandidateReason/filteredCandidateTeam, candidateComparisonRetainedLimit, and candidateComparisonAlternativesPerCandidate to pair retained top candidates with nearest filtered alternatives by target-swap similarity and guardrail gap when a standalone comparison step is preferred. Use gate_balldontlie_three_team_candidate_comparison with candidateComparisonPath/candidateComparisonReportPath to fail on comparison schema/content drift. Preset defaults are intentionally opinionated but overridable: balanced_multi_team adds an aggregate all-team fantasy floor, apron_escape adds a target salary-relief floor, and star_protected adds target-swap diversity caps. In CI or Pi, gate emitted audit artifacts with gate_balldontlie_three_team_guardrail_audit or npm run gate:balldontlie-three-team-guardrail-audit -- --audit <run>/balldontlie-three-team-trade-search/three-team-guardrail-audit.json --out <gate.json> --report <gate.md> to fail when returned-candidate verification is not clean or required audit count fields are missing. Use Pi action gate_balldontlie_three_team_source_fit_explanations with inputPath/sourceFitSummaryPath and optional minimumConfidence, or npm run gate:balldontlie-three-team-source-fit-explanations -- --summary <run>/balldontlie-three-team-trade-search/summary.json --out <source-fit-gate.json> --report <source-fit-gate.md>, to fail when retained candidates lose sourceFit fields, explanation artifacts drift, or filtered-candidate near-miss artifacts disappear/schema-drift. The workspace CI/release-preflight smoke uses npm run gate:balldontlie-three-team-guardrail-audit:smoke to generate one combined synthetic guardrail + source-fit + candidate-comparison gate evidence summary/report plus the underlying gate, comparison, and filtered-near-miss artifacts.

Continue with sports-impact analysis by asking Pi to normalize valid external handoffs with normalize_external_handoff_game_footage, gate external handoff fixture-pack CI evidence with gate_game_footage_external_handoff_fixture_pack, gate invalid external handoff manifests with gate_game_footage_external_handoff_invalid_fixtures, generate downstream external handoff gate CI YAML with generate_game_footage_external_handoff_gate_ci, verify adopted external handoff gate CI YAML with verify_game_footage_external_handoff_gate_ci, verify downstream adoption registries with verify_game_footage_external_handoff_gate_ci_registry, gate downstream adoption registry policy/drift with gate_game_footage_external_handoff_gate_ci_registry, generate registry-gate CI YAML with generate_game_footage_external_handoff_gate_ci_registry_gate, verify adopted registry-gate CI YAML with verify_game_footage_external_handoff_gate_ci_registry_gate, verify registry-gate CI adoption registries with verify_game_footage_external_handoff_gate_ci_registry_gate_registry, gate registry-gate CI adoption registry policy/drift with gate_game_footage_external_handoff_gate_ci_registry_gate_registry, generate/verify downstream CI YAML for that verifier+gate pair with generate_game_footage_external_handoff_gate_ci_registry_gate_registry_gate / verify_game_footage_external_handoff_gate_ci_registry_gate_registry_gate, verify adoption registries for that generated workflow with verify_game_footage_external_handoff_gate_ci_registry_gate_registry_gate_registry, analyze precomputed tracking outputs with analyze_game_footage, render deterministic court SVGs with render_game_footage_court, materialize fixture-pack visualization artifacts with materialize_game_footage_visualizations, verify materialized visualization bundles with verify_game_footage_visualization_bundle, compare visualization bundles with compare_game_footage_visualization_bundles, gate visualization bundle drift with gate_game_footage_visualization_bundle_drift, check committed visualization baselines with check_game_footage_visualization_baseline, create promotion evidence with promote_game_footage_visualization_baseline, verify promotion evidence with verify_game_footage_visualization_baseline_promotion, check baseline suites with check_game_footage_visualization_baseline_suite, append and verify promotion ledgers with append_game_footage_visualization_baseline_promotion_ledger_entry / verify_game_footage_visualization_baseline_promotion_ledger, verify promotion-ledger registries with verify_game_footage_visualization_baseline_promotion_ledger_registry, gate promotion-ledger registry policy with gate_game_footage_visualization_baseline_promotion_ledger_registry, compare promotion-ledger registries over time with compare_game_footage_visualization_baseline_promotion_ledger_registries, gate registry-comparison policy with gate_game_footage_visualization_baseline_promotion_ledger_registry_comparison, scaffold lifecycle policy presets with scaffold_game_footage_visualization_baseline_lifecycle, verify lifecycle conformance with verify_game_footage_visualization_baseline_lifecycle, audit lifecycle run directories with audit_game_footage_visualization_baseline_lifecycle, generate lifecycle CI adoption YAML with generate_game_footage_visualization_baseline_lifecycle_ci, verify adopted lifecycle CI with verify_game_footage_visualization_baseline_lifecycle_ci, compare lifecycle audit trends with compare_game_footage_visualization_baseline_lifecycle_runs, gate lifecycle trend policy with gate_game_footage_visualization_baseline_lifecycle_trend, verify/gate reusable lifecycle trend registries with verify_game_footage_visualization_baseline_lifecycle_trend_registry / gate_game_footage_visualization_baseline_lifecycle_trend_registry, compare registry history with compare_game_footage_visualization_baseline_lifecycle_trend_registries, gate registry deltas with gate_game_footage_visualization_baseline_lifecycle_trend_registry_comparison using scaffolded policy files, aggregate registry/gate history into a dashboard with create_game_footage_visualization_baseline_lifecycle_dashboard, verify dashboard adoption with verify_game_footage_visualization_baseline_lifecycle_dashboard_adoption, verify/gate/compare dashboard adoption registries with verify_game_footage_visualization_baseline_lifecycle_dashboard_adoption_registry, gate_game_footage_visualization_baseline_lifecycle_dashboard_adoption_registry, compare_game_footage_visualization_baseline_lifecycle_dashboard_adoption_registries, and gate_game_footage_visualization_baseline_lifecycle_dashboard_adoption_registry_comparison, audit game-footage fixture packs with audit_game_footage_fixture_pack (including external handoff validation/normalization evidence and optional visualization artifact hashes), verify deterministic game-footage fixture-pack reruns with verify_game_footage_fixture_pack_rerun, split trade backtests with split_trade_backtests, evaluate readiness gates with evaluate_trade_model_readiness, score reserved holdouts with evaluate_trade_holdout, run unified audits with audit_trade_fixtures, diagnose residuals with diagnose_trade_model, or execute the fixture-backed workflows in examples/nba-injury/, examples/nba-trade/, examples/nba-trade-calibration/, examples/nba-trade-fixture-quality/, examples/nba-trade-historical-template/, and examples/nba-game-footage/. See docs/PI_INSTALL.md in the repository for a full prompt and guardrails.