README.md

---
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:**

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

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

**Response:**

```json
{
  "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

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

Then:

```bash
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.