README.md

metadata

title: Transformer4Chess
emoji: ♟️
colorFrom: gray
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: Transformer-based chess move predictor served via FastAPI.

Transformer4Chess

A FastAPI inference service for a transformer-based chess policy model. Given a list of UCI moves played from the starting position, it returns the model's predicted next move.

API

POST /inference

Request body:

{
  "moves": ["e2e4", "e7e5", "g1f3"]
}

• moves — list of UCI-encoded moves played from the standard starting position.

Response:

{
  "move": "b8c6"
}

Status codes:

• 200 — inference succeeded.
• 400 — one of the supplied moves is illegal in the resulting position.
• 500 — the model failed to evaluate the position.

Interactive docs

FastAPI auto-generates Swagger UI at /docs and ReDoc at /redoc.

Local development

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --reload

Then:

curl -X POST http://127.0.0.1:8000/inference \
  -H "Content-Type: application/json" \
  -d '{"moves": ["e2e4", "e7e5"]}'

Model

• ChessPolicyModel — causal transformer with per-position CNN board cross-attention.
• Tokenizer — BPE-style tokenizer trained on UCI move strings.
• Weights and tokenizer are loaded once at startup via FastAPI's lifespan hook.