README.md

---
license: cc0-1.0
library_name: sklearn
tags:
- football
- soccer
- world-cup
- fifa
- tabular-classification
- gradient-boosting
datasets:
- sergiopesch/wc2026-internationals
pipeline_tag: tabular-classification
---

# WC2026 Match Predictor — `ml-xgboost-v1`

A 3-class (`HOME_WIN` / `DRAW` / `AWAY_WIN`) gradient-boosted classifier predicting FIFA
World Cup 2026 match outcomes from team-strength features.

- **Algorithm:** scikit-learn `HistGradientBoostingClassifier` (gradient-boosted trees)
- **Training data:** [sergiopesch/wc2026-internationals](https://huggingface.co/datasets/sergiopesch/wc2026-internationals) — 499 historical internationals between the 48 finalists
- **5-fold CV accuracy:** 0.545 (vs 0.455 majority-class baseline)
- **Live demo + API:** [sergiopesch/wc2026-match-predictor Space](https://huggingface.co/spaces/sergiopesch/wc2026-match-predictor)

## Features
Engineered to be **symmetric / rating-based** so they generalise monotonically (raw
rank/points levels were deliberately excluded — they let the trees memorise this
friendly-heavy sample and invert on unseen mismatches):

| feature | meaning |
|---|---|
| `rank_diff` = away_rank − home_rank | >0 favours home |
| `pts_diff` = home_pts − away_pts | >0 favours home |
| `home_is_host` | home side is a 2026 host (USA/Mexico/Canada) |

## Usage
```python
import joblib, pandas as pd
from huggingface_hub import hf_hub_download

model = joblib.load(hf_hub_download("sergiopesch/wc2026-match-predictor", "model.joblib"))
X = pd.DataFrame([{"rank_diff": 11 - 5, "pts_diff": 1776 - 1694, "home_is_host": 0}])
print(dict(zip(model.classes_, model.predict_proba(X)[0])))
```

Or call the hosted API:
```bash
curl -X POST https://sergiopesch-wc2026-match-predictor.hf.space/predict \
  -H "Content-Type: application/json" \
  -d '{"home_rank":5,"home_pts":1776,"away_rank":11,"away_pts":1694,"home_is_host":0}'
```

## How it's used
Registered in **Salesforce Einstein Studio** as a Bring-Your-Own-Model, scoring live 2026
fixtures from a Data Cloud feature pipeline — one of four prediction engines in a World Cup
demo (alongside a transparent rules model, an Elo rating system, and a native Einstein
Studio model).

## Limitations
Three coarse features capture broad strength gaps, not form, injuries, or tactics.
Educational/demo use; predictions are illustrative. Licence: **CC0-1.0**.