🏆 FinalWhistle AI

Universal Tournament Prediction System

Predict league tables, knockout tournament outcomes, and championship probabilities using Machine Learning and Monte Carlo Simulation.

---

✨ Features

Module	Capability
League Predictor	Predicts next season's points, positions & champion probabilities
Knockout Predictor	Predicts individual match outcomes using ELO + ML
Tournament Simulator	10,000+ Monte Carlo simulations for full bracket
Analytics Dashboard	Strength rankings, historical trends, ELO ratings

---

📁 Project Structure

FinalWhistle_AI/
│
├── app.py                    # Streamlit dashboard (main entry point)
├── train_league_model.py     # League regression training pipeline
├── train_knockout_model.py   # Knockout classification training pipeline
├── tournament_simulator.py   # Monte Carlo bracket simulator
├── elo_rating.py             # ELO rating system
├── utils.py                  # Shared utilities, feature engineering, charts
│
├── data/
│   ├── sample_league.csv     # 5 Premier League seasons (2019–2023)
│   └── sample_knockout.csv   # UEFA CL, IPL, World Cup knockout data
│
├── models/                   # Saved trained models (auto-created)
│   ├── league_model.pkl
│   └── knockout_model.pkl
│
├── notebooks/                # Jupyter exploration notebooks
├── requirements.txt
└── README.md

---

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

Note: On Windows, XGBoost installs cleanly via pip. No CMake/MSVC required.

2. Launch the Dashboard

streamlit run app.py

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

3. Train via CLI (optional)

# League model
python train_league_model.py --data data/sample_league.csv

# Knockout model
python train_knockout_model.py --data data/sample_knockout.csv

---

📊 Input Data Format

League CSV

Column	Aliases	Required
season	year	✅
team	team_name, club, squad	✅
played	matches_played, mp	✅
wins	w, won	✅
draws	d, drawn	✅
losses	l, lost	✅
goals_scored	gf, goals_for, runs_scored	✅
goals_conceded	ga, goals_against	✅
goal_difference	gd	✅
points	pts	✅
position	pos, rank	Optional

Knockout CSV

Column	Aliases	Required
team_a	home_team, team1	✅
team_b	away_team, team2	✅
winner	match_winner, result	✅
rating_a	elo_a, strength_a	Optional
rating_b	elo_b, strength_b	Optional
h2h	head_to_head	Optional
form_a	recent_form_a	Optional
form_b	recent_form_b	Optional

⚡ Column aliases are auto-detected. The system normalises common naming variants automatically.

---

🤖 Machine Learning Models

League Predictor (Regression)

• Random Forest Regressor — ensemble tree method
• XGBoost Regressor — gradient boosting
• Ridge Regression — regularised linear baseline

Selection criterion: lowest cross-validated RMSE (5-fold CV)

Knockout Predictor (Binary Classification)

• Random Forest Classifier
• XGBoost Classifier
• Logistic Regression

Selection criterion: highest cross-validated F1 score

---

⚙️ Advanced Features

ELO Rating System

• Dynamic K-factor (scales with margin of victory)
• Home advantage adjustment (+100 ELO points default)
• Snapshot-based: ratings captured before each match to prevent data leakage

Team Strength Index

Weighted composite score:

Strength = 0.40 × Win Rate + 0.30 × Goal Difference (normalised) + 0.30 × PPG

Monte Carlo Simulation

from tournament_simulator import simulate_tournament

result = simulate_tournament(
    teams=["Team A", "Team B", "Team C", "Team D"],
    model=model, scaler=scaler,
    feature_cols=feature_cols,
    elo_system=elo_system,
    n_simulations=10_000,
)
print(result["champion_probs"])

---

🌐 Supported Sports

FinalWhistle AI is sport-agnostic. The same system works for:

• ⚽ Football / Soccer (Premier League, Champions League, World Cup)
• 🏏 Cricket (IPL, T20 World Cup)
• 🎮 Esports (any structured league/tournament format)
• 🏀 Basketball, 🏈 American Football, 🎾 Tennis, 🏒 Ice Hockey

Just provide CSV data in the expected format.

---

🛠 Deployment

Local

streamlit run app.py

Docker

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8501
CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

docker build -t finalwhistle-ai .
docker run -p 8501:8501 finalwhistle-ai

Streamlit Community Cloud

1. Push to a GitHub repository
2. Go to share.streamlit.io
3. Connect your repo → set main file as app.py
4. Click Deploy

---

📦 Dependencies

streamlit==1.32.0
pandas==2.2.1
numpy==1.26.4
scikit-learn==1.4.1
xgboost==2.0.3
matplotlib==3.8.3
plotly==5.20.0
joblib==1.3.2
scipy==1.12.0
seaborn==0.13.2

---

🗂 Sample Datasets

File	Content
data/sample_league.csv	Premier League 2019–2023 (5 seasons, 20 teams each)
data/sample_knockout.csv	UEFA Champions League, IPL, FIFA World Cup knockout rounds

---

📄 License

MIT License — free to use, modify, and distribute.

---

Built with ❤️ · FinalWhistle AI · Universal Tournament Prediction System