| --- |
| language: en |
| license: cc-by-nc-4.0 |
| tags: |
| - chess |
| - chess-engine |
| - transformer |
| - from-scratch |
| - small-model |
| --- |
| |
| # Parallax-Chess-Preview |
|
|
| A chess move prediction engine trained from scratch on a single laptop GPU. Predicts the best move given a board position using a custom chess tokenizer and a 4.4M parameter transformer. |
|
|
| ## How It Works |
|
|
| Unlike traditional chess engines (Stockfish, Leela), Parallax-Chess-Preview uses **pure neural network evaluation** — no hand-crafted rules, no opening books, no endgame tables. It learned chess purely from 50,000 Lichess puzzles. |
|
|
| - **Custom chess tokenizer**: Board positions encoded as 66 tokens (64 squares + side-to-move + separator), moves encoded as (from-square, to-square) pairs. Total vocab: 402 tokens. |
| - **Architecture**: Transformer decoder (6 layers, 256 dim, 4 heads, GQA 4:2) |
| - **Training**: 100K steps on 50K Lichess puzzles, final loss 0.088 |
|
|
| ## Benchmarks |
|
|
| | Metric | Value | |
| |--------|-------| |
| | Legal move rate | 100% | |
| | Speed | 6 moves/sec (CPU) | |
| | Estimated ELO | ~700 | |
| | vs Stockfish (max) | 0-1 (W), 1-0 (B, blunder) | |
| | Training data | 50K Lichess puzzles | |
| | Training time | ~1 hour on RTX 5060 | |
|
|
| ## Quick Start |
|
|
| ```python |
| import chess |
| from vela_chess_engine import VelaChessV2 |
| |
| engine = VelaChessV2("model.safetensors", "chess_encoding.py") |
| board = chess.Board() |
| move = engine.choose_move(board) |
| print(move.uci()) # e.g. "g1f3" |
| ``` |
|
|
| ## Interactive Play |
|
|
| ```bash |
| python play.py |
| ``` |
|
|
| Then type moves in UCI format (e.g. `e2e4`). |
|
|
| ## Architecture Details |
|
|
| ``` |
| SmallLMConfig( |
| vocab_size=402, # Custom chess vocabulary |
| d_model=256, # Embedding dimension |
| n_heads=4, # Attention heads |
| n_kv_heads=2, # GQA grouped query attention |
| n_layers=6, # Transformer layers |
| intermediate_size=1024, |
| max_seq_len=128, |
| norm_type='rms', |
| rope_theta=10000.0, |
| ) |
| ``` |
|
|
| ## Training Data |
|
|
| 50,000 chess puzzles from the [Lichess puzzle database](https://database.lichess.org/#puzzles), filtered to ratings 800-2500 with 2-6 move solutions. |
|
|
| ## Limitations |
|
|
| - **~700 ELO** — plays at beginner level |
| - No search tree — purely neural move prediction |
| - Trained on puzzle data only (not full games) |
| - Cannot play from arbitrary positions outside training distribution |
|
|
| ## What This Proves |
|
|
| Even a tiny 4.4M parameter model can: |
| - Learn legal chess move patterns from data alone |
| - Achieve 100% legal move rate |
| - Make occasionally reasonable opening choices (Nf3, Nc3) |
| - Be trained from scratch in 1 hour on a laptop GPU |
|
|
| ## Hardware |
|
|
| - **Training**: Single RTX 5060 Laptop GPU (8GB VRAM) |
| - **Inference**: CPU-only, ~6 moves/sec |
|
|
| ## License |
|
|
| CC BY-NC 4.0 (weights), AGPL-3.0 (code) |
|
|
