Create README.md

README.md

@@ -0,0 +1,87 @@
+---
+license: mit
+tags:
+- xgboost
+- lightgbm
+- sports-prediction
+- formula1
+- tabular
+- classification
+- ensemble
+- optuna
+language:
+- en
+---
+
+# Telemetry Chaos — F1 Race Prediction Model
+
+XGBoost + LightGBM ensemble predicting Formula 1 race winners from 76 seasons of historical data. Tuned with Optuna hyperparameter optimization across 200 trials. Auto-retrains weekly during the active season.
+
+**Live demo:** [telemetrychaos.space](https://telemetrychaos.space)
+
+## Performance
+
+| Metric | Score |
+|---|---|
+| Top-1 Accuracy | 53% |
+| Top-3 Accuracy | 85% |
+| Top-5 Accuracy | 96% |
+
+Evaluated on 2024–2025 seasons with time-series split to prevent data leakage.
+
+## Features (21 per driver per race)
+
+- **Form:** Rolling average points, recent podiums, win streak
+- **Pace:** Practice session lap time delta vs. teammate and field
+- **Constructor:** Team rolling performance, reliability score
+- **Track history:** Driver-specific circuit win rate, podium rate
+- **Tyre:** Degradation profile, pit stop speed, strategy tendency
+- **Conditions:** Weather forecast, safety car probability
+- **Grid:** Starting position, qualifying gap to pole
+
+## Architecture
+
+```
+XGBoost (GPU) + LightGBM
+Optuna HPO: 200 trials, TPE sampler
+Time-series split: train on seasons N-5 to N-1, evaluate on N
+Final output: softmax win probabilities per driver
+```
+
+## Dataset
+
+- **Coverage:** 1950–2025, 76 seasons
+- **Records:** 1,322,914 race records
+- **Telemetry laps:** 470K+
+- **Sources:** FastF1, Jolpica-F1, f1db, Kaggle
+
+## Usage
+
+```python
+import joblib
+
+model = joblib.load("f1_ensemble.joblib")
+# Input: 21-feature vector per driver
+# Output: win probability (0-1)
+probs = model.predict_proba(X)
+```
+
+## Auto-Update Pipeline
+
+During the active F1 season the model retrains weekly:
+1. Pull latest race results and telemetry via FastF1
+2. Engineer features for upcoming race grid
+3. Retrain ensemble with updated data
+4. Publish updated predictions to telemetrychaos.space
+
+## Citation
+
+```bibtex
+@misc{rubin2026telemetrychaos,
+  author = {Rubin, Theodore},
+  title = {Telemetry Chaos: F1 Race Prediction with XGBoost/LightGBM Ensemble},
+  year = {2026},
+  publisher = {HuggingFace},
+  url = {https://huggingface.co/datamatters24/f1-race-predictor-model}
+}
+```