World Cup 2026 Predictor

A lightweight forecasting project for the 2026 FIFA World Cup. It downloads public football data, builds a match-level feature set, trains a model, and runs a Monte Carlo tournament simulation for the 48 teams.

What this repo does

• refreshes match results and Elo ratings from public sources
• builds a historical training matrix for international matches
• trains a model for match outcomes and score expectations
• simulates the tournament to estimate team-level probabilities
• exposes predictions through a CLI and a lightweight Flask API

Repository layout

wc2026_predictor/
├── api.py                  # Flask API for match predictions
├── auto_update.py          # refreshes historical results and Elo data
├── config.py               # paths, team lists, fixtures, and constants
├── create_notebooks.py     # notebook scaffolding helper
├── index.html              # lightweight front-end preview
├── predict.py              # CLI for team/date predictions
├── requirements.txt        # Python dependencies
├── retrain_and_simulate.py # rebuilds features, trains, and runs Monte Carlo
├── README.md               # project overview
├── data/                   # created at runtime for raw/processed/output data
├── catboost_info/          # CatBoost training artifacts
└── .gitignore              # repo ignores

Quick start

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 retrain_and_simulate.py
python3 predict.py "United States" "Paraguay"

Scope and limits

• This is an exploratory forecasting project, not a production-grade betting or analytics platform.
• The current workflow is intentionally simple and readable rather than heavily instrumented.
• Public data availability, scraping behavior, and model assumptions can change over time.

2026 World Cup context

• Tournament window: 11 June to 19 July 2026
• Teams: 48 across 12 groups
• Hosts: United States, Canada, and Mexico
• Match and venue metadata are defined in config.py

Data and modeling

The project relies on public international results, Elo history, fixture metadata, and team-state features to estimate match probabilities. It also includes a Monte Carlo tournament simulation and a small API surface for local experimentation.

This README is intentionally smaller than the earlier version because the project is a focused forecasting prototype rather than a fully audited multi-source data platform.