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).
