# 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.