Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

ย 
ย 

Latest commit

ย 

History

48 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

โšฝ Real-Time Football Match RAG System

A real-time football match streaming system with AI-powered chat using Kafka and Mistral AI.

๐ŸŒ Live Demo

Try it here!

Note: This demo link may expire. If it's not working, you can run the project locally following the setup instructions below.

๐ŸŽฏ What It Does

Stream football matches in real-time and chat with an AI assistant that knows what's happening in the game. Ask questions like "What's the score?" or "Who scored?" and get instant, context-aware answers.

๐Ÿ—๏ธ How It Works

Match Data (JSON files)
    โ†“
Kafka Producer (replay_streamer.py) - Streams match events
    โ†“
Kafka Topics (comments, events, scores)
    โ†“
Kafka Consumer (kafka_context_store.py) - Tracks last 30 events
    โ†“
RAG Engine (rag_engine_simple.py) - Reads context + asks Mistral AI
    โ†“
You get smart answers! ๐Ÿค–

โœจ Features

  • โšก Real-time streaming - Watch matches unfold minute by minute
  • ๐Ÿค– AI chatbot - Ask questions about the match in natural language
  • ๐ŸŽฎ Multiple matches - Stream several games at once
  • โฐ Start anywhere - Begin at any minute (e.g., 45'+2, 60')
  • ๐Ÿ“Š Smart context - AI knows the last 30 events (10 goals + 10 events + 10 comments)

๐Ÿš€ Quick Start

1. Install Kafka

macOS:

brew install kafka
brew services start kafka

Linux:

# Download and extract Kafka
wget https://downloads.apache.org/kafka/3.6.0/kafka_2.13-3.6.0.tgz
tar -xzf kafka_2.13-3.6.0.tgz
cd kafka_2.13-3.6.0

# Start Zookeeper
bin/zookeeper-server-start.sh config/zookeeper.properties &

# Start Kafka
bin/kafka-server-start.sh config/server.properties &

Windows:

# Option 1: Use WSL2 (recommended)
# Install WSL2, then follow Linux instructions

# Option 2: Native Windows
# Download from https://kafka.apache.org/downloads
# Extract to C:\kafka
# Run from C:\kafka:
.\bin\windows\zookeeper-server-start.bat .\config\zookeeper.properties
# In new terminal:
.\bin\windows\kafka-server-start.bat .\config\server.properties

2. Setup Backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set Mistral API key (get yours at https://console.mistral.ai/)
export MISTRAL_API_KEY="your_key_here"  # On Windows: set MISTRAL_API_KEY=your_key_here

# Start backend
uvicorn backend.app:app --reload

Backend runs on http://localhost:8000

3. Setup Frontend

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:3000

4. Use the App

  1. Open http://localhost:3000
  2. Select a match from "Match history"
  3. Click "Stream selected games"
  4. Click the match in "Currently streaming"
  5. Ask questions in the chatbot!

๐Ÿ’ฌ Example Questions

  • "What's the score?"
  • "Who scored?"
  • "Any yellow cards?"
  • "What happened in the last 5 minutes?"
  • "Tell me about the goals"

๐Ÿ“ Project Structure

project/
โ”œโ”€โ”€ backend/
โ”‚   โ”œโ”€โ”€ app.py                    # FastAPI server
โ”‚   โ”œโ”€โ”€ replay_streamer.py        # Kafka producer (streams events)
โ”‚   โ”œโ”€โ”€ kafka_context_store.py   # Kafka consumer (tracks context)
โ”‚   โ”œโ”€โ”€ rag_engine_simple.py     # AI chatbot with Mistral
โ”‚   โ””โ”€โ”€ runtime/                 # Generated context files
โ”‚       โ””โ”€โ”€ {game_id}/
โ”‚           โ””โ”€โ”€ rag_recap.txt    # Last 30 events (used by AI)
โ”œโ”€โ”€ data/
โ”‚   โ””โ”€โ”€ games/
โ”‚       โ””โ”€โ”€ {game_id}/
โ”‚           โ”œโ”€โ”€ meta.json        # Match info
โ”‚           โ”œโ”€โ”€ events.json      # Goals, cards, subs
โ”‚           โ””โ”€โ”€ comments.json    # Commentary
โ”œโ”€โ”€ frontend/
โ”‚   โ””โ”€โ”€ app/
โ”‚       โ””โ”€โ”€ page.tsx             # React UI
โ””โ”€โ”€ requirements.txt

๐Ÿ”ง Configuration

Environment Variables

# Required
export MISTRAL_API_KEY="your_mistral_key"

# Optional (defaults shown)
export MISTRAL_MODEL="mistral-small-latest"
export KAFKA_BOOTSTRAP="localhost:9092"

๐Ÿ“Š How the AI Works

Context Window

The AI sees the last 30 events:

  • 10 goals with scorer info
  • 10 events (cards, subs, VAR)
  • 10 comments (commentary)

Why Not Vector Search?

We use simple file-based RAG instead of vector databases because:

โœ… Recent context is what matters - You care about the last 10 events, not searching through 500
โœ… Simpler - No embeddings, no Qdrant, no complexity
โœ… Faster - Direct file read (~1ms) vs vector search
โœ… Cheaper - No embedding API calls
โœ… Perfect for live matches - Chronological order, not semantic similarity

๐ŸŽฎ Advanced Usage

Start at Specific Time

# Start at minute 45, extra time +2
{
  "games": [{
    "game_id": "chelsea_aston_villa_2025-12-27",
    "startAtMinute": 45,
    "startAtExtra": 2
  }]
}

Stream Multiple Matches

# Stream 3 matches at once
{
  "games": [
    {"game_id": "match1", "startAtMinute": 0, "startAtExtra": 0},
    {"game_id": "match2", "startAtMinute": 45, "startAtExtra": 0},
    {"game_id": "match3", "startAtMinute": 60, "startAtExtra": 0}
  ]
}

๐Ÿ› Troubleshooting

"Failed to load games"

Check backend is running:

curl http://localhost:8000/api/games
# Should return JSON with game list

Check game data exists:

ls -la data/games/
# Should show game folders with meta.json, events.json, comments.json

"No context available"

Wait for streaming to start - Context builds as events stream

Check Kafka is running:

# Should show active brokers
kafka-broker-api-versions.sh --bootstrap-server localhost:9092

"Mistral API error"

Check API key is set:

echo $MISTRAL_API_KEY  # Should show your key

Verify key is valid at https://console.mistral.ai/

๐Ÿ“ API Reference

GET /api/games

List available matches

POST /api/replay/start

Start streaming match(es)

{
  "games": [
    {
      "game_id": "match_id",
      "startAtMinute": 0,
      "startAtExtra": 0
    }
  ]
}

GET /api/replay/progress

Get current match status

POST /api/chat

Ask AI about match

{
  "game_id": "match_id",
  "message": "What's the score?"
}

POST /api/replay/reset

Stop all streams

๐Ÿšข Deploy to Railway

Backend

  1. Create new Railway project
  2. Connect your GitHub repo
  3. Set environment variables:
    • MISTRAL_API_KEY = your_key
    • KAFKA_BOOTSTRAP = (Railway provides this)
  4. Deploy!

Frontend

  1. Create new Railway project
  2. Connect your GitHub repo
  3. Set environment variable:
  4. Deploy!

Important: Railway provides managed Kafka - you don't need to run it separately!

๐Ÿ“ฆ Adding Match Data

Create a folder in data/games/ with these files:

meta.json:

{
  "game_id": "team1_team2_2026-01-01",
  "team_home": "Team 1",
  "team_away": "Team 2",
  "competition": "League Name",
  "date": "2026-01-01"
}

events.json:

{
  "response": [
    {
      "time": { "elapsed": 23, "extra": null },
      "team": { "name": "Team 1" },
      "player": { "name": "John Doe" },
      "type": "Goal",
      "detail": "Normal Goal"
    }
  ]
}

comments.json:

[
  {
    "minute": 1,
    "extra": 0,
    "type": "Commentary",
    "text": "Match kicks off!"
  }
]

๐ŸŽ“ Tech Stack

  • Backend: FastAPI, Kafka, Mistral AI
  • Frontend: Next.js, React, TypeScript
  • Streaming: Apache Kafka
  • AI: Mistral (mistral-small-latest)

๐Ÿค Contributing

Contributions welcome! Ideas:

  • Add player statistics
  • Support more data sources
  • Add match highlights
  • Multi-language support
  • Voice input/output
  • Live score notifications

๐Ÿ™ Credits

Built with:


Made for football fans

Questions? Open an issue on GitHub!

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages