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

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):

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

Verify the GPU is actually used:

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

.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

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

should end with ALL SELF-CHECKS PASS.