DEPLOY.md

# Deploying to HuggingFace Spaces

## Option A — web UI (easiest)

1. Create a new Space at https://huggingface.co/new-space
2. Owner: your username (or org). Name: e.g. `roulette-predictor`.
3. SDK: **Docker**. License: MIT. Hardware: CPU basic (2 vCPU / 16 GB RAM is enough).
4. Visibility: Public or Private.
5. Click **Create Space**, then on the Space page choose **Files → Upload files**
   and upload **everything inside `deployment/`**:

   ```
   app.py
   requirements.txt
   Dockerfile
   README.md
   .dockerignore
   ml/
   models/
   ```

   Keep directory structure (drag the `ml/` and `models/` folders as-is).

6. HuggingFace will build the container automatically. First build takes
   3–5 minutes. When it finishes, the Space serves at:
   ```
   https://<username>-roulette-predictor.hf.space
   ```
   Interactive docs live at `/docs`.

## Option B — git push (repeatable)

```bash
# 1. Create the Space (Docker SDK) on the HF website first.
# 2. Clone it locally:
git clone https://huggingface.co/spaces/<username>/roulette-predictor
cd roulette-predictor

# 3. Copy all deployment/ files into this directory:
cp -r /path/to/tej/deployment/* .

# 4. Commit and push:
git add .
git commit -m "initial deploy"
git push                            # may need: git lfs install && git lfs track "models/*"
```

> **LFS note:** `svc__column.v2.joblib` is ~4 MB and `xgboost__dozen.joblib` is
> ~3 MB — both fit under the 10 MB normal-git-push limit on HF. If you ever
> add a model over 10 MB, run `git lfs install && git lfs track "models/*.joblib"`
> first.

## Sanity checks after deploy

```bash
export SPACE=https://<username>-roulette-predictor.hf.space

# Health
curl -s "$SPACE/" | jq

# Predict via JSON
curl -s -X POST "$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}' \
  | jq

# Predict via CSV upload (test.csv with a "Winner" or "number" column)
curl -s -X POST "$SPACE/predict/file?steps=10" -F "file=@test.csv" | jq
```

## Local test before deploying

```bash
cd deployment
docker build -t roulette-predictor .
docker run --rm -p 7860:7860 roulette-predictor
# then open http://localhost:7860/docs
```

## What's inside

| File | Purpose |
|------|---------|
| `app.py` | FastAPI service with `/predict`, `/predict/file`, `/models`, `/` |
| `Dockerfile` | Python 3.11-slim, non-root user UID 1000, port 7860 (HF convention) |
| `requirements.txt` | fastapi, uvicorn, pandas, openpyxl, xlrd, lxml, numpy, scikit-learn, xgboost, joblib |
| `README.md` | HF Space metadata frontmatter + user docs |
| `ml/features.py` | v1 hand-crafted features (window=10, 25 dims) |
| `ml/features_v2.py` | v2 features (window=20, 51 dims, run-length, autocorrelation, wheel-neighbor) |
| `models/*.joblib` | Five winning model artefacts (number, color, parity, dozen, column) |

Total image size is ~1.3 GB (mostly sklearn + xgboost + numpy wheels).