# Fantasy GM

[![Tests](https://github.com/younim2837/fantasy-football-gm/actions/workflows/tests.yml/badge.svg)](https://github.com/younim2837/fantasy-football-gm/actions/workflows/tests.yml)

Fantasy GM is a local, read-only fantasy-football decision backend. It supports lineup optimization, waiver-priority and FAAB recommendations, post-waiver free-agent sweeps, and player-only trade evaluation/discovery. Scoring, roster slots, team count, waiver mechanism, season, and roster depth come from each league's saved Sleeper state.

The backend exposes the same typed operations through its CLI and a standard MCP server. Codex and other MCP-capable clients can use it; the conversational client explains structured results but does not invent projections or decisions.

## Install for your leagues

Prerequisites: Git and Python 3.11 or newer. Each installation keeps its own
configuration and league data; cloning this repository does not include another
user's Sleeper profile, rosters, recommendations, or FantasyPros credentials.

```powershell
git clone https://github.com/younim2837/fantasy-football-gm.git
cd fantasy-football-gm
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[agent]"
.\.venv\Scripts\fantasy-gm.exe setup
```

On macOS/Linux, replace `.\.venv\Scripts\` with `.venv/bin/`.

`fantasy-gm setup` discovers current NFL leagues and owned rosters, suggests aliases, and asks which alias should be the default. For unattended setup using every suggested alias:

```powershell
.\.venv\Scripts\fantasy-gm.exe setup --username <sleeper-username> --accept-suggested --default <alias>
```

Sleeper access uses its public read-only API. No Sleeper password, login session, or write access is requested.

## Connect projections

FantasyPros data is optional for inspection but required for projection-based decisions. The preferred integration imports lossless results from the official FantasyPros MCP tools:

```powershell
codex mcp add fantasypros --url https://api.fantasypros.com/mcp
codex mcp login fantasypros
.\.venv\Scripts\fantasy-gm.exe configure-projections weekly_stats
```

Native Codex/Astra owns authenticated FantasyPros access. Fantasy GM owns capture
validation, immutable persistence, scoring, modeling, optimization and recommendations.
Ordinary users ask their fantasy question; the agent handles refresh/import/retry.
The former Python bearer client is retired; legacy `fantasypros` configuration now
uses the validated MCP-capture provider. Native Codex authentication is never copied.

After Codex and FantasyPros are configured, the packaged agent entry point runs the
complete evidence-refresh and recommendation workflow:

```powershell
.\.venv\Scripts\fantasy-gm-agent.exe --operation recommend_lineup --leagues default
```

Supported operations are `recommend_lineup`, `recommend_waivers`,
`recommend_free_agents`, `recommend_streamers`, and `discover_trades`.

## Start the MCP server

```powershell
.\.venv\Scripts\fantasy-gm.exe serve
```

Configure an MCP client with an absolute command path appropriate to that computer:

```json
{
  "mcpServers": {
    "fantasy-gm": {
      "command": "/absolute/path/to/fantasy-football-gm/.venv/bin/python",
      "args": ["-m", "fantasy_gm", "serve"]
    }
  }
}
```

On Windows, the command normally ends in `.venv\\Scripts\\python.exe`. Add `--data-dir <path>` to `args` for an isolated profile. Otherwise data lives under `~/.fantasy-gm`.

Useful questions:

- “Check all my leagues.”
- “Who should I start this week?”
- “Check waivers in dynasty.”
- “Waivers cleared—what free agents should I add?”
- “What defense should I stream this week?”
- “Any better kickers available?”
- “Find me trades in work.”

When no league is named, the configured default is used. Every league-aware tool also accepts a case-insensitive alias or numeric Sleeper league ID.

## Everyday CLI commands

```powershell
.\.venv\Scripts\fantasy-gm.exe status
.\.venv\Scripts\fantasy-gm.exe leagues
.\.venv\Scripts\fantasy-gm.exe check-all
.\.venv\Scripts\fantasy-gm.exe default-league <alias>
.\.venv\Scripts\fantasy-gm.exe check --league <alias>
.\.venv\Scripts\fantasy-gm.exe lineup --league <alias>
.\.venv\Scripts\fantasy-gm.exe waivers --league <alias>
.\.venv\Scripts\fantasy-gm.exe free-agent-sweep --league <alias>
.\.venv\Scripts\fantasy-gm.exe trades --league <alias>
```

`check-all` is intentionally lightweight: it reports each roster, opponent, week, acquisition mechanism, balance/priority, freshness, and errors without running deep trade searches.

## Local data and isolation

Configuration and user data are never required from the checkout. The default layout is:

```text
~/.fantasy-gm/
  profile.json
  cache/players-nfl.json
  leagues/<sleeper-league-id>/
    snapshots/<snapshot-id>/
    recommendations/<recommendation-id>.json
    projections/
    waiver-pools/
```

`profile.json` contains non-secret aliases and stable Sleeper identifiers. League state, exact scoring, projection references, waiver pools, and recommendation history are isolated by league ID. Shared catalogs and raw provider captures are source data; every decision validates league, season, week, scoring, and identity context before use.

Use a separate data directory for a different person:

```powershell
$env:FANTASY_GM_DATA_DIR = "C:\path\to\isolated-data"
.\.venv\Scripts\fantasy-gm.exe setup
```

The backend rejects mixing different Sleeper users inside one profile. A clean clone starts with no profile and no access to another user's local data, caches, secrets, or history.

## Decision boundaries

- Sleeper operations are read-only; the user executes lineup and roster changes.
- Weekly numeric projections and ordinal ROS ECR remain separate.
- Unknown forced slots may cancel only when they cannot affect the decision; decision-changing uncertainty remains unavailable.
- `WAIVER_PRIORITY`, `FAAB`, `FREE_AGENT`, and `UNKNOWN_UNSUPPORTED` are distinct acquisition strategies.
- FAAB outputs use remaining budget, preferred bid, range, walk-away price, and exposed completed-bid history. Priority leagues never receive FAAB fields.
- Unrostered does not prove immediate free-agent availability; post-waiver immediacy remains user-attested unless verified.
- K/DST weekly streaming uses FantasyPros MCP aggregate fields plus explicit modeled field-goal-distance and points-allowed buckets, then applies the selected league's exact scoring weights. Source fields and modeled components remain separate in the evidence.
- K/DST switches use position- and acquisition-specific expected weekly-point thresholds when the incoming player actually starts; the provisional zero-cost K/DST defaults are +0.8. Interval overlap is reported as an explicitly uncalibrated risk diagnostic, not an automatic hold. See [streaming policy](docs/streaming-policy.md).

## Verify and troubleshoot

```powershell
.\.venv\Scripts\python.exe -m unittest discover -v
.\.venv\Scripts\fantasy-gm.exe discover --username <sleeper-username>
.\.venv\Scripts\fantasy-gm.exe status
```

Common errors include `LEAGUE_NOT_CONFIGURED`, `LEAGUE_NOT_FOUND`, `PROJECTIONS_UNAVAILABLE`, and `PROFILE_USER_MISMATCH`. Restart or reconnect the MCP server after an upgrade.

See [multi-league architecture](docs/multi-league.md), [decision model](docs/decision-model.md), and [MCP client setup](docs/astra-integration.md).


All lineup advice must come from `recommend_lineup.lineup_decision` (also exposed
on the response envelope). Render `conversational_response` faithfully:
`COMPLETE` permits the full lineup; `DECISION_SUFFICIENT` permits only
`supported_decisions`, labeled `VALIDATED DECISIONS (partial)`, followed by
`unresolved_decisions` and `limitations`; `UNAVAILABLE` permits no lineup advice.
An error or missing contract is unavailable. Do not select starters or conditional
injury replacements from raw FantasyPros projections, ECR, injury/status data,
current rosters, coverage comparisons, or LLM reasoning. These are evidence for
the engine, never a separate fallback engine. Do not fill unresolved slots.
For multi-league lineup questions, call the engine independently for each league,
even after another fails. The lightweight check-all tool does not validate lineups.
The CLI exposes the same fields as JSON; `lineup --league <alias> --format text`
prints the canonical rendering. Historical records without the contract require
a fresh engine call before giving advice.

Evidence refresh is automatic for missing or expired FantasyPros pools. Warm
captures are reused; failed refresh never authorizes stale lineup advice.
The agent calls `ensure_fantasypros_evidence`, fulfils its exact native MCP calls,
imports structured results, and retries the original engine operation. The Python
backend does not open or persist FantasyPros OAuth credentials.

Use `fantasy-gm refresh-evidence <alias> --workflow lineup` for acquisition diagnostics
and `fantasy-gm league-doctor <alias>` for compatibility and coverage.
`check-all --include-lineup` explicitly adds independent engine calls; ordinary
`check-all` remains state inspection. Every lineup response must still follow
the decision contract above.

## Privacy and license

Fantasy GM uses Sleeper's public, read-only API and stores league state under the
local data directory described above. Keep that directory, `.env` files, and API
keys out of source control. The repository's ignore rules exclude the standard
local locations.

Fantasy GM is available under the [MIT License](LICENSE). It is an independent
project and is not affiliated with Sleeper or FantasyPros.