---
title: FPL Scout Agent
emoji: ⚽️
colorFrom: green
colorTo: purple
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
tags:
- mcp-in-action-track-consumer
- agent
- football
- fpl
- smolagents
short_description: AI Agent analyzing live FPL data to help you win
---

# ⚽️ FPL Scout Agent (MCP Hackathon)

### 🚀 [Watch the Demo Video Here](https://youtu.be/-_JfC3KWiDY)

## 🌟 Overview
Welcome to our submission for the **Hugging Face GenAI Agents & MCP Hackathon**! 

The **FPL Scout Agent** is an intelligent tactical assistant designed to solve the biggest problem in Fantasy Premier League: **Information Overload**. Instead of browsing 10 different stats websites, users can simply ask complex strategic questions and get data-driven answers instantly.

It leverages the **Model Context Protocol (MCP)** pattern to connect a powerful LLM (`Qwen 2.5-Coder`) with the live **Official FPL API**, enabling real-time analysis of player form, fixtures, and pricing.

---

## ⚡️ Key Features

### 1. 🔍 Real-Time "Hidden Gem" Scanner
Most managers pick the same template players. Our agent actively hunts for **Differentials** (players with <10% ownership) who are hitting peak form.
- *User:* "Find me a cheap differential midfielder under 6.5m."
- *Agent:* Scans the database, filters by price/ownership, and recommends players like **Semenyo** or **Rogers**.

### 2. ⚔️ Head-to-Head Comparison Engine
Solves "Captaincy Dilemmas" by mathematically weighing players against each other using a weighted formula (60% Recent Form + 40% Long-term Consistency).
- *User:* "Who should I captain: Salah or Haaland?"
- *Agent:* "Salah is better this week (Rating 8.2 vs 7.5) because he plays Leeds (H)."

### 3. 🛡️ Anti-Hallucination Protocol
LLMs famously invent fake stats. We implemented a strict **"Tool-First" Architecture**:
- The Agent **cannot** speak about prices/teams without first running a tool.
- It is explicitly banned from using its pre-trained (outdated) memory for player data.
- If the API fails, the Agent admits it rather than guessing.

---

## 🔧 Technical Architecture

This project uses a **Multi-Stage Reasoning Loop**:

1.  **Intent Recognition:** The LLM identifies if the user needs *Data* (Prices, Form) or *Strategy* (Chip rules).
2.  **Tool Execution (MCP Pattern):**
    - `get_player_report(name)`: Fetches live history + upcoming fixtures.
    - `compare_players(name1, name2)`: Runs the comparison algorithm.
    - `find_hidden_gems(pos, price)`: Iterates through 700+ players to filter results.
3.  **Context Injection:** The raw JSON output from the tool is injected back into the chat context.
4.  **Final Synthesis:** The LLM generates a natural language response based *only* on the injected data.

### 🛠️ Tech Stack
- **Framework:** Gradio 6.0 (ChatInterface)
- **Model:** Qwen/Qwen2.5-Coder-32B-Instruct (via Hugging Face Inference API)
- **Data Source:** Official Fantasy Premier League API (`bootstrap-static`, `element-summary`)
- **Theme:** Custom CSS matching the Official Premier League branding (Purple/Neon Green).

---