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)

# 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

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

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).