deploy.md

# Deploy Maia3 Chess API to Hugging Face Spaces

## Prerequisites

- [Hugging Face account](https://huggingface.co/join)
- [Git](https://git-scm.com/)
- Python 3.10+

## 1. Login to Hugging Face

```bash
pip install huggingface-hub
huggingface-cli login
# Paste your HF token from https://huggingface.co/settings/tokens
```

## 2. Build seed database (optional but recommended)

Fetches 500 real game positions from Lichess for better puzzle quality:

```bash
pip install requests python-chess
python build_seeds.py
# Generates puzzle_seeds.json
```

## 3. Create the Space

```bash
python -c "
from huggingface_hub import HfApi
api = HfApi()
api.create_repo(
    repo_id='YOUR_USERNAME/maia3-chess-api',
    repo_type='space',
    space_sdk='docker',
    exist_ok=True
)
print('Space created')
"
```

## 4. Push code

```bash
git init
git add -A
git commit -m "Initial deploy"
git branch -M main
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/maia3-chess-api
git push space main --force
```

## 5. Wait for build

The Docker build takes ~5 minutes (installs PyTorch CPU, downloads 316MB maia3-79m model on first startup). Check status:

```bash
python -c "
from huggingface_hub import HfApi
api = HfApi()
r = api.get_space_runtime('YOUR_USERNAME/maia3-chess-api')
print('Stage:', r.stage)
"
```

When stage is `RUNNING`, the API is live.

## 6. Test

```bash
# Health
curl https://YOUR_USERNAME-maia3-chess-api.hf.space/api/health

# Analyze a move
curl -X POST https://YOUR_USERNAME-maia3-chess-api.hf.space/api/analyze-move \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-maia3-2026" \
  -d '{"fen":"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1","player_elo":1450,"played_move":"e2e4"}'

# Generate a puzzle
curl -X POST https://YOUR_USERNAME-maia3-chess-api.hf.space/api/generate-puzzle \
  -H "Content-Type: application/json" \
  -d '{"category":"fork","difficulty":"medium"}'

# List categories
curl https://YOUR_USERNAME-maia3-chess-api.hf.space/api/categories
```

## Environment variables

Set in HF Space Settings, no rebuild needed:

| Variable | Default | Description |
|----------|---------|-------------|
| `MAIA3_MODEL` | `79m` | Model size: `5m`, `23m`, or `79m` |
| `MAIA3_API_KEY` | `sk-maia3-2026` | API key for auth |

## Project structure

```
maia3-api/
├── app.py              # FastAPI server (all endpoints)
├── puzzles.py          # Puzzle generation + category detection
├── build_seeds.py      # Lichess position fetcher
├── puzzle_seeds.json   # 500 real game positions (generated)
├── Dockerfile          # Python 3.11 + PyTorch CPU + uvicorn
├── requirements.txt    # Python dependencies
├── README.md           # Hugging Face Space card
└── maia3/              # Maia3 model source (forked from CSSLab/maia3)
    ├── models.py
    ├── utils.py
    ├── dataset.py
    └── model_registry.py
```

## API Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/api/health` | No | Status, model info, uptime |
| `POST` | `/api/bestmove` | Yes | Predict next move (top N) |
| `POST` | `/api/analyze-move` | Yes | Classify + autopsy a played move |
| `POST` | `/api/generate-puzzle` | No | Generate puzzle by category |
| `GET` | `/api/categories` | No | List all 14 puzzle categories |

## Updating

```bash
git add -A && git commit -m "your changes" && git push space main
```

## Switching models

For faster inference on CPU, use the 5M model:

```bash
# Set in Space settings, then restart
MAIA3_MODEL=5m
```

| Model | Size | Accuracy | CPU inference |
|-------|------|----------|---------------|
| `5m` | 20MB | 55.4% | ~300ms |
| `23m` | 92MB | 56.6% | ~800ms |
| `79m` | 316MB | 57.1% | ~150ms* |

*After warm-up, the 79M model is cached in RAM.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `RUNTIME_ERROR` stage | Check Space logs on HF dashboard |
| Model download timeout | Set `MAIA3_MODEL=5m` for faster startup |
| `No puzzle found` | Run `python build_seeds.py` to refresh seed DB |
| All puzzles return same | Cache is stale — restart Space |