# OpenCode Master Prompt — "Does It Sound Broken?"

Paste the block below into OpenCode (or Codex/Cursor) from inside the
`sound-broken/` folder. The project is **already scaffolded** — your job is to
verify it, fill the remaining gaps, get it running, and deploy. A from-scratch
fallback is included at the end in case you start in an empty folder.

---

## PROMPT TO PASTE

> You are finishing a Hugging Face Gradio hackathon project in the current
> folder. The architecture is already implemented across these files:
> `app.py`, `audio_analyzer.py`, `fault_rules.py`, `feature_prompt.py`,
> `json_guard.py`, `requirements.txt`, `README.md`, `assets/custom.css`,
> `assets/generate_samples.py`, `tests/test_pipeline.py`.
>
> **Concept (do not change it):** audio → deterministic librosa features (CPU)
> → transparent rule engine ranks candidate faults (CPU) → Nemotron-3-Nano-4B
> picks + explains the best-supported one (GPU) → validated JSON → UI. The model
> NEVER hears raw audio; it only reasons over measured features and rule-derived
> candidates. The rule layer is the floor — `json_guard.py` must snap any
> ungrounded model output back to the top deterministic candidate.
>
> **Hard constraints (keep these):**
> - Model id: `nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16` (or `-FP8`). NEVER use
>   `nvidia/Nemotron-3-Nano-4B-Instruct` — it 404s.
> - **Architecture: Modal-only compute.** The HF Space (`app.py`) is a THIN
>   Gradio client that depends on only `gradio` + `modal`. ALL heavy work
>   (librosa feature extraction + rule ranking + the 4B model) runs inside the
>   Modal container defined in `modal_backend.py` (`@app.cls(gpu="A10G")` with
>   `@modal.enter()` to load the model and a `@modal.method()` pipeline). Do NOT
>   put librosa/torch/transformers in the Space's requirements.txt or import them
>   in app.py. Do NOT use HF ZeroGPU/`spaces.GPU`.
> - The Space looks the backend up with `modal.Cls.from_name("sound-broken",
>   "Diagnoser")` and calls `.run.remote(audio_bytes, suffix, appliance)`, which
>   returns a JSON-serializable dict `{ok, error, features, candidates, result}`.
> - Appliance type is a REQUIRED input. Greedy decoding (`do_sample=False`),
>   `max_new_tokens=384`, use `tokenizer.apply_chat_template`.
> - Robustness is non-negotiable: every handler returns a friendly result and
>   never raises; all model-derived text is `html.escape`d before rendering.
>
> **Do these tasks in order, and report (don't guess) on any blocker:**
> 1. `pip install -r requirements.txt`.
> 2. `python assets/generate_samples.py` to create the 4 test WAVs.
> 3. `python -m pytest tests/ -q` — all tests must pass. The bearing sample MUST
>    trigger a bearing candidate; the good sample MUST stay calm; empty audio MUST
>    NOT crash. Fix `audio_analyzer.py` / `fault_rules.py` if any fail.
> 4. `SOUNDBROKEN_MOCK=1 python app.py` and confirm the UI loads, both tabs work,
>    Examples render an urgency banner + evidence panel, and Compare shows a
>    before/after delta. Fix any Gradio wiring issues.
> 5. Review the CSS renders the industrial amber-on-charcoal theme; tighten if
>    the verdict card or urgency colors look off. Verify mobile (single column).
> 6. If a GPU is available, unset MOCK and confirm a real diagnosis returns valid
>    grounded JSON. If the model OOMs, switch `MODEL_ID` to the `-FP8` variant.
> 7. Verify `README.md` frontmatter (sdk gradio, hardware zero-gpu, correct model
>    tag). Add real screenshots once the UI runs.
> 8. Expand `fault_rules.RULES` to cover the remaining appliances in
>    `app.APPLIANCES` (Tumble dryer, Refrigerator/Freezer, Air conditioner,
>    Vacuum cleaner, Dishwasher, Microwave, Bicycle, Power drill). 2–4 rules each,
>    same `Rule(name, urgency, weight, when, evidence)` shape, weights 0.6–0.9,
>    evidence templates that reference real feature fields. Keep `when` lambdas
>    defensive (no exceptions on edge values).
>
> **Definition of done:** tests green; `python app.py` runs end-to-end; all 4
> examples produce grounded reproducible diagnoses with a visible evidence chain;
> Compare tab shows a numeric delta; no unhandled exception on empty/garbage audio;
> README renders on a Space. Work incrementally and run the tests after each change.
>
> **Stretch (only if time remains):** add `finetune/train.py` — a LoRA fine-tune
> of the 4B model on ~200–300 (feature-description → known-fault) pairs derived
> from the MIMII dataset; document uploading the adapter to the Hub for the
> Well-Tuned badge. Do not let this block the core submission.

---

## FROM-SCRATCH FALLBACK (only if the folder is empty)

If the scaffold is missing, build it module by module in this exact order, running
a quick check after each: (1) `audio_analyzer.py` with the `AudioFeatures`
dataclass + NaN-guarded `extract_features`; (2) `fault_rules.py` with `Rule`,
`Candidate`, `RULES` tables and `rank_candidates` (always returns ≥1 candidate);
(3) `feature_prompt.py` `build_diagnosis_prompt(features, candidates, appliance)`
demanding strict JSON; (4) `json_guard.py` `validate()` with rule fallback;
(5) `app.py` Gradio Blocks with `@spaces.GPU`, mock mode via `SOUNDBROKEN_MOCK`,
Diagnose + Compare tabs, evidence accordion; (6) `assets/generate_samples.py`,
`assets/custom.css`, `tests/`, `requirements.txt`, `README.md` with the
frontmatter above. Use the constraints listed in the main prompt verbatim.