README.md

---
title: Roulette Next-Spin Predictor
emoji: 🎰
colorFrom: red
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: All-models roulette predicto\
---

# Roulette Next-Spin Predictor — all-models edition

FastAPI service that runs **every persisted model** (classical ML + deep
learning + Markov chains) on your past-spins history and returns, for each of
the next N spins and each target (number, color, parity, dozen, column):

- the **consensus** prediction (majority vote across models), and
- **every individual model's** prediction.

Total models in the registry: **~55** across all targets — a mix of LogReg,
HistGradientBoosting, MLP, XGBoost, LightGBM, CatBoost, KNN, GaussianNB,
Ridge, SGD, SVC, LSTM, GRU, Transformer, and Markov orders 1/2/3.

## Endpoints

| Method | Path | Purpose |
|-------|------|---------|
| `GET`  | `/` | Health, route summary, count of models per target |
| `POST` | `/predict` | JSON: `{numbers: [...], steps: N}` |
| `POST` | `/predict/file` | CSV or Excel upload (column `Winner`/`number`) |
| `GET`  | `/docs` | Swagger UI |


## File upload notes

The `/predict/file` endpoint accepts CSV, `.xlsx`, `.xls`, and HTML files that contain a table. The file must contain a column named `Winner`, `winning number`, or `number` (case-insensitive). If not found, the last column is used.

## Example request

```bash
curl -X POST https://<space>.hf.space/predict \
  -H 'Content-Type: application/json' \
  -d '{"numbers":[28,35,36,31,12,17,12,34,6,10,15,14,19,19,22,2,9,11,33,16],"steps":10}'
```

## Example response (one step)

```jsonc
{
  "predictions": [
    {
      "step": 1,
      "number": {
        "consensus": 7,
        "by_model": {
          "logreg": 11, "hist_gradient_boosting": 24, "mlp": 31,
          "xgboost": 11, "lightgbm": 7, "catboost": 23, "knn": 4,
          "gaussian_nb": 7, "ridge": 7, "sgd": 17,
          "lstm": 7, "gru": 33, "transformer": 3,
          "markov_order1": 0, "markov_order2": 12, "markov_order3": 7
        }
      },
      "color":   { "consensus": "black", "by_model": { ... } },
      "parity":  { "consensus": "even",  "by_model": { ... } },
      "dozen":   { "consensus": "third", "by_model": { ... } },
      "column":  { "consensus": "second","by_model": { ... } }
    }
  ],
  "notes": []
}
```

Interpreting disagreement: if all models agree, the consensus is high
confidence. If models are split (e.g. 6 say "black", 5 say "red"), the
consensus is fragile and the true answer is likely close to the wheel's
marginal probability. Use the per-model columns to gauge that.

## Forecast mechanics

- Input must contain past spins with each number in `[0, 36]`.
- We roll the window forward step by step using the **consensus number** each
  step, so longer horizons compound any model disagreement.
- Minimum useful context is 20 past numbers (matching the v2 feature window).
  Shorter inputs are zero-padded from the left.

## Honest disclaimer

Roulette on a fair wheel produces independent draws. The `number` prediction
accuracy (about **4%** on held-out data) is only marginally above the 2.70%
uniform-random baseline. The higher per-target accuracies on color / parity
come mostly from the wheel's structural class imbalance, not from learned
temporal patterns.

**Do not gamble money based on these outputs.** This is a machine-learning
demo.

## Local run

```bash
docker build -t roulette-predictor .
docker run -p 7860:7860 roulette-predictor
open http://localhost:7860/docs
```