KickoffAI - Premier League Predictions

A production-ready FastAPI application that predicts Premier League match outcomes using Elo ratings and machine learning.

Features

• Real-time predictions for upcoming Premier League matches
• Elo rating system tracking team strength over time
• Machine learning model (multinomial logistic regression) for probability predictions
• Beautiful web dashboard with dark mode support
• REST API for programmatic access
• PostgreSQL for persistent data storage
• One-click deployment to Render

Quick Start

Prerequisites

• Python 3.11+
• PostgreSQL database
• Football-data.org API token (free tier available)

Local Development

1. Clone the repository

   git clone https://github.com/yourusername/kickoffai.git
   cd kickoffai

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment

   cp .env.example .env
   # Edit .env with your settings

5. Run database migrations

   alembic upgrade head

6. Start the server

   uvicorn app.main:app --reload

7. Open the dashboard Navigate to http://localhost:8000

8. Sync data and train model

   • Click "Sync Data" to fetch matches from football-data.org
   • Click "Retrain Model" to train the prediction model

API Endpoints

Health Check

GET /health

Returns server status and version.

Response:

{
  "status": "ok",
  "time": "2025-01-26T12:00:00.000Z",
  "version": "1.0.0"
}

Sync Data

POST /api/sync

Fetches latest Premier League data from football-data.org.

Response:

{
  "status": "completed",
  "teams_synced": 20,
  "matches": {
    "matches_upserted": 380,
    "new_matches": 10,
    "updated_matches": 370
  }
}

Train Model

POST /api/train

Trains the prediction model on historical data.

Response:

{
  "status": "completed",
  "model_id": 1,
  "dataset_size": 760,
  "metrics": {
    "logloss": 0.9823,
    "brier": 0.2156,
    "train_accuracy": 0.52,
    "test_accuracy": 0.48
  }
}

Get Predictions

GET /api/predictions?days_ahead=14

Returns predictions for upcoming matches.

Parameters:

• days_ahead (optional): Number of days to look ahead (1-90, default: 14)

Response:

{
  "predictions": [
    {
      "match_id": 12345,
      "home_team": {
        "id": 57,
        "name": "Arsenal",
        "short_name": "ARS"
      },
      "away_team": {
        "id": 65,
        "name": "Manchester City",
        "short_name": "MCI"
      },
      "utc_date": "2025-01-28T15:00:00Z",
      "probabilities": {
        "home": 0.32,
        "draw": 0.28,
        "away": 0.40
      },
      "explanation": "Man City rated 85 Elo higher; Arsenal in better recent form",
      "confidence": "medium"
    }
  ],
  "count": 10,
  "model_info": {
    "trained_at": "2025-01-26T10:00:00Z",
    "logloss": 0.9823
  }
}

Match Details

GET /api/matches/{match_id}

Returns detailed information about a specific match.

Teams

GET /api/teams

Returns all Premier League teams with their current Elo ratings.

Model Info

GET /api/model

Returns information about the current prediction model.

Deployment to Render

Using render.yaml (Recommended)

1. Fork/clone this repository to your GitHub account

2. Create a Render account at render.com

3. Connect your repository

   • Go to Render Dashboard → New → Blueprint
   • Select your repository
   • Render will detect render.yaml automatically

4. Set environment variables

   • FOOTBALL_DATA_TOKEN: Your football-data.org API token

5. Deploy

   • Click "Apply" to create the services
   • Wait for deployment to complete

6. Initialize the application

   # After deployment, sync data and train model via API
   curl -X POST https://your-app.onrender.com/api/sync
   curl -X POST https://your-app.onrender.com/api/train

Manual Deployment

1. Create a PostgreSQL database on Render
2. Create a Web Service with:
   • Build Command: pip install -r requirements.txt && alembic upgrade head
   • Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
3. Set environment variables:
   • DATABASE_URL: From your Render PostgreSQL
   • FOOTBALL_DATA_TOKEN: Your API token
   • APP_ENV: production

Project Structure

kickoffai/
├── app/
│   ├── __init__.py          # App version
│   ├── main.py               # FastAPI application
│   ├── api.py                # API routes
│   ├── db.py                 # Database configuration
│   ├── models.py             # SQLAlchemy models
│   ├── crud.py               # Database operations
│   ├── services/
│   │   ├── football_data.py  # football-data.org client
│   │   ├── elo.py            # Elo rating system
│   │   ├── features.py       # Feature engineering
│   │   ├── train.py          # ML model training
│   │   └── predict.py        # Prediction service
│   ├── templates/
│   │   ├── base.html         # Base template
│   │   └── index.html        # Dashboard template
│   └── static/
│       ├── styles.css        # CSS styles
│       └── app.js            # Frontend JavaScript
├── alembic/
│   ├── env.py                # Alembic configuration
│   └── versions/             # Database migrations
├── tests/
│   ├── test_elo.py           # Elo system tests
│   ├── test_features.py      # Feature tests
│   └── test_predict.py       # Prediction tests
├── alembic.ini               # Alembic config
├── requirements.txt          # Python dependencies
├── render.yaml               # Render deployment config
├── .env.example              # Environment template
└── README.md                 # This file

Data Model

Teams

Column	Type	Description
id	Integer	football-data.org team ID
name	String	Full team name
short_name	String	3-letter abbreviation
crest_url	String	Team crest image URL

Matches

Column	Type	Description
id	Integer	football-data.org match ID
utc_date	DateTime	Match kickoff time (UTC)
status	String	SCHEDULED, FINISHED, etc.
home_team_id	Integer	Home team foreign key
away_team_id	Integer	Away team foreign key
home_score	Integer	Home team goals (nullable)
away_score	Integer	Away team goals (nullable)
season	String	Season year (e.g., "2024")
matchday	Integer	Matchday number

Elo Ratings

Column	Type	Description
id	Integer	Primary key
team_id	Integer	Team foreign key
as_of_date	DateTime	Rating timestamp
elo	Float	Elo rating value

Model Meta

Column	Type	Description
id	Integer	Primary key
trained_at	DateTime	Training timestamp
dataset_size	Integer	Number of training samples
logloss	Float	Log loss metric
brier	Float	Brier score metric
model_blob	Binary	Serialized model

Prediction Model

Features

• Elo ratings: Home and away team Elo, difference
• Recent form: Last 5 matches points per game
• Goals: Goals for/against per match
• Home/Away specific form: Performance at home/away venues

Model

• Multinomial Logistic Regression
• Outputs probabilities for Home Win, Draw, Away Win
• Probabilities are normalized to sum to 1

Evaluation Metrics

• Log Loss: Measures probability calibration
• Brier Score: Average squared error of predictions
• Accuracy: Percentage of correct predictions

Running Tests

pytest tests/ -v

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• football-data.org for the Premier League data API
• Render for hosting