FPL Platform
A grounded Fantasy Premier League assistant. Deterministic FPL logic drives all answers; an optional LLM layer polishes the prose. The LLM is subordinate to the backend — it never invents stats.
What it does
- Answers captain, transfer, chip, and fixture questions with real FPL data
- Supports multi-turn sessions with pronoun resolution (English + Spanish)
- Exposes a stable HTTP API for stateless and session-based flows
- Optionally wraps answers with Claude or Gemini for natural-language polish
Packages
| Package | Language | Purpose |
|---|
fpl-grounded-assistant | Python | Core platform — HTTP server, session management, intent routing, LLM integration |
fpl-pipeline | Python | Assembles FPL context: bootstrap + fixtures + FDR in one call |
fpl-tool-runner | Python | ToolRegistry dispatcher for in-process tool execution |
fpl-tool-contract | Python | Defines the 5 structured tools (resolve_player, player_summary, current_gameweek, captain_score, rank_candidates) |
fpl-captain-engine | Python + TS | Captaincy scoring formula (form, xGI/90, fixture difficulty, minutes risk) |
fpl-data-core | Python | Season registry, rolling analytics (xGI/90), position schemas |
fpl-api-client | Python | FPL bootstrap + fixtures HTTP client |
fpl-player-registry | Python | Player identity and nickname resolution (KDB, Salah, etc.) |
fpl-query-tools | Python | Composition layer bridging registry and bootstrap |
fpl-ui | Next.js + TS | Web frontend — Spanish-first slash commands, Patreon-gated |
fpl-charts | TypeScript | Brand color and risk-level theme constants |
football-data-contract | Python | Provider-neutral canonical entities, provenance, and structured evidence contracts |
sportmonks-client | Python | FI-3 Sportmonks transport, provider models, pagination/retry, and offline mocks; no canonical normalization yet |
football-identity-registry | Python | FI-2 deterministic cross-provider identity crosswalk and owned corpus baseline |
football-intelligence | Python | Football feature/module boundary (FI-0(b) scaffold only) |
Tech stack
Backend: Python 3.13, FastAPI, Pydantic v2, Pandas, Anthropic SDK (optional), Google Generativeai (optional)
Frontend: Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS, shadcn/ui
Infrastructure: Docker, Railway (backend), Vercel (frontend)
Running the backend
# Docker
docker build -t fpl-backend:local -f packages/fpl-grounded-assistant/Dockerfile .
docker run --rm -p 8000:8000 \
-e DEFAULT_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY=<key> \
fpl-backend:local
Or with the dev script:
packages/fpl-grounded-assistant/dev-backend.sh
The server exposes /ask (stateless) and /session/* (multi-turn) endpoints.
Running the frontend
cd packages/fpl-ui
npm install
npm run dev # http://localhost:3000
Tests
The test suite is self-contained — no pytest, no network calls, no API key required:
cd packages/fpl-grounded-assistant
PYTHONPATH=../fpl-tool-runner:../fpl-player-registry:../fpl-captain-engine:\
../fpl-data-core:../fpl-tool-contract:../fpl-query-tools:\
../fpl-api-client:../fpl-pipeline:. python run_phase3d_tests.py
Contract drift gate (run by CI):
bash scripts/run_contract_gate.sh
Documentation
