⚽ Sports Intelligence Multi-Agent Crew

Autonomous multi-agent sports analytics copilot powered by CrewAI, Google Gemini, and the Football-Data.org API, built with zero-hallucination factual guardrails, robust entity resolution, and real-time external tool orchestration.

🎯 Overview & Problem Statement

Sports analytics queries often suffer from two major challenges when processed by standard LLMs:

1. Entity & Schema Ambiguity: Users ask questions using casual slang, club nicknames (e.g., "The Blues", "Spurs", "Barca", "PSG"), or informal tournament names that off-the-shelf APIs cannot resolve directly.
2. Hallucination & Stale Data: Traditional LLMs hallucinate match scores, misquote league positions, or invent squad transfers and rumors.

Sports Intelligence Crew solves this by implementing a deterministic multi-agent sequential pipeline:

• Agent 1 (Entity & Intent Resolver) maps colloquial terms, nicknames, and multilingual aliases to canonical database identifiers.
• Agent 2 (Data Retrieval Specialist) invokes specialized API tools with strict parameters.
• Agent 3 (Anti-Hallucination Sports Analyst) compiles structured Markdown briefings strictly grounded on verified API payloads, explicitly declaring data boundary limits when information (such as transfer financial transactions) falls outside standard match feeds.

🏗️ Multi-Agent Architecture

flowchart TD
    User([🧑‍💻 User Query]) --> App[🖥️ Streamlit UI / CLI Runner]
    App --> A1[🤖 Agent 1: Entity & Intent Resolver]
    
    subgraph Multi-Agent Pipeline
        A1 -->|Resolved Team & Comp IDs| A2[🤖 Agent 2: Data Retrieval Specialist]
        
        subgraph Tool Calling Layer
            A2 --> T1[📊 get_league_standings]
            A2 --> T2[🏟️ get_team_matches]
            A2 --> T3[👥 get_squad_info]
            A2 --> T4[⚽ get_top_scorers]
            A2 --> T5[⚔️ get_head_to_head]
        end
        
        T1 & T2 & T3 & T4 & T5 -->|Verified JSON Payloads| A3[🤖 Agent 3: Sports Intelligence Analyst]
    end
    
    A3 -->|Strict Fact-Grounded Markdown| Output([📑 Structured Report & Insights])

🚀 Key Engineering Highlights

| Feature | Description | |---|---| | Autonomous Multi-Agent Crew | Orchestrated via CrewAI with specialized system prompts, backstories, and task dependency chains. | | Robust Tool Calling | Custom @tool decorated functions calling RESTful Football-Data.org v4 endpoints with error handling. | | Strict Anti-Hallucination Guardrails | Strict prompt engineering and boundary checks forcing the reporting agent to state lack of data rather than speculating on scores, stats, or transfer rumors. | | Dual Execution Modes | <ul><li>Live CrewAI Mode: Uses Google Gemini (gemini-3.6-flash) and live API endpoints.</li><li>Offline Instant Demo Mode: Zero-friction demo with verified realistic mock data (runs without API keys).</li></ul> | | Comprehensive Test Suite | 25+ automated unit and integration tests with pytest covering API clients, caching, entity resolution, and CLI. | | Container & CI/CD Ready | Multi-stage Dockerfile, .dockerignore, and GitHub Actions CI workflow. | | Streamlit Web UI & CLI | Interactive conversational interface, quick query buttons, and terminal CLI REPL. |

🧰 Tech Stack

• Orchestration: CrewAI (>=0.86.0)
• LLM / Foundation Model: Google Gemini (gemini-3.6-flash / gemini-1.5-flash)
• Tooling & Data: Football-Data.org API & requests
• Validation & Schemas: pydantic
• User Interface: streamlit
• Testing & CI: pytest, GitHub Actions
• Environment & Execution: uv, Docker, python-dotenv

📂 Project Structure

sports_intelligence_crew/
├── .github/
│   └── workflows/
│       └── ci.yml            # Automated GitHub Actions test pipeline
├── tests/
│   ├── test_api_football.py  # Unit tests for API client, caching & resolution
│   ├── test_crew.py          # Multi-agent tools & offline demo tests
│   └── test_cli.py           # CLI invocation & argument tests
├── api_football.py           # API service client, entity resolver & mock fallback
├── crew.py                   # CrewAI multi-agent definitions & tools orchestration
├── app.py                    # Streamlit conversational web application
├── main.py                   # Terminal CLI runner (interactive & one-shot)
├── Dockerfile                # Production-ready Docker container configuration
├── .dockerignore             # Docker build exclusions
├── requirements.txt          # Pinned Python package dependencies
├── pyproject.toml            # Standard packaging, uv environment & pytest config
├── .env.example              # Environment variable template with setup guides
└── README.md                 # Project documentation & architecture

⚡ Quickstart Guide

1. Clone & Navigate

cd sports_intelligence_crew

2. Configure Environment (Optional for Live Mode)

Copy the environment template:

cp .env.example .env

Edit .env to add your free API keys:

• Google Gemini API Key: Google AI Studio
• Football-Data.org Token: Football-Data.org Client Registration

Note: If no API keys are provided, the system automatically launches in Offline Demo Mode with realistic data.

3. Install Dependencies

Using uv (recommended):

uv pip install -r requirements.txt

Or standard pip:

pip install -r requirements.txt

🧪 Running Automated Tests

Run the full pytest suite:

pytest

Or via uv:

uv run pytest

🖥️ Running the Application

Option A: Launch Streamlit Web UI

streamlit run app.py

Open http://localhost:8501 in your browser.

Option B: Terminal CLI (Interactive REPL)

python main.py

Option C: One-Shot CLI Command

python main.py --query "How has Chelsea performed recently?"

Force offline demo mode:

python main.py --demo --query "Show me the Premier League standings table"

🐳 Docker Deployment

Build the container:

docker build -t sports-intelligence-crew .

Run container:

docker run -p 8501:8501 --env-file .env sports-intelligence-crew

Access the web UI at http://localhost:8501.

💡 Example Queries to Try

• 📊 "Show me the Premier League standings table and analyze top 4 contenders"
• 🏟️ "How has Chelsea performed in their recent matches?"
• ⚽ "Who are the top goalscorers in the Premier League?"
• 👥 "What is the squad and key players for Real Madrid?"
• ⚔️ "Compare head-to-head match history between Chelsea and Arsenal"
• 🔍 "How was Paris Saint-Germain's transfer window? Did they buy anyone new?"

📜 License

MIT License. Created for AI Engineering Portfolio.