ffb

Personal fantasy-football tooling for Brian's Yahoo league. The Python CLI downloads free projection, ADP, schedule, and identity data; snapshots each raw response; stores normalized rows in DuckDB; and produces league-scored rankings and a draft board. A separate Cloudflare Worker in tracker/ consumes the exported board.json for live and mock drafts.

League state comes from a validated fixture, the tracker's browser-captured Yahoo bundle, or the live Sleeper adapter. There is no Yahoo API access. See DESIGN.md for product scope.

Requirements and setup

• Python 3.12 or newer and uv
• Node 24.18.0 and npm 11.16.0 for tracker/ (nvm use applies the pins)

make init

make init installs both toolchains. For the Python package only, run uv sync.

Quick start

Synchronize a season explicitly, then read the persisted data:

uv run ffb season sync 2026 --refresh
uv run ffb season status 2026
uv run ffb rankings 2026 -p RB --show-sources
uv run ffb board show 2026
uv run ffb board export 2026
uv run ffb ros 2026
uv run ffb season sync 2026 --week 1 --source projections
uv run ffb league sync 2026 --fixture PATH
uv run ffb lineup 2026
uv run ffb digest 2026

season sync is the only projection, ADP, schedule, injury, headline, and crosswalk ingestion path. Its default policy reuses existing snapshots and fetches only missing ones. Use --refresh to fetch selected sources again, --offline to prohibit network access, --rebuild to force cached data back through parsing and atomic replacement, and --week N to also ingest that week's Sleeper/ESPN projections (stored as scope=week{N}; rankings and the board stay season-only). A database from before schedule_games.gameday / gametime is moved aside and replayed; the one-time kickoff backfill is uv run ffb season sync 2026 --source schedule --refresh. See Operations.

uv run ffb calibrate priors is a separate one-time snapshot of 2024–2025 weekly projections and nflverse stats for calibration. It does not write DuckDB or publish. uv run ffb calibrate waivers 2024 --week 1 grades Sleeper free agents from those snapshots. See Operations.

Read commands never fetch. They warn about missing, failed, stale, or untracked inputs and use whatever valid projection sources are persisted. Inspect misses with:

uv run ffb season unmatched 2026
uv run ffb season unmatched 2026 --source ffc

ffb ros is a read-time rest-of-season report: season consensus, playoff-week opponents and opponent-DEF schedule strength, and (when a user roster is stored) bye-week planning. It does not ingest usage trends or change the board.

The draft board combines league-scored projection consensus with Fantasy Football Calculator ADP, schedule-derived bye weeks, VORP, and positional tiers. It defaults to players that current source evidence marks as draftable; use --player-pool all for the complete matched diagnostic pool. Export writes Markdown, CSV, and the self-contained board.json v1 contract to exports/.

League settings

League scoring, roster shape, teams, and current-week rosters can be loaded from a validated fixture or the tracker's last accepted bundle:

uv run ffb league sync 2026 --fixture tests/fixtures/yahoo_league_minimal.json
uv run ffb league sync 2026 --from-tracker
uv run ffb league show 2026 --rosters

Without stored league state, the CLI uses the confirmed 10-team Yahoo fallback in src/ffb/config.py. After a current-week fixture is stored and weekly projections are ingested, ffb lineup compares the user team's selected_position to optimal weekly starters. Current and optimal rows show Sleeper Q/O/D/IR flags on the stored current week. Out, doubtful, and IR-list players are not started and count as zero in current totals. It never writes back to Yahoo.

ffb digest is a read-time injury/headline brief for the user roster and unrostered players mentioned in ESPN/RSS news. It never changes rankings or sit/start numbers. Without ANTHROPIC_API_KEY it still prints headlines and injury labels; with a key, Haiku adds per-player flags and Sonnet writes a short weekly brief. Every player a headline names is labelled for the LLM as mine, rostered by another team, a free agent, or unknown, so the brief never files a rival's player under your team.

ffb lineup, ffb digest, ffb retro, and ffb ros accept --publish to POST the report they just printed to the tracker, where the read-only /command dashboard shows all four with per-card freshness. ffb league sync --from-tracker imports the league bundle the tracker last accepted, and ffb league sync --league sleeper --push posts a live Sleeper bundle to it. All of these need FFB_TRACKER_URL and FFB_TRACKER_API_KEY; see docs/operations.md for the twice-weekly runbook.

Draft tracker

The tracker is a separate TypeScript Cloudflare Worker with its own dependencies and tests. It reads board.json from KV, stores live and isolated mock-draft state in D1, and has no runtime dependency on Python.

cd tracker
nvm use
npm ci
npm run typecheck
npm test
npm run test:browser
npm run dev

Local development needs TRACKER_API_KEY=<anything> in the gitignored tracker/.dev.vars. Export a board first, then run npm run publish:board to seed local KV. See docs/tracker.md for behavior and API details and docs/operations.md for local and production workflows.

Development

uv run pytest
uv run ruff check .
uv run ruff format --check .

cd tracker
npm run typecheck
npm test
npm run test:browser

# Cross-stack fixture → CLI → DuckDB/board → Worker KV/D1 journey
cd ..
make test-backend-e2e

CI runs the Python, tracker, and backend end-to-end suites independently and without live data sources.

Documentation

• Architecture — boundaries, data flow, identity, storage, and board computation
• Data sources — endpoints, parsing, snapshots, and source-specific gotchas
• Draft tracker — live and mock behavior, APIs, persistence, and UI invariants
• Starter priority — how the live Available list ranks players by opportunity cost
• Operations — rebuilds, environment overrides, testing, publishing, and deployment
• Refresh job — how to run the Wed–Sun morning refresh for both leagues
• Design — product direction and deferred weekly-management scope