README.md

metadata

title: Chess Vision Backend
emoji: ♟️
colorFrom: indigo
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

♟️ Chess Vision — Backend (API)

FastAPI service for my MSc project: chess board digitization + human-like move prediction. Upload a board image to get its FEN, then ask for the moves a human would likely play (CNN trained on Lichess games) combined with Stockfish.

Models are served as quantized ONNX (the original ~444 MB of PyTorch weights → ~47 MB ONNX), so the image is small and CPU inference is fast.

Endpoints

Method	Path	Description
GET	/health	Liveness probe
POST	/digitize	multipart image → FEN board placement
POST	/predict-move	{ "fen": "...", "top_n": 3 } → CNN / Stockfish / hybrid moves
GET	/docs	Swagger UI

curl -X POST .../predict-move -H 'Content-Type: application/json' \
  -d '{"fen":"rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1","top_n":3}'
# -> {"cnn":["e7e5","g8f6","d7d5"], "stockfish":["e7e5","c7c5","e7e6"], "hybrid":[...]}

How it works

• Digitization (app/digitize.py): fixed crop → Canny → Hough grid (exact MSc pipeline) → 64 square crops → ONNX MobileNetV2 piece classifier → FEN.
• Move prediction (app/predict.py): board → 12×8×8 tensor → a piece-type CNN + six destination-square CNNs → legal human-like moves; black is mirrored; Stockfish adds engine moves and a non-blundering hybrid.

Run locally

python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Stockfish: apt install stockfish (Linux) and set STOCKFISH_PATH, or omit for CNN-only
uvicorn app.main:app --reload --port 7860

Models

models_onnx/ holds the quantized ONNX weights (digitizer + piece + 6 square classifiers). Regenerate from the original .pth with convert_to_onnx.py.

The demo backend runs on a free Hugging Face Space that sleeps after inactivity; the first request after that triggers a short cold start.