Sleeper Fantasy Agent

A LangGraph agent that monitors your Sleeper fantasy football teams and gives you an edge: it optimizes your starting lineup, surfaces hot trending pickups, and finds the best trade targets — using matchups, injuries, news, and roster analysis.

It's the Sleeper sibling of yahoo-fantasy-agent, and works with any OpenAI-compatible LLM endpoint (OpenAI, Ollama, vLLM, LM Studio, OpenRouter, Together, Groq, …).

---

No auth required (and an important limitation)

The Sleeper API is read-only and completely key-less — no OAuth, no developer account, no token. You only provide your Sleeper username.

The trade-off: Sleeper has no public write API. This agent therefore cannot change lineups, add/drop players, or submit trades for you. It is a powerful analyst and advisor — it produces concrete, ready-to-apply recommendations (exact players + slots) that you execute with a couple taps in the Sleeper app. Because nothing it does is destructive, there's no approval gate.

Compared to the Yahoo agent, which has full OAuth read/write (auto lineup changes, add/drops, and waiver "snipes"), the Sleeper agent trades write capability for zero-setup, auth-free access.

---

Install

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env        # then set SLEEPER_USERNAME + your LLM endpoint

Configure (.env)

SLEEPER_USERNAME=your_username   # that's the only required field
SLEEPER_SEASON=                  # optional; defaults to current season

OPENAI_BASE_URL=https://api.openai.com/v1   # or http://localhost:11434/v1 for Ollama
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o-mini

Usage

sfa config-show              # verify config
sfa leagues                 # list your leagues + ids
sfa roster <league_id>      # show your roster (ranked by value)
sfa lineup <league_id>      # recommended optimal starting lineup + changes
sfa trending                # hot adds league-wide
sfa daily                   # full routine: lineups + pickups + trades
sfa run "find me a trade in league 11223344"
sfa chat                    # interactive

---

Architecture

src/sfa/
├── config.py            # env settings (just a username + LLM)
├── llm.py               # OpenAI-compatible ChatOpenAI factory
├── sleeper/client.py    # read-only Sleeper API + daily-cached players dump
├── data/news.py         # ESPN key-less news + injury signals
├── projections.py       # pluggable projection providers (Sleeper / FantasyPros)
├── analysis.py          # valuation, lineup optimizer, trade matching (pure fns)
├── tools.py             # 14 read/analyze LangChain tools
├── agent.py             # create_react_agent graph + SQLite checkpointer
└── cli.py               # typer CLI

Tools (all read/analyze — recommendations only)

list_leagues, get_roster, get_roster_positions, recommend_lineup, trending_pickups, list_available_players, evaluate_roster, evaluate_player_value, get_player_projection, find_trade_targets, get_matchup, get_injuries, get_news, get_player_news.

Projections (player value)

Player value is driven by weekly projected fantasy points, in your league's detected scoring format (PPR / half-PPR / standard). The source is pluggable via PROJECTIONS_SOURCE:

Source	Key needed?	What it uses
sleeper (default)	No	Sleeper's own projections endpoint — real pts_ppr/pts_half_ppr/pts_std, keyed directly by Sleeper player_id (no name matching).
fantasypros	Yes (FANTASYPROS_API_KEY)	FantasyPros Expert Consensus Rankings, matched to Sleeper ids by normalized name; ECR converted to a comparable value. Falls back to sleeper if no key is set.
none	No	Falls back to Sleeper search_rank (popularity proxy).

Projections flow automatically into recommend_lineup, list_available_players, trending_pickups, evaluate_roster, and find_trade_targets; query a single player with get_player_projection. Need/surplus thresholds are scale-invariant, so the analysis works on either the points scale or the search_rank fallback.

How the rest of the analysis works

• Value fallback (when projections are off): Sleeper's search_rank normalized to ~0–100 so it's comparable across positions.
• Lineup optimizer fills fixed slots first, then flex (FLEX, SUPER_FLEX, etc.) from the remaining pool, and diffs against your current starters.
• Trade finder grades every roster's depth per position (need/ok/surplus, with a flex cushion for RB/WR/TE) and pairs your surplus with an opponent's need and vice-versa — e.g. their spare WR for your spare RB.
• Trending pickups come straight from Sleeper's add/drop trend counts, filtered to players still available in your league.

Notes

• The /players/nfl dump is ~5 MB; it's cached under .cache/ and refreshed at most once per day.
• ESPN news/injury endpoints are unofficial and fail soft (return empty).
• This project is unaffiliated with Sleeper.

License

MIT