---
license: agpl-3.0
library_name: mlx
pipeline_tag: text-generation
tags:
- chess
- mlx
- autoregressive
- custom-code
datasets:
- Lichess/chess-games
---

# Human Chess MLX

An autoregressive MLX model trained on complete human chess-game histories. Moves are atomic UCI tokens. Metadata and padding may be input context, but training and validation loss are calculated only for human move targets.

The checkpoint was trained on 27,971,437 chronological January 2025 Lichess games (45.6% of one shuffled epoch). Lichess database exports are CC0.

## Configuration

- Context length: `256` tokens
- Vocabulary size: `2075`
- Transformer layers: `6`
- Embedding width: `384`
- Validation bits per human move: `4.098970`
- Out-of-time test bits per human move: `4.114732`
- Raw exact next-move accuracy: `27.68%`
- Raw top-1 legal-move rate: `87.29%`
- Legal-masked top-1 accuracy: `30.97%`
- Legal-masked top-5 accuracy: `66.82%`

Metrics use fixed 8,192-game chronological holdouts. The test split was evaluated only after training stopped.

## Loading

```python
import mlx.core as mx
from chess_model import ChessTokenizer, load_model

model = load_model(".")
tokenizer = ChessTokenizer.from_pretrained(".")
tokens = mx.array([tokenizer.encode_tokens(["BOS"])])
logits = model(tokens)
```

This is a custom MLX architecture, not a Transformers `AutoModelForCausalLM` checkpoint. The repository includes `chess_model.py` for loading.

Legal-move-masked inference is available through `legal_inference.py`; it reconstructs the board from the full supplied move history before scoring only legal continuations.

Source code: https://github.com/SrulyRosenblat/human-chess-mlx

## License

AGPL-3.0. See `LICENSE`.