Upload README.md with huggingface_hub

README.md

@@ -7,90 +7,96 @@ tags:
   - transformer
   - from-scratch
   - small-model
+  - mcts
 ---
 
 # 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.
+A chess engine trained from scratch on a single laptop GPU (RTX 5060). Uses a 25.9M parameter transformer with Monte Carlo Tree Search (MCTS) for move selection.
 
-## How It Works
+## What's Inside
 
-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.
+- **25.9M param transformer** trained on 200K+ positions with Stockfish evaluations
+- **Policy network**: predicts best move from board state (4352-class output covering all possible moves)
+- **Value network**: evaluates positions in centipawns (trained on Stockfish depth-10 evaluations)
+- **MCTS search**: looks ahead multiple moves using the neural network for evaluation
+- **Custom chess tokenizer**: no external tokenizer needed — pure chess-aware encoding
+- **Tkinter GUI**: interactive chess board with click-to-move interface
 
-- **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
+## Performance
 
 | 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 |
+| Parameters | 25.9M |
+| Training data | 200K Stockfish-evaluated positions + 143K puzzles |
+| Training time | ~2 hours on RTX 5060 |
+| Policy loss | 8.47 → 2.50 (4352-class prediction) |
+| Speed (greedy) | ~19 moves/sec |
+| Speed (MCTS 200 sims) | ~2 moves/sec |
+| Estimated ELO | ~800-1000 (greedy), ~1200-1500 (MCTS) |
+| Opens with | e2e4, Nf3, Ruy Lopez — real chess openings |
 
 ## Quick Start
 
+### Greedy (fast, weaker)
 ```python
+from train_v3 import ParallaxChessV3
 import chess
-from vela_chess_engine import VelaChessV2
 
-engine = VelaChessV2("model.safetensors", "chess_encoding.py")
+model = ParallaxChessV3.load("model.pt")
 board = chess.Board()
-move = engine.choose_move(board)
-print(move.uci())  # e.g. "g1f3"
+move = model.predict_move(board)
+print(move.uci())  # e.g. "e2e4"
 ```
 
-## Interactive Play
+### MCTS Search (slower, stronger)
+```python
+from mcts_engine import ParallaxChessMCTS
 
-```bash
-python play.py
+engine = ParallaxChessMCTS("model.safetensors")
+board = chess.Board()
+move = engine.choose_move(board, n_simulations=200)
+print(move.uci())
 ```
 
-Then type moves in UCI format (e.g. `e2e4`).
+### Interactive GUI
+```bash
+python play_gui.py
+```
+Click pieces to select, click again to move. Legal moves shown as dots.
 
-## Architecture Details
+## Architecture
 
 ```
-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,
+ParallaxChessV3(
+  board_encoder: Embedding(402, 512),
+  backbone: SmallLM(8 layers, 512 dim, 8 heads, GQA 4:2),
+  policy_head: Linear(512, 4352),  # from_sq * 64 + to_sq
+  value_head: Linear(512, 256) → Linear(256, 1) → Tanh
 )
 ```
 
-## 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.
+## Training Details
 
-## 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
+1. **Data**: 200K positions from Stockfish self-play (depth 10) + 143K Lichess puzzles
+2. **Policy target**: Stockfish best move as move index (from_square × 64 + to_square)
+3. **Value target**: Stockfish centipawn evaluation (scaled to [-1, 1])
+4. **Optimizer**: AdamW (lr=1e-3, weight_decay=0.01, cosine schedule)
+5. **Augmentation**: 50% horizontal board flip
 
 ## 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
+- A 25.9M param model can learn real chess openings from scratch
+- Policy + value heads can be trained simultaneously on a single GPU
+- MCTS search can boost a weak neural player to competitive play
+- Custom chess encoding (no tokenizer dependency) works well
 
-## Hardware
+## Limitations
 
-- **Training**: Single RTX 5060 Laptop GPU (8GB VRAM)
-- **Inference**: CPU-only, ~6 moves/sec
+- ~1000-1500 ELO (intermediate club player)
+- Weak in endgames (training data biased toward openings/middlegame)
+- No opening book — learns openings from training data only
+- MCTS adds ~10x latency per move
 
 ## License