stathead 0.1.0__tar.gz

stathead-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+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/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
+# 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
+.claude/*
+!.claude/commands/
+!.claude/commands/**
+CLAUDE.local.md
+__pycache__/
+.nflverse-cache/
+.cache/
+.venv/
+pdfs/

stathead-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: stathead
+Version: 0.1.0
+Summary: Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, dynasty values, and flattened feature matrices.
+Project-URL: Homepage, https://github.com/dachhack/stathead
+Project-URL: Source, https://github.com/dachhack/stathead
+Project-URL: Issues, https://github.com/dachhack/stathead/issues
+Author: StatHead
+License: MIT
+Keywords: adp,dynasty,fantasy-football,ktc,nfl,rookie-prospects
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: duckdb>=0.10; extra == 'dev'
+Requires-Dist: polars>=0.20; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.10; extra == 'duckdb'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# stathead
+
+Python client for the [StatHead](https://github.com/dachhack/stathead) fantasy football model. Returns pandas DataFrames of rookie career predictions, historical ADP, KeepTradeCut dynasty values, and the flattened feature matrix used to train the models.
+
+## Install
+
+```bash
+pip install stathead
+```
+
+Optional extras:
+
+```bash
+pip install "stathead[polars]"   # for .to_polars() helpers
+pip install "stathead[duckdb]"   # for local SQL querying
+```
+
+## Quick start
+
+```python
+import stathead as sh
+
+# 2026 rookie class predictions (77 players × ~80 columns)
+rookies = sh.load_career_predictions_2026()
+rookies.nlargest(10, "percentile")[["name", "position", "predictedCareerPPG", "modelTier"]]
+
+# Historical backtest — predicted vs actual for every drafted rookie 2010-2025
+backtest = sh.load_career_backtest()
+wr = backtest[backtest.position == "WR"]
+wr.groupby("modelTier")[["actualPPG", "predictedPPG"]].mean()
+
+# Historical ADP, every season fully populated
+adp = sh.load_adp_historical()
+adp[(adp.season == 2023) & (adp.adp <= 24)]
+
+# Dynasty values
+ktc = sh.load_ktc()
+ktc.nlargest(25, "value_1qb")
+
+# Daily KTC history (for momentum / trend analysis)
+hist = sh.load_ktc_history()
+hist.pivot_table(index="date", columns="name", values="value_1qb")
+```
+
+## Pinning to a specific version
+
+Loaders resolve against the upstream GitHub repo. Pin to a commit SHA, tag,
+or branch for reproducibility:
+
+```python
+sh.pin_version("a6720e5")   # or a tagged release
+```
+
+Clear the local cache if you want to re-fetch:
+
+```python
+sh.clear_cache()
+```
+
+## Data freshness
+
+Data files are cached under `~/.cache/stathead/<ref>/` after the first
+download. Subsequent runs read from disk — no network roundtrip. Delete the
+cache directory or call `clear_cache()` to force a refresh.
+
+## Available loaders
+
+| 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_adp_historical()` | Model-training ADP 2010-2025 | 4507 × 10 |
+| `load_adp_ffc(season=None)` | FFC PPR raw ADP (per season as fetched) | variable |
+| `load_ktc()` | Current KTC dynasty values | ~500 × 9 |
+| `load_ktc_history()` | Daily KTC history | ~100k × 7 |
+| `load_prospect_grades(year=2026)` | Draft scouting grades | ~200 × 7 |
+| `load_feature_matrix()` | Raw `feature-matrix.json` (dict) | — |
+| `load_manual_overrides()` | Manual CFBD usage overrides (dict) | — |
+
+## Licensing & attribution
+
+Package code is MIT-licensed. The data this package retrieves is derived
+from the StatHead project's own modeling pipeline; upstream sources
+(nflverse, FFC, KeepTradeCut, CFBD, etc.) retain their own terms — see
+each source's license before redistributing. If you're building on these
+predictions, a link back to the StatHead repo is appreciated but not
+required.
+
+## Contributing
+
+The package is small and focused — see
+[`python/src/stathead/`](./src/stathead/) for the loader modules. Issues
+and PRs welcome at the [main repo](https://github.com/dachhack/stathead).

stathead-0.1.0/README.md

@@ -0,0 +1,93 @@
+# stathead
+
+Python client for the [StatHead](https://github.com/dachhack/stathead) fantasy football model. Returns pandas DataFrames of rookie career predictions, historical ADP, KeepTradeCut dynasty values, and the flattened feature matrix used to train the models.
+
+## Install
+
+```bash
+pip install stathead
+```
+
+Optional extras:
+
+```bash
+pip install "stathead[polars]"   # for .to_polars() helpers
+pip install "stathead[duckdb]"   # for local SQL querying
+```
+
+## Quick start
+
+```python
+import stathead as sh
+
+# 2026 rookie class predictions (77 players × ~80 columns)
+rookies = sh.load_career_predictions_2026()
+rookies.nlargest(10, "percentile")[["name", "position", "predictedCareerPPG", "modelTier"]]
+
+# Historical backtest — predicted vs actual for every drafted rookie 2010-2025
+backtest = sh.load_career_backtest()
+wr = backtest[backtest.position == "WR"]
+wr.groupby("modelTier")[["actualPPG", "predictedPPG"]].mean()
+
+# Historical ADP, every season fully populated
+adp = sh.load_adp_historical()
+adp[(adp.season == 2023) & (adp.adp <= 24)]
+
+# Dynasty values
+ktc = sh.load_ktc()
+ktc.nlargest(25, "value_1qb")
+
+# Daily KTC history (for momentum / trend analysis)
+hist = sh.load_ktc_history()
+hist.pivot_table(index="date", columns="name", values="value_1qb")
+```
+
+## Pinning to a specific version
+
+Loaders resolve against the upstream GitHub repo. Pin to a commit SHA, tag,
+or branch for reproducibility:
+
+```python
+sh.pin_version("a6720e5")   # or a tagged release
+```
+
+Clear the local cache if you want to re-fetch:
+
+```python
+sh.clear_cache()
+```
+
+## Data freshness
+
+Data files are cached under `~/.cache/stathead/<ref>/` after the first
+download. Subsequent runs read from disk — no network roundtrip. Delete the
+cache directory or call `clear_cache()` to force a refresh.
+
+## Available loaders
+
+| 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_adp_historical()` | Model-training ADP 2010-2025 | 4507 × 10 |
+| `load_adp_ffc(season=None)` | FFC PPR raw ADP (per season as fetched) | variable |
+| `load_ktc()` | Current KTC dynasty values | ~500 × 9 |
+| `load_ktc_history()` | Daily KTC history | ~100k × 7 |
+| `load_prospect_grades(year=2026)` | Draft scouting grades | ~200 × 7 |
+| `load_feature_matrix()` | Raw `feature-matrix.json` (dict) | — |
+| `load_manual_overrides()` | Manual CFBD usage overrides (dict) | — |
+
+## Licensing & attribution
+
+Package code is MIT-licensed. The data this package retrieves is derived
+from the StatHead project's own modeling pipeline; upstream sources
+(nflverse, FFC, KeepTradeCut, CFBD, etc.) retain their own terms — see
+each source's license before redistributing. If you're building on these
+predictions, a link back to the StatHead repo is appreciated but not
+required.
+
+## Contributing
+
+The package is small and focused — see
+[`python/src/stathead/`](./src/stathead/) for the loader modules. Issues
+and PRs welcome at the [main repo](https://github.com/dachhack/stathead).

stathead-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stathead"
+version = "0.1.0"
+description = "Python client for the StatHead fantasy football model — rookie career predictions, historical ADP, dynasty values, and flattened feature matrices."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "StatHead" }]
+keywords = ["fantasy-football", "nfl", "dynasty", "rookie-prospects", "adp", "ktc"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "pandas>=1.5",
+]
+
+[project.optional-dependencies]
+polars = ["polars>=0.20"]
+duckdb = ["duckdb>=0.10"]
+dev = ["pytest>=7", "polars>=0.20", "duckdb>=0.10"]
+
+[project.urls]
+Homepage = "https://github.com/dachhack/stathead"
+Source = "https://github.com/dachhack/stathead"
+Issues = "https://github.com/dachhack/stathead/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stathead"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

stathead-0.1.0/src/stathead/__init__.py

@@ -0,0 +1,43 @@
+"""StatHead — Python client for the fantasy football model.
+
+Loaders return pandas DataFrames sourced from the upstream repo at
+https://github.com/dachhack/stathead. First call downloads + caches the
+underlying JSON/CSV; subsequent calls read from the cache.
+
+Quick start:
+
+    import stathead as sh
+
+    rookies = sh.load_career_predictions_2026()
+    backtest = sh.load_career_backtest()
+    adp = sh.load_adp_historical()
+    ktc = sh.load_ktc()
+
+Pin to a specific commit for reproducibility:
+
+    sh.pin_version("a6720e5")  # or any git ref/tag/SHA
+"""
+from ._fetch import clear_cache, pin_version, set_ref
+from .adp import load_adp_ffc, load_adp_historical
+from .features import load_feature_matrix, load_manual_overrides
+from .ktc import load_ktc, load_ktc_history
+from .predictions import load_career_backtest, load_career_predictions_2026
+from .prospects import load_prospect_grades
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "clear_cache",
+    "pin_version",
+    "set_ref",
+    "load_adp_ffc",
+    "load_adp_historical",
+    "load_career_backtest",
+    "load_career_predictions_2026",
+    "load_feature_matrix",
+    "load_ktc",
+    "load_ktc_history",
+    "load_manual_overrides",
+    "load_prospect_grades",
+]

stathead-0.1.0/src/stathead/_fetch.py

@@ -0,0 +1,89 @@
+"""Fetch + on-disk cache for files hosted in the stathead repo.
+
+All loaders go through :func:`fetch_json` / :func:`fetch_csv_gz`, which
+resolve the URL against the currently-pinned git ref and cache the raw
+bytes under ``~/.cache/stathead/<ref>/<path>``.
+
+Override the ref via :func:`pin_version` (per-session) or the
+``STATHEAD_REF`` env var (per-shell).
+"""
+from __future__ import annotations
+
+import gzip
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen
+
+_BASE_URL = "https://raw.githubusercontent.com/dachhack/stathead"
+_DEFAULT_REF = "main"
+_ref: str = os.environ.get("STATHEAD_REF", _DEFAULT_REF)
+
+
+def pin_version(ref: str) -> None:
+    """Pin all future loaders to a specific git ref (commit SHA, tag, or
+    branch name). Passing ``"main"`` resets to latest."""
+    set_ref(ref)
+
+
+def set_ref(ref: str) -> None:
+    """Alias of :func:`pin_version` with a clearer name."""
+    global _ref
+    _ref = ref
+
+
+def current_ref() -> str:
+    """Return the git ref currently used for fetches."""
+    return _ref
+
+
+def _cache_root() -> Path:
+    try:
+        from platformdirs import user_cache_dir  # type: ignore
+
+        return Path(user_cache_dir("stathead"))
+    except ImportError:
+        root = os.environ.get("XDG_CACHE_HOME")
+        if root:
+            return Path(root) / "stathead"
+        return Path.home() / ".cache" / "stathead"
+
+
+def _cache_path(path: str) -> Path:
+    return _cache_root() / _ref / path
+
+
+def clear_cache(ref: str | None = None) -> None:
+    """Remove cached files for the given ref (default: current ref).
+    Pass ``"*"`` to nuke the entire cache."""
+    if ref == "*":
+        root = _cache_root()
+    else:
+        root = _cache_root() / (ref or _ref)
+    if root.exists():
+        shutil.rmtree(root)
+
+
+def _fetch(path: str) -> bytes:
+    cache = _cache_path(path)
+    if cache.exists():
+        return cache.read_bytes()
+    url = f"{_BASE_URL}/{_ref}/{path}"
+    req = Request(url, headers={"User-Agent": "stathead-py"})
+    with urlopen(req, timeout=60) as resp:  # noqa: S310 — trusted domain
+        data = resp.read()
+    cache.parent.mkdir(parents=True, exist_ok=True)
+    cache.write_bytes(data)
+    return data
+
+
+def fetch_json(path: str) -> Any:
+    """Fetch a JSON file from the repo and parse it."""
+    return json.loads(_fetch(path).decode("utf-8"))
+
+
+def fetch_csv_gz(path: str) -> bytes:
+    """Fetch a .csv.gz file and return the decompressed CSV bytes."""
+    return gzip.decompress(_fetch(path))

stathead-0.1.0/src/stathead/adp.py

@@ -0,0 +1,67 @@
+"""ADP loaders — historical (all seasons, model training data) + FFC raw."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def load_adp_historical() -> pd.DataFrame:
+    """Historical ADP used in model training, fully populated 2010-2025.
+
+    Sourced from the feature-store profile + players shards (already
+    normalized across sources — this is the ADP the model actually trains
+    on, not a single vendor's raw response).
+
+    Columns: ``season``, ``name``, ``name_norm``, ``position``, ``adp``,
+    ``adpRound``, ``nflDraftPick``, ``nflDraftRound``, ``age``,
+    ``yearsInLeague``.
+
+    Use this for any cross-year ADP analysis — it has no gaps.
+    """
+    profile = fetch_json("public/data/feature-store/profile.json")
+    players = fetch_json("public/data/feature-store/players.json")
+    rows: list[dict] = []
+    for key, rec in profile.items():
+        if "::" not in key:
+            continue
+        name_norm, season_str = key.rsplit("::", 1)
+        try:
+            season = int(season_str)
+        except ValueError:
+            continue
+        info = players.get(key) or {}
+        rows.append({
+            "season": season,
+            "name": info.get("displayName", name_norm),
+            "name_norm": name_norm,
+            "position": info.get("position"),
+            "adp": rec.get("adp"),
+            "adpRound": rec.get("adpRound"),
+            "nflDraftPick": rec.get("nflDraftPick"),
+            "nflDraftRound": rec.get("nflDraftRound"),
+            "age": rec.get("age"),
+            "yearsInLeague": rec.get("yearsInLeague"),
+        })
+    return pd.DataFrame(rows).sort_values(["season", "adp"], na_position="last").reset_index(drop=True)
+
+
+def load_adp_ffc(season: int | None = None) -> pd.DataFrame:
+    """FantasyFootballCalculator PPR ADP — raw API responses.
+
+    Coverage depends on what has been fetched into the repo (currently 2025).
+    Pass a ``season`` to filter, or leave ``None`` to load everything available.
+
+    Columns: ``season``, ``name``, ``position``, ``team``, ``adp``, ``high``,
+    ``low``, ``stdev``, ``timesDrafted``, ``bye``.
+    """
+    seasons = [season] if season else [2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026]
+    rows: list[dict] = []
+    for s in seasons:
+        try:
+            d = fetch_json(f"public/data/ffc_adp_ppr_{s}.json")
+        except Exception:
+            continue
+        for p in d.get("players") or []:
+            rows.append({"season": s, **p})
+    return pd.DataFrame(rows)

stathead-0.1.0/src/stathead/features.py

@@ -0,0 +1,27 @@
+"""Raw feature matrix + manual feature overrides used by the pipeline."""
+from __future__ import annotations
+
+from typing import Any
+
+from ._fetch import fetch_json
+
+
+def load_feature_matrix() -> dict[str, Any]:
+    """Return the full ``feature-matrix.json`` as a dict.
+
+    The file contains many sub-structures (``careerPredictions2026``,
+    ``predRows``, ``vorNorm``, schema-per-position, etc.). Most users want
+    :func:`~stathead.load_career_predictions_2026` instead — this is an
+    escape hatch for advanced introspection.
+    """
+    return fetch_json("public/data/feature-matrix.json")
+
+
+def load_manual_overrides() -> dict[str, Any]:
+    """Manual CFBD usage overrides keyed by ``"Name|POS"``.
+
+    Contains per-season carries / receptions / team totals for players
+    missing from CFBD's player-usage file (Odell Beckham Jr., Duke Johnson,
+    Todd Gurley, etc.). See ``scripts/backfill_cfbd_variants.py``.
+    """
+    return fetch_json("public/data/manual-cfbd-overrides.json")

stathead-0.1.0/src/stathead/ktc.py

@@ -0,0 +1,66 @@
+"""KeepTradeCut dynasty values — current snapshot + daily history."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def load_ktc() -> pd.DataFrame:
+    """Current KTC dynasty values, one row per player.
+
+    The 1QB rankings file carries both the ``value`` (1QB) and
+    ``superflexValue`` in the same record, so a single fetch gives both
+    formats.
+
+    Columns: ``playerID``, ``name``, ``position``, ``positionRank``, ``team``,
+    ``age``, ``value_1qb``, ``value_superflex``, ``isRookie``.
+    """
+    raw = fetch_json("public/data/ktc_rankings_1qb.json")
+    rows = [{
+        "playerID": r["playerID"],
+        "name": r["playerName"],
+        "position": r["position"],
+        "positionRank": r.get("positionRank"),
+        "team": r.get("team"),
+        "age": r.get("age"),
+        "value_1qb": r.get("value"),
+        "value_superflex": r.get("superflexValue"),
+        "isRookie": r.get("isRookie", False),
+    } for r in raw]
+    return pd.DataFrame(rows)
+
+
+def load_ktc_history() -> pd.DataFrame:
+    """Daily KTC value history — one row per (playerID, date).
+
+    1QB and Superflex values are emitted side-by-side to make trend /
+    momentum queries easy. ~100k rows (200+ days × 500 players).
+
+    Columns: ``playerID``, ``name``, ``position``, ``team``, ``date``,
+    ``value_1qb``, ``value_superflex``.
+    """
+    current = fetch_json("public/data/ktc_rankings_1qb.json")
+    info_by_id = {r["playerID"]: {
+        "name": r["playerName"], "position": r["position"], "team": r.get("team"),
+    } for r in current}
+
+    history = fetch_json("public/data/ktc_history.json")
+    rows: list[dict] = []
+    for h in history:
+        info = info_by_id.get(h["playerID"], {})
+        sf_map = {p["d"]: p["v"] for p in (h.get("superflex") or {}).get("valueHistory") or []}
+        for p in (h.get("oneQB") or {}).get("valueHistory") or []:
+            rows.append({
+                "playerID": h["playerID"],
+                "name": info.get("name"),
+                "position": info.get("position"),
+                "team": info.get("team"),
+                "date": p["d"],
+                "value_1qb": p["v"],
+                "value_superflex": sf_map.get(p["d"]),
+            })
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df["date"] = pd.to_datetime(df["date"])
+    return df

stathead-0.1.0/src/stathead/predictions.py

@@ -0,0 +1,46 @@
+"""Rookie career model predictions — 2026 class + historical backtest."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def _flatten(row: dict) -> dict:
+    """Lift ``features`` sub-dict into top-level columns."""
+    features = row.pop("features", None) or {}
+    return {**row, **features}
+
+
+def load_career_predictions_2026() -> pd.DataFrame:
+    """2026 draft-class career predictions, one row per scored prospect.
+
+    Columns (non-exhaustive): ``name``, ``position``, ``adp``, ``team``,
+    ``predictedCareerPPG``, ``percentile``, ``modelTier``, ``boomProb``,
+    ``bustProb``, ``boomZ``, ``bustZ``, plus every feature in the model
+    (``collegeDominatorRating``, ``collegeUsageOverall``, ``rspDotDraft``,
+    ``pdfRankOverallMean``, ``recruitRating``, ``relativeAthleticScore``, …).
+    """
+    fm = fetch_json("public/data/feature-matrix.json")
+    rows = [_flatten(dict(p)) for p in fm.get("careerPredictions2026") or []]
+    return pd.DataFrame(rows)
+
+
+def load_career_backtest() -> pd.DataFrame:
+    """Historical rookie backtest rows (2010-2025) with predictedPPG + actualPPG.
+
+    Used to evaluate the career model (both the precomputed tier system and
+    the GBM + Ridge ensemble). One row per drafted prospect across QB/RB/WR/TE.
+
+    Columns: ``name``, ``position``, ``draftSeason``, ``predictedPPG``,
+    ``actualPPG``, ``percentile``, ``modelTier``, ``combinedScore``,
+    plus every feature used in training.
+    """
+    cache = fetch_json("public/data/model-cache-career-v72.json")
+    out: list[dict] = []
+    for pos, model in (cache.get("rookieCareerModels") or {}).items():
+        for r in model.get("backtestRows") or []:
+            row = dict(r)
+            row.setdefault("position", pos)
+            out.append(_flatten(row))
+    return pd.DataFrame(out)

stathead-0.1.0/src/stathead/prospects.py

@@ -0,0 +1,18 @@
+"""2026 draft prospect scouting grades (NFL.com / PFN composite)."""
+from __future__ import annotations
+
+import pandas as pd
+
+from ._fetch import fetch_json
+
+
+def load_prospect_grades(year: int = 2026) -> pd.DataFrame:
+    """NFL draft prospect scouting grades for the given class.
+
+    Currently only ``year=2026`` is distributed with the repo.
+
+    Columns: ``name``, ``pos``, ``school``, ``grade``, ``projRound``,
+    ``projPick``, ``tier``.
+    """
+    data = fetch_json(f"src/data/prospect-grades-{year}.json")
+    return pd.DataFrame(data)

stathead-0.1.0/tests/test_smoke.py

@@ -0,0 +1,95 @@
+"""Smoke tests — verifies every loader returns a non-empty DataFrame when
+run against a local checkout (pointed at the current working tree via a
+file:// fetch override).
+
+These tests run offline by reading files directly out of the repo's
+``public/data`` folder. This keeps CI fast and avoids hitting GitHub.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+REPO = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO / "python" / "src"))
+
+import stathead  # noqa: E402
+from stathead import _fetch  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def local_fetch(monkeypatch):
+    """Redirect the package fetcher at the current working tree."""
+    def _read(path: str) -> bytes:
+        full = REPO / path
+        return full.read_bytes()
+
+    monkeypatch.setattr(_fetch, "_fetch", _read)
+    yield
+
+
+def test_career_predictions_2026_has_rookies():
+    df = stathead.load_career_predictions_2026()
+    assert not df.empty
+    assert {"name", "position", "predictedCareerPPG", "modelTier", "percentile"}.issubset(df.columns)
+
+
+def test_career_backtest_has_history():
+    df = stathead.load_career_backtest()
+    assert len(df) > 800
+    assert {"name", "position", "predictedPPG", "actualPPG", "modelTier"}.issubset(df.columns)
+    assert df.position.isin(["QB", "RB", "WR", "TE"]).all()
+
+
+def test_adp_historical_is_fully_populated():
+    df = stathead.load_adp_historical()
+    assert len(df) > 4000
+    assert {"season", "name", "position", "adp"}.issubset(df.columns)
+    # Every season from 2010-2025 should be present.
+    assert set(range(2010, 2026)).issubset(set(df.season.unique()))
+
+
+def test_ktc_current_values():
+    df = stathead.load_ktc()
+    assert not df.empty
+    assert {"name", "value_1qb", "value_superflex", "isRookie"}.issubset(df.columns)
+
+
+def test_ktc_history_is_long():
+    df = stathead.load_ktc_history()
+    assert not df.empty
+    assert {"playerID", "date", "value_1qb"}.issubset(df.columns)
+    assert pd.api.types.is_datetime64_any_dtype(df.date)
+
+
+def test_prospect_grades_2026():
+    df = stathead.load_prospect_grades(2026)
+    assert not df.empty
+    assert {"name", "pos", "grade"}.issubset(df.columns)
+
+
+def test_feature_matrix_is_dict():
+    m = stathead.load_feature_matrix()
+    assert isinstance(m, dict)
+    assert "careerPredictions2026" in m
+
+
+def test_manual_overrides_keyed_by_name_pos():
+    o = stathead.load_manual_overrides()
+    assert isinstance(o, dict)
+    keys = [k for k in o if not k.startswith("_")]
+    assert any("|" in k for k in keys)
+
+
+def test_pin_version_changes_cache_root(tmp_path, monkeypatch):
+    # With a custom cache root, the cache file should end up under <ref>/<path>.
+    monkeypatch.setattr(_fetch, "_cache_root", lambda: tmp_path)
+    _fetch.set_ref("abc123")
+    p = _fetch._cache_path("foo/bar.json")
+    assert p.parent.name == "foo"
+    assert p.parent.parent.name == "abc123"
+    _fetch.set_ref("main")  # reset