stathead 0.2.1__tar.gz → 0.3.1__tar.gz

stathead-0.3.1/.gitignore

@@ -0,0 +1,118 @@
+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/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/
+
+# 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stathead
-Version: 0.2.1
+Version: 0.3.1
 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,60 @@ 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_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.1}/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,60 @@ 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_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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stathead"
-version = "0.2.1"
+version = "0.3.1"
 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.1}/src/stathead/__init__.py

@@ -24,11 +24,24 @@ 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,
+)
+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.1"
 
 __all__ = [
     "__version__",
@@ -37,13 +50,28 @@ __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",
     "get_player",
     "resolve_player",
+    "query",
+    "register",
+    "list_tables",
+    "to_polars",
+    "load_polars",
 ]

{stathead-0.2.1 → stathead-0.3.1}/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.
 

stathead-0.3.1/src/stathead/dynasty.py

@@ -0,0 +1,192 @@
+"""In-house dynasty value — the same blended value the web app shows.
+
+The app is built on a KTC-trained forecast but displays every value on
+FantasyCalc's scale. The bridge is a per-player ratio ``fc_value /
+ktc_value`` (with a positional-median fallback for players below a value
+floor or missing from FantasyCalc), precomputed offline into
+``public/data/dynasty-fc-rescale.json`` by ``scripts/build-rescale-snapshot.cjs``.
+
+These loaders apply that existing snapshot to the KTC values — they do not
+invent a new blend. The output is the canonical "blended dynasty value"
+(KTC rescaled to FC scale); no raw KTC value is exposed.
+
+Mirrors ``src/lib/valueRescale.ts``. Keep in sync.
+"""
+from __future__ import annotations
+
+from statistics import median
+from typing import Any
+
+import pandas as pd
+
+from ._fetch import fetch_json
+from .crosswalk import _norm, key_by_name_pos
+
+_SUPPORTED_POS = ("QB", "RB", "WR", "TE")
+# KTC values below this fall back to the positional-median ratio (mirrors
+# RESCALE_FLOOR in valueRescale.ts).
+_RESCALE_FLOOR = 500
+
+
+class _Rescaler:
+    """Resolve and apply per-player / positional KTC->FC ratios."""
+
+    def __init__(self, snap: dict[str, Any]):
+        self._floor = snap.get("floor", _RESCALE_FLOOR)
+        self._per_player: dict[int, dict[str, float]] = {
+            int(pid): v for pid, v in (snap.get("perPlayer") or {}).items()
+        }
+        self._positional: dict[str, dict[str, float]] = snap.get("positional") or {}
+
+    def ratio(self, player_id: int, ktc_value: float, position: str,
+              fmt: str) -> float | None:
+        if position not in _SUPPORTED_POS:
+            return None
+        key = "oneQB" if fmt == "1qb" else "sf"
+        player = self._per_player.get(player_id)
+        if player and player.get(key) is not None and ktc_value >= self._floor:
+            return player[key]
+        return (self._positional.get(position) or {}).get(key)
+
+    def value(self, player_id: int, ktc_value: float, position: str,
+              fmt: str) -> float:
+        r = self.ratio(player_id, ktc_value, position, fmt)
+        return ktc_value if r is None else round(ktc_value * r)
+
+
+def _load_rescaler() -> _Rescaler:
+    """Load the committed snapshot; if absent, derive one from the current
+    KTC + FantasyCalc snapshots (mirrors buildRescaleSnapshot)."""
+    try:
+        return _Rescaler(fetch_json("public/data/dynasty-fc-rescale.json"))
+    except Exception:
+        return _Rescaler(_build_snapshot())
+
+
+def _build_snapshot() -> dict[str, Any]:
+    """Fallback: build the KTC->FC ratio snapshot from live values, exactly
+    as scripts/build-rescale-snapshot.cjs does."""
+    ktc = fetch_json("public/data/ktc_rankings_1qb.json") or []
+    fc_1qb = fetch_json("public/data/fantasycalc_dynasty_1qb.json") or []
+    fc_sf = fetch_json("public/data/fantasycalc_dynasty_sf.json") or []
+
+    def fc_map(src: list[dict]) -> dict[tuple[str, str], float]:
+        out: dict[tuple[str, str], float] = {}
+        for r in src:
+            p = r.get("player") or {}
+            out[(_norm(p.get("name", "")), p.get("position", ""))] = r.get("value")
+        return out
+
+    fc1q, fcsf = fc_map(fc_1qb), fc_map(fc_sf)
+    per_player: dict[str, dict[str, float]] = {}
+    samples: dict[str, dict[str, list[float]]] = {
+        pos: {"oneQB": [], "sf": []} for pos in _SUPPORTED_POS
+    }
+    for k in ktc:
+        pos = k.get("position", "")
+        if pos not in _SUPPORTED_POS:
+            continue
+        key = (_norm(k.get("playerName", "")), pos)
+        entry: dict[str, float] = {}
+        fc1 = fc1q.get(key)
+        fcs = fcsf.get(key)
+        if fc1 is not None and (k.get("value") or 0) >= _RESCALE_FLOOR:
+            entry["oneQB"] = fc1 / k["value"]
+            samples[pos]["oneQB"].append(entry["oneQB"])
+        if fcs is not None and (k.get("superflexValue") or 0) >= _RESCALE_FLOOR:
+            entry["sf"] = fcs / k["superflexValue"]
+            samples[pos]["sf"].append(entry["sf"])
+        if entry:
+            per_player[str(k["playerID"])] = entry
+
+    positional = {
+        pos: {
+            "oneQB": median(samples[pos]["oneQB"]) if samples[pos]["oneQB"] else 1,
+            "sf": median(samples[pos]["sf"]) if samples[pos]["sf"] else 1,
+        }
+        for pos in _SUPPORTED_POS
+    }
+    return {"floor": _RESCALE_FLOOR, "perPlayer": per_player, "positional": positional}
+
+
+def load_dynasty_values() -> pd.DataFrame:
+    """Blended dynasty market value (1QB + Superflex) — the value the web
+    app displays.
+
+    KTC rankings rescaled into FantasyCalc's scale via the in-house
+    per-player ratio snapshot. Unsupported positions (K, picks) keep their
+    raw value; everything else is the rescaled blend.
+
+    Columns: ``player_key``, ``name``, ``position``, ``team``, ``age``,
+    ``value_1qb``, ``value_superflex``, ``positionRank``, ``isRookie``.
+    Sorted by ``value_1qb`` desc.
+    """
+    ktc = fetch_json("public/data/ktc_rankings_1qb.json") or []
+    rescaler = _load_rescaler()
+    keymap = key_by_name_pos()
+
+    rows: list[dict[str, Any]] = []
+    for r in ktc:
+        pid, pos = r.get("playerID"), r.get("position", "")
+        name = r.get("playerName", "")
+        rows.append({
+            "player_key": keymap.get((_norm(name), pos)),
+            "name": name,
+            "position": pos,
+            "team": r.get("team"),
+            "age": r.get("age"),
+            "value_1qb": rescaler.value(pid, r.get("value") or 0, pos, "1qb"),
+            "value_superflex": rescaler.value(pid, r.get("superflexValue") or 0, pos, "superflex"),
+            "positionRank": r.get("positionRank"),
+            "isRookie": r.get("isRookie"),
+        })
+    df = pd.DataFrame(rows)
+    return df.sort_values("value_1qb", ascending=False,
+                          na_position="last").reset_index(drop=True)
+
+
+def load_dynasty_value_history() -> pd.DataFrame:
+    """Daily dynasty value history (1QB + Superflex), rescaled to FC scale.
+
+    Same per-player ratio as :func:`load_dynasty_values`, applied to KTC's
+    daily history. One row per (player, date) with both formats side-by-side.
+
+    Columns: ``player_key``, ``name``, ``position``, ``date``,
+    ``value_1qb``, ``value_superflex``. Sorted by ``name``, ``date``.
+    """
+    ktc = fetch_json("public/data/ktc_rankings_1qb.json") or []
+    history = fetch_json("public/data/ktc_history.json") or []
+    rescaler = _load_rescaler()
+    keymap = key_by_name_pos()
+
+    # KTC history is keyed by playerID; map it back to name/position/team.
+    info = {
+        r.get("playerID"): (r.get("playerName", ""), r.get("position", ""))
+        for r in ktc
+    }
+
+    rows: list[dict[str, Any]] = []
+    for h in history:
+        pid = h.get("playerID")
+        name, pos = info.get(pid, ("", ""))
+        if not name:
+            continue
+        key = keymap.get((_norm(name), pos))
+        sf_by_date = {
+            p.get("d"): p.get("v")
+            for p in (h.get("superflex") or {}).get("valueHistory") or []
+        }
+        for p in (h.get("oneQB") or {}).get("valueHistory") or []:
+            date, v1 = p.get("d"), p.get("v")
+            vsf = sf_by_date.get(date)
+            rows.append({
+                "player_key": key,
+                "name": name,
+                "position": pos,
+                "date": date,
+                "value_1qb": rescaler.value(pid, v1 or 0, pos, "1qb"),
+                "value_superflex": (rescaler.value(pid, vsf, pos, "superflex")
+                                    if vsf is not None else None),
+            })
+    df = pd.DataFrame(rows)
+    return df.sort_values(["name", "date"]).reset_index(drop=True)

stathead-0.3.1/src/stathead/polars.py

@@ -0,0 +1,65 @@
+"""Polars interop — convert loader output to polars DataFrames.
+
+Loaders return pandas (that's the package's lingua franca); this is a thin
+bridge for callers who prefer polars, especially on the big tables like
+``load_player_stats`` (~400k rows) where polars is noticeably faster.
+
+    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)
+
+Requires the ``polars`` extra::
+
+    pip install "stathead[polars]"
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    import pandas as pd
+    import polars as pl
+
+
+def _polars() -> Any:
+    try:
+        import polars  # noqa: PLC0415
+    except ImportError as e:  # pragma: no cover - exercised via message
+        raise ImportError(
+            "stathead.to_polars() needs polars. Install it with:\n"
+            '    pip install "stathead[polars]"'
+        ) from e
+    return polars
+
+
+def to_polars(df: "pd.DataFrame") -> "pl.DataFrame":
+    """Convert a pandas DataFrame (any loader's output) to a polars DataFrame.
+
+    >>> import stathead as sh
+    >>> sh.to_polars(sh.load_dynasty_values()).head()
+    """
+    pl = _polars()
+    try:
+        return pl.from_pandas(df)
+    except ImportError:
+        # from_pandas needs pyarrow for object / extension-dtype columns
+        # (names, positions). Keep the polars extra light by falling back to a
+        # column-dict construction. NaN -> None first, or polars chokes on a
+        # str column with a float NaN mixed in.
+        clean = df.astype(object).where(df.notna(), None)
+        return pl.DataFrame({c: clean[c].to_list() for c in clean.columns})
+
+
+def load_polars(loader: Callable[..., "pd.DataFrame"], *args: Any, **kwargs: Any) -> "pl.DataFrame":
+    """Call a loader and return its result as a polars DataFrame.
+
+    Sugar for ``to_polars(loader(*args, **kwargs))`` so you don't repeat the
+    DataFrame:
+
+    >>> import stathead as sh
+    >>> sh.load_polars(sh.load_player_stats, 2024)
+    """
+    return to_polars(loader(*args, **kwargs))

stathead-0.3.1/src/stathead/projections.py

@@ -0,0 +1,116 @@
+"""Model projection outputs — the same numbers the web app's projection,
+ADP-value, volume, and taxi-squad tabs render.
+
+All of these are StatHead's own model outputs (scored from the feature
+store), so there's no third-party redistribution concern. Each loader
+stamps a canonical ``player_key`` where a name + position is available.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+from .crosswalk import _norm, key_by_name_pos
+
+
+def _stamp_keys(df: pd.DataFrame, name_col: str = "name",
+                pos_col: str = "position") -> pd.DataFrame:
+    """Add a leading ``player_key`` column resolved from (name, position)."""
+    if name_col not in df.columns or pos_col not in df.columns:
+        return df
+    keymap = key_by_name_pos()
+    keys = [
+        keymap.get((_norm(str(n)), str(p)))
+        for n, p in zip(df[name_col], df[pos_col])
+    ]
+    df.insert(0, "player_key", keys)
+    return df
+
+
+def load_redraft_projections() -> pd.DataFrame:
+    """Seasonal redraft projections — projected PPG (PPR) + receptions/game.
+
+    Veterans blend prior-season actuals, a 2-year average, and an age curve;
+    rookies use the career model's best-2-of-3 PPG with a per-position,
+    pick-based Year-1 discount. ``recPG`` (receptions/game) supports TE-premium
+    scoring.
+
+    Columns: ``player_key``, ``name``, ``position``, ``ppg``, ``recPG``,
+    ``season``, ``scoring``.
+    """
+    data = fetch_json("public/data/redraft-projections.json")
+    df = pd.DataFrame(data.get("players") or [])
+    df["season"] = data.get("season")
+    df["scoring"] = data.get("scoring")
+    return _stamp_keys(df)
+
+
+def load_ppg_projections() -> pd.DataFrame:
+    """Model-predicted points-per-game for established players.
+
+    Columns: ``player_key``, ``name``, ``position``, ``predictedPPG``.
+    """
+    df = pd.DataFrame(fetch_json("public/data/score-store/ppg.json"))
+    return _stamp_keys(df)
+
+
+def load_adp_value_model() -> pd.DataFrame:
+    """ADP value model — predicted value-over-replacement vs market ADP,
+    with a calibrated hit probability and confidence interval.
+
+    Columns: ``player_key``, ``name``, ``position``, ``team``, ``adp``,
+    ``predictedVor``, ``hitProb`` (label), ``ciLower``, ``ciUpper``,
+    ``isRookie``.
+    """
+    df = pd.DataFrame(fetch_json("public/data/score-store/adp.json"))
+    df = df.drop(columns=[c for c in ("headshotUrl",) if c in df.columns])
+    return _stamp_keys(df)
+
+
+def load_volume_projections() -> pd.DataFrame:
+    """Team + player volume projections with low/high bands.
+
+    Columns: ``player_key``, ``name``, ``position``, ``team``,
+    ``teamPassAtt`` (+ ``Low`` / ``High``), ``teamRushAtt`` (+ bands),
+    ``teamTargets`` (+ bands), ``projPlayerPPG``.
+    """
+    df = pd.DataFrame(fetch_json("public/data/score-store/volumes.json"))
+    return _stamp_keys(df)
+
+
+def load_share_projections() -> pd.DataFrame:
+    """Predicted target share + rush share for each player.
+
+    Columns: ``player_key``, ``name``, ``position``, ``team``,
+    ``predTargetShare``, ``predRushShare``.
+    """
+    df = pd.DataFrame(fetch_json("public/data/score-store/shares.json"))
+    return _stamp_keys(df)
+
+
+def load_taxi_predictions() -> pd.DataFrame:
+    """Taxi-squad model — probability a young player makes / sticks on a
+    fantasy roster.
+
+    Columns: ``player_key``, ``name``, ``position``, ``p1`` (year-1 roster
+    probability), ``p2`` (year-2), ``pEver`` (ever rostered). Model metadata
+    (training date, thresholds, LOSO AUC) is attached on
+    ``df.attrs['meta']``.
+    """
+    data = fetch_json("public/data/score-store/taxi.json")
+    df = pd.DataFrame(data.get("players") or [])
+    df = _stamp_keys(df)
+    df.attrs["meta"] = data.get("meta") or {}
+    return df
+
+
+def load_career_2027() -> pd.DataFrame:
+    """2027 draft-class early prospect board — grades + college aggregates.
+
+    The next class after :func:`~stathead.load_prospect_grades`. Columns
+    include ``name``, ``pos``, ``school``, ``grade``, ``projPick``,
+    ``projRound``, ``tier``, plus college career box-score totals
+    (``careerPassYds``, ``careerRushYds``, ``careerRecYds``, …).
+    """
+    df = pd.DataFrame(fetch_json("public/data/career-2027.json"))
+    return _stamp_keys(df, pos_col="pos")

stathead-0.3.1/src/stathead/sql.py

@@ -0,0 +1,162 @@
+"""Local SQL over the loaders, via DuckDB.
+
+``sh.query(sql)`` registers each loader as a DuckDB table and runs SQL
+against it — the same surface as the web app's Data Query tab, in Python.
+Tables join on ``player_key``.
+
+    import stathead as sh
+
+    sh.query('''
+        SELECT c.name, 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
+    ''')
+
+Requires the ``duckdb`` extra::
+
+    pip install "stathead[duckdb]"
+
+Tables are loaded lazily — only those a query references are materialized,
+so a query that never touches ``player_stats`` (~400k rows) doesn't pay for
+it. Loaded tables are cached for the process and keyed to the pinned ref;
+calling :func:`~stathead.pin_version` resets the cache.
+
+Register your own DataFrame (a roster, a league export) to join against the
+model tables::
+
+    sh.register("my_roster", roster_df)
+    sh.query("SELECT * FROM career_2026 c JOIN my_roster r USING (player_key)")
+"""
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any, Callable
+
+from . import _fetch
+from .adp import load_adp_ffc, load_adp_historical
+from .crosswalk import load_player_crosswalk
+from .dynasty import load_dynasty_value_history, load_dynasty_values
+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,
+)
+from .prospects import load_prospect_grades
+from .stats import load_player_stats
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+# Table name -> loader. Names mirror the web app's Data Query tab where they
+# overlap, with the projection loaders added.
+_TABLES: dict[str, Callable[[], "pd.DataFrame"]] = {
+    "player_crosswalk": load_player_crosswalk,
+    "career_2026": load_career_predictions_2026,
+    "career_2027": load_career_2027,
+    "backtest": load_career_backtest,
+    "prospects": load_prospect_grades,
+    "player_stats": load_player_stats,
+    "adp_historical": load_adp_historical,
+    "adp_ffc": load_adp_ffc,
+    "adp_value_model": load_adp_value_model,
+    "redraft_projections": load_redraft_projections,
+    "ppg_projections": load_ppg_projections,
+    "volume_projections": load_volume_projections,
+    "share_projections": load_share_projections,
+    "taxi_predictions": load_taxi_predictions,
+    "dynasty_values": load_dynasty_values,
+    "dynasty_value_history": load_dynasty_value_history,
+}
+
+# Lazily-built per-process state, keyed to the pinned ref so a pin_version()
+# call transparently invalidates it.
+_conn: Any = None
+_conn_ref: str | None = None
+_registered: set[str] = set()
+# DataFrames must stay referenced for the lifetime of the DuckDB view.
+_frames: dict[str, "pd.DataFrame"] = {}
+_user_tables: dict[str, "pd.DataFrame"] = {}
+
+# Matches bare identifiers so we can spot which known tables a query names.
+_IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+def _duckdb() -> Any:
+    try:
+        import duckdb  # noqa: PLC0415
+    except ImportError as e:  # pragma: no cover - exercised via message
+        raise ImportError(
+            "stathead.query() needs DuckDB. Install it with:\n"
+            '    pip install "stathead[duckdb]"'
+        ) from e
+    return duckdb
+
+
+def _connection() -> Any:
+    """Return the cached connection, rebuilding if the ref changed."""
+    global _conn, _conn_ref
+    if _conn is None or _conn_ref != _fetch.current_ref():
+        _conn = _duckdb().connect()
+        _conn_ref = _fetch.current_ref()
+        _registered.clear()
+        _frames.clear()
+        # Re-register any user tables onto the fresh connection.
+        for name, df in _user_tables.items():
+            _conn.register(name, df)
+    return _conn
+
+
+def _ensure_registered(conn: Any, names: set[str]) -> None:
+    for name in names:
+        if name in _registered or name in _user_tables:
+            continue
+        loader = _TABLES.get(name)
+        if loader is None:
+            continue
+        df = loader()
+        _frames[name] = df  # keep alive
+        conn.register(name, df)
+        _registered.add(name)
+
+
+def _referenced_tables(sql: str) -> set[str]:
+    """Known table names that appear as identifiers in the query. Loading a
+    superset is harmless (an unreferenced table just goes unused), so a
+    cheap token scan beats a real SQL parse."""
+    tokens = {t.lower() for t in _IDENT_RE.findall(sql)}
+    return {name for name in _TABLES if name in tokens}
+
+
+def register(name: str, df: "pd.DataFrame") -> None:
+    """Register a user DataFrame as a queryable table.
+
+    Persists across :func:`query` calls (and across a ref change). Pass the
+    same name again to replace it.
+    """
+    _user_tables[name] = df
+    if _conn is not None:
+        _conn.register(name, df)
+
+
+def list_tables() -> list[str]:
+    """Names available to :func:`query` — built-in loaders plus any tables
+    added via :func:`register`."""
+    return sorted(set(_TABLES) | set(_user_tables))
+
+
+def query(sql: str) -> "pd.DataFrame":
+    """Run SQL over the loader tables and return a pandas DataFrame.
+
+    Only the tables referenced by the query are loaded (and then cached).
+    See the module docstring for the available tables and examples.
+    """
+    conn = _connection()
+    _ensure_registered(conn, _referenced_tables(sql))
+    return conn.execute(sql).df()

stathead-0.3.1/src/stathead/stats.py

@@ -0,0 +1,56 @@
+"""Weekly NFL player stats — per-player per-week box scores, 2010-present."""
+from __future__ import annotations
+
+import io
+
+import pandas as pd
+
+from ._fetch import fetch_csv_gz
+from .crosswalk import key_by_gsis
+
+# nflverse weekly stats ship one gzipped CSV per season. Coverage grows as
+# the repo's refresh workflow commits the current year, so we probe a
+# generous range and skip seasons not present in the pinned ref.
+_SEASONS = tuple(range(2010, 2027))
+
+
+def load_player_stats(season: int | None = None) -> pd.DataFrame:
+    """Per-player per-week NFL stats (regular + postseason).
+
+    One row per (player, season, week). Includes passing / rushing /
+    receiving box-score columns plus ``fantasy_points`` and
+    ``fantasy_points_ppr``, and a canonical ``player_key`` stamped from the
+    crosswalk so this joins cleanly to every other loader.
+
+    Pass a ``season`` to load a single year, or leave ``None`` to load every
+    season available in the pinned ref (2010-present, ~400k rows).
+
+    The upstream schema drifted in 2025 (``recent_team`` → ``team``,
+    ``interceptions`` → ``passing_interceptions``, ``sacks`` →
+    ``sacks_suffered``). Both spellings are kept side-by-side when present;
+    ``COALESCE`` / :meth:`~pandas.Series.combine_first` in your own code to
+    normalize across years.
+
+    Columns (non-exhaustive): ``player_key``, ``player_id``, ``player_name``,
+    ``player_display_name``, ``position``, ``recent_team`` / ``team``,
+    ``season``, ``week``, ``season_type``, ``opponent_team``,
+    ``passing_yards``, ``passing_tds``, ``rushing_yards``, ``rushing_tds``,
+    ``carries``, ``receptions``, ``targets``, ``receiving_yards``,
+    ``receiving_tds``, ``fantasy_points``, ``fantasy_points_ppr``.
+    """
+    seasons = [season] if season is not None else list(_SEASONS)
+    frames: list[pd.DataFrame] = []
+    for s in seasons:
+        try:
+            raw = fetch_csv_gz(f"public/data/player_stats_{s}.csv.gz")
+        except Exception:
+            continue
+        frames.append(pd.read_csv(io.BytesIO(raw), low_memory=False))
+    if not frames:
+        return pd.DataFrame()
+    # sort=False keeps first-seen column order; concat unions columns across
+    # the 2024/2025 schema drift (missing cells become NaN), mirroring the
+    # web app's UNION ALL BY NAME.
+    out = pd.concat(frames, ignore_index=True, sort=False)
+    out.insert(0, "player_key", out["player_id"].astype("string").map(key_by_gsis()))
+    return out

{stathead-0.2.1 → stathead-0.3.1}/tests/test_smoke.py

@@ -114,6 +114,164 @@ def test_manual_overrides_keyed_by_name_pos():
     assert any("|" in k for k in keys)
 
 
+def test_player_stats_weekly_box_scores():
+    df = stathead.load_player_stats(2024)
+    assert not df.empty
+    assert {"player_key", "player_id", "season", "week",
+            "fantasy_points_ppr"}.issubset(df.columns)
+    assert (df.season == 2024).all()
+    # player_key should resolve for the vast majority of rows (every NFL
+    # player with a GSIS ID is in the crosswalk).
+    assert df.player_key.notna().mean() > 0.9
+
+
+def test_redraft_projections():
+    df = stathead.load_redraft_projections()
+    assert not df.empty
+    assert {"player_key", "name", "position", "ppg", "recPG"}.issubset(df.columns)
+
+
+def test_ppg_and_adp_value_model():
+    ppg = stathead.load_ppg_projections()
+    adp = stathead.load_adp_value_model()
+    assert {"name", "position", "predictedPPG"}.issubset(ppg.columns)
+    assert {"name", "position", "adp", "predictedVor", "hitProb"}.issubset(adp.columns)
+    # headshot URLs are stripped from the public surface.
+    assert "headshotUrl" not in adp.columns
+
+
+def test_volume_and_share_projections():
+    vol = stathead.load_volume_projections()
+    shr = stathead.load_share_projections()
+    assert {"name", "teamPassAtt", "teamTargets", "projPlayerPPG"}.issubset(vol.columns)
+    assert {"name", "predTargetShare", "predRushShare"}.issubset(shr.columns)
+
+
+def test_taxi_predictions_carry_meta():
+    df = stathead.load_taxi_predictions()
+    assert {"name", "position", "p1", "p2", "pEver"}.issubset(df.columns)
+    assert isinstance(df.attrs.get("meta"), dict)
+    assert "thresholds" in df.attrs["meta"]
+
+
+def test_career_2027_class():
+    df = stathead.load_career_2027()
+    assert not df.empty
+    assert {"name", "pos", "grade"}.issubset(df.columns)
+
+
+def test_dynasty_values_match_app_blend():
+    df = stathead.load_dynasty_values()
+    assert not df.empty
+    assert {"name", "position", "value_1qb", "value_superflex",
+            "positionRank", "isRookie"}.issubset(df.columns)
+    # Sorted by 1QB value, descending.
+    top = df.value_1qb.dropna().tolist()
+    assert top == sorted(top, reverse=True)
+    # Values are rescaled onto FantasyCalc's scale, so the top asset no
+    # longer sits at KTC's hard 9999 ceiling (it maps up into FC's range).
+    assert df.value_1qb.max() != 9999
+    assert df.value_1qb.min() >= 0
+
+
+def test_dynasty_value_history_rescaled():
+    df = stathead.load_dynasty_value_history()
+    assert not df.empty
+    assert {"name", "position", "date", "value_1qb",
+            "value_superflex"}.issubset(df.columns)
+
+
+def test_query_runs_a_join():
+    df = stathead.query("""
+        SELECT c.name, 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
+        LIMIT 10
+    """)
+    assert not df.empty
+    assert list(df.columns) == ["name", "predictedCareerPPG", "value_1qb"]
+    # value_1qb is sorted descending.
+    vals = df.value_1qb.dropna().tolist()
+    assert vals == sorted(vals, reverse=True)
+
+
+def test_list_tables_covers_core_loaders():
+    names = set(stathead.list_tables())
+    assert {"career_2026", "backtest", "player_stats", "dynasty_values",
+            "adp_historical", "prospects"}.issubset(names)
+
+
+def test_register_user_table_and_join():
+    import pandas as pd
+    # Pick a real 2026-class name so the join is guaranteed to resolve.
+    rookie = stathead.load_career_predictions_2026().iloc[0]["name"]
+    roster = pd.DataFrame({"name": [rookie], "slot": ["pick"]})
+    stathead.register("my_roster", roster)
+    assert "my_roster" in stathead.list_tables()
+    df = stathead.query("""
+        SELECT c.name, r.slot, c.percentile
+        FROM career_2026 c JOIN my_roster r USING (name)
+    """)
+    assert (df.name == rookie).any()
+
+
+def test_query_only_loads_referenced_tables():
+    from stathead import sql
+    # A query that names only career_2026 must not materialize player_stats.
+    sql._connection()
+    sql._registered.discard("player_stats")
+    stathead.query("SELECT COUNT(*) AS n FROM career_2026")
+    assert "player_stats" not in sql._registered
+
+
+def test_query_without_duckdb_gives_install_hint(monkeypatch):
+    import builtins
+    from stathead import sql
+    real_import = builtins.__import__
+
+    def _no_duckdb(name, *args, **kwargs):
+        if name == "duckdb":
+            raise ImportError("No module named 'duckdb'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", _no_duckdb)
+    with pytest.raises(ImportError, match=r"stathead\[duckdb\]"):
+        sql._duckdb()
+
+
+def test_to_polars_roundtrip():
+    pl = pytest.importorskip("polars")
+    df = stathead.load_dynasty_values()
+    pdf = stathead.to_polars(df)
+    assert isinstance(pdf, pl.DataFrame)
+    assert pdf.height == len(df)
+    assert list(pdf.columns) == list(df.columns)
+
+
+def test_load_polars_calls_loader():
+    pl = pytest.importorskip("polars")
+    pdf = stathead.load_polars(stathead.load_redraft_projections)
+    assert isinstance(pdf, pl.DataFrame)
+    assert "name" in pdf.columns
+
+
+def test_to_polars_without_polars_gives_install_hint(monkeypatch):
+    import builtins
+    from stathead import polars as polars_mod
+    real_import = builtins.__import__
+
+    def _no_polars(name, *args, **kwargs):
+        if name == "polars":
+            raise ImportError("No module named 'polars'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", _no_polars)
+    with pytest.raises(ImportError, match=r"stathead\[polars\]"):
+        polars_mod._polars()
+
+
 def test_no_vendor_named_columns_leak():
     """Source-agnostic feature naming — no rsp*/pdf* columns reach users."""
     pred = stathead.load_career_predictions_2026()

stathead-0.2.1/.gitignore

@@ -1,63 +0,0 @@
-node_modules
-dist
-.DS_Store
-*.local
-public/data/*
-!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/depth-chart-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-aliases.json
-!public/data/player-promotions.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/espn_adp_*.json
-!public/data/fantasycalc_*.json
-!public/data/fantasycalc_history_*.json
-!public/data/ktc-fc-rescale.json
-.claude/*
-!.claude/commands/
-!.claude/commands/**
-CLAUDE.local.md
-__pycache__/
-.nflverse-cache/
-.cache/
-.venv/
-pdfs/