feat: refactor AlphaBetaSearch and ClassicalBot for improved evaluation and organization

modules/bot/QUICKSTART.md

@@ -0,0 +1,144 @@
+# NNUE Pipeline Quickstart
+
+## Prerequisites
+
+### Install Python Dependencies
+
+```bash
+cd modules/bot/python
+pip install -r requirements.txt
+```
+
+### Install Stockfish
+
+**macOS:**
+```bash
+brew install stockfish
+```
+
+**Linux (Debian/Ubuntu):**
+```bash
+apt-get install stockfish
+```
+
+**Windows:**
+- Download from https://stockfishchess.org
+- Or use Chocolatey: `choco install stockfish`
+- Add to PATH or set `STOCKFISH_PATH` environment variable
+
+## Run the Full Pipeline
+
+### Easiest: Launcher Scripts (Recommended)
+
+From `modules/bot/` directory:
+
+**Windows (Command Prompt or PowerShell):**
+```cmd
+run_nnue_pipeline.bat
+```
+
+**Linux/macOS/Windows (Git Bash/WSL):**
+```bash
+chmod +x run_nnue_pipeline.sh
+./run_nnue_pipeline.sh
+```
+
+### Alternative: Direct Scripts
+
+From `modules/bot/python/` directory:
+
+**Windows (Command Prompt):**
+```cmd
+cd python
+set STOCKFISH_PATH=C:\path\to\stockfish.exe
+run_pipeline.bat
+```
+
+**Bash (Linux, macOS, Git Bash, WSL):**
+```bash
+cd python
+export STOCKFISH_PATH=/path/to/stockfish
+chmod +x run_pipeline.sh
+./run_pipeline.sh
+```
+
+**PowerShell (Windows):**
+```powershell
+cd python
+$env:STOCKFISH_PATH = "C:\path\to\stockfish.exe"
+bash ./run_pipeline.sh
+```
+
+The pipeline will:
+1. Generate 500,000 random positions (~2-3 minutes)
+2. Evaluate with Stockfish depth 12 (~24-36 hours on typical machine)
+3. Train NNUE network (20 epochs, ~2-4 hours on GPU)
+4. Export weights to Scala (~1 minute)
+
+## For Quick Testing
+
+Reduce the position count to test the pipeline quickly:
+
+```python
+# Edit generate_positions.py, change:
+# for game_num in range(500000):  # Change 500000 to 1000
+# for game_num in range(1000):
+```
+
+Then run:
+```bash
+./run_pipeline.sh
+```
+
+This will complete in ~30-60 minutes total, allowing you to test the full pipeline.
+
+## After Pipeline Completes
+
+```bash
+# Navigate to project root
+cd ../..
+
+# Recompile (loads the new NNUEWeights.scala)
+./compile
+
+# Run tests
+./test
+```
+
+## Architecture Quick Reference
+
+- **Input:** Board position (768 binary features)
+- **Network:** Linear(768→256) → ReLU → Linear(256→32) → ReLU → Linear(32→1)
+- **Output:** Centipawn evaluation (-20000 to +20000)
+- **Training:** Stockfish evals → sigmoid(eval/400) targets → MSE loss
+
+## Troubleshooting
+
+**"Module not found: chess"**
+```bash
+pip install python-chess==1.10.0
+```
+
+**"CUDA out of memory"**
+- Edit `train_nnue.py` line 91: change `batch_size=4096` to `batch_size=2048`
+
+**"Stockfish not found"**
+```bash
+export STOCKFISH_PATH=$(which stockfish)
+# or provide full path
+export STOCKFISH_PATH=/usr/bin/stockfish
+```
+
+**"ModuleNotFoundError: No module named 'torch'"**
+```bash
+pip install torch==2.1.2
+```
+
+## Files Generated
+
+- `positions.txt` — 500,000 FENs
+- `training_data.jsonl` — FEN + Stockfish evaluation pairs
+- `nnue_weights.pt` — PyTorch model
+- `../src/main/scala/de/nowchess/bot/bots/nnue/NNUEWeights.scala` — Scala code
+
+See `README_NNUE.md` for detailed documentation.