Skip to content

Latest commit

 

History

History
104 lines (74 loc) · 4.21 KB

README.md

File metadata and controls

104 lines (74 loc) · 4.21 KB

Alpha Sim Framework

Standalone NFL decision/simulation framework that integrates with espn_api league objects.

What It Includes

  • AdvancedFantasySimulator for matchup, trade, and free-agent analysis
  • MonteCarloSimulator for season/playoff simulation plus alpha-mode workflows
  • Alpha utility modules (alpha_model, alpha_snapshot, alpha_backtest, alpha_provider, alpha_types)
  • Composite provider (CompositeSignalProvider) with a 10-signal base blend plus optional extended high/medium signals behind enable_extended_signals
  • League context pipeline (league_context) for persistent ESPN history + derived behavior analytics
  • League adapter (from_espn_league) to convert live ESPN objects into a stable internal shape
  • CLI entrypoint: fantasy-decision-maker

Install

uv sync
git config core.hooksPath .githooks

Quick Run

Default mode is interactive (menu-driven):

uv run fantasy-decision-maker --league-id <LEAGUE_ID> --team-id <TEAM_ID> --year <YEAR>

Non-interactive report generation:

uv run fantasy-decision-maker --league-id <LEAGUE_ID> --team-id <TEAM_ID> --year <YEAR> --report-only

Python Usage (Adapter + Simulator)

from espn_api.football import League
from alpha_sim_framework import MonteCarloSimulator, from_espn_league

espn_league = League(league_id=123, year=2026, espn_s2="...", swid="...")
league_ctx = from_espn_league(espn_league)

sim = MonteCarloSimulator(league_ctx, num_simulations=2000, alpha_mode=True)
results = sim.run_simulations(explain=True)

A/B With Composite Provider

Fill in league/team/year values in config.ab.template.json first, then run:

uv run fantasy-decision-maker \
  --ab-config config.ab.template.json \
  --ab-eval

A/B With Free API Gateways (No Separate Service)

Use config.ab.free.template.json to run canonical feed ingestion directly from free sources (free://... adapters for Open-Meteo + Sleeper + league-derived heuristics):

uv run fantasy-decision-maker \
  --ab-config config.ab.free.template.json \
  --ab-eval

Optional: set ODDS_API_KEY to enrich odds from The Odds API free tier.

Gateway Endpoint Discovery

uv run gateway-probe --config config.gateway_probe.template.json --output-dir reports/gateway_probe

Research Sources

Fantasy football modeling references used for current roadmap and TODO prioritization:

  • Becker, A., & Sun, X. A. (2016). An analytical approach for fantasy football draft and lineup management. Journal of Quantitative Analysis in Sports. DOI: 10.1515/jqas-2013-0009
  • Mlcoch, D., & Hubacek, O. (2024). Competing in daily fantasy sports using generative models. International Transactions in Operational Research. DOI: 10.1111/itor.13344
  • Kissell, R., & Poserina, J. (2017). Optimal Sports Math, Statistics, and Fantasy. Academic Press. Publisher page
  • Bonello, N., Beel, J., Lawless, S., & Debattista, J. (2019). Multi-stream Data Analytics for Enhanced Performance Prediction in Fantasy Football. arXiv. DOI: 10.48550/arXiv.1912.07441
  • Landers, J. R., & Duperrouzel, B. (2019). Machine Learning Approaches to Competing in Fantasy Leagues for the NFL. IEEE Transactions on Games. DOI: 10.1109/TG.2018.2841057

TODO

  • Add player_uncertainty_overrides output to support variance-level adjustments (not only mean projection shifts).
  • Add confidence_scores output for per-player signal reliability and gating in downstream decisions.
  • Add feature_attribution output for explainability/audit trails of alpha contributions.
  • Add per-player data_quality_flags output to surface stale/missing/low-quality external feed inputs.

Docs Index