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