stathead 0.2.1__tar.gz → 0.3.2__tar.gz

stathead-0.3.2/.gitignore

@@ -0,0 +1,125 @@
+node_modules
+dist
+# ...except the published MCP server bundle (the distributable artifact).
+!mcp/dist/
+!mcp/dist/server.mjs
+.DS_Store
+*.local
+.env
+!.env.example
+public/data/*
+!public/data/schedule-*.json
+!public/data/redraft-projections-presets.json
+# Mike Clay's NFL Projection Guide (ESPN+) is a paid product — its raw extracts
+# are LOCAL-ONLY (regenerate via scripts/extract_clay_*.py from a PDF you own).
+# Never commit clay-*.json; only the derived/anonymized blends ship. See
+# DATA_SOURCES.md ("Paid products — never redistribute the source").
+public/data/clay-projections-*.json
+public/data/clay-unit-grades-*.json
+public/data/clay-matchups-*.json
+public/data/clay-team-projections-*.json
+!public/data/training-rows-cache-*.json
+!public/data/trained-models-cache-*.json
+!public/data/model-cache-*.json
+!public/data/feature-store/
+!public/data/score-store/
+!public/data/ktc_rankings_*.json
+!public/data/ktc_history.json
+!public/data/nflverse_weekly_2025.json
+!public/data/ppg-feature-ablation.json
+!public/data/ppg-hyperparam-sweep.json
+!public/data/residual-feature-ablation.json
+!public/data/residual-hyperparam-sweep.json
+!public/data/ktc-feature-ablation.json
+!public/data/ktc-hyperparam-sweep.json
+!public/data/pdf-career-ablation-predraft.json
+!public/data/pdf-career-ablation-postdraft.json
+!public/data/rsp-career-ablation-predraft.json
+!public/data/rsp-career-ablation-postdraft.json
+!public/data/pdf-only-career-test.json
+!public/data/qb-beast-ablation.json
+!public/data/ktc-forecasts-*.json
+!public/data/redraft-projections.json
+!public/data/projection-base-*.json
+!public/data/weekly-projections-*.json
+!public/data/model-eval-*.json
+!public/data/team-metrics-*.json
+!public/data/coach-tendencies.json
+!public/data/player-metrics-*.json
+!public/data/pbp-slim-*.json.gz
+!public/data/prospect-boom-bust.json
+!public/data/prospect-grades-*.json
+!public/data/depth-order-2026.json
+!public/data/career-2027.json
+!public/data/cfbd-college-stats.json
+!public/data/cfbd-sp-ratings.json
+!public/data/cfbd-recruiting.json
+!public/data/cfbd-games.json
+!public/data/cfbd-team-talent.json
+!public/data/cfbd-player-usage.json
+!public/data/cfbd/
+!public/data/cfbd/*.json
+!public/data/pdf-prospect-features.json
+!public/data/pdf-prospect-features-merged.json
+!public/data/rsp-historical-rankings.json
+!public/data/rsp-qb-features.json
+!public/data/manual-cfbd-overrides.json
+!public/data/player-crosswalk.json
+!public/data/player-id-map.json
+!public/data/player-aliases.json
+!public/data/player-promotions.json
+!public/data/player-conflicts.json
+!public/data/player-buzz.json
+# Raw upstream sources committed as .csv.gz (~35 MB vs ~200 MB raw).
+# TS readLocalFile auto-decompresses; Python runs `bash scripts/extract-data.sh`
+# once to materialize the .csv. See scripts/pull-all-data-sources.sh.
+!public/data/*.csv.gz
+!public/data/ffc_adp_ppr_*.json
+!public/data/ffc_adp_2qb_*.json
+!public/data/espn_adp_*.json
+!public/data/espn-nfl-ids.json
+!public/data/fantasycalc_*.json
+!public/data/fantasycalc_history_*.json
+!public/data/sleeper-players.json
+!public/data/sleeper-adp-*.json
+!public/data/ktc-fc-rescale.json
+# Aggregated, anonymized expert activity (no usernames) — committed/deployed.
+# Built by scripts/build_expert_data.py from the gitignored private/ list.
+!public/data/expert-ownership.json
+!public/data/expert-adds.json
+!public/data/expert-trades.json
+!public/data/expert-graph.json
+!public/data/expert-league-graph.json
+!public/data/expert-candidates.json
+# expert-names.json (index -> username) is intentionally NOT un-ignored: it stays
+# local-only so the social graph / rankings can show names in dev but never ship.
+# Its passphrase-encrypted form (scripts/encrypt-expert-names.mjs) IS committed:
+# the deployed Social Graph decrypts it in-browser after an "unlock" passphrase.
+# The ciphertext is public, so the passphrase is the only protection — keep it strong.
+!public/data/expert-names.enc.json
+.claude/*
+!.claude/commands/
+!.claude/commands/**
+CLAUDE.local.md
+__pycache__/
+.nflverse-cache/
+.cache/
+.venv/
+pdfs/
+
+# Footballguys SFB cheatsheet (paid product) — LOCAL-ONLY, never committed.
+# Regenerate from a PDF you own:
+#   pdftotext -layout <cheatsheet.pdf> - | npx tsx scripts/parse-sfb-cheatsheet.ts > public/data/sfb16-cheatsheet.json
+# (already covered by the public/data/* ignore; listed here for discoverability)
+public/data/sfb16-cheatsheet.json
+
+# Proprietary inputs (Clay PDFs + parsed dataset) — never committed.
+/private/
+# Local-only Clay projection set consumed at runtime by the "Consensus" preset.
+# Never committed — absent in the public deploy so Clay's numbers ship nowhere.
+/public/data/clay/
+
+# Downloaded headshot images
+headshots.zip
+headshots_part*.zip
+!public/data/depth-starters-*.json

{stathead-0.2.1 → stathead-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stathead
-Version: 0.2.1
+Version: 0.3.2
 Summary: Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, and flattened feature matrices.
 Project-URL: Homepage, https://github.com/dachhack/stathead
 Project-URL: Source, https://github.com/dachhack/stathead
@@ -39,8 +39,8 @@ pip install stathead
 Optional extras:
 
 ```bash
-pip install "stathead[polars]"   # for .to_polars() helpers
-pip install "stathead[duckdb]"   # for local SQL querying
+pip install "stathead[polars]"   # for sh.to_polars() / sh.load_polars() helpers
+pip install "stathead[duckdb]"   # for local SQL querying (sh.query)
 ```
 
 ## Quick start
@@ -62,6 +62,58 @@ adp = sh.load_adp_historical()
 adp[(adp.season == 2023) & (adp.adp <= 24)]
 ```
 
+## SQL querying
+
+With the `duckdb` extra, `sh.query()` runs SQL over the loaders — the same
+surface as the site's Data Query tab, in Python. Every table joins on
+`player_key`.
+
+```bash
+pip install "stathead[duckdb]"
+```
+
+```python
+import stathead as sh
+
+sh.query("""
+    SELECT c.name, c.position, c.predictedCareerPPG, d.value_1qb
+    FROM career_2026 c
+    JOIN dynasty_values d USING (player_key)
+    WHERE c.percentile >= 80
+    ORDER BY d.value_1qb DESC
+""")
+
+sh.list_tables()   # every queryable table name
+```
+
+Tables load lazily — only the ones a query references are materialized, so a
+query that never touches `player_stats` (~400k rows) doesn't pay for it.
+Register your own DataFrame (a roster, a league export) to join against the
+model tables:
+
+```python
+sh.register("my_roster", roster_df)
+sh.query("SELECT * FROM career_2026 c JOIN my_roster r USING (player_key)")
+```
+
+## Polars
+
+Loaders return pandas. With the `polars` extra, convert any of them — handy on
+the big tables like `load_player_stats` (~400k rows) where polars is faster.
+
+```bash
+pip install "stathead[polars]"
+```
+
+```python
+import stathead as sh
+
+pl_df = sh.to_polars(sh.load_player_stats(2024))
+
+# Or convert a loader by reference, without calling it yourself:
+pl_df = sh.load_polars(sh.load_player_stats, 2024)
+```
+
 ## Pinning to a specific version
 
 Loaders resolve against the upstream GitHub repo. Pin to a commit SHA, tag,
@@ -85,16 +137,61 @@ cache directory or call `clear_cache()` to force a refresh.
 
 ## Available loaders
 
+Every table on the [StatHead site](https://github.com/dachhack/stathead) is
+available here as a pandas DataFrame.
+
+**Predictions & prospects**
+
 | Function | Returns | Shape |
 |---|---|---|
 | `load_career_predictions_2026()` | 2026 rookie predictions | ~77 × ~80 cols |
 | `load_career_backtest()` | Historical rookies with pred + actual PPG | ~1087 × ~100 cols |
+| `load_prospect_grades(year=2026)` | Scouting-report grades | ~200 × 7 |
+| `load_career_2027()` | 2027 draft-class early board + college aggregates | ~200 × ~30 |
+
+**Projections (model outputs)**
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_redraft_projections()` | Seasonal redraft PPG (PPR) + receptions/game | ~250 × 7 |
+| `load_weekly_projections()` | Per-week matchup-adjusted projections, one row per player-game (opp, home, matchup mult, PPR pts; `df.attrs['def_vs_pos']`) | ~445 × 17 rows/player |
+| `load_ppg_projections()` | Model-predicted PPG for established players | ~250 × 4 |
+| `load_adp_value_model()` | VOR vs ADP, hit probability, confidence interval | ~153 × 10 |
+| `load_volume_projections()` | Team pass/rush/target volumes with low/high bands | ~153 × ~14 |
+| `load_share_projections()` | Predicted target + rush share | ~153 × 6 |
+| `load_taxi_predictions()` | Taxi-squad roster/drop probabilities (+ `df.attrs['meta']`) | ~96 × 6 |
+
+**Market & stats**
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_player_stats(season=None)` | Per-player per-week NFL box scores 2010-present | ~400k × ~50 |
+| `load_dynasty_values()` | In-house blended dynasty value (1QB + Superflex) | ~500 × 10 |
+| `load_dynasty_value_history()` | Blended daily dynasty value history | variable |
 | `load_adp_historical()` | Model-training ADP 2010-2025 | 4507 × 10 |
 | `load_adp_ffc(season=None)` | FFC PPR raw ADP (per season as fetched) — data via [Fantasy Football Calculator](https://fantasyfootballcalculator.com/adp/ppr) | variable |
-| `load_prospect_grades(year=2026)` | Scouting-report grades | ~200 × 7 |
+
+**Identity & raw**
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_player_crosswalk()` | Canonical cross-source player IDs | ~10k × ~20 |
+| `resolve_player(name, position=None)` / `get_player(key)` / `load_player_profile(key)` | Name → `player_key` helpers | — |
 | `load_feature_matrix()` | Raw `feature-matrix.json` (dict) | — |
 | `load_manual_overrides()` | Manual CFBD usage overrides (dict) | — |
 
+Every row-shaped loader carries a `player_key` column that joins to
+`load_player_crosswalk()`.
+
+### Dynasty values are the app's in-house blend
+
+`load_dynasty_values()` returns the same blended value the web app displays:
+KTC rankings rescaled into FantasyCalc's scale via a per-player ratio
+(`fc_value / ktc_value`, with a positional-median fallback below a value
+floor). The ratio snapshot is built offline and committed as
+`public/data/dynasty-fc-rescale.json`; the loader just applies it. No raw KTC
+value is exposed — only the rescaled blend.
+
 ## Feature columns
 
 Career-prediction and backtest rows include flattened model features

{stathead-0.2.1 → stathead-0.3.2}/README.md

@@ -11,8 +11,8 @@ pip install stathead
 Optional extras:
 
 ```bash
-pip install "stathead[polars]"   # for .to_polars() helpers
-pip install "stathead[duckdb]"   # for local SQL querying
+pip install "stathead[polars]"   # for sh.to_polars() / sh.load_polars() helpers
+pip install "stathead[duckdb]"   # for local SQL querying (sh.query)
 ```
 
 ## Quick start
@@ -34,6 +34,58 @@ adp = sh.load_adp_historical()
 adp[(adp.season == 2023) & (adp.adp <= 24)]
 ```
 
+## SQL querying
+
+With the `duckdb` extra, `sh.query()` runs SQL over the loaders — the same
+surface as the site's Data Query tab, in Python. Every table joins on
+`player_key`.
+
+```bash
+pip install "stathead[duckdb]"
+```
+
+```python
+import stathead as sh
+
+sh.query("""
+    SELECT c.name, c.position, c.predictedCareerPPG, d.value_1qb
+    FROM career_2026 c
+    JOIN dynasty_values d USING (player_key)
+    WHERE c.percentile >= 80
+    ORDER BY d.value_1qb DESC
+""")
+
+sh.list_tables()   # every queryable table name
+```
+
+Tables load lazily — only the ones a query references are materialized, so a
+query that never touches `player_stats` (~400k rows) doesn't pay for it.
+Register your own DataFrame (a roster, a league export) to join against the
+model tables:
+
+```python
+sh.register("my_roster", roster_df)
+sh.query("SELECT * FROM career_2026 c JOIN my_roster r USING (player_key)")
+```
+
+## Polars
+
+Loaders return pandas. With the `polars` extra, convert any of them — handy on
+the big tables like `load_player_stats` (~400k rows) where polars is faster.
+
+```bash
+pip install "stathead[polars]"
+```
+
+```python
+import stathead as sh
+
+pl_df = sh.to_polars(sh.load_player_stats(2024))
+
+# Or convert a loader by reference, without calling it yourself:
+pl_df = sh.load_polars(sh.load_player_stats, 2024)
+```
+
 ## Pinning to a specific version
 
 Loaders resolve against the upstream GitHub repo. Pin to a commit SHA, tag,
@@ -57,16 +109,61 @@ cache directory or call `clear_cache()` to force a refresh.
 
 ## Available loaders
 
+Every table on the [StatHead site](https://github.com/dachhack/stathead) is
+available here as a pandas DataFrame.
+
+**Predictions & prospects**
+
 | Function | Returns | Shape |
 |---|---|---|
 | `load_career_predictions_2026()` | 2026 rookie predictions | ~77 × ~80 cols |
 | `load_career_backtest()` | Historical rookies with pred + actual PPG | ~1087 × ~100 cols |
+| `load_prospect_grades(year=2026)` | Scouting-report grades | ~200 × 7 |
+| `load_career_2027()` | 2027 draft-class early board + college aggregates | ~200 × ~30 |
+
+**Projections (model outputs)**
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_redraft_projections()` | Seasonal redraft PPG (PPR) + receptions/game | ~250 × 7 |
+| `load_weekly_projections()` | Per-week matchup-adjusted projections, one row per player-game (opp, home, matchup mult, PPR pts; `df.attrs['def_vs_pos']`) | ~445 × 17 rows/player |
+| `load_ppg_projections()` | Model-predicted PPG for established players | ~250 × 4 |
+| `load_adp_value_model()` | VOR vs ADP, hit probability, confidence interval | ~153 × 10 |
+| `load_volume_projections()` | Team pass/rush/target volumes with low/high bands | ~153 × ~14 |
+| `load_share_projections()` | Predicted target + rush share | ~153 × 6 |
+| `load_taxi_predictions()` | Taxi-squad roster/drop probabilities (+ `df.attrs['meta']`) | ~96 × 6 |
+
+**Market & stats**
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_player_stats(season=None)` | Per-player per-week NFL box scores 2010-present | ~400k × ~50 |
+| `load_dynasty_values()` | In-house blended dynasty value (1QB + Superflex) | ~500 × 10 |
+| `load_dynasty_value_history()` | Blended daily dynasty value history | variable |
 | `load_adp_historical()` | Model-training ADP 2010-2025 | 4507 × 10 |
 | `load_adp_ffc(season=None)` | FFC PPR raw ADP (per season as fetched) — data via [Fantasy Football Calculator](https://fantasyfootballcalculator.com/adp/ppr) | variable |
-| `load_prospect_grades(year=2026)` | Scouting-report grades | ~200 × 7 |
+
+**Identity & raw**
+
+| Function | Returns | Shape |
+|---|---|---|
+| `load_player_crosswalk()` | Canonical cross-source player IDs | ~10k × ~20 |
+| `resolve_player(name, position=None)` / `get_player(key)` / `load_player_profile(key)` | Name → `player_key` helpers | — |
 | `load_feature_matrix()` | Raw `feature-matrix.json` (dict) | — |
 | `load_manual_overrides()` | Manual CFBD usage overrides (dict) | — |
 
+Every row-shaped loader carries a `player_key` column that joins to
+`load_player_crosswalk()`.
+
+### Dynasty values are the app's in-house blend
+
+`load_dynasty_values()` returns the same blended value the web app displays:
+KTC rankings rescaled into FantasyCalc's scale via a per-player ratio
+(`fc_value / ktc_value`, with a positional-median fallback below a value
+floor). The ratio snapshot is built offline and committed as
+`public/data/dynasty-fc-rescale.json`; the loader just applies it. No raw KTC
+value is exposed — only the rescaled blend.
+
 ## Feature columns
 
 Career-prediction and backtest rows include flattened model features

{stathead-0.2.1 → stathead-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stathead"
-version = "0.2.1"
+version = "0.3.2"
 description = "Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, and flattened feature matrices."
 readme = "README.md"
 license = { text = "MIT" }

{stathead-0.2.1 → stathead-0.3.2}/src/stathead/__init__.py

@@ -24,11 +24,25 @@ from .crosswalk import (
     load_player_profile,
     resolve_player,
 )
+from .dynasty import load_dynasty_value_history, load_dynasty_values
 from .features import load_feature_matrix, load_manual_overrides
 from .predictions import load_career_backtest, load_career_predictions_2026
+from .projections import (
+    load_adp_value_model,
+    load_career_2027,
+    load_ppg_projections,
+    load_redraft_projections,
+    load_share_projections,
+    load_taxi_predictions,
+    load_volume_projections,
+    load_weekly_projections,
+)
+from .polars import load_polars, to_polars
 from .prospects import load_prospect_grades
+from .sql import list_tables, query, register
+from .stats import load_player_stats
 
-__version__ = "0.2.1"
+__version__ = "0.3.2"
 
 __all__ = [
     "__version__",
@@ -37,13 +51,29 @@ __all__ = [
     "set_ref",
     "load_adp_ffc",
     "load_adp_historical",
+    "load_adp_value_model",
+    "load_career_2027",
     "load_career_backtest",
     "load_career_predictions_2026",
+    "load_dynasty_value_history",
+    "load_dynasty_values",
     "load_feature_matrix",
     "load_manual_overrides",
     "load_player_crosswalk",
     "load_player_profile",
+    "load_player_stats",
+    "load_ppg_projections",
     "load_prospect_grades",
+    "load_redraft_projections",
+    "load_share_projections",
+    "load_taxi_predictions",
+    "load_volume_projections",
+    "load_weekly_projections",
     "get_player",
     "resolve_player",
+    "query",
+    "register",
+    "list_tables",
+    "to_polars",
+    "load_polars",
 ]

{stathead-0.2.1 → stathead-0.3.2}/src/stathead/crosswalk.py

@@ -72,6 +72,42 @@ def _crosswalk_cached() -> list[dict[str, Any]]:
     return fetch_json("public/data/player-crosswalk.json").get("players") or []
 
 
+@lru_cache(maxsize=1)
+def key_by_name_pos() -> dict[tuple[str, str], str]:
+    """``(_norm(name), position) -> player_key`` for every name a player has
+    gone by (display name, ``all_names``, aliases) crossed with every
+    position they've held. First writer wins so the canonical record is
+    preferred over an alias. Used by loaders that only carry name+position
+    (dynasty blend, projections) to stamp the canonical ``player_key``."""
+    out: dict[tuple[str, str], str] = {}
+    for rec in _crosswalk_cached():
+        key = rec.get("player_key")
+        if not key:
+            continue
+        names = {rec.get("display_name", "")}
+        names.update(rec.get("all_names") or [])
+        names.update(a.get("name", "") for a in rec.get("aliases") or [])
+        positions = set(rec.get("all_positions") or []) | {rec.get("position") or ""}
+        for nm in names:
+            n = _norm(nm)
+            if not n:
+                continue
+            for pos in positions:
+                out.setdefault((n, pos), key)
+    return out
+
+
+@lru_cache(maxsize=1)
+def key_by_gsis() -> dict[str, str]:
+    """``gsis_id -> player_key``. Used to stamp the canonical key onto
+    weekly ``player_stats`` rows (whose ``player_id`` is the GSIS ID)."""
+    return {
+        str(rec["gsis_id"]): rec["player_key"]
+        for rec in _crosswalk_cached()
+        if rec.get("gsis_id") and rec.get("player_key")
+    }
+
+
 def resolve_player(name: str, position: str | None = None) -> str:
     """Return the canonical ``player_key`` for a player name.