deploy.md

Deploy Maia3 Chess API to Hugging Face Spaces

Prerequisites

• Hugging Face account
• Git
• Python 3.10+

1. Login to Hugging Face

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:

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

3. Create the Space

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

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:

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

# 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

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

Switching models

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

# 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