Create README.md

README.md

@@ -0,0 +1,101 @@
+---
+language: en
+license: mit
+tags:
+- sports
+- football
+- soccer
+- premier-league
+- tabular
+- poisson
+- expected-goals
+- statsmodels
+library_name: statsmodels
+pipeline_tag: summarization
+---
+
+# ⚽ EPL-Pulse_v1  
+**English Premier League Match Outcome & Goals Predictor**
+
+`EPL-Pulse_v1` is a **leakage-safe football match prediction model** trained on historical English Premier League data (1993/94 → 2024/25 mid-season).
+
+The model estimates:
+- **Expected goals (xG)** for home and away teams
+- **Outcome probabilities**:
+  - Home Win
+  - Draw
+  - Away Win
+- **Scoreline probability distribution** (e.g., 1–0, 2–1, 0–0)
+
+This repository contains the **production-ready model artifacts** used by the public Hugging Face Space.
+
+---
+
+## 🔍 What’s inside this repository
+
+### Model artifacts
+- `home_goals_model.pkl`  
+  Poisson regression model for **home team goals**
+- `away_goals_model.pkl`  
+  Poisson regression model for **away team goals**
+- `feature_list.pkl`  
+  Ordered list of features used during training
+- `team_state.pkl`  
+  Latest per-team snapshot used for inference:
+  - Elo rating
+  - Rolling goals-for / goals-against
+  - Timestamp of last update
+
+> `team_state.pkl` enables **fast production inference** without recomputing rolling features at request time.
+
+---
+
+## 🧠 Modeling approach
+
+### Model type
+- **Poisson Generalized Linear Models (GLM)**  
+  (one model for home goals, one for away goals)
+
+### Why Poisson?
+- Goals are discrete counts
+- Well-established baseline in football analytics
+- Interpretable and deployable
+- Produces full scoreline probability distributions
+
+### Outcome probabilities
+Win / Draw / Loss probabilities are derived from the joint scoreline distribution:
+\[
+P(H=i, A=j) = \text{Poisson}(i|\lambda_H) \times \text{Poisson}(j|\lambda_A)
+\]
+
+---
+
+## 📊 Features used (leakage-safe)
+
+All features are **computed strictly from matches played before kickoff**.
+
+
+
+This design prevents **data leakage** and supports reliable backtesting.
+
+---
+
+## 🚀 Quickstart (Python)
+
+### 1️⃣ Install dependencies
+
+
+from huggingface_hub import hf_hub_download
+import joblib
+
+REPO_ID = "YOUR_USERNAME/EPL-Pulse_v1"
+
+home_path = hf_hub_download(REPO_ID, "home_goals_model.pkl")
+away_path = hf_hub_download(REPO_ID, "away_goals_model.pkl")
+feat_path = hf_hub_download(REPO_ID, "feature_list.pkl")
+state_path = hf_hub_download(REPO_ID, "team_state.pkl")
+
+home_model = joblib.load(home_path)
+away_model = joblib.load(away_path)
+feature_list = joblib.load(feat_path)
+team_state = joblib.load(state_path)