sruly/human-chess-mlx

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

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.