Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,97 @@
+---
+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)