max-pf 1.0.0__tar.gz

max_pf-1.0.0/.claude/settings.local.json

@@ -0,0 +1,53 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /home/weezy/activity/basketball_max_pf log --oneline -5)",
+      "Bash(python3 -c \"import requests; print\\('requests ok', requests.__version__\\)\")",
+      "Bash(timeout 120 python3 /tmp/probe_fantrax.py)",
+      "Bash(python3 -m pip install -q pytest)",
+      "Bash(python3 -m pytest -q)",
+      "Bash(python3 -m venv /tmp/mpf_venv)",
+      "Bash(/tmp/mpf_venv/bin/pip install *)",
+      "Bash(/tmp/mpf_venv/bin/python -m pytest -q)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(timeout 120 /tmp/mpf_venv/bin/python /tmp/probe_fantrax3.py)",
+      "Bash(timeout 120 /tmp/mpf_venv/bin/python /tmp/validate_proj.py)",
+      "Bash(timeout 120 /tmp/mpf_venv/bin/python /tmp/probe_fantrax4.py)",
+      "Bash(timeout 180 /tmp/mpf_venv/bin/python /tmp/validate_period.py)",
+      "Bash(timeout 150 /tmp/mpf_venv/bin/python /tmp/probe_fantrax5.py)",
+      "Bash(/tmp/mpf_venv/bin/python -c \"import ast,sys; src=open\\('src/max_pf/platforms/fantrax.py'\\).read\\(\\); print\\('project_period_line' in src and 'still referenced' or 'clean: no stale project_period_line ref'\\)\")",
+      "Bash(timeout 200 /tmp/mpf_venv/bin/python /tmp/validate_opt.py)",
+      "Bash(timeout 400 /tmp/mpf_venv/bin/python /tmp/validate_delta.py)",
+      "Bash(timeout 150 /tmp/mpf_venv/bin/python /tmp/probe_fantrax6.py)",
+      "Bash(PYTHONPATH=src:/tmp/FantraxAPI_ref timeout 550 /tmp/mpf_venv/bin/python -m max_pf wserh14rmbbpqtcg --periods 1-3 --out /tmp/season_test)",
+      "Bash(timeout 120 /tmp/mpf_venv/bin/python /tmp/probe_fantrax7.py)",
+      "Bash(timeout 120 /tmp/mpf_venv/bin/python /tmp/probe8.py)",
+      "Bash(curl -s -m 12 -o /dev/null -w \"%{http_code}\" -H \"User-Agent: Mozilla/5.0\" -H \"Referer: https://www.nba.com/\" \"https://stats.nba.com/stats/scoreboardv2?GameDate=2025-12-01&LeagueID=00&DayOffset=0\")",
+      "Bash(curl -s -m 12 -o /dev/null -w \"%{http_code}\" -H \"User-Agent: Mozilla/5.0\" \"https://www.basketball-reference.com/robots.txt\")",
+      "Bash(/tmp/mpf_venv/bin/pip download *)",
+      "Bash(timeout 200 /tmp/mpf_venv/bin/python /tmp/validate_stage1.py)",
+      "Bash(/tmp/mpf_venv/bin/python -c \"import bs4; print\\('bs4', bs4.__version__\\)\")",
+      "Bash(timeout 550 /tmp/mpf_venv/bin/python /tmp/validate_box.py)",
+      "Bash(/tmp/mpf_venv/bin/python /tmp/analyze_unmatched.py)",
+      "Bash(timeout 550 /tmp/mpf_venv/bin/python /tmp/validate_hindsight.py)",
+      "Bash(PYTHONPATH=src:/tmp/FantraxAPI_ref nohup /tmp/mpf_venv/bin/python -m max_pf wserh14rmbbpqtcg --out season_report)",
+      "Bash(echo \"launched PID $!\")",
+      "Bash(kill 127435)",
+      "Bash(PYTHONPATH=src:/tmp/FantraxAPI_ref /tmp/mpf_venv/bin/python *)",
+      "Bash(python -c \"import max_pf; print\\('max_pf OK', max_pf.__file__\\)\")",
+      "Bash(python -c \"import fantraxapi; print\\('fantraxapi OK', fantraxapi.__version__ if hasattr\\(fantraxapi,'__version__'\\) else 'installed'\\)\")",
+      "Bash(pip show *)",
+      "Bash(python -c \"import urllib.request; r=urllib.request.urlopen\\('https://www.fantrax.com', timeout=10\\); print\\('fantrax', r.status\\)\")",
+      "Bash(python3 -c \"import urllib.request as u; print\\(u.urlopen\\('https://www.fantrax.com', timeout=12\\).status\\)\")",
+      "Bash(python3 -c \"import urllib.request as u; print\\(u.urlopen\\('https://www.fantrax.com/fxea/general/getLeagueInfo?leagueId=wserh14rmbbpqtcg', timeout=15\\).status\\)\")",
+      "Bash(gh --version)",
+      "Bash(git push *)",
+      "Bash(env)",
+      "Bash(git rm *)",
+      "Bash(curl -s --max-time 20 \"https://api.github.com/repos/riders994/basketball_max_pf/pulls?state=open&head=riders994:initial_dev\")",
+      "Bash(curl -s --max-time 20 -o /tmp/prs.json -w \"HTTP %{http_code}\\\\n\" \"https://api.github.com/repos/riders994/basketball_max_pf/pulls?state=open\")",
+      "Read(//tmp/**)"
+    ]
+  }
+}

max_pf-1.0.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtualenvs
+.venv/
+venv/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Cached external data (basketball-reference HTML, etc.)
+.cache/
+
+# Secrets / platform credentials
+*.cookie
+fantraxloggedin.cookie
+.env

max_pf-1.0.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Planned work is tracked in [TODO.md](TODO.md).
+
+## [1.0.0] - 2026-06-18
+
+First public release. Computes the "max points for" metric for 9-category
+head-to-head fantasy basketball.
+
+### Added
+
+- **Metric & engine.** Opponent-relative category wins (ties = draws worth 0.5,
+  turnovers inverted); one-round best response yielding **M1 / M2 / Δ** (the
+  opponent-mismanagement dividend). FG%/FT% aggregated as Σmakes/Σattempts.
+- **Two methodologies** behind a pluggable `StatSource`: **A-expected**
+  (season-to-date projections) and **A-hindsight** (realized box scores).
+- **Data sources.** Fantrax for league structure (the FantraxAPI fork, vendored
+  under `max_pf._vendor` so installs need no VCS/URL dependency) and
+  basketball-reference for exact per-player makes/attempts (disk-cached). Exact
+  A-expected on box scores replaces the FG/FT attempt estimator (kept as a
+  no-extra-dependency fallback).
+- **Three lineup objectives.** A (`catwins`, opponent-aware category wins),
+  B (`zscore`, scarcity-weighted z-value — benches below-replacement players to
+  protect ratios/TO), C (`raw`, raw output / volume). All pluggable.
+- **Nash mutual ceiling, stage 1.** `engine.nash_ceiling` runs iterated best
+  response to a pure-strategy equilibrium (**M3**), with cycle detection for
+  matchups with no pure equilibrium.
+- **Entry point & CLI.** `max_pf.run(login, weeks=..., methodology=...,
+  objective=...)` takes a platform login dict and returns the season report;
+  `max-pf <login.json|yaml>` (also `python -m max_pf ...`) renders a table and
+  writes CSV/Markdown. `weeks` scopes to one week or a selection.
+- Installable package (`src/` layout, hatchling) with `boxscores` and `yaml`
+  extras; 52 unit tests; live-validated against a finished public league.
+
+[1.0.0]: https://github.com/riders994/basketball_max_pf/releases/tag/v1.0.0

max_pf-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 riders994
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

max_pf-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: max-pf
+Version: 1.0.0
+Summary: Methodology + tooling to compute the 'max points for' metric for 9-cat fantasy basketball leagues.
+Project-URL: Homepage, https://github.com/riders994/basketball_max_pf
+Project-URL: Repository, https://github.com/riders994/basketball_max_pf
+Project-URL: Issues, https://github.com/riders994/basketball_max_pf/issues
+Project-URL: Changelog, https://github.com/riders994/basketball_max_pf/blob/primary/CHANGELOG.md
+Author-email: Rohan V <r.vahalia@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 riders994
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: 9-cat,basketball,fantasy,fantrax,optimization
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: requests>=2.28
+Provides-Extra: boxscores
+Requires-Dist: beautifulsoup4>=4.12; extra == 'boxscores'
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# basketball_max_pf
+
+A Python package for computing a **"max points for"** metric for a 9-category
+head-to-head fantasy basketball league. Give it your league platform and a
+league id and it reconstructs, for every team and every matchup period, the
+best lineup you *could* have set — and turns the gap between that and reality
+into a single interpretable number.
+
+The first supported platform is **Fantrax**; the design keeps the platform,
+the player-stat source, and the lineup objective behind seams so other sports
+or platforms can be added later.
+
+> Status: Objective A (opponent-aware category-win maximization) is implemented
+> end-to-end and validated against a finished public league. See
+> [Roadmap](#roadmap) for what's next, and
+> [`docs/PROMPT_LOG.md`](docs/PROMPT_LOG.md) for the full design journal.
+
+## The metric
+
+"Points for" in this league *are* category wins — they only exist relative to
+an opponent (a tie is a **draw**, worth 0.5; Fantrax awards ties, it does not
+wash or split them). So the metric and the benchmark are one decision, not two.
+
+For each matchup period we compute a one-round **best response** (each side
+optimizes against the *other side's actual* lineup — a well-posed fixed target,
+avoiding the Nash infinite regress):
+
+| Quantity | Definition | Reads as |
+| --- | --- | --- |
+| **M1** | catwins(`mine_opt`, `opp_actual`) | your exploitation ceiling vs how they actually played |
+| **M2** | catwins(`mine_opt`, `their_opt`) | the same lineup vs their best counter |
+| **Δ** | M1 − M2 | the **opponent-mismanagement dividend** — points banked purely because the opponent didn't optimize |
+| **Luck** | Actual − M1 | points left on the table (negative ⇒ you fell short of your own ceiling) |
+
+FG% and FT% are aggregated correctly across a lineup via Σmakes / Σattempts
+(never by averaging percentages); TO is treated as lower-is-better.
+
+The best-response above is **Objective A** (the default, `--objective catwins`):
+each side optimizes category wins against the other's *actual* lineup. The
+optimizer's objective is pluggable, with two opponent-independent alternatives
+that report catwins as a readout: **Objective B** (`--objective zscore`) maximizes
+total **z-score value** (scarcity-weighted), and **Objective C** (`--objective raw`)
+maximizes total **raw output** (scarcity-blind, volume-chasing). Both *bench
+below-replacement (negative-value) players* — since value prices in FG%/FT%
+volume-impact and turnovers, dropping them protects the ratio cats and TO that
+swing a week (C, whose raw value is almost always positive, benches far less).
+See [Roadmap](#roadmap).
+
+## Two methodologies
+
+The optimizer needs a target statline for each player. Where that comes from is
+the **ex-ante vs ex-post** fork, and the package implements both:
+
+- **A-expected** (`--methodology expected`) — season-to-date *per-game rates*
+  placed on the days each player's team plays in the period. No clairvoyance;
+  the ceiling is a projection. Rates come from exact basketball-reference
+  box scores (real makes/attempts, no estimator); the Fantrax season-to-date
+  view + position-based FG/FT attempt estimator is the no-extra-dependency
+  fallback when box scores aren't attached. Its `Luck` mixes forecast variance
+  with real mismanagement.
+- **A-hindsight** (`--methodology hindsight`) — *realized* per-day box scores
+  from basketball-reference, joined to the full historical roster. This is the
+  true "best lineup you could have set" ceiling: **M1 ≥ Actual always**, so
+  `Luck` is genuine lineup mismanagement with projection noise removed.
+
+## Data sources
+
+- **Fantrax** (via the [stable fork of FantraxAPI](https://github.com/riders994/FantraxAPI),
+  **vendored** under `max_pf._vendor` — see `src/max_pf/_vendor/NOTICE.md`) is the
+  source of truth for league structure: rosters (incl. historical daily
+  membership), active-slot config, matchup schedule, and **actual results**.
+  Public leagues read with only the league id (no credentials).
+- **basketball-reference** supplies exact per-player per-day 9-cat lines with
+  real makes/attempts (FG%/FT% denominators Fantrax never exposes). Disk-cached
+  under `.cache/bref/` at a polite request rate; `nba_api` is a drop-in for
+  local runs where stats.nba.com is reachable.
+
+These sit behind a pluggable `StatSource` seam, so the optimizer, engine, and
+report are identical across methodologies.
+
+## Install
+
+```bash
+pip install -e ".[boxscores]"   # add 'dev' for the test suite
+```
+
+The Fantrax adapter works out of the box — its API client is vendored, so there
+is no VCS/URL dependency (and the package installs cleanly from PyPI). `boxscores`
+pulls beautifulsoup4 for the basketball-reference source; `yaml` adds YAML
+login-file support on the CLI (JSON works without it). (Per packaging convention, all
+version specifiers are `>=` for compatibility.)
+
+## Usage
+
+**Programmatic** — pass a *login dict* naming the platform and its details; you
+get back the season-to-date report rows (render with the `render_*` helpers):
+
+```python
+import max_pf
+
+rows = max_pf.run({"platform": "fantrax", "league_id": "wserh14rmbbpqtcg"})
+print(max_pf.render_table(rows))
+
+# Scope to one week or a selection, and pick methodology / objective:
+rows = max_pf.run(login, weeks="1-6", methodology="hindsight", objective="zscore")
+rows = max_pf.run(login, weeks=6)            # a single week
+```
+
+`weeks` accepts a single int, a list, or a spec string (`"5"`, `"1-6"`,
+`"1,2,5"`); `None` (the default) is the whole season to date. Box scores back
+both methodologies by default; pass `boxscores=False` for the no-extra-dependency
+Fantrax estimator (A-expected only).
+
+**Command line** — point it at a JSON or YAML file holding the same login dict:
+
+```bash
+# league.json: {"platform": "fantrax", "league_id": "wserh14rmbbpqtcg"}
+python -m max_pf league.json
+python -m max_pf league.yaml --weeks 1-6 --methodology hindsight --out reports/half1
+```
+
+It prints the table and writes `<out>.csv` and `<out>.md`.
+
+## Findings
+
+Full-season run on the finished public league `wserh14rmbbpqtcg` ("Mao's Macho
+Mandarins", 2025-26 NBA, 16 teams × 24 periods), A-expected vs A-hindsight.
+(The committed sample reports were removed in 1.0.0 pending regeneration on the
+box-score default — see [`TODO.md`](TODO.md); reproduce with
+`python -m max_pf league.json [--methodology hindsight]`.)
+
+- **The ceiling invariant holds under hindsight.** M1 ≥ Actual for every team
+  in both reports; A-hindsight makes this a *guarantee* (realized data),
+  whereas A-expected can't because a team that ran hot beats its projection.
+- **Projections are optimistic.** A-expected M1 > A-hindsight M1 for 15 of 16
+  teams (smooth per-game rates, no DNPs/variance). The lone exception is
+  *Trusting the Process*, whose players out-ran their season rates in the games
+  actually played.
+- **Hindsight isolates real mismanagement.** With projection variance stripped,
+  `Luck` magnitudes shrink (band −6.5…−60 vs expected −9.5…−66) — the Actual−M1
+  gap becomes genuine points left on the table, not forecast noise.
+- **The dividend Δ tightens to a credible band.** The expected spread (7–73)
+  compresses to 11–35 under hindsight. The dbyun89 expected outlier (Δ=73,
+  driven by an implausible expected M2=38) corrects to Δ=35 (M2=71), confirming
+  it was a projection artifact rather than a real opponent giveaway.
+
+**Takeaway:** A-hindsight is the trustworthy read for both the efficiency
+ceiling (`Luck`) and the dividend (`Δ`); A-expected is the no-clairvoyance
+projection useful before results are in.
+
+## Roadmap
+
+- Live re-validation against the updated `@stable` fork — **done** (results
+  bit-identical to the pre-update fork; see the prompt log).
+- Exact A-expected on box scores (estimator replaced as the metric's data
+  source) — **done**; reproduces the estimator's category-win metric while using
+  real makes/attempts and the real schedule.
+- Objective B (z-score / punt-aware weighting) — **done**. `--objective zscore`
+  plays each side's opponent-independent max-total-z-value lineup (league-wide
+  per-game population; volume-weighted ratio impact, TO inverted); catwins is a
+  readout. Objective A's category-win M1 is >= Objective B's by construction.
+- Objective C (raw statistical output) — **done**. `--objective raw` plays each
+  side's max-raw-output lineup (same league-wide population as B, but values
+  players without scarcity weighting, so it chases volume); opponent-independent,
+  catwins as a readout.
+- Nash "mutual ceiling" (two-player equilibrium): stage 1 done —
+  `engine.nash_ceiling` runs iterated best response to the fixed point where each
+  lineup best-responds to the other (pure-strategy Nash), yielding **M3** = the
+  both-sides-optimal category split; it flags cycles (no pure equilibrium). On
+  the test league it converges in ~80% of periods.
+
+Open items (Nash stage 2, M3 in the report, artifact regeneration, CI, more
+platforms) are tracked in [`TODO.md`](TODO.md). See
+[`docs/PROMPT_LOG.md`](docs/PROMPT_LOG.md) for the complete design history.

max_pf-1.0.0/README.md

@@ -0,0 +1,174 @@
+# basketball_max_pf
+
+A Python package for computing a **"max points for"** metric for a 9-category
+head-to-head fantasy basketball league. Give it your league platform and a
+league id and it reconstructs, for every team and every matchup period, the
+best lineup you *could* have set — and turns the gap between that and reality
+into a single interpretable number.
+
+The first supported platform is **Fantrax**; the design keeps the platform,
+the player-stat source, and the lineup objective behind seams so other sports
+or platforms can be added later.
+
+> Status: Objective A (opponent-aware category-win maximization) is implemented
+> end-to-end and validated against a finished public league. See
+> [Roadmap](#roadmap) for what's next, and
+> [`docs/PROMPT_LOG.md`](docs/PROMPT_LOG.md) for the full design journal.
+
+## The metric
+
+"Points for" in this league *are* category wins — they only exist relative to
+an opponent (a tie is a **draw**, worth 0.5; Fantrax awards ties, it does not
+wash or split them). So the metric and the benchmark are one decision, not two.
+
+For each matchup period we compute a one-round **best response** (each side
+optimizes against the *other side's actual* lineup — a well-posed fixed target,
+avoiding the Nash infinite regress):
+
+| Quantity | Definition | Reads as |
+| --- | --- | --- |
+| **M1** | catwins(`mine_opt`, `opp_actual`) | your exploitation ceiling vs how they actually played |
+| **M2** | catwins(`mine_opt`, `their_opt`) | the same lineup vs their best counter |
+| **Δ** | M1 − M2 | the **opponent-mismanagement dividend** — points banked purely because the opponent didn't optimize |
+| **Luck** | Actual − M1 | points left on the table (negative ⇒ you fell short of your own ceiling) |
+
+FG% and FT% are aggregated correctly across a lineup via Σmakes / Σattempts
+(never by averaging percentages); TO is treated as lower-is-better.
+
+The best-response above is **Objective A** (the default, `--objective catwins`):
+each side optimizes category wins against the other's *actual* lineup. The
+optimizer's objective is pluggable, with two opponent-independent alternatives
+that report catwins as a readout: **Objective B** (`--objective zscore`) maximizes
+total **z-score value** (scarcity-weighted), and **Objective C** (`--objective raw`)
+maximizes total **raw output** (scarcity-blind, volume-chasing). Both *bench
+below-replacement (negative-value) players* — since value prices in FG%/FT%
+volume-impact and turnovers, dropping them protects the ratio cats and TO that
+swing a week (C, whose raw value is almost always positive, benches far less).
+See [Roadmap](#roadmap).
+
+## Two methodologies
+
+The optimizer needs a target statline for each player. Where that comes from is
+the **ex-ante vs ex-post** fork, and the package implements both:
+
+- **A-expected** (`--methodology expected`) — season-to-date *per-game rates*
+  placed on the days each player's team plays in the period. No clairvoyance;
+  the ceiling is a projection. Rates come from exact basketball-reference
+  box scores (real makes/attempts, no estimator); the Fantrax season-to-date
+  view + position-based FG/FT attempt estimator is the no-extra-dependency
+  fallback when box scores aren't attached. Its `Luck` mixes forecast variance
+  with real mismanagement.
+- **A-hindsight** (`--methodology hindsight`) — *realized* per-day box scores
+  from basketball-reference, joined to the full historical roster. This is the
+  true "best lineup you could have set" ceiling: **M1 ≥ Actual always**, so
+  `Luck` is genuine lineup mismanagement with projection noise removed.
+
+## Data sources
+
+- **Fantrax** (via the [stable fork of FantraxAPI](https://github.com/riders994/FantraxAPI),
+  **vendored** under `max_pf._vendor` — see `src/max_pf/_vendor/NOTICE.md`) is the
+  source of truth for league structure: rosters (incl. historical daily
+  membership), active-slot config, matchup schedule, and **actual results**.
+  Public leagues read with only the league id (no credentials).
+- **basketball-reference** supplies exact per-player per-day 9-cat lines with
+  real makes/attempts (FG%/FT% denominators Fantrax never exposes). Disk-cached
+  under `.cache/bref/` at a polite request rate; `nba_api` is a drop-in for
+  local runs where stats.nba.com is reachable.
+
+These sit behind a pluggable `StatSource` seam, so the optimizer, engine, and
+report are identical across methodologies.
+
+## Install
+
+```bash
+pip install -e ".[boxscores]"   # add 'dev' for the test suite
+```
+
+The Fantrax adapter works out of the box — its API client is vendored, so there
+is no VCS/URL dependency (and the package installs cleanly from PyPI). `boxscores`
+pulls beautifulsoup4 for the basketball-reference source; `yaml` adds YAML
+login-file support on the CLI (JSON works without it). (Per packaging convention, all
+version specifiers are `>=` for compatibility.)
+
+## Usage
+
+**Programmatic** — pass a *login dict* naming the platform and its details; you
+get back the season-to-date report rows (render with the `render_*` helpers):
+
+```python
+import max_pf
+
+rows = max_pf.run({"platform": "fantrax", "league_id": "wserh14rmbbpqtcg"})
+print(max_pf.render_table(rows))
+
+# Scope to one week or a selection, and pick methodology / objective:
+rows = max_pf.run(login, weeks="1-6", methodology="hindsight", objective="zscore")
+rows = max_pf.run(login, weeks=6)            # a single week
+```
+
+`weeks` accepts a single int, a list, or a spec string (`"5"`, `"1-6"`,
+`"1,2,5"`); `None` (the default) is the whole season to date. Box scores back
+both methodologies by default; pass `boxscores=False` for the no-extra-dependency
+Fantrax estimator (A-expected only).
+
+**Command line** — point it at a JSON or YAML file holding the same login dict:
+
+```bash
+# league.json: {"platform": "fantrax", "league_id": "wserh14rmbbpqtcg"}
+python -m max_pf league.json
+python -m max_pf league.yaml --weeks 1-6 --methodology hindsight --out reports/half1
+```
+
+It prints the table and writes `<out>.csv` and `<out>.md`.
+
+## Findings
+
+Full-season run on the finished public league `wserh14rmbbpqtcg` ("Mao's Macho
+Mandarins", 2025-26 NBA, 16 teams × 24 periods), A-expected vs A-hindsight.
+(The committed sample reports were removed in 1.0.0 pending regeneration on the
+box-score default — see [`TODO.md`](TODO.md); reproduce with
+`python -m max_pf league.json [--methodology hindsight]`.)
+
+- **The ceiling invariant holds under hindsight.** M1 ≥ Actual for every team
+  in both reports; A-hindsight makes this a *guarantee* (realized data),
+  whereas A-expected can't because a team that ran hot beats its projection.
+- **Projections are optimistic.** A-expected M1 > A-hindsight M1 for 15 of 16
+  teams (smooth per-game rates, no DNPs/variance). The lone exception is
+  *Trusting the Process*, whose players out-ran their season rates in the games
+  actually played.
+- **Hindsight isolates real mismanagement.** With projection variance stripped,
+  `Luck` magnitudes shrink (band −6.5…−60 vs expected −9.5…−66) — the Actual−M1
+  gap becomes genuine points left on the table, not forecast noise.
+- **The dividend Δ tightens to a credible band.** The expected spread (7–73)
+  compresses to 11–35 under hindsight. The dbyun89 expected outlier (Δ=73,
+  driven by an implausible expected M2=38) corrects to Δ=35 (M2=71), confirming
+  it was a projection artifact rather than a real opponent giveaway.
+
+**Takeaway:** A-hindsight is the trustworthy read for both the efficiency
+ceiling (`Luck`) and the dividend (`Δ`); A-expected is the no-clairvoyance
+projection useful before results are in.
+
+## Roadmap
+
+- Live re-validation against the updated `@stable` fork — **done** (results
+  bit-identical to the pre-update fork; see the prompt log).
+- Exact A-expected on box scores (estimator replaced as the metric's data
+  source) — **done**; reproduces the estimator's category-win metric while using
+  real makes/attempts and the real schedule.
+- Objective B (z-score / punt-aware weighting) — **done**. `--objective zscore`
+  plays each side's opponent-independent max-total-z-value lineup (league-wide
+  per-game population; volume-weighted ratio impact, TO inverted); catwins is a
+  readout. Objective A's category-win M1 is >= Objective B's by construction.
+- Objective C (raw statistical output) — **done**. `--objective raw` plays each
+  side's max-raw-output lineup (same league-wide population as B, but values
+  players without scarcity weighting, so it chases volume); opponent-independent,
+  catwins as a readout.
+- Nash "mutual ceiling" (two-player equilibrium): stage 1 done —
+  `engine.nash_ceiling` runs iterated best response to the fixed point where each
+  lineup best-responds to the other (pure-strategy Nash), yielding **M3** = the
+  both-sides-optimal category split; it flags cycles (no pure equilibrium). On
+  the test league it converges in ~80% of periods.
+
+Open items (Nash stage 2, M3 in the report, artifact regeneration, CI, more
+platforms) are tracked in [`TODO.md`](TODO.md). See
+[`docs/PROMPT_LOG.md`](docs/PROMPT_LOG.md) for the complete design history.

max_pf-1.0.0/TODO.md

@@ -0,0 +1,35 @@
+# TODO — open roadmap items
+
+Tracked work beyond the 1.0.0 release. See `docs/PROMPT_LOG.md` for the full
+design history and `CHANGELOG.md` for what shipped.
+
+## Next release round
+
+- [ ] **Regenerate the season report artifacts** on the box-score default and
+      re-commit them. The 1.0.0 release removed the previous `season_report.*`
+      files because they were generated on the old Fantrax-estimator path
+      (pre-dating exact A-expected on box scores) and were stale.
+- [ ] **Nash mutual ceiling, stage 2.** Mixed-strategy / minimax *value* via a
+      double-oracle LP for the ~20% of matchup periods where iterated best
+      response cycles (no pure equilibrium). Adds an LP dependency + a
+      payoff-matrix builder.
+- [ ] **Wire Nash M3 into the report.** Surface the mutual-ceiling split (and the
+      `M1 − M3` decomposition) as columns in the CSV/Markdown season report.
+
+## Packaging / infra
+
+- [ ] **Replace the vendored fantraxapi with a real dependency** once a published
+      `fantraxapi` (PyPI, with maintainer access) is available. Swap
+      `src/max_pf/_vendor/fantraxapi` for a versioned `>=` dep; refresh steps are
+      in `src/max_pf/_vendor/NOTICE.md`.
+- [ ] **CI** (GitHub Actions): run `pytest` and a vendored-import
+      self-containment check (import with no top-level `fantraxapi` installed) on
+      pushes/PRs.
+- [ ] *(Optional)* Prune the vendored fantraxapi to just the modules the adapter
+      uses (trades / trade blocks / standings are unused), trading a slightly
+      smaller footprint for more effort at each fork refresh.
+
+## Methodology / scope
+
+- [ ] **Additional platforms** behind the `LeaguePlatform` interface (beyond
+      Fantrax) via the `register_platform` hook.