Apppublic

LiberoSports/FPLAIManager

sourceHugging Faceupdated 1mo agoView on Hugging Face

0likes

App README

FPL AI Manager

FPL AI Manager is a Gradio application for season-long Fantasy Premier League decision support. It retrieves and validates current public data from the official Fantasy Premier League API, then keeps facts, analytics, optimisation, simulations, decision memory, and conversational explanation in deliberately separate layers. [1]

Data principle: official FPL facts and deterministic model outputs are shown separately. The chat assistant receives only a structured evidence bundle and is not permitted to invent statistics, fixtures, injuries, prices, or set-piece assignments.

Product capabilities

Area	Implemented behaviour	Data-confidence treatment
Official data	Validated `bootstrap-static`, fixtures, player summary, live event, entry history, transfer, and entry-picks client methods with retries and an atomic TTL cache	Reports network, cache, or stale-cache source; fails visibly without usable data
Player analysis	Expected minutes, fixture windows, expected-point MVP projection, value, underlying-stat, threat, defensive, differential, rotation, hidden-gem, and attacking-defender metrics	Every scorecard carries visible component fields and a confidence level
Initial squad	Mixed-integer 15-player optimiser using budget, 2/5/5/3 position counts, and a three-per-club cap from the current FPL game settings	Pre-season proposal; not a connected user entry
Weekly selection	Legal formation, bench ordering, captain, vice-captain, alternative captain, roll, and single-transfer recommendations	Shows projection horizon, transfer cost, minutes, and fixture drivers
Chips and scenarios	Conservative chip save/use logic plus 1/3/5/8-gameweek transfer/captain/chip comparisons	Wildcard and Free Hit require a user-supplied rebuilt squad to simulate their full effect
Memory	SQLite-backed manager preferences, squad snapshots, and immutable decision rationale	Durable only when `FPL_STATE_DB` points to persistent storage
Chat	Optional OpenAI-compatible explainer using the current verified `gpt-5-mini` default, overridable through `LLM_MODEL`	Safe structured fallback when no LLM secret is configured
Interface	All requested management tabs: My Team, Ask the FPL AI, Transfers, Captain, Chips, Hidden Gems, Set Pieces, Attacking Defenders, Fixtures, Time Machine, Compare Players, and Player Rankings	Displays current data freshness and pre-season limitations

Run locally

Use Python 3.11 or later. The commands below create an isolated environment, install all declared requirements, and run the Space launch command.

bash

cd fpl-ai-manager
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Gradio normally serves the interface at http://127.0.0.1:7860. Select Refresh official FPL data to bypass the 15-minute cache. The first dashboard load builds a legal modelled squad from the current official snapshot.

Configuration

Copy the template only for local work. Never commit actual secrets.

bash

cp .env.example .env

Variable	Purpose	Required
`FPL_API_BASE_URL`	Official FPL API root; defaults to the public official endpoint	No
`FPL_CACHE_TTL_SECONDS`	Raw-data cache duration, default `900` seconds	No
`FPL_STATE_DB`	SQLite database path for preferences, snapshots, and decisions	No locally; yes for durable deployment
`OPENAI_API_KEY`	OpenAI-compatible API key for optional chat narration	No
`LLM_MODEL`	Conversational model ID; defaults to verified `gpt-5-mini`	No

Validate before deployment

The offline tests do not depend on FPL network availability. The diagnostic and dashboard smoke test then exercise the current public API contract and full analytical bundle.

bash

pytest -q
python scripts/validate_fpl_api.py --refresh
python scripts/smoke_dashboard.py

To inspect entry-specific endpoint availability for a public FPL team, pass an explicit team ID. Pre-season picks can legitimately be unavailable before the official game exposes them; the client reports that condition rather than producing a fabricated squad.

bash

python scripts/validate_fpl_api.py --refresh --entry-id YOUR_FPL_TEAM_ID

Deploy to Hugging Face Spaces

Create a new Gradio Space on Hugging Face, clone its repository, and copy this project's files into the cloned repository root.

bash

git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cp -R fpl-ai-manager/. YOUR_SPACE_NAME/
cd YOUR_SPACE_NAME
git add .
git commit -m "Deploy FPL AI Manager"
git push

Hugging Face reads the YAML metadata at the top of this README, installs requirements.txt, and starts app.py. The official FPL API is public and therefore needs no secret. To enable chat, add OPENAI_API_KEY and optionally LLM_MODEL through Space Settings → Variables and secrets; do not put them in the repository.

Choose season-memory storage before production

A long-running manager needs a durable state location. Choose one of the following paths before relying on preferences or decision history; then set FPL_STATE_DB accordingly.

Approach	Trade-offs	Cost	Setup complexity
Persistent Space storage with the SQLite implementation	Simplest for a single private manager; requires the Space’s persistent disk to be enabled and mounted	Depends on the Space storage plan	Low
External managed database with a future repository adapter	More suitable for multiple users and independent backups; needs provider credentials and a database migration	Provider-dependent	Medium

The default repository-local .data directory is suitable for development only. It must not be treated as production season memory on non-persistent Space disk.

Current product boundaries

The application intentionally does not claim information it cannot verify. As of the current pre-season FPL response, the underlying performance model is low confidence until official current-season minutes accumulate. The Set Pieces tab remains source-gated until an explicitly sourced provider is configured. The transfer dashboard analyses the modelled initial squad; connecting a user’s official entry requires entering a public entry ID once the FPL picks endpoint is available for the gameweek. These boundaries are explicit rather than silently filled with speculation.

Detailed data contracts, scoring methodology, optimisation rules, scenario design, memory design, and source-provenance rules are in `docs/architecture.md`.

References

[1] Official Fantasy Premier League API — current bootstrap data