NowChessSystems/modules/bot/README_WINDOWS.md

# Windows Users: Start Here!

This guide gets you running the NNUE pipeline on Windows in 5 minutes.

## TL;DR — Quick Start

1. **Install prerequisites:**
   ```cmd
   pip install -r python/requirements.txt
   ```

2. **Download Stockfish** from https://stockfishchess.org/download/ and note the path

3. **Run the pipeline:**
   ```cmd
   set STOCKFISH_PATH=C:\path\to\stockfish.exe
   run_nnue_pipeline.bat
   ```

Done! The pipeline will:
- Generate 500,000 chess positions (~2 min)
- Evaluate with Stockfish (~24-36 hours)
- Train neural network (~2-4 hours)
- Generate Scala code (~1 min)

## Launcher Options

### 1. Command Prompt/PowerShell (Easiest)

```cmd
cd modules\bot

REM Optional: set Stockfish path
set STOCKFISH_PATH=C:\stockfish\stockfish.exe

REM Run the pipeline
run_nnue_pipeline.bat
```

### 2. PowerShell (Colorful Output)

```powershell
cd modules\bot

# Optional: set Stockfish path
$env:STOCKFISH_PATH = "C:\stockfish\stockfish.exe"

# Run the pipeline
.\run_nnue_pipeline.ps1
```

### 3. Git Bash (If You Have It)

```bash
cd modules/bot
export STOCKFISH_PATH=/c/stockfish/stockfish.exe
bash run_nnue_pipeline.sh
```

## Available Scripts

| Script | Location | Usage |
|--------|----------|-------|
| `run_nnue_pipeline.bat` | `modules/bot/` | Windows batch launcher (easiest) |
| `run_nnue_pipeline.ps1` | `modules/bot/` | PowerShell launcher (colorful) |
| `run_nnue_pipeline.sh` | `modules/bot/` | Bash launcher (for Git Bash/WSL) |
| `run_pipeline.bat` | `modules/bot/python/` | Direct batch runner |
| `run_pipeline.sh` | `modules/bot/python/` | Direct bash runner |

## Step-by-Step Setup

### Step 1: Check Python

```cmd
python --version
```

If Python is not installed:
1. Download from https://python.org
2. Run installer
3. **IMPORTANT:** Check "Add Python to PATH"
4. Verify: `python --version`

### Step 2: Install Dependencies

```cmd
cd modules\bot\python
pip install -r requirements.txt
```

This installs:
- `python-chess` — chess engine interface
- `torch` — neural network training
- `tqdm` — progress bars

### Step 3: Get Stockfish

Option A (Recommended): Download from https://stockfishchess.org/download/
- Extract to `C:\stockfish`
- Verify: `C:\stockfish\stockfish.exe --version`

Option B (If using Chocolatey):
```cmd
choco install stockfish
```

### Step 4: Run Pipeline

From `modules\bot\`:

```cmd
set STOCKFISH_PATH=C:\stockfish\stockfish.exe
run_nnue_pipeline.bat
```

## What Each Step Does

### Step 1: Generate Positions (2-3 minutes)
```cmd
python python\generate_positions.py python\positions.txt
```
Creates 500,000 random chess positions saved to `positions.txt`

### Step 2: Evaluate with Stockfish (24-36 hours)
```cmd
set STOCKFISH_PATH=C:\stockfish\stockfish.exe
python python\label_positions.py python\positions.txt python\training_data.jsonl %STOCKFISH_PATH%
```
Evaluates each position at depth 12. This is the slowest step.

### Step 3: Train Network (2-4 hours)
```cmd
python python\train_nnue.py python\training_data.jsonl python\nnue_weights.pt
```
Trains a 768→256→32→1 neural network. Faster on GPU.

### Step 4: Export Weights (1 minute)
```cmd
python python\export_weights.py python\nnue_weights.pt src\main\scala\de\nowchess\bot\bots\nnue\NNUEWeights.scala
```
Exports PyTorch weights as Scala code.

## Monitoring Progress

### Check Step 2 (Stockfish) Progress

The Stockfish evaluation is slow but shows progress. Check the size of `training_data.jsonl`:

```cmd
cd modules\bot\python
dir training_data.jsonl
```

The file grows as positions are evaluated. If it's increasing, the pipeline is working!

### If Pipeline Gets Interrupted

The pipeline saves progress and can resume:

```cmd
REM Just run the pipeline again
run_nnue_pipeline.bat

REM It will skip already-processed positions and continue
```

## Troubleshooting

### "python is not recognized"

Python isn't in PATH. Fix:
1. Reinstall Python from python.org
2. **CHECK** "Add Python to PATH" during installation
3. Restart Command Prompt

Or manually add to PATH:
1. Press `Win+R`, type `systempropertiesadvanced.exe`
2. Click "Environment Variables"
3. Add `C:\Users\YourName\AppData\Local\Programs\Python\Python310` to `Path`

### "stockfish not found"

Set the full path:
```cmd
where stockfish
REM Then use the full path:
set STOCKFISH_PATH=C:\full\path\to\stockfish.exe
```

### "ModuleNotFoundError: No module named 'torch'"

Reinstall PyTorch:
```cmd
pip install torch==2.1.2
```

### "CUDA out of memory"

If using GPU and training fails, reduce batch size:

Edit `modules\bot\python\train_nnue.py`, line ~91:
```python
# Change from:
train_loader = DataLoader(train_dataset, batch_size=4096, shuffle=True)

# To:
train_loader = DataLoader(train_dataset, batch_size=2048, shuffle=True)
```

## After Pipeline Completes

1. New file created: `modules\bot\src\main\scala\de\nowchess\bot\bots\nnue\NNUEWeights.scala`

2. Rebuild the project:
   ```cmd
   cd ..\..\
   compile.bat
   test.bat
   ```

## Expected Output

When running `run_nnue_pipeline.bat`, you should see:

```
=== NNUE Training Pipeline ===

Step 1: Generating 500,000 random positions...
[progress bar]
[OK] Positions generated

Step 2: Labeling positions with Stockfish (depth 12)...
[progress bar - this takes 24+ hours]
[OK] Positions labeled

Step 3: Training NNUE model (20 epochs)...
[progress bar showing epoch progress]
[OK] Model trained

Step 4: Exporting weights to Scala...
[progress bar]
[OK] Weights exported

=== Pipeline Complete ===

Next steps:
1. Navigate to project root: cd ..\..
2. Compile: .\compile.bat
3. Test: .\test.bat
```

## Need More Info?

- **Quick reference:** See `QUICKSTART.md`
- **Detailed setup:** See `WINDOWS_SETUP.md`
- **Complete docs:** See `python/README_NNUE.md`
- **Implementation details:** See `NNUE_IMPLEMENTATION_SUMMARY.md`

## Still Stuck?

Check `WINDOWS_SETUP.md` section "Troubleshooting" for more solutions, or see `python/README_NNUE.md` for common issues.