docs/SETUP.md

# Reproducible environment setup

Declared to work exactly once, on the author's machine, and replayable by a
reviewer. All commands run from the repo root.

## 1. Python + venv

```bash
python -m venv .venv
# Windows (Git Bash / PowerShell alike):
.venv/Scripts/python -m pip install --upgrade pip
.venv/Scripts/python -m pip install -r requirements.txt
```

Use `python` from `.venv/Scripts/` everywhere (the `ml` package is imported as
`from ml.model...` so run with the repo root on `PYTHONPATH`, e.g. the
`python -m` entry points below handle this).

## 2. CUDA PyTorch (NVIDIA GPU)

torch installs CPU wheels by default; force the CUDA build that matches the
local driver (this project uses cu124):

```bash
.venv/Scripts/python -m pip install torch --index-url https://download.pytorch.org/whl/cu124
```

Verify the GPU is actually used:

```bash
.venv/Scripts/python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU')"
# e.g. 2.6.0+cu124 True NVIDIA GeForce RTX 4050 Laptop GPU
```

The stutter trainer uses fp16 mixed precision; it still works correctly on CPU
(slower) — the results are identical, just slower to arrive.

## 3. HuggingFace authentication

Two corpora (SEP-28k on `DynamicSuperb/...`, UCLASS) ask for HF auth:

```bash
.venv/Scripts/python -c "from huggingface_hub import login; login()"
```

## 4. Model artifacts (downloaded once, cached)

At runtime the pipeline pulls two real public checkpoints from the HF Hub
(small, cached locally, git-ignored):

- `facebook/wav2vec2-base`            — encoder for the fine-tuned stutter head
- `facebook/wav2vec2-base-960h`       — CTC acoustic model for pronunciation GOP

No pre-trained weights are committed to the repo (licensing + size).

## 5. Smoke test

```bash
.venv/Scripts/python -m ml.cli self-check
```

should end with `ALL SELF-CHECKS PASS`.