README.md

---
title: DramaMeter 2026
emoji: ⚽
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 6.20.0
python_version: "3.12"
app_file: app.py
pinned: false
license: mit
short_description: Live, explainable World Cup drama analytics
---

# DramaMeter 2026

A live football analytics product for the 2026 World Cup. Pick a current, upcoming or recent fixture and get a pre-match forecast, a live drama index, the match events behind it and a post-ready take.

## What makes it real

- Loads the current 2026 World Cup schedule, scores and match statistics from ESPN Match Center's public JSON feed.
- Retrains a gradient-boosted tree ensemble on every completed tournament match at startup.
- Builds rolling pre-match features without using future match statistics.
- Reports held-out MAE and improvement over a naive mean baseline instead of hiding model quality.
- Replaces the forecast with an observed live index once a match starts.
- Shows fetch time, data source, model inputs and feature importance in the UI.

The observed target is an editorial proxy derived from fouls, cards, goals, score closeness, late goals, stage and extra time. It is not a claim about social-media sentiment and it is not betting advice.

## Run locally

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python app.py
```

Run tests with `python -m pytest`.

## Architecture

- `feed.py` — live data client, 30–45 second cache and fixture selection
- `drama.py` — rolling features, observed target and gradient-boosted model training
- `app.py` — responsive Gradio product UI and data-driven match report
- `tests/` — deterministic model and feed-contract tests

Data availability depends on ESPN's public Match Center endpoints. Cached data is used if a refresh fails after at least one successful request.