Apppublic

tram11/fantasy-football-advisor

sourceHugging Faceupdated 4mo agoView on Hugging Face

0likes

App README

Fantasy Football LLM Advisor

A tool-calling LLM agent that answers fantasy football questions by querying real player stats, projections, Vegas lines, defensive matchups, and news — never from memory.

What it does

—Scrapes live data from Sleeper (players, per-week stats, projections, schedules) and ESPN (news, Vegas betting lines)
—Stores it in SQLite (structured queries) and ChromaDB (semantic search)
—Routes questions through 5 tools — exact lookups go to SQL, conceptual questions go to vector search
—Shows its work — every answer comes with the actual tool calls and data the agent used
—Multi-turn chat with conversation history preserved across the session

Tech stack

—Backend: Python 3.11, FastAPI, SQLAlchemy, SQLite
—LLM: Groq API (default: openai/gpt-oss-120b)
—Embeddings: sentence-transformers (local CPU)
—Vector store: ChromaDB
—Frontend: React 18 + TailwindCSS, served as static files (no build step)
—Data sources: Sleeper public API, ESPN public + core APIs

Project structure

backend/
├── app/
│   ├── api/             # FastAPI server (chat endpoint + static frontend mount)
│   ├── config.py        # App configuration
│   ├── db/              # SQLAlchemy models, CRUD, migration helper
│   ├── llm/             # Groq client wrapper with retries
│   ├── models/          # Pydantic models (Player, Stats, Projection, Game, TeamLine, ...)
│   ├── pipeline/        # Scrape → chunk → embed orchestration
│   ├── rag/             # Tool-calling agent loop + system prompt
│   ├── scrapers/        # Sleeper + ESPN scrapers
│   ├── tools/           # 5 tools the agent can call (sql, search, players, news, nfl_state)
│   └── vectorstore/     # ChromaDB integration
├── evals/               # Eval harness with question battery, checks, runner, CLI
└── tests/               # 225+ unit tests
frontend/
├── index.html           # Single-file React entry (loads via CDN, no build needed)
└── app.jsx              # Chat UI

Setup

bash

git clone https://github.com/your/Fantasy-Football-LLM.git
cd Fantasy-Football-LLM/backend
uv venv && source .venv/bin/activate
uv sync --extra dev
cp .env.example .env      # then add GROQ_API_KEY

Then run the data pipeline once to populate the DB:

bash

python -m app.pipeline.processor       # players + season stats + news
# or via the python REPL for individual backfills:
python -c "import asyncio; from app.pipeline.processor import backfill_projections; asyncio.run(backfill_projections(2025))"
python -c "import asyncio; from app.pipeline.processor import backfill_schedule; asyncio.run(backfill_schedule([2024, 2025, 2026]))"
python -c "import asyncio; from app.pipeline.processor import backfill_team_lines; asyncio.run(backfill_team_lines(2025))"
python -c "from app.pipeline.processor import backfill_opponents; backfill_opponents(2025)"

Run the chat UI

bash

cd backend
uvicorn app.api.server:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 in a browser. That's it — no separate frontend process. Conversation history persists in localStorage.

Run the eval battery

bash

cd backend
python -m evals.cli                              # full battery
python -m evals.cli --id top_rbs_rushing_2025    # single question
python -m evals.cli --tag sql --concurrency 1    # by tag

Tests

bash

cd backend
pytest                # all 225+ tests
pytest tests/test_api.py -v

API endpoints

—GET / — chat UI
—GET /health — liveness check
—GET /nfl-state — current NFL season/week
—POST /chat — {messages: [{role, content}, ...]} → agent response with sources

Status

Phase G complete: working multi-turn chat UI on top of the tool-calling agent. The agent can pull projections, Vegas lines, per-week stats, snap counts, defensive matchups, news, and form summaries, and chain them across turns.