---
title: Chess Assist
emoji: "♟️"
colorFrom: gray
colorTo: green
sdk: gradio
sdk_version: "4.44.1"
app_file: app.py
pinned: false
---


# Chess Assist (v3): Image → FEN → Best Move

This bundle is hardened for Hugging Face Spaces:
- **apt.txt** installs system `stockfish`.
- **requirements.txt** pins CPU Torch wheels for Ultralytics.
- Better error messages in UI to surface what's failing (model download, engine path, etc.).

## Deploy Steps
1. Create a new Space (Gradio, Python).
2. Upload: `app.py`, `requirements.txt`, `apt.txt`, `runtime.txt`, `README.md`.
3. In Space **Settings → Space hardware**, choose **CPU Basic** (enough for this demo).
4. In Space **Settings → Networking**, ensure **"Allow internet access"** is **ON** so the YOLO weights can download.
5. Commit and wait for build. First run will download the YOLO weights.

## Common Issues
- **Ultralytics / Torch errors**: We pinned Torch CPU wheels. If still failing, change runtime to Python 3.10 (provided here).
- **Stockfish not found**: `apt.txt` should install it. If still missing, check build logs and confirm `/usr/bin/stockfish` exists.
- **No opening name**: Many midgame positions have no named opening; this is normal.
- **Board not detected**: Try a straighter photo with the board filling the frame; glare can confuse corner detection.

## Local Run
```
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python app.py
```

## Notes
- Labels assumed like `wpawn`, `bqueen`, etc. Adjust `LABEL_TO_FEN` if your detector uses different names.
- Evaluation score is kept internal per your specs; only a simple explanation is shown.