# Atlas Trainer

Periodically trains a new Atlas model from accumulated worker trajectories
and uploads it as the new global model. Workers automatically pick up the
new model on their next heartbeat.

**Recommended host:** a Windows gaming rig with an NVIDIA GPU. CPU works too
(just slower). Mac/Linux supported via the underlying `train.py` directly.

---

## Install (Windows + NVIDIA GPU)

1. **Install Python 3.11+** from https://python.org if you don't have it.
   During the installer, check "Add Python to PATH".

2. **Download the trainer bundle:**

   In PowerShell:
   ```powershell
   mkdir C:\Atlas-Trainer; cd C:\Atlas-Trainer
   Invoke-WebRequest https://downloads.landover.io/atlas-trainer-win-x64.zip -OutFile trainer.zip
   Expand-Archive trainer.zip -Force
   ```

3. **Configure:**

   Copy `atlas-trainer.example.json` to `atlas-trainer.json` and fill in:
   - `adminKey` — ask Jay for the admin key (separate from the worker key).
   - `r2*` fields — R2 credentials (also from Jay).

4. **First-run setup** (installs Python venv + PyTorch CUDA):
   ```powershell
   .\atlas-train.ps1 -Setup
   ```

   This downloads ~2 GB of PyTorch + CUDA libraries. Takes ~5 minutes.

5. **Train + upload:**
   ```powershell
   .\atlas-train.ps1
   ```

   Steps:
   - Downloads recent trajectories from R2 → Parquet (~30s for 50K games)
   - Trains a neural net on GPU (~1-5 min depending on dataset size)
   - Uploads the new ONNX model to the API
   - Workers worldwide will pick it up within their heartbeat window (~5 min)

   You should see the model version on https://atlas.landover.io flip to your new version shortly after.

---

## Schedule it on Windows Task Scheduler

To train automatically every few hours:

```powershell
$action = New-ScheduledTaskAction `
    -Execute 'powershell.exe' `
    -Argument '-NoProfile -ExecutionPolicy Bypass -File C:\Atlas-Trainer\atlas-train.ps1' `
    -WorkingDirectory 'C:\Atlas-Trainer'
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(5) -RepetitionInterval (New-TimeSpan -Hours 4)
Register-ScheduledTask -TaskName 'Atlas-Trainer' -Action $action -Trigger $trigger -RunLevel Highest
```

Adjust `-RepetitionInterval` to taste (every 1h, every 6h, etc.).

---

## Run on Mac / Linux

Use `atlas-ml/train.py` directly from the repo:

```sh
# One-time
git clone https://github.com/VexHex-Games/Atlas.git
cd Atlas
python3 -m venv atlas-ml/.venv
atlas-ml/.venv/bin/pip install torch onnx onnxscript pyarrow numpy

# Each run
dotnet run --project src/Atlas.Cli -c Release -- replay-r2 trajectories/ data.parquet --max-games 50000
ATLAS_ADMIN_KEY=... atlas-ml/.venv/bin/python atlas-ml/train.py \
    --data data.parquet --gametype 2p --out v3.onnx \
    --epochs 20 --hidden 128 --arch deep \
    --upload-to-api https://atlas-engine.landover.io \
    --upload-version v3-$(date -u +%Y%m%dT%H%M%SZ)
```

---

## What's in the bundle

| File | Purpose |
|------|---------|
| `atlas-train.ps1` | Top-level PowerShell script |
| `atlas-cli.exe` | C# binary for the `replay-r2` step |
| `atlas-ml\train.py` | Python trainer (consumes Parquet, exports ONNX) |
| `atlas-trainer.example.json` | Sample config |

## Config fields

| Field | Required | Default | Meaning |
|-------|----------|---------|---------|
| `apiUrl` | yes | — | The Atlas API endpoint |
| `adminKey` | yes | — | Admin bearer token (lets you upload models) |
| `r2Endpoint` | yes | — | R2 S3 endpoint |
| `r2AccessKeyId` | yes | — | R2 credentials |
| `r2SecretAccessKey` | yes | — | R2 credentials |
| `r2Bucket` | no | `atlas-trajectories` | Bucket name |
| `maxGames` | no | `50000` | How many games to replay each run |
| `epochs` | no | `20` | Training epochs |
| `hidden` | no | `128` | Hidden layer width |
| `arch` | no | `deep` | `small` or `deep` |

## Asking for the admin key

The admin key is separate from the worker key and gives upload access.
Ping Jay or open an issue. Only one or two people need this key — most
contributors just run the worker.
