DEPLOY.md

# Deploy — Disfluency Remover Space

> **STATUS: NOT PUBLISHED.** Everything below is a deliberate, outward-facing
> publishing action and requires the user's explicit go-ahead. The local
> `space/` artifacts are committed; nothing has been pushed to the Hub.

## Prerequisites

### 1. Push the v1 adapter to the Hub (REQUIRED — Space can't load without it)
`space/app.py` loads `ADAPTER = "pradachan/whisper-large-v3-turbo-disfluency-lora"`.
That Hub repo does **not exist yet** — the v1 adapter lives locally at
`/models/whisper-lora-disfluency`. Push it first:

```bash
# from a machine with the adapter + huggingface_hub installed and logged in
huggingface-cli login   # or: export HF_TOKEN=hf_...
huggingface-cli upload \
  pradachan/whisper-large-v3-turbo-disfluency-lora \
  /models/whisper-lora-disfluency . \
  --repo-type=model
```

If you prefer to keep the adapter **private** at skeleton stage, create it
private and add the token as a Space secret (step 4) — the Space will then
authenticate to pull it.

### 2. Export gallery audio clips (so example chips are clickable)
The precomputed gallery text is already baked into `app.py`. To make the
example *clips* playable, export the matching test-set audio by idx:

```python
# run once; writes space/examples/idx_XXX.wav
import soundfile as sf
from datasets import load_dataset, Audio

ds = load_dataset("amaai-lab/DisfluencySpeech", split="test", trust_remote_code=True)
ds = ds.cast_column("audio", Audio(sampling_rate=16000))
for idx in (1, 125, 43, 248):
    a = ds[idx]["audio"]
    sf.write(f"space/examples/idx_{idx:03d}.wav", a["array"], a["sampling_rate"])
```

`app.py` only registers `gr.Examples` for clips that exist on disk, so the app
runs fine with or without this step.

## Create + push the Space

```bash
# one-time: create the Space (gradio SDK, ZeroGPU hardware) under the user's account
huggingface-cli repo create disfluency-remover --type space --space_sdk gradio

# push the contents of space/ to the Space repo root
cd space
git init && git remote add origin https://huggingface.co/spaces/pradachan/disfluency-remover
git add app.py requirements.txt README.md examples/ 2>/dev/null
git commit -m "Disfluency Remover skeleton (v1 adapter)"
git push origin main      # use an HF token / git credential helper
```

(Alternatively `pip install huggingface_hub` and use
`HfApi().upload_folder(folder_path="space", repo_id="pradachan/disfluency-remover", repo_type="space")`.)

### 3. Set ZeroGPU hardware
`README.md` already declares `hardware: zero-gpu` in the YAML header. Confirm in
the Space **Settings → Hardware** that ZeroGPU is selected after the first push.

### 4. Set the Space secret (only if the adapter repo is private)
Space **Settings → Variables and secrets → New secret**:
- Name: `HF_TOKEN`
- Value: a token with read access to the private adapter repo.

The `transformers`/`peft` loaders read `HF_TOKEN` automatically.

## Live verification (after the Space is up)
- **Mic clip:** record ~10s saying "you know" / "I mean" / a repeated word →
  the *Cleaned* pane drops them and the *diff* pane shows red strikethroughs.
  Warm latency should be < 15s.
- **Chunking:** upload a ~60s clip → it is split into 30s windows and the texts
  are concatenated; output should be coherent end to end.
- **Phone-number caveat:** upload a clip containing a spoken number sequence and
  confirm whether digits collapse. If they do, keep such an example **out of the
  gallery** and document it in the limitations note (and as the Epic 08 "honest
  failure" example at final stage).
- **Cold start:** first request after idle is ~30s (model load on ZeroGPU). The
  baked-in gallery text keeps the page demonstrable during that window.

## Final-stage swap (Epic 07/09 — NOT now)
- Point `ADAPTER` at the winner adapter Hub repo.
- Curate gallery to **3 wins + 1 self-repair + 1 honest failure** (add the Epic
  08 failure to `GALLERY` in `app.py` with a "limitation" label).
- Update README claim numbers to match Epic 09 claims rules.

## Decision gate
- ZeroGPU quota/queue problems on demo day → fall back to a paid T4 Space
  (`hardware: t4-small`, ~$0.60/h). Decide by Jun 14 evening; do not debug live.
- If the winner adapter isn't ready by Jun 14 evening, ship with v1 permanently
  and update the card numbers accordingly (v1 beats vanilla; demo works).