Deploy headless recognizer API (Docker)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+models/raaga_xgb.json filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,18 @@
+# Headless recognizer API as a Hugging Face Docker Space (or any container host).
+# The assembled build (space/assemble.sh output, or the repo) provides raaga_id/, models/, api.py.
+FROM python:3.10-slim
+
+# ffmpeg: decode webm/opus/m4a the browser sends. libsndfile: soundfile backend.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ffmpeg libsndfile1 build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements-api.txt .
+RUN pip install --no-cache-dir -r requirements-api.txt
+
+COPY . .
+ENV MODEL_PATH=/app/models/raaga_xgb.json
+# HF Spaces route to $PORT (7860). Warm the model on the first request, not at build.
+EXPOSE 7860
+CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,22 @@
 ---
-title: Recognizer Api
-emoji: 📈
+title: twelveswaras recognizer API
+emoji: 🎧
 colorFrom: yellow
-colorTo: blue
+colorTo: red
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# twelveswaras recognizer API (headless)
+
+The decoupled inference backend. No UI: it exposes JSON only. The user-facing wheel lives
+first-party on twelveswaras.com (Cloudflare Pages) and calls this through a Cloudflare Worker.
+
+- `GET /health` -> `{ "status": "ok", "raagas": 40 }`
+- `POST /identify` (multipart `audio`) -> `{ top3, tonic_hz, heard_seconds, no_prediction, swara_activation[12] }`
+
+This Space is a **Docker** SDK space (not Gradio). It builds `space/Dockerfile`, which runs
+`uvicorn api:app` on port 7860. To deploy, assemble the build (raaga_id/, models/, api.py,
+Dockerfile, requirements-api.txt) and push to a Space whose README has the front-matter above.
+See `cloudflare/DEPLOY.md`.

api.py

@@ -0,0 +1,105 @@
+"""Headless inference API for the twelveswaras recognizer (the decoupled backend).
+
+The recognizer used to be a Gradio app that rendered its own UI. In the decoupled architecture
+the UI lives first-party on the site (Cloudflare Pages) and this is a pure JSON API. No UI, no
+branding: the front end renders everything.
+
+    POST /identify   multipart: audio=<file>   ->
+      {
+        "no_prediction": false,
+        "tonic_hz": 147.0,
+        "heard_seconds": 42.3,
+        "top3": [{"raaga": "Kalyāṇi", "confidence": 0.91}, ...],
+        "swara_activation": [12 floats]   # tonic-normalized pitch-class mass, folded to the 12
+                                          # swara positions (Sa first) — drives the wheel glow
+      }
+    GET /health  ->  {"status": "ok", "raagas": 40}
+
+Runs the EXACT production pipeline (essentia predominant pitch + compiam tonic -> windowed TDMS
+-> XGBoost). Serves on port 7860 for a Hugging Face Docker Space, but is a plain FastAPI app
+runnable anywhere. Requires the numpy<2 inference stack (see requirements-api.txt).
+"""
+from __future__ import annotations
+
+import io
+import os
+
+import numpy as np
+from fastapi import FastAPI, File, Form, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from raaga_id import pitch_extract
+from raaga_id.config import MODELS_DIR, TOP_K
+from raaga_id.model import RaagaXGB
+
+MODEL_PATH = os.environ.get("MODEL_PATH", str(MODELS_DIR / "raaga_xgb.json"))
+SWARAS = 12
+
+app = FastAPI(title="twelveswaras recognizer API", docs_url="/docs", redoc_url=None)
+# CORS is permissive here because the public entry point is the Cloudflare Worker (same-origin to
+# the browser); direct browser calls are allowed too for local dev.
+app.add_middleware(
+    CORSMiddleware, allow_origins=["*"],
+    allow_methods=["GET", "POST", "OPTIONS"], allow_headers=["*"],
+)
+
+_model = None
+
+
+def model() -> RaagaXGB:
+    global _model
+    if _model is None:
+        _model = RaagaXGB.load(MODEL_PATH)
+        pitch_extract.warmup()          # pay the essentia/compiam import cost once, at first call
+    return _model
+
+
+def fold_swaras(pcd) -> list[float]:
+    """Fold the tonic-normalized pitch-class distribution (PCD_BINS bins over the octave) into the
+    12 swara positions, Sa first. This is the real data the wheel lights up with."""
+    if pcd is None:
+        return [0.0] * SWARAS
+    a = np.asarray(pcd, dtype=float)
+    if a.size < SWARAS or a.sum() <= 0:
+        return [0.0] * SWARAS
+    per = a.size // SWARAS
+    out = [float(a[i * per:(i + 1) * per].sum()) for i in range(SWARAS)]
+    s = sum(out) or 1.0
+    return [round(v / s, 4) for v in out]
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "raagas": len(model().classes)}
+
+
+@app.post("/identify")
+async def identify(audio: UploadFile = File(...), contribute: str = Form("no")):
+    import librosa
+
+    m = model()
+    raw = await audio.read()
+    try:
+        y, sr = librosa.load(io.BytesIO(raw), sr=None, mono=True)
+    except Exception as e:  # noqa: BLE001
+        return JSONResponse({"error": "could not decode audio", "detail": str(e)[:200]}, status_code=400)
+
+    windows, tonic, heard, pcd = pitch_extract.audio_to_features(y, sr)
+    if not windows:
+        return {
+            "no_prediction": True,
+            "tonic_hz": round(float(tonic), 1) if tonic else None,
+            "heard_seconds": round(float(heard or 0), 1),
+            "top3": [],
+            "swara_activation": fold_swaras(pcd),
+        }
+
+    preds = m.aggregate_top_k(np.vstack(windows), k=TOP_K)
+    return {
+        "no_prediction": False,
+        "tonic_hz": round(float(tonic), 1),
+        "heard_seconds": round(float(heard), 1),
+        "top3": [{"raaga": p.raaga, "confidence": round(float(p.confidence), 4)} for p in preds],
+        "swara_activation": fold_swaras(pcd),
+    }

apps/__init__.py

@@ -0,0 +1,6 @@
+"""Serving layer — Gradio apps for the HF Space (PRD §6.6, §17).
+
+identify.py   -> v0: mic/upload -> top-3 raagas.
+contribute.py -> v1: predict -> confirm/correct -> writeback to the commons.
+verify.py     -> v1: community verification queue.
+"""

apps/contribute.py

@@ -0,0 +1,80 @@
+"""v1 contribution loop — predict -> confirm/correct -> writeback (PRD §18.3, §13).
+
+Anonymous by default (D12): no login, dedup via audio_sha256, optional handle for
+attribution only. Rights gate (§12): nothing is saved unless the contributor
+affirms it's their own performance / they have the right to share it.
+
+Writes {id}.flac + {id}.json into incoming/ of the dataset repo; the consolidate
+cron promotes verified clips into shards (pipeline/consolidate.py).
+"""
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import io
+import json
+import os
+import uuid
+
+# Neutral org (D19). The Space holds an HF write token scoped to this dataset repo.
+DATASET_REPO = "twelveswaras/twelveswaras-commons"
+CONSENT_VERSION = "2026-07-01-v1"
+
+
+def utcnow() -> str:
+    return dt.datetime.utcnow().replace(microsecond=0).isoformat() + "Z"
+
+
+def pseudonym(handle: str) -> str:
+    # Optional, never PII (D12). Random per-clip id if no handle given.
+    return "u_" + hashlib.sha256(handle.encode()).hexdigest()[:8]
+
+
+def submit(audio, chosen_raaga, is_own, license_, handle, instrument, form, ctx) -> str:
+    if not is_own:
+        return "❌ Not saved — you must confirm this is your own performance / you may share it."
+
+    import soundfile as sf
+    from huggingface_hub import CommitOperationAdd, HfApi
+
+    api = HfApi(token=os.environ["HF_WRITE_TOKEN"])  # Space secret, scoped to the dataset repo
+    sr, wav = audio
+    buf = io.BytesIO()
+    sf.write(buf, wav, sr, format="FLAC")
+    raw = buf.getvalue()
+    rid = uuid.uuid4().hex[:8]
+    meta = {
+        "id": rid,
+        "audio_file": f"{rid}.flac",
+        "audio_sha256": hashlib.sha256(raw).hexdigest(),
+        "raaga": chosen_raaga,
+        "tradition": "carnatic",
+        "contributor_id": pseudonym(handle or rid),
+        "is_own_performance": True,
+        "license": license_,
+        "consent_version": CONSENT_VERSION,
+        "created_at": utcnow(),
+        "label_source": "model_confirmed" if chosen_raaga == ctx.get("pred") else "contributor_declared",
+        "model_prediction": ctx.get("pred"),
+        "model_confidence": float(ctx.get("conf", 0.0)),
+        "verification_status": "unverified",
+        "split": "pending",
+        "votes_agree": 0,
+        "votes_disagree": 0,
+        "instrument": instrument,
+        "form": form,
+    }
+    api.create_commit(
+        repo_id=DATASET_REPO,
+        repo_type="dataset",
+        commit_message=f"contrib {rid} ({chosen_raaga})",
+        operations=[
+            CommitOperationAdd(f"incoming/{rid}.flac", raw),
+            CommitOperationAdd(f"incoming/{rid}.json", json.dumps(meta, ensure_ascii=False).encode()),
+        ],
+    )
+    return f"✅ Saved as {chosen_raaga} — thank you! It enters the verification queue."
+
+
+# TODO(v1): assemble the Gradio Blocks UI (predict button + confirm/correct form).
+# The identify half already lives in apps/identify.py; this file owns the writeback.

apps/identify.py

@@ -0,0 +1,317 @@
+"""v0 "Shazam for raagas" — mic/upload -> top-3 (PRD build-order step 7).
+
+    python -m apps.identify        # launches the Gradio app (needs the inference env)
+
+Runs the PCD path (essentia pitch + tonic -> pooled model), shows top-3 as confidence
+bars + the estimated Sa + recognition time. Styled to the shared urbanmorph design
+system (dark #0a0a0a canvas, system-ui, hairline borders) with twelveswaras' amber hue.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import numpy as np
+
+from raaga_id import pitch_extract
+from raaga_id.config import MODELS_DIR, TOP_K
+from raaga_id.model import RaagaXGB
+
+from apps import usage_log
+
+ASSETS = Path(__file__).resolve().parent.parent / "assets"
+MODEL_PATH = MODELS_DIR / "raaga_xgb.json"
+
+# Inline logo tile (12-bar pitch-class histogram = the twelve swaras), amber gradient.
+_TILE = """
+<svg width="46" height="46" viewBox="0 0 256 256" style="flex:0 0 auto">
+  <defs><linearGradient id="tsl" x1="0" y1="0" x2="0" y2="1">
+    <stop offset="0" stop-color="#f59e0b"/><stop offset="1" stop-color="#b45309"/></linearGradient></defs>
+  <rect width="256" height="256" rx="56" fill="url(#tsl)"/>
+  <g fill="#fff">
+    <rect x="36" y="140" width="10" height="60" rx="5"/><rect x="52" y="105" width="10" height="95" rx="5"/>
+    <rect x="68" y="145" width="10" height="55" rx="5"/><rect x="84" y="80" width="10" height="120" rx="5"/>
+    <rect x="100" y="120" width="10" height="80" rx="5"/><rect x="116" y="95" width="10" height="105" rx="5"/>
+    <rect x="132" y="64" width="10" height="136" rx="5"/><rect x="148" y="130" width="10" height="70" rx="5"/>
+    <rect x="164" y="90" width="10" height="110" rx="5"/><rect x="180" y="115" width="10" height="85" rx="5"/>
+    <rect x="196" y="100" width="10" height="100" rx="5"/><rect x="212" y="135" width="10" height="65" rx="5"/>
+  </g></svg>
+"""
+
+TITLE_HTML = f"""
+<div id="ts-title" style="display:flex; align-items:center; justify-content:center; gap:.65rem; margin:.4rem 0 .2rem">
+  {_TILE}
+  <div style="text-align:left; line-height:1.05">
+    <div style="font-size:clamp(1.4rem,6.5vw,2.1rem); font-weight:800; letter-spacing:-1px"><span style="color:#ededed">twelve</span><span style="color:#f59e0b">swaras</span></div>
+    <div style="font-size:clamp(.72rem,3.2vw,.92rem); color:#9ca3af; letter-spacing:.2px">identify the raaga</div>
+  </div>
+</div>
+"""
+
+FOOTER_HTML = """
+<div id="ts-footer">a non-commercial, open-source public good · Carnatic first · CC-BY data commons</div>
+"""
+
+CSS = """
+.gradio-container { max-width: 640px !important; margin: 0 auto !important; }
+footer { display: none !important; }
+#ts-footer { text-align:center; color:#9ca3af; opacity:.7; font-size:.78rem; margin:1rem 0 .3rem; }
+/* privacy reassurance shown right above the recorder (visible in the embed too) */
+#ts-privacy { text-align:center; color:#9ca3af; font-size:.82rem; margin:.1rem 0 .3rem; }
+#ts-privacy p { margin:0; }
+/* confidence bars in the brand amber */
+.gradio-container .label span.text + div, .gradio-container .fill { background: #f59e0b !important; }
+/* audio player: keep the seek bar from covering the 0:00 / total time read-outs */
+.gradio-container .timestamps { position: relative; z-index: 3; margin-top: 4px; }
+.gradio-container .timestamps time { background: #0a0a0a; padding: 0 3px; border-radius: 3px; }
+/* embed mode (loaded in the twelveswaras.com iframe via ?embed=1): hide the app's own logo,
+   footer, and the drone tip (the page already carries all three) so it fits without scrolling */
+body.embed #ts-title, body.embed #ts-footer, body.embed #ts-drone { display: none !important; }
+body.embed .gap, body.embed .contain { gap: 10px !important; }
+body.embed .gradio-container { padding-top: 2px !important; padding-bottom: 0 !important;
+  overflow: hidden !important; max-width: 100% !important; }  /* fill page width; no bottom slack
+  so the auto-resized frame ends right at the content (640px cap is for standalone) */
+/* breathing room around the status line so Gradio's progress bar doesn't crowd the "Listening…" text */
+#ts-status { margin-top: 10px !important; }
+#ts-status p { padding-top: 6px !important; }
+/* frame is sized to content -> the iframe itself never scrolls; the page does. Kills Gradio's
+   always-on scrollbar track. (overflow only — no height changes, which would blank the app.) */
+html:has(body.embed), body.embed { overflow: hidden !important; }
+"""
+
+
+def _theme():
+    import gradio as gr
+
+    return gr.themes.Base(
+        primary_hue=gr.themes.colors.amber,
+        secondary_hue=gr.themes.colors.amber,
+        neutral_hue=gr.themes.colors.neutral,
+        font=["system-ui", "ui-sans-serif", "-apple-system", "Segoe UI", "sans-serif"],
+        font_mono=["ui-monospace", "SFMono-Regular", "Menlo", "monospace"],
+    ).set(
+        body_background_fill="#0b0a08",   # match the twelveswaras.com page ground (no seam)
+        body_text_color="#ededed",
+        body_text_color_subdued="#9ca3af",
+        background_fill_primary="#15151a",
+        background_fill_secondary="#1a1a1f",
+        block_background_fill="#15151a",
+        block_border_color="#262626",
+        block_border_width="1px",
+        block_radius="12px",
+        block_label_background_fill="#1a1a1f",
+        block_label_text_color="#fbbf24",
+        border_color_primary="#262626",
+        input_background_fill="#1a1a1f",
+        button_primary_background_fill="#d97706",
+        button_primary_background_fill_hover="#b45309",
+        button_primary_text_color="#ffffff",
+        button_primary_border_color="#d97706",
+    )
+
+
+def _load_model() -> RaagaXGB:
+    if not MODEL_PATH.exists():
+        raise SystemExit(f"no model at {MODEL_PATH} — run `python -m raaga_id.train` first.")
+    return RaagaXGB.load(MODEL_PATH)
+
+
+def _learn_plot(raaga, user_profile):
+    """A dark/amber bar chart of which of the seven swaras the raaga rests on vs the user's
+    clip — the 'how to hear this raaga' visual, in the notes a beginner knows."""
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    from raaga_id import learn
+    from raaga_id.features import to_swaras7
+
+    names, user7 = to_swaras7(user_profile)
+    x = np.arange(len(names))
+    fig, ax = plt.subplots(figsize=(6, 2.4))
+    fig.patch.set_facecolor("#0a0a0a")
+    ax.set_facecolor("#0a0a0a")
+    ref = learn.reference_profile(raaga)
+    if ref is not None:
+        ax.bar(x - 0.2, to_swaras7(ref)[1], width=0.4, color="#f59e0b", label=raaga)
+    ax.bar(x + 0.2, user7, width=0.4, color="#6b7280", label="your clip")
+    ax.set_xticks(x)
+    ax.set_xticklabels(names, color="#ededed", fontsize=9)
+    ax.tick_params(axis="x", length=0)
+    ax.set_yticks([])
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+    ax.legend(facecolor="#15151a", edgecolor="#262626", labelcolor="#ededed", fontsize=8, loc="upper right")
+    fig.tight_layout()
+    return fig
+
+
+def _mmss(seconds: float) -> str:
+    """Whole-second duration as m:ss (e.g. 90 -> '1:30'), for the 'heard 0:00-…' label."""
+    s = int(round(seconds))
+    return f"{s // 60}:{s % 60:02d}"
+
+
+def identify(audio, model: RaagaXGB):
+    """audio = (sample_rate, np.ndarray) from Gradio. A GENERATOR: it yields a "listening"
+    state first (so the app is visibly working before it answers — D24), then the final
+    (labels, info, plot, learn_md). The info line names the segment it actually heard."""
+    if audio is None:
+        yield {}, "Upload or record ~10 s+ of melody. A clear line with a drone works best.", None, ""
+        return
+    # Show that we're listening BEFORE the ~3.5 s of pitch+tonic extraction, and clear any
+    # previous result, so the answer never appears to precede the analysis.
+    yield {}, "🎧 **Listening…** finding the tonic (Sa) and tracing the swaras.", None, ""
+
+    sr, wav = audio
+    t0 = time.perf_counter()
+    windows, tonic, heard, display_pcd = pitch_extract.audio_to_features(wav, sr)
+    if not windows:
+        usage_log.record(no_prediction=True, tonic_hz=tonic, heard_seconds=heard)
+        yield {}, "🤔 Couldn't find a clear melody + tonic. Try a longer, cleaner clip with a drone.", None, ""
+        return
+    X = np.vstack(windows)
+    preds = model.aggregate_top_k(X, k=TOP_K)
+    elapsed = time.perf_counter() - t0
+    print(f"[identify] {preds[0].raaga} ({preds[0].confidence:.0%}) · Sa≈{tonic:.0f}Hz · "
+          f"heard {_mmss(heard)} · {elapsed:.1f}s", flush=True)
+    usage_log.record(top1=preds[0].raaga, confidence=preds[0].confidence,
+                     top3=[{"raaga": p.raaga, "conf": round(float(p.confidence), 3)} for p in preds],
+                     tonic_hz=tonic, heard_seconds=heard, elapsed_s=elapsed)
+
+    from raaga_id.calibrate import confidence_state
+    labels = {p.raaga: float(p.confidence) for p in preds}
+    state, note = confidence_state(preds)   # calibrated top-2 -> "confident" / "close" / "unsure"
+    info = (f"**Sa ≈ {tonic:.0f} Hz**  ·  heard **0:00–{_mmss(heard)}**  ·  "
+            f"recognized in **{elapsed:.1f} s**  ·  {note}")
+
+    from raaga_id import learn
+    from raaga_id.features import pcd_to_swaras
+    top = preds[0].raaga
+    user_profile = pcd_to_swaras(display_pcd)   # human-readable swaras from the PCD, not the TDMS surface
+    learn_md = learn.summary_md(top, user_profile)
+    # On a close call, lead the learner panel with how to tell the top two apart (D29 Explorer).
+    if state == "close":
+        cmp = learn.comparison_md(preds[0].raaga, preds[1].raaga)
+        if cmp:
+            learn_md = cmp + "\n\n---\n\n" + learn_md
+    yield labels, info, _learn_plot(top, user_profile), learn_md
+
+
+# When the recognizer is loaded inside the twelveswaras.com page (i.e. in an iframe), hide its
+# own logo/footer/drone-tip so it reads as part of the page. Injected in <head> so it always
+# runs; detects embedding by iframe (window.self !== window.top) — no query-param dependency —
+# and hides elements DIRECTLY by id, re-applying on a few timers because Gradio renders its
+# components asynchronously after first paint. Standalone (hf.space direct) keeps full branding.
+EMBED_HEAD = """
+<script>
+(function () {
+  function embedded() { try { return window.self !== window.top; } catch (e) { return true; } }
+  function hideChrome() {
+    if (!embedded()) return;
+    document.body.classList.add('embed');
+    // The frame is sized to content, so the recognizer never needs to scroll itself — the PAGE
+    // scrolls. Hide the iframe's own overflow so Gradio's always-on scrollbar track disappears.
+    // (Only overflow — no height/min-height changes, which would collapse the layout.)
+    document.documentElement.style.overflow = 'hidden';
+    document.body.style.overflow = 'hidden';
+    ['ts-title', 'ts-drone', 'ts-footer'].forEach(function (id) {
+      var el = document.getElementById(id);
+      if (el) { el.style.display = 'none'; }
+    });
+  }
+  // Tell the parent page our content height so it can grow the iframe to fit — the PAGE scrolls,
+  // the frame never gets its own scrollbar. Fires on load, timers, window resize, and (via
+  // ResizeObserver) whenever the content changes — a result appears, the accordion opens, etc.
+  var lastH = 0;
+  function reportHeight() {
+    if (!embedded()) return;
+    // Gradio stretches every CONTAINER to fill the viewport (= the frame height), so measuring any
+    // of them loops the auto-resize to infinity ("grows like a worm"). The #ts-end sentinel is a
+    // plain marker that flows right after the last component, so its bottom is the TRUE content
+    // height and can't stretch. absolute = rect.bottom + scrollY. +10px breathing room.
+    var end = document.getElementById('ts-end');
+    if (!end) return;
+    var h = Math.ceil(end.getBoundingClientRect().bottom + window.scrollY) + 10;
+    if (h > 0 && h !== lastH) {
+      lastH = h;
+      try { window.parent.postMessage({ twelveswaras_height: h }, '*'); } catch (er) {}
+    }
+  }
+  function hideDeadMic() {
+    // Gradio's audio device <select> shows a misleading "No microphone found" before mic permission
+    // is granted, even though recording works fine on the default device. Hide that control while it
+    // shows the dead label, and restore ONLY the ones we hid once a real device name appears.
+    var L = 'No microphone found';
+    document.querySelectorAll('select, button').forEach(function (el) {
+      var t = (el.textContent || '').replace(/\\s+/g, ' ').trim();
+      if (t === L) { el.style.display = 'none'; el.dataset.tsDeadmic = '1'; }
+      else if (el.dataset.tsDeadmic === '1') { el.style.display = ''; delete el.dataset.tsDeadmic; }
+    });
+  }
+  function tick() { hideChrome(); hideDeadMic(); reportHeight(); }
+  if (document.readyState !== 'loading') tick();
+  document.addEventListener('DOMContentLoaded', tick);
+  [150, 400, 900, 1800].forEach(function (t) { setTimeout(tick, t); });
+  window.addEventListener('resize', reportHeight);
+  // Gradio's body is pinned to 100vh, so opening the accordion / getting a result overflows it
+  // WITHOUT changing its size — ResizeObserver never fires. So poll the sentinel (deduped, cheap).
+  setInterval(tick, 300);
+})();
+</script>
+"""
+
+
+def build_ui():
+    import gradio as gr
+
+    model = _load_model()
+    pitch_extract.warmup()          # pay the essentia/compiam import cost once, up front
+
+    with gr.Blocks(title="twelveswaras", theme=_theme(), css=CSS, head=EMBED_HEAD) as demo:
+        gr.HTML(TITLE_HTML)
+        gr.Markdown("🔒 Your recording is **never stored**. It is analyzed to find the raaga, then discarded.",
+                    elem_id="ts-privacy")
+        # buttons=["download"] drops Gradio's built-in "share": it re-uploads the raw clip to HF's
+        # MIME-restricted uploader (rejects m4a/aac/flac/…) and shares the *input*, not the result
+        # — confusing + flaky. A real "share this raga" is an Explorer feature (D29). Keep download.
+        audio = gr.Audio(sources=["microphone", "upload"], type="numpy", autoplay=True,
+                         label="Upload or record ~15–30 s", buttons=["download"])
+        gr.Markdown("🎚️ **For best accuracy, include a tanpura / shruti-box drone.** A live "
+                    "concert always has one — the tonic (Sa) is found from it, so solo voice "
+                    "without a drone is unreliable.", elem_id="ts-drone")
+        result = gr.Label(num_top_classes=TOP_K, label="Raaga")
+        info = gr.Markdown("_Recognition runs automatically when you upload or finish recording._",
+                           elem_id="ts-status")
+        with gr.Accordion("🎓 How to hear this raaga", open=False):
+            learn_plot = gr.Plot(label="Typical shape from recordings (gold) vs your clip (grey)")
+            learn_md = gr.Markdown()
+        gr.HTML(FOOTER_HTML)
+        # Sentinel at the very end of the content. Gradio stretches every CONTAINER to fill the
+        # viewport (so measuring any of them loops the auto-resize), but this plain marker just
+        # flows after the last component — its position IS the true content height.
+        gr.HTML('<div id="ts-end" style="height:1px"></div>')
+
+        outs = [result, info, learn_plot, learn_md]
+
+        def on_audio(a):        # generator fn so Gradio streams "listening…" then the result
+            yield from identify(a, model)
+
+        # No button: auto-identify when a file is uploaded or a recording stops.
+        # show_progress="hidden": the generator already yields a "🎧 Listening…" status, so Gradio's
+        # per-output progress spinners are redundant AND duplicate on mobile — each of the 4 outputs
+        # renders its own "N.Ns" eta, and on a narrow layout one floats over the caption text.
+        audio.upload(on_audio, audio, outs, show_progress="hidden")
+        audio.stop_recording(on_audio, audio, outs, show_progress="hidden")
+
+        # Clearing the audio (Gradio's ✕) must also reset the result/Sa/panels below — otherwise
+        # the previous clip's raaga lingers under an empty input.
+        def clear_panels():
+            return {}, "_Recognition runs automatically when you upload or finish recording._", None, ""
+        audio.clear(clear_panels, None, outs)
+    return demo
+
+
+if __name__ == "__main__":
+    favicon = ASSETS / "favicon.svg"
+    build_ui().launch(favicon_path=str(favicon) if favicon.exists() else None)

apps/usage_log.py

@@ -0,0 +1,68 @@
+"""Aggregate, privacy-preserving usage logging.
+
+Logs the RESULT of each identification (predicted raaga + confidence + tonic + whether a
+prediction was made) to a private Hugging Face Dataset. It NEVER logs the audio, an IP, or any
+user identifier — just anonymous per-identification result metadata, so we can see how much the
+app is used and what it's recognising in the wild (the passive real-world signal).
+
+Robustness:
+- Disabled unless HF_TOKEN is set (a write token, as a Space secret). Without it the app runs
+  exactly as before, just without logging.
+- Every call is wrapped so a logging failure can NEVER break recognition.
+- Uses huggingface_hub.CommitScheduler: appends locally, flushes to the dataset every few minutes
+  (one commit per identification would be far too many).
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+DATASET = "twelveswaras/usage-logs"
+LOG_DIR = Path("usage_logs")
+LOG_FILE = LOG_DIR / "identifications.jsonl"
+
+_scheduler = None
+_tried = False
+
+
+def _scheduler_or_none():
+    global _scheduler, _tried
+    if _scheduler is not None or _tried:
+        return _scheduler
+    _tried = True
+    if not os.environ.get("HF_TOKEN"):
+        return None                       # logging off; app still works
+    try:
+        from huggingface_hub import CommitScheduler
+        LOG_DIR.mkdir(exist_ok=True)
+        _scheduler = CommitScheduler(repo_id=DATASET, repo_type="dataset", private=True,
+                                     folder_path=str(LOG_DIR), path_in_repo="data", every=5)
+    except Exception:                     # noqa: BLE001  (bad token / no access -> stay disabled)
+        _scheduler = None
+    return _scheduler
+
+
+def record(*, top1=None, confidence=None, top3=None, tonic_hz=None,
+           heard_seconds=None, no_prediction=False, elapsed_s=None) -> None:
+    """Append one identification's RESULT metadata. No audio, no PII. Never raises."""
+    try:
+        sch = _scheduler_or_none()
+        if sch is None:
+            return
+        from datetime import datetime, timezone
+        row = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "top1": top1,
+            "confidence": round(float(confidence), 3) if confidence is not None else None,
+            "top3": top3,
+            "tonic_hz": round(float(tonic_hz)) if tonic_hz else None,
+            "heard_s": round(float(heard_seconds), 1) if heard_seconds is not None else None,
+            "no_prediction": bool(no_prediction),
+            "elapsed_s": round(float(elapsed_s), 2) if elapsed_s is not None else None,
+        }
+        with sch.lock:
+            with open(LOG_FILE, "a", encoding="utf-8") as fh:
+                fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+    except Exception:                     # noqa: BLE001  (logging must never break recognition)
+        pass

apps/verify.py

@@ -0,0 +1,24 @@
+"""v1 community verification queue (PRD §14, D13).
+
+Serves unverified clips from incoming/, collects agree/disagree votes, and applies
+the promotion rule: >=3 agree AND >=80% agreement -> train; disagreement -> disputed
+-> expert queue (Sathya + a small trusted circle). Thresholds live in config.py and
+are configurable.
+"""
+from __future__ import annotations
+
+from raaga_id.config import PROMOTE_MIN_AGREEMENT, PROMOTE_MIN_VOTES
+
+
+def decide(votes_agree: int, votes_disagree: int) -> str:
+    """Return the verification_status for a clip given its current votes (D13)."""
+    total = votes_agree + votes_disagree
+    if total < PROMOTE_MIN_VOTES:
+        return "unverified"
+    if votes_agree / total >= PROMOTE_MIN_AGREEMENT:
+        return "verified"
+    return "disputed"
+
+
+# TODO(v1): Gradio queue UI — play a clip, show the declared raaga, agree/disagree;
+# persist votes back to incoming/{id}.json; hand `disputed` to the expert queue.

models/raaga_xgb.calib.json

@@ -0,0 +1,12 @@
+{
+  "temperature": 0.50304316348938,
+  "fit": {
+    "method": "temperature",
+    "k": 4,
+    "n_tracks": 567,
+    "nll_before": 0.9527,
+    "nll_after": 0.6602,
+    "ece_before": 0.347,
+    "ece_after": 0.0741
+  }
+}

models/raaga_xgb.classes.json

@@ -0,0 +1 @@
+["A\u1e6d\u0101na", "Beh\u0101g", "Bhairavi", "Bilahari", "B\u0113ga\u1e0da", "Dhany\u0101si", "D\u0113vag\u0101ndh\u0101ri", "Gau\u1e37a", "Harik\u0101mbh\u014dji", "Huss\u0113n\u012b", "Kaly\u0101\u1e47i", "Kam\u0101s", "Karaharapriya", "K\u0101mavardani", "K\u0101na\u1e0da", "K\u0101pi", "K\u0101\u1e41bh\u014dji", "K\u0113d\u0101ragau\u1e37a", "Madhyam\u0101vati", "Mukh\u0101ri", "M\u0101y\u0101m\u0101\u1e37avagau\u1e37a", "M\u014dhana\u1e41", "N\u0101\u1e6da", "N\u0101\u1e6dakurinji", "P\u016brv\u012bka\u1e37y\u0101\u1e47i", "R\u012btigau\u1e37a", "Sah\u0101n\u0101", "Sencuru\u1e6d\u1e6di", "Sindhubhairavi", "Sura\u1e6di", "S\u0101ma", "S\u0101v\u0113ri", "T\u014d\u1e0di", "Var\u0101\u1e37i", "Yadukula k\u0101\u1e41b\u014dji", "\u0100nandabhairavi", "\u015aankar\u0101bhara\u1e47a\u1e41", "\u015ar\u012b", "\u015ar\u012branjani", "\u1e62anmukhapriya"]

models/raaga_xgb.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a25af1edf468ae6b64210950e020f3158b0737afa0b3b17255c7440ac6873c6
+size 19030603

raaga_guide.json

@@ -0,0 +1,591 @@
+{
+  "Aṭāna": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2",
+      "N3"
+    ]
+  },
+  "Behāg": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": []
+  },
+  "Bhairavi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D1",
+      "D2",
+      "N2"
+    ]
+  },
+  "Bilahari": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N3"
+    ]
+  },
+  "Bēgaḍa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2",
+      "N3"
+    ]
+  },
+  "Dhanyāsi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G2",
+      "M1",
+      "P",
+      "D1",
+      "N2"
+    ]
+  },
+  "Dēvagāndhāri": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N3"
+    ]
+  },
+  "Gauḷa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G3",
+      "M1",
+      "P",
+      "N3"
+    ]
+  },
+  "Harikāmbhōji": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Hussēnī": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Kalyāṇi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M2",
+      "P",
+      "D2",
+      "N3"
+    ]
+  },
+  "Kamās": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Karaharapriya": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Kāmavardani": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G3",
+      "M2",
+      "P",
+      "D1",
+      "N3"
+    ]
+  },
+  "Kānaḍa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Kāpi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": []
+  },
+  "Kāṁbhōji": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Kēdāragauḷa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Madhyamāvati": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "M1",
+      "P",
+      "N2"
+    ]
+  },
+  "Mukhāri": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D1",
+      "D2",
+      "N2"
+    ]
+  },
+  "Māyāmāḷavagauḷa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G3",
+      "M1",
+      "P",
+      "D1",
+      "N3"
+    ]
+  },
+  "Mōhanaṁ": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "P",
+      "D2"
+    ]
+  },
+  "Nāṭa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": []
+  },
+  "Nāṭakurinji": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Pūrvīkaḷyāṇi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G3",
+      "M2",
+      "P",
+      "D2",
+      "N3"
+    ]
+  },
+  "Rītigauḷa": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Sahānā": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Sencuruṭṭi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Sindhubhairavi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": []
+  },
+  "Suraṭi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Sāma": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2"
+    ]
+  },
+  "Sāvēri": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G3",
+      "M1",
+      "P",
+      "D1",
+      "N3"
+    ]
+  },
+  "Tōḍi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R1",
+      "G2",
+      "M1",
+      "P",
+      "D1",
+      "N2"
+    ]
+  },
+  "Varāḷi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": []
+  },
+  "Yadukula kāṁbōji": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Ānandabhairavi": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": []
+  },
+  "Śankarābharaṇaṁ": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G3",
+      "M1",
+      "P",
+      "D2",
+      "N3"
+    ]
+  },
+  "Śrī": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "P",
+      "D2",
+      "N2"
+    ]
+  },
+  "Śrīranjani": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M1",
+      "D2",
+      "N2"
+    ]
+  },
+  "Ṣanmukhapriya": {
+    "arohana": "",
+    "avarohana": "",
+    "pakad": "",
+    "listen_for": "",
+    "vs": "",
+    "swaras": [
+      "S",
+      "R2",
+      "G2",
+      "M2",
+      "P",
+      "D1",
+      "N2"
+    ]
+  }
+}

raaga_id/__init__.py

@@ -0,0 +1,12 @@
+"""twelveswaras — raaga identification pipeline.
+
+An open "Shazam for raagas": infer the raaga of any Carnatic performance, paired
+with a CC-BY-4.0 data commons. Non-commercial, open-source only (PRD D1).
+
+Pipeline order (PRD §6.7):
+    audio -> [tonic ID + predominant-melody] -> normalize to Sa
+          -> features (swara histogram / TDMS / mel-CQT) -> model -> top-3.
+
+The tonic step (PRD D5, essentia/compIAM) is Phase 2 — Phase 1 is a librosa-only
+floor so we get a working baseline without native-lib pain on Apple Silicon.
+"""

raaga_id/calibrate.py

@@ -0,0 +1,98 @@
+"""Probability calibration + confidence state (D25).
+
+The shown %s are the mean of XGBoost softmax over a clip's windows — a *relative* ranking,
+not a true likelihood. Two fixes live here:
+
+1. **Temperature scaling** — one scalar T (fit offline on leak-free out-of-fold predictions,
+   `tools/calibrate.py`) reshapes the probabilities so the number means what it says, WITHOUT
+   changing which raaga wins (argmax-preserving). Stored in a `<model>.calib.json` sidecar.
+2. **Confidence state** — turns a flat top-2 into an honest "close call — X vs Y" instead of a
+   falsely-precise single answer.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+from .config import CLOSE_MARGIN, LOW_CONFIDENCE
+
+
+def apply_temperature(proba, temperature: float):
+    """Temperature-scale a probability vector (or a batch; classes = last axis).
+
+    q_i ∝ p_i**(1/T). T>1 flattens (less confident), T<1 sharpens, T=1 is identity. Monotone,
+    so the argmax (winning raaga) never changes — only the spread of the confidences does.
+    """
+    p = np.asarray(proba, dtype=float)
+    q = np.power(np.clip(p, 0.0, None), 1.0 / temperature)
+    s = q.sum(axis=-1, keepdims=True)
+    s = np.where(s == 0.0, 1.0, s)
+    return q / s
+
+
+def nll(P, y_idx, eps: float = 1e-12) -> float:
+    """Mean negative log-likelihood of the true class — the thing temperature scaling minimizes."""
+    P = np.atleast_2d(np.asarray(P, dtype=float))
+    y = np.asarray(y_idx)
+    picked = P[np.arange(len(y)), y]
+    return float(-np.mean(np.log(np.clip(picked, eps, 1.0))))
+
+
+def ece(P, y_idx, n_bins: int = 10) -> float:
+    """Expected calibration error: |confidence − accuracy| averaged over confidence bins.
+    0 = perfectly calibrated (a bin of "70% sure" predictions is right 70% of the time)."""
+    P = np.atleast_2d(np.asarray(P, dtype=float))
+    y = np.asarray(y_idx)
+    conf = P.max(axis=1)
+    correct = (P.argmax(axis=1) == y).astype(float)
+    edges = np.linspace(0.0, 1.0, n_bins + 1)
+    e = 0.0
+    for b in range(n_bins):
+        m = (conf > edges[b]) & (conf <= edges[b + 1])
+        if m.any():
+            e += m.mean() * abs(conf[m].mean() - correct[m].mean())
+    return float(e)
+
+
+def fit_temperature(P, y_idx, lo: float = 0.2, hi: float = 6.0, n: int = 60) -> float:
+    """Return the temperature over [lo, hi] (geometric grid) that minimizes NLL. Grid search —
+    no scipy dependency, and T needs no great precision."""
+    P = np.atleast_2d(np.asarray(P, dtype=float))
+    grid = np.geomspace(lo, hi, n)
+    losses = [nll(apply_temperature(P, T), y_idx) for T in grid]
+    return float(grid[int(np.argmin(losses))])
+
+
+def confidence_state(preds, low: float = LOW_CONFIDENCE, close_margin: float = CLOSE_MARGIN):
+    """Map a decoded top-k list to (state, note). `unsure` when the top score is below `low`;
+    else `close` when the top two are within `close_margin`; else `confident`."""
+    p1 = preds[0].confidence
+    p2 = preds[1].confidence if len(preds) > 1 else 0.0
+    if p1 < low:
+        return "unsure", "🤔 not sure — melody or tonic unclear; try a longer, cleaner clip with a drone"
+    if p1 - p2 < close_margin:
+        return "close", f"🤔 close call — {preds[0].raaga} vs {preds[1].raaga}"
+    return "confident", "✓ confident"
+
+
+# --- sidecar persistence: temperature lives next to the model as <model>.calib.json ---
+def temperature_path(model_path) -> Path:
+    return Path(model_path).with_suffix(".calib.json")
+
+
+def load_temperature(model_path, default: float = 1.0) -> float:
+    p = temperature_path(model_path)
+    if p.exists():
+        return float(json.loads(p.read_text()).get("temperature", default))
+    return default
+
+
+def save_temperature(model_path, temperature: float, extra: dict | None = None) -> Path:
+    p = temperature_path(model_path)
+    payload = {"temperature": float(temperature)}
+    if extra:
+        payload.update(extra)
+    p.write_text(json.dumps(payload, indent=2))
+    return p

raaga_id/config.py

@@ -0,0 +1,85 @@
+"""Shared constants, grounded in the PRD decisions log."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Repo layout (PRD §17). data/ and models/ are gitignored; benchmark/ is tracked.
+# Point the corpus at an external SSD without editing code: export TWELVESWARAS_DATA=/Volumes/....
+ROOT = Path(__file__).resolve().parent.parent
+DATA_DIR = Path(os.environ.get("TWELVESWARAS_DATA", ROOT / "data"))
+MODELS_DIR = ROOT / "models"
+BENCHMARK_DIR = ROOT / "benchmark"
+RAAGAS_PATH = ROOT / "raagas.json"
+
+# Audio (PRD §6.7 + D7).
+SAMPLE_RATE = 16_000       # 16 kHz mono throughout
+CLIP_SECONDS = 10.0        # D7: 10 s analysis window
+MIN_CLIP_SECONDS = 5.0     # D7: accept >=5 s with a warning
+HOP_SECONDS = 5.0          # stride when aggregating predictions across a long clip
+
+# Output UX (D6).
+TOP_K = 3                  # always show top-3 + confidence
+# Below this averaged top-1 probability -> "not sure". Calibrated to the v0 floor:
+# real clips average ~0.28-0.60 for the top class, near-random/percussion ~0.08-0.12
+# (uniform = 1/12 = 0.083), so 0.15 shows top-3 for real music and gates only noise.
+LOW_CONFIDENCE = 0.15
+# When the top two raagas are within this (calibrated) margin, call it a "close call — X vs Y"
+# rather than a confident single answer (D25). Allied raagas (Mōhanaṁ/Bilahari/Bēgaḍa …) share
+# a pitch-class profile, so an honest close-call is common and correct.
+CLOSE_MARGIN = 0.06
+INFER_MAX_WINDOWS = 60     # analyse ~first 10 min of a long upload (matches training)
+INFER_SECONDS = 90         # cap raw-audio analysed at inference — tonic salience is ~1min/2min
+PCD_BINS = 120             # pitch-class-distribution resolution (10-cent bins); the display feature
+
+# Production model feature = windowed Time-Delayed Melody Surface (D28). The gate benchmark
+# (tools/tdms_benchmark) put TDMS-30s at top1 0.866 / top3 0.954 vs windowed-PCD 0.780 / 0.926,
+# and the allied triple at 0.881 vs 0.714 — gamaka/movement is what the static PCD threw away.
+TDMS_BINS = 48             # surface is TDMS_BINS x TDMS_BINS (10-cent-ish, 25-cent bins over an octave)
+TDMS_DELAY = 0.3           # seconds; the (pitch(t), pitch(t+delay)) lag that exposes gamaka
+TDMS_WINDOW_S = 30.0       # 30 s windows — dense enough to fill the surface (10 s was too sparse)
+TDMS_HOP_S = 30.0
+TDMS_MAX_WINDOWS = 20      # cap windows/track in training (20 x 30 s = 600 s, matches the gate)
+# Junk gate (D6/D8): drop windows whose predominant-melody pitch is voiced less than this fraction
+# of the time — i.e. percussion solos, speech, applause, long silences, where there's no stable
+# melody for Melodia to track. Real melody is voiced most of the window; junk is mostly unvoiced.
+MIN_VOICED_FRAC = 0.5
+
+# Verification (D13). Configurable; these are the v0 defaults.
+PROMOTE_MIN_VOTES = 3
+PROMOTE_MIN_AGREEMENT = 0.80
+
+
+def load_raagas() -> dict:
+    """Return the controlled vocabulary from raagas.json (canonical + aliases)."""
+    import json
+
+    with open(RAAGAS_PATH, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def fold_raaga(name: str) -> str:
+    """Normalize a raaga name for matching: strip diacritics + case + separators.
+
+    Saraga uses diacritics (Mōhanaṁ, Tōḍi, Śudda sāvēri); our vocab/aliases are ASCII.
+    NFKD-decompose, drop combining marks, lowercase, keep only alphanumerics so
+    'Mōhanaṁ' and 'Mohanam' fold to the same key.
+    """
+    import unicodedata
+
+    decomposed = unicodedata.normalize("NFKD", name)
+    stripped = "".join(c for c in decomposed if not unicodedata.combining(c))
+    return "".join(c for c in stripped.lower() if c.isalnum())
+
+
+def canonical_raaga(name: str, vocab: dict | None = None) -> str:
+    """Map a raw raaga label to its canonical form via the alias table (diacritic-insensitive)."""
+    vocab = vocab or load_raagas()
+    key = fold_raaga(name)
+    for canon in vocab["canonical"]:
+        if key == fold_raaga(canon):
+            return canon
+    for canon, aliases in vocab.get("aliases", {}).items():
+        if key in {fold_raaga(a) for a in aliases}:
+            return canon
+    return name  # unknown -> pass through (surfaces as an out-of-vocab label)

raaga_id/data.py

@@ -0,0 +1,214 @@
+"""Data loading — Saraga Carnatic via mirdata (PRD §6.3, D10).
+
+Seed corpus for v0 is Saraga (D10). The multi-GB download is deliberately NOT run
+at import time; call `download_saraga()` explicitly (held until storage is
+confirmed). Everything here degrades to a clear error if the data is absent.
+"""
+from __future__ import annotations
+
+import json
+import random
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import BENCHMARK_DIR, DATA_DIR, canonical_raaga, fold_raaga, load_raagas
+
+FROZEN_TEST_PATH = BENCHMARK_DIR / "test_track_ids.json"
+
+SARAGA_DATASET = "saraga_carnatic"
+SARAGA_HOME = DATA_DIR / "saraga_carnatic"
+
+
+@dataclass
+class Clip:
+    """One labelled audio example: a path + its canonical raaga."""
+    track_id: str
+    audio_path: Path
+    raaga: str            # canonical (raagas.json)
+    tradition: str = "carnatic"
+    tonic_hz: float | None = None   # Saraga ctonic annotation (precise Sa), if present
+
+
+@dataclass
+class PitchClip:
+    """A labelled predominant-melody pitch track + its tonic — the PCD feature source.
+    Dataset-agnostic so Saraga and IAMRRD pool through the same path."""
+    dataset: str
+    track_id: str
+    raaga: str
+    tonic_hz: float
+    times: "object"        # np.ndarray of frame times (s)
+    freqs: "object"        # np.ndarray of f0 (Hz), 0/NaN where unvoiced
+
+
+def _dataset(download: bool = False):
+    import mirdata
+
+    ds = mirdata.initialize(SARAGA_DATASET, data_home=str(SARAGA_HOME))
+    if download:
+        ds.download()
+    return ds
+
+
+def download_saraga() -> Path:
+    """Download Saraga Carnatic into data/ (a few GB). Run once, on demand."""
+    SARAGA_HOME.mkdir(parents=True, exist_ok=True)
+    _dataset(download=True)
+    return SARAGA_HOME
+
+
+def iter_clips(only_vocab: bool = True):
+    """Yield Clip(track_id, audio_path, raaga) for every Saraga track with a raaga.
+
+    only_vocab=True keeps just the v0 controlled-vocabulary raagas (raagas.json).
+    """
+    ds = _dataset(download=False)
+    vocab = load_raagas()
+    keep = {r.lower().replace(" ", "") for r in vocab["canonical"]}
+
+    for track_id, track in ds.load_tracks().items():
+        raw = _raaga_of(track)
+        if not raw:
+            continue
+        canon = canonical_raaga(raw, vocab)
+        if only_vocab and canon.lower().replace(" ", "") not in keep:
+            continue
+        audio_path = getattr(track, "audio_path", None)
+        if not audio_path or not Path(audio_path).exists():
+            continue
+        yield Clip(track_id=track_id, audio_path=Path(audio_path), raaga=canon,
+                   tonic_hz=_tonic_of(track))
+
+
+def load_frozen_test() -> set[str] | None:
+    """The frozen held-out track ids, or None if no benchmark is frozen yet."""
+    if FROZEN_TEST_PATH.exists():
+        return set(json.loads(FROZEN_TEST_PATH.read_text()))
+    return None
+
+
+def freeze_test(test_ids: set[str]) -> Path:
+    """Write the benchmark test split ONCE. Refuses to overwrite an existing freeze
+    (build-order step 6: a frozen set stays frozen so scores stay comparable)."""
+    if FROZEN_TEST_PATH.exists():
+        raise FileExistsError(f"{FROZEN_TEST_PATH} already frozen — delete it to re-split.")
+    FROZEN_TEST_PATH.parent.mkdir(parents=True, exist_ok=True)
+    FROZEN_TEST_PATH.write_text(json.dumps(sorted(test_ids), indent=2) + "\n")
+    return FROZEN_TEST_PATH
+
+
+def split_by_track(clips: list[Clip], test_frac: float = 0.25, seed: int = 0) -> tuple[set[str], set[str]]:
+    """Return (train_ids, test_ids), split BY TRACK so windows never leak across the
+    split, stratified per raaga. Honors an existing frozen test set; otherwise draws a
+    deterministic split and freezes it.
+    """
+    all_ids = {c.track_id for c in clips}
+    frozen = load_frozen_test()
+    if frozen is not None:
+        test = frozen & all_ids
+        return all_ids - test, test
+
+    by_raaga: dict[str, list[str]] = defaultdict(list)
+    for c in clips:
+        by_raaga[c.raaga].append(c.track_id)
+
+    rng = random.Random(seed)
+    test: set[str] = set()
+    for raaga, ids in by_raaga.items():
+        ids = sorted(ids)
+        rng.shuffle(ids)
+        n_test = int(len(ids) * test_frac)
+        if len(ids) >= 2:                       # keep >=1 in each side when possible
+            n_test = max(1, n_test)
+        test.update(ids[:n_test])
+
+    freeze_test(test)
+    return all_ids - test, test
+
+
+def _raga_name(val) -> str | None:
+    """Extract a raaga name from the various shapes mirdata returns (str / dict / list)."""
+    if isinstance(val, str) and val.strip():
+        return val
+    if isinstance(val, dict):
+        return val.get("name")
+    if isinstance(val, (list, tuple)) and val:
+        first = val[0]
+        return first.get("name") if isinstance(first, dict) else str(first)
+    return None
+
+
+def _raaga_of(track) -> str | None:
+    """Raaga label across schemas: IAMRRD's ``track.raga`` (name string) or Saraga's
+    ``track.metadata["raaga"]`` (list of dicts with a ``name``)."""
+    try:
+        name = _raga_name(getattr(track, "raga", None))   # IAMRRD (compmusic_raga)
+    except Exception:  # noqa: BLE001
+        name = None
+    if name:
+        return name
+    try:
+        meta = track.metadata                             # Saraga
+    except Exception:  # noqa: BLE001 — missing/corrupt per-track metadata json
+        return None
+    return _raga_name(meta.get("raaga")) if meta else None
+
+
+def _tradition_of(track, default: str = "carnatic") -> str:
+    """Track tradition (carnatic/hindustani). IAMRRD sets ``track.tradition``; Saraga
+    Carnatic has none, so it defaults to carnatic."""
+    try:
+        t = getattr(track, "tradition", None)
+    except Exception:  # noqa: BLE001
+        t = None
+    return t.lower() if isinstance(t, str) and t else default
+
+
+def _tonic_of(track) -> float | None:
+    """Saraga's ctonic annotation (tonic in Hz), if present. mirdata exposes it as
+    ``track.tonic`` (loads the .ctonic file) — the precise Sa for tonic normalization."""
+    try:
+        t = track.tonic
+    except Exception:  # noqa: BLE001 — missing/unreadable ctonic file
+        return None
+    return float(t) if isinstance(t, (int, float)) and t > 0 else None
+
+
+def _pitch_of(track):
+    """(times, freqs) from a track's predominant-melody pitch annotation, or None.
+    Handles Saraga (``track.pitch``) and IAMRRD (``pitch`` / ``pitch_post_processed``)."""
+    for attr in ("pitch", "pitch_post_processed"):
+        try:
+            p = getattr(track, attr, None)
+        except Exception:  # noqa: BLE001 — missing/unreadable pitch file
+            continue
+        if p is not None and getattr(p, "frequencies", None) is not None:
+            return p.times, p.frequencies
+    return None
+
+
+def iter_pitch_clips(only_vocab: bool = True, datasets=("saraga_carnatic",), tradition="carnatic"):
+    """Yield PitchClip across datasets — a labelled pitch track + tonic per recording.
+    Filters to one tradition (Hindustani shares raaga names like Bhairavi/Todi but they
+    are different ragas). Skips tracks missing a raaga, tonic, or pitch annotation."""
+    import mirdata
+
+    vocab = load_raagas()
+    keep = {fold_raaga(r) for r in vocab["canonical"]}
+    for name in datasets:
+        ds = mirdata.initialize(name, data_home=str(DATA_DIR / name))
+        for track_id, track in ds.load_tracks().items():
+            if tradition and _tradition_of(track) != tradition:
+                continue
+            raw = _raaga_of(track)
+            if not raw:
+                continue
+            canon = canonical_raaga(raw, vocab)
+            if only_vocab and fold_raaga(canon) not in keep:
+                continue
+            tonic = _tonic_of(track)
+            pitch = _pitch_of(track)
+            if not tonic or pitch is None:
+                continue
+            yield PitchClip(name, track_id, canon, tonic, pitch[0], pitch[1])

raaga_id/evaluate.py

@@ -0,0 +1,52 @@
+"""Evaluation against the frozen benchmark (PRD §15, build-order step 6).
+
+    python -m raaga_id.evaluate --model models/raaga_xgb.json
+
+Scores per TRACK on the frozen test split: PCD-window each held-out recording, average
+the window probabilities (D7), take top-k, compare to the true raaga. Top-3 is the
+headline (the product shows top-3, D6). The frozen benchmark stays the original Saraga
+test tracks so numbers compare across features/data.
+"""
+from __future__ import annotations
+
+import argparse
+
+import numpy as np
+
+from . import data, features
+from .config import TOP_K
+from .model import RaagaXGB
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Score the raaga model on the frozen benchmark.")
+    ap.add_argument("--model", required=True)
+    ap.add_argument("--datasets", nargs="+", default=["saraga_carnatic"])
+    ap.add_argument("--max-windows", type=int, default=None)
+    args = ap.parse_args()
+
+    model = RaagaXGB.load(args.model)
+    frozen = data.load_frozen_test()
+    if frozen is None:
+        raise SystemExit("No frozen benchmark yet — run `python -m raaga_id.train` first "
+                         "(it freezes benchmark/test_track_ids.json).")
+
+    top1 = top3 = n = 0
+    for pc in data.iter_pitch_clips(only_vocab=True, datasets=tuple(args.datasets)):
+        if pc.track_id not in frozen:
+            continue
+        wins = features.model_windows(pc.times, pc.freqs, pc.tonic_hz, max_windows=args.max_windows)
+        if not wins:
+            continue
+        names = [p.raaga for p in model.aggregate_top_k(np.vstack(wins), k=TOP_K)]
+        n += 1
+        top1 += int(names[0] == pc.raaga)
+        top3 += int(pc.raaga in names)
+
+    if n == 0:
+        raise SystemExit("no evaluation tracks matched the frozen split — check the data.")
+    print(f"n={n} tracks  top1={top1 / n:.3f}  top{TOP_K}={top3 / n:.3f}")
+
+
+if __name__ == "__main__":
+    main()

raaga_id/features.py

@@ -0,0 +1,288 @@
+"""Feature extraction.
+
+Modeling ladder (D16): tonic-normalized pitch-class/swara histogram + XGBoost floor
+-> TDMS -> CNN on mel/CQT. The floor (D16 step 1) is a librosa chroma histogram rolled
+so the tonic (Sa) sits at bin 0 (D5). The tonic comes from Saraga's ctonic annotation
+when available (precise), else a drone-argmax estimate; essentia TonicIndianArtMusic is
+the inference-time upgrade for unlabelled clips (Phase 2).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .config import CLIP_SECONDS, MIN_CLIP_SECONDS, MIN_VOICED_FRAC, SAMPLE_RATE
+
+
+def _voiced_fraction(seg) -> float:
+    """Fraction of a window's predominant-melody frames that carry a pitch (f0>0). Low for
+    percussion/speech/applause/silence (the junk gate, D6/D8); high for real melody."""
+    seg = np.asarray(seg, dtype=float)
+    return float((seg > 0).mean()) if seg.size else 0.0
+
+
+def load_audio(path: str, sr: int = SAMPLE_RATE, duration: float | None = None) -> np.ndarray:
+    """Decode any format to mono float32 at `sr` (ffmpeg handles mp3/m4a).
+
+    `duration` caps the decode length — Saraga tracks run 20-30 min, so decoding the
+    whole file to use only the first N windows wastes most of the work.
+    """
+    import librosa
+
+    y, _ = librosa.load(path, sr=sr, mono=True, duration=duration)
+    return y.astype(np.float32)
+
+
+def estimate_tonic_pc(y: np.ndarray, sr: int = SAMPLE_RATE) -> int:
+    """Cheap tonic (Sa) estimate: the most energetic pitch class over the clip.
+
+    Carnatic performances carry a continuous tanpura drone on Sa, so the summed
+    chromagram peaks at the tonic. This is the librosa-only stand-in for the precise
+    essentia `TonicIndianArtMusic` used in Phase 2 (D5).
+    """
+    import librosa
+
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+    return int(chroma.mean(axis=1).argmax())
+
+
+def tonic_pc_from_hz(hz: float) -> int:
+    """Map a tonic frequency (Hz) to its chroma pitch class (0-11). Used with a
+    precise tonic — Saraga's ctonic annotation, or essentia at inference."""
+    import librosa
+
+    return int(round(librosa.hz_to_midi(hz))) % 12
+
+
+# 12 semitone positions relative to Sa (common Carnatic labels for the swara-sthanas).
+SWARA_LABELS = ["S", "R1", "R2", "G2", "G3", "M1", "M2", "P", "D1", "D2", "N2", "N3"]
+
+# The seven swaras every learner knows. For the "how to hear this raaga" panel we fold the 12
+# chromatic positions down to these names (sa ri ga ma pa da ni) — the beginner's vocabulary,
+# not the R1/R2/G2/G3 sthana subscripts. Each name groups its sthana variants.
+SWARA7 = ["Sa", "Ri", "Ga", "Ma", "Pa", "Da", "Ni"]
+_SWARA7_GROUPS = [[0], [1, 2], [3, 4], [5, 6], [7], [8, 9], [10, 11]]  # indices into SWARA_LABELS
+
+
+def to_swaras7(profile):
+    """Fold a 12-position swara profile to the seven named swaras (SWARA7), summing each swara's
+    sthana variants. Returns (names, values). The friendly display unit for new learners."""
+    p = np.asarray(profile, dtype=float)
+    vals = np.array([p[g].sum() for g in _SWARA7_GROUPS])
+    return SWARA7, vals
+
+
+def pcd_to_swaras(pcd) -> np.ndarray:
+    """Fold a fine PCD (n_bins, a multiple of 12) to a 12-position swara profile
+    (one bin per semitone), normalized — the human-readable raaga fingerprint."""
+    a = np.asarray(pcd, dtype=float)
+    a = a.reshape(12, a.size // 12).sum(axis=1)
+    return a / (a.sum() + 1e-9)
+
+
+def pitch_class_histogram(f0_hz, tonic_hz: float, n_bins: int = 120) -> np.ndarray:
+    """Tonic-normalized pitch-class distribution (PCD) from a predominant-melody pitch
+    track — the classic raaga fingerprint (D16). Each voiced f0 becomes cents relative
+    to Sa, folded to one octave, binned and normalized; unvoiced frames (f0<=0) are
+    ignored. Works on any (pitch, tonic) source, so Saraga and IAMRRD pool cleanly.
+    Returns zeros when nothing is voiced.
+    """
+    f0 = np.asarray(f0_hz, dtype=float)
+    voiced = f0[f0 > 0]
+    if voiced.size == 0:
+        return np.zeros(n_bins, dtype=np.float32)
+    cents = 1200.0 * np.log2(voiced / tonic_hz)
+    bins = np.mod((np.mod(cents, 1200.0) / (1200.0 / n_bins)).astype(int), n_bins)
+    hist = np.bincount(bins, minlength=n_bins).astype(np.float32)
+    return hist / hist.sum()
+
+
+def tdms(times, f0_hz, tonic_hz: float, delay: float = 0.3, n_bins: int = 48) -> np.ndarray:
+    """Time-Delayed Melody Surface (Gulati et al., ISMIR 2016) — the gamaka feature (refines
+    D16). A 2-D histogram of (pitch(t), pitch(t+delay)) over the tonic-normalized, octave-folded
+    melody: a held note sits on the diagonal, while gamaka/transitions smear off-diagonal in a
+    raaga-characteristic way. This keeps the *movement* the 1-D PCD discards — the information
+    that should separate allied raagas (Mōhanaṁ/Bilahari/Bēgaḍa) which share a scale.
+
+    Returns a flat (n_bins*n_bins,) surface normalized to sum 1, or zeros when too few voiced
+    pairs. `delay` is in seconds; the frame hop is inferred from `times`.
+    """
+    times = np.asarray(times, dtype=float)
+    f0 = np.asarray(f0_hz, dtype=float)
+    zeros = np.zeros(n_bins * n_bins, dtype=np.float32)
+    if times.size < 2:
+        return zeros
+    voiced = f0 > 0
+    cents = np.zeros_like(f0)
+    cents[voiced] = np.mod(1200.0 * np.log2(f0[voiced] / tonic_hz), 1200.0)
+    bins = np.mod((cents / (1200.0 / n_bins)).astype(int), n_bins)
+
+    hop = float(np.median(np.diff(times)))
+    d = max(1, int(round(delay / hop)))
+    if d >= bins.size:
+        return zeros
+    a, b = bins[:-d], bins[d:]
+    both = voiced[:-d] & voiced[d:]          # count a pair only if both endpoints are voiced
+    a, b = a[both], b[both]
+    if a.size == 0:
+        return zeros
+    surf = np.zeros((n_bins, n_bins), dtype=np.float64)
+    np.add.at(surf, (a, b), 1.0)
+    return (surf / surf.sum()).astype(np.float32).ravel()
+
+
+def tdms_windows(
+    times,
+    f0_hz,
+    tonic_hz: float,
+    window_s: float = CLIP_SECONDS,
+    hop_s: float = CLIP_SECONDS,
+    max_windows: int | None = None,
+    delay: float = 0.3,
+    n_bins: int = 48,
+    min_voiced: float = MIN_VOICED_FRAC,
+) -> list[np.ndarray]:
+    """Slide a window over a predominant-melody pitch track -> one TDMS surface per window
+    (the delay-surface analog of pitch_windows, D28). Slices identically to pitch_windows so
+    surfaces aggregate exactly like PCD windows. Windows voiced less than `min_voiced` of the
+    time are dropped (junk gate, D6/D8 — percussion/speech/silence, no stable melody to track).
+    """
+    times = np.asarray(times, dtype=float)
+    f0 = np.asarray(f0_hz, dtype=float)
+    if times.size == 0 or times[-1] < MIN_CLIP_SECONDS:
+        return []
+    end = float(times[-1])
+    out: list[np.ndarray] = []
+    start = 0.0
+    while start < end:
+        if min(start + window_s, end) - start < MIN_CLIP_SECONDS:
+            break
+        mask = (times >= start) & (times < start + window_s)
+        if _voiced_fraction(f0[mask]) >= min_voiced:
+            surf = tdms(times[mask], f0[mask], tonic_hz, delay=delay, n_bins=n_bins)
+            if surf.sum() > 0:
+                out.append(surf)
+        if max_windows and len(out) >= max_windows:
+            break
+        start += hop_s
+    return out
+
+
+def model_windows(times, f0_hz, tonic_hz: float, max_windows: int | None = None,
+                  hop_s: float | None = None) -> list[np.ndarray]:
+    """THE production model feature (D28): windowed TDMS at the config's winning settings.
+    train / evaluate / calibrate / inference all call this one function, so the feature can
+    never drift between how the model is trained and how it's served. `hop_s` overrides only the
+    stride — inference passes a smaller hop so a short clip yields more windows to average (each
+    window is still classified independently, so overlap is safe and doesn't change the feature).
+    """
+    from .config import TDMS_BINS, TDMS_DELAY, TDMS_HOP_S, TDMS_MAX_WINDOWS, TDMS_WINDOW_S
+
+    return tdms_windows(times, f0_hz, tonic_hz, window_s=TDMS_WINDOW_S, hop_s=hop_s or TDMS_HOP_S,
+                        max_windows=max_windows or TDMS_MAX_WINDOWS, delay=TDMS_DELAY, n_bins=TDMS_BINS)
+
+
+def frame_vector(y: np.ndarray, sr: int = SAMPLE_RATE, tonic_pc: int = 0) -> np.ndarray:
+    """Tonic-relative pitch-class descriptor for one window (D16 step 1).
+
+    Raaga lives in the pitch classes *relative to Sa*, so we roll the chromagram so
+    the tonic pitch class -> bin 0, then summarize as a normalized 12-bin pitch-class
+    histogram (the raaga fingerprint) + per-bin spread. Timbre features (MFCC,
+    spectral shape) are deliberately EXCLUDED: they encode recording/instrument
+    identity and make the model memorize tracks instead of learning raaga.
+    """
+    import librosa
+
+    if y.size == 0:
+        raise ValueError("empty audio")
+
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+    chroma = np.roll(chroma, -tonic_pc, axis=0)          # tonic -> bin 0
+    hist = chroma.mean(axis=1)
+    hist = hist / (hist.sum() + 1e-8)                     # pitch-class distribution
+    return np.concatenate([hist, chroma.std(axis=1)]).astype(np.float32)  # 24-dim
+
+
+def window_vectors(
+    y: np.ndarray,
+    sr: int = SAMPLE_RATE,
+    window_s: float = CLIP_SECONDS,
+    hop_s: float = CLIP_SECONDS,
+    max_windows: int | None = None,
+    tonic_hz: float | None = None,
+) -> list[np.ndarray]:
+    """Slide a `window_s` window over a (long) clip -> one frame vector per window.
+
+    Saraga tracks are full concert recordings, so one vector per track would be a
+    single over-smoothed sample. Windowing (D7: 10 s) turns each recording into many
+    training examples. Tail segments shorter than MIN_CLIP_SECONDS are dropped;
+    hop_s == window_s gives non-overlapping windows (the training default).
+    """
+    win = int(round(window_s * sr))
+    hop = max(1, int(round(hop_s * sr)))
+    min_len = int(round(MIN_CLIP_SECONDS * sr))
+    if len(y) < min_len:
+        return []
+    if max_windows:  # only look at the span we'll use (fast tonic estimate on long uploads)
+        y = y[: win + hop * (max_windows - 1)]
+    # Prefer a precise tonic (Saraga ctonic) when given; else the drone-argmax heuristic.
+    tonic_pc = tonic_pc_from_hz(tonic_hz) if tonic_hz else estimate_tonic_pc(y, sr)
+    out: list[np.ndarray] = []
+    start = 0
+    while start < len(y):
+        seg = y[start : start + win]
+        if len(seg) < min_len:
+            break
+        out.append(frame_vector(seg, sr, tonic_pc))
+        if max_windows and len(out) >= max_windows:
+            break
+        start += hop
+    return out
+
+
+def pitch_windows(
+    times,
+    f0_hz,
+    tonic_hz: float,
+    window_s: float = CLIP_SECONDS,
+    hop_s: float = CLIP_SECONDS,
+    max_windows: int | None = None,
+    n_bins: int = 120,
+    min_voiced: float = MIN_VOICED_FRAC,
+) -> list[np.ndarray]:
+    """Slide a window over a predominant-melody pitch track -> one tonic-normalized PCD
+    per window (the pitch-track analog of window_vectors, D7). Windows that are voiced less
+    than `min_voiced` of the time are dropped (junk gate, D6/D8 — percussion/speech/silence);
+    a trailing window >= MIN_CLIP_SECONDS is kept. Works on any (pitch, tonic) source.
+    """
+    times = np.asarray(times, dtype=float)
+    f0 = np.asarray(f0_hz, dtype=float)
+    if times.size == 0 or times[-1] < MIN_CLIP_SECONDS:
+        return []
+    end = float(times[-1])
+    out: list[np.ndarray] = []
+    start = 0.0
+    while start < end:
+        if min(start + window_s, end) - start < MIN_CLIP_SECONDS:
+            break
+        seg = f0[(times >= start) & (times < start + window_s)]
+        if _voiced_fraction(seg) >= min_voiced:
+            hist = pitch_class_histogram(seg, tonic_hz, n_bins)
+            if hist.sum() > 0:
+                out.append(hist)
+        if max_windows and len(out) >= max_windows:
+            break
+        start += hop_s
+    return out
+
+
+def extract_windows(
+    path: str,
+    sr: int = SAMPLE_RATE,
+    max_windows: int | None = None,
+    tonic_hz: float | None = None,
+) -> list[np.ndarray]:
+    """Load a (long) recording and return one frame vector per 10 s window.
+    Pass tonic_hz (Saraga ctonic) for a precise tonic; otherwise it's estimated."""
+    duration = None if max_windows is None else max_windows * CLIP_SECONDS + 1.0
+    y = load_audio(path, sr, duration=duration)
+    return window_vectors(y, sr, max_windows=max_windows, tonic_hz=tonic_hz)

raaga_id/learn.py

@@ -0,0 +1,159 @@
+"""'How to hear this raaga' — the data-derived learner layer (PRD §16.1).
+
+Reference swara profiles are computed from the corpus (tools/build_raaga_profiles.py);
+the summary is auto-generated from the pitch data (safe). The curated guide
+(arohana/avarohana/pakad/contrasts) is EXPERT-vetted content loaded from
+raaga_guide.json — never auto-generated here, because wrong musicology is worse than
+none. All loaders degrade gracefully when the files are absent.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+
+import numpy as np
+
+from .config import ROOT
+from .features import to_swaras7
+
+PROFILES_PATH = ROOT / "raaga_profiles.json"
+GUIDE_PATH = ROOT / "raaga_guide.json"
+
+
+@lru_cache(maxsize=1)
+def _profiles() -> dict:
+    return json.loads(PROFILES_PATH.read_text()) if PROFILES_PATH.exists() else {}
+
+
+@lru_cache(maxsize=1)
+def _guide() -> dict:
+    return json.loads(GUIDE_PATH.read_text()) if GUIDE_PATH.exists() else {}
+
+
+def reference_profile(raaga: str):
+    """The raaga's average 12-position swara profile, or None if not built yet."""
+    p = _profiles().get(raaga)
+    return np.asarray(p, dtype=float) if p else None
+
+
+def top_swaras(profile, k: int = 4) -> list[str]:
+    """The k swaras the raaga rests on most, by their everyday names (Sa Ri Ga Ma Pa Da Ni),
+    dropping ones it barely touches."""
+    names, vals = to_swaras7(profile)
+    order = np.argsort(vals)[::-1][:k]
+    return [names[i] for i in order if vals[i] > 0.03]
+
+
+def guide(raaga: str) -> dict:
+    """Curated per-raaga notes, empty fields dropped ({} until an expert fills them in)."""
+    return {k: v for k, v in _guide().get(raaga, {}).items() if v}
+
+
+# --- Allied-raaga comparison (D29 Explorer): how to tell two close-call raagas apart, from their
+# swara SETS (which of the 12 notes each uses — a documented fact). Seed sets live in
+# raaga_guide.json["swaras"]; empty until seeded/expert-filled. Beginner-friendly note names below;
+# a variety qualifier is only added when two raagas share a base note but differ in its variety.
+from .features import SWARA_LABELS  # noqa: E402
+
+_BASE = {"S": "sa", "R1": "ri", "R2": "ri", "G2": "ga", "G3": "ga", "M1": "ma", "M2": "ma",
+         "P": "pa", "D1": "da", "D2": "da", "N2": "ni", "N3": "ni"}
+_VARIETY = {"R1": "the lower ri", "R2": "ri", "G2": "the lower ga", "G3": "ga",
+            "M1": "the natural ma", "M2": "the sharp ma (prati-madhyama)", "D1": "the lower da",
+            "D2": "da", "N2": "ni", "N3": "the sharp ni"}
+_SEED_OVERRIDE = None  # tests inject swara sets here without touching the guide file
+
+
+def swaras(raaga: str):
+    """The raaga's swara set (12-position labels), or None if not seeded/filled."""
+    if _SEED_OVERRIDE is not None and raaga in _SEED_OVERRIDE:
+        return _SEED_OVERRIDE[raaga]
+    s = _guide().get(raaga, {}).get("swaras")
+    return s or None
+
+
+def distinguish(a: str, b: str):
+    """Set-difference of two raagas' swaras, or None if either lacks data. Returns which notes
+    each has that the other doesn't (ordered), and whether the sets are identical."""
+    sa, sb = swaras(a), swaras(b)
+    if not sa or not sb:
+        return None
+    order = {lab: i for i, lab in enumerate(SWARA_LABELS)}
+    A, B = set(sa), set(sb)
+    return {"a_only": sorted(A - B, key=lambda x: order.get(x, 99)),
+            "b_only": sorted(B - A, key=lambda x: order.get(x, 99)),
+            "same": A == B}
+
+
+_ORDER7 = ["sa", "ri", "ga", "ma", "pa", "da", "ni"]
+
+
+def _join(names) -> str:
+    names = list(dict.fromkeys(names))  # dedupe, keep order
+    if len(names) <= 2:
+        return " and ".join(names)
+    return ", ".join(names[:-1]) + " and " + names[-1]
+
+
+def _variety_desc(labels) -> str:
+    """Describe the varieties of ONE base note a raaga uses (e.g. both dhaivatas, or the sharp ni)."""
+    return f"both {_BASE[labels[0]]}s" if len(labels) >= 2 else _VARIETY[labels[0]]
+
+
+def comparison_md(a: str, b: str) -> str:
+    """A plain-language 'how to tell them apart' line for a close call, or '' if no data.
+    Compares base note by base note so it stays correct for bhashanga raagas that use *both*
+    varieties of a note (e.g. Bhairavi's two dhaivatas)."""
+    sa, sb = swaras(a), swaras(b)
+    if not sa or not sb:
+        return ""
+    A, B = set(sa), set(sb)
+    if A == B:
+        return (f"**Telling {a} from {b}:** they use the **same notes** — the difference is in the "
+                f"*gamaka* (how each note is shaken and slid) and the phrasing, not the scale. "
+                f"(Phrase guidance coming soon.)")
+    a_extra, b_extra, variety = [], [], []
+    for base in _ORDER7:
+        av = [x for x in A if _BASE[x] == base]
+        bv = [x for x in B if _BASE[x] == base]
+        if set(av) == set(bv):
+            continue
+        if av and not bv:
+            a_extra.append(base)          # a has this note entirely, b doesn't
+        elif bv and not av:
+            b_extra.append(base)
+        else:                              # both have the note but in different varieties
+            variety.append((base, av, bv))
+    parts = [f"the **{base}** differs — {a} uses {_variety_desc(av)}, {b} uses {_variety_desc(bv)}"
+             for base, av, bv in variety]
+    if b_extra:
+        parts.append(f"{b} uses **{_join(b_extra)}**, which {a} leaves out")
+    if a_extra:
+        parts.append(f"{a} uses **{_join(a_extra)}**, which {b} leaves out")
+    return f"**Telling {a} from {b}:** " + "; ".join(parts) + ". Listen for those notes."
+
+
+def summary_md(raaga: str, user_profile=None) -> str:
+    """A warm, plain-language 'how to hear this raaga' note for someone new to Carnatic music —
+    which of the seven swaras the raaga rests on, what their clip leaned on, and (when an expert
+    has filled it in) the raaga's ascent/descent and its telltale phrase."""
+    lines = [f"### How to hear **{raaga}**",
+             "Every raaga is a way of moving through the seven swaras — "
+             "**sa · ri · ga · ma · pa · da · ni**. Here's what to listen for."]
+    # NB: we do NOT auto-state which swaras the *raaga* uses — the data profiles are gamaka-
+    # smeared (ornaments glide pitch across neighbours), so that claim can be wrong. The raaga's
+    # actual notes belong to the expert guide below. We only describe the user's own clip.
+    if user_profile is not None:
+        lines.append(f"In your clip, the melody sat mostly on **{' · '.join(top_swaras(user_profile))}** — "
+                     "the notes it kept returning to.")
+
+    g = guide(raaga)
+    if g:
+        for label, key in (("Going up", "arohana"), ("Coming down", "avarohana"),
+                           ("Its signature phrase", "pakad"), ("Listen for", "listen_for"),
+                           ("Easy to mix up with", "vs")):
+            if g.get(key):
+                lines.append(f"- **{label}:** {g[key]}")
+    else:
+        lines.append("_More on the way — how the raaga rises and falls, its signature phrase, "
+                     "and the raagas it's easy to mix up with (written by musicians, not guessed)._")
+    return "\n\n".join(lines)

raaga_id/model.py

@@ -0,0 +1,95 @@
+"""Model: architecture + load/save (PRD §17).
+
+Framework is PyTorch (D15). The v0 floor (D16 step 1) is an XGBoost classifier over
+the fixed-length frame vector — cheap, strong, trains in minutes on CPU. The CNN /
+TDMS / transformer rungs come later; `RaagaCNN` is a stub marking that seam.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from .config import MODELS_DIR, TOP_K
+
+
+@dataclass
+class Prediction:
+    raaga: str
+    confidence: float
+
+
+class RaagaXGB:
+    """XGBoost floor over frame vectors. Wraps label<->index + top-k decode."""
+
+    def __init__(self, classes: list[str], booster=None, temperature: float = 1.0):
+        self.classes = list(classes)
+        self._booster = booster
+        self.temperature = temperature   # calibration (D25); 1.0 = uncalibrated identity
+
+    def fit(self, X: np.ndarray, y_idx: np.ndarray, **kwargs):
+        from xgboost import XGBClassifier
+
+        self._booster = XGBClassifier(
+            objective="multi:softprob",
+            num_class=len(self.classes),
+            n_estimators=kwargs.pop("n_estimators", 400),
+            max_depth=kwargs.pop("max_depth", 6),
+            learning_rate=kwargs.pop("learning_rate", 0.1),
+            n_jobs=-1,
+            **kwargs,
+        )
+        self._booster.fit(X, y_idx)
+        return self
+
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        if self._booster is None:
+            raise RuntimeError("model is not trained/loaded")
+        return self._booster.predict_proba(X)
+
+    def top_k(self, x: np.ndarray, k: int = TOP_K) -> list[Prediction]:
+        """Top-k raagas + confidence for one frame vector (D6: always top-3)."""
+        proba = self.predict_proba(x.reshape(1, -1))[0]
+        return self._decode(proba, k)
+
+    def aggregate_top_k(self, X: np.ndarray, k: int = TOP_K) -> list[Prediction]:
+        """Top-k for a clip given its per-window vectors: mean the window
+        probabilities, then decode (D7: aggregate predictions across a long clip)."""
+        X = np.atleast_2d(X)
+        proba = self.predict_proba(X).mean(axis=0)
+        return self._decode(proba, k)
+
+    def _decode(self, proba: np.ndarray, k: int) -> list[Prediction]:
+        from .calibrate import apply_temperature
+        proba = apply_temperature(proba, self.temperature)   # D25; argmax-preserving
+        order = np.argsort(proba)[::-1][:k]
+        return [Prediction(self.classes[i], float(proba[i])) for i in order]
+
+    def save(self, path: str | Path | None = None) -> Path:
+        path = Path(path) if path else MODELS_DIR / "raaga_xgb.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._booster.save_model(str(path))
+        path.with_suffix(".classes.json").write_text(json.dumps(self.classes))
+        return path
+
+    @classmethod
+    def load(cls, path: str | Path) -> "RaagaXGB":
+        from xgboost import XGBClassifier
+
+        from .calibrate import load_temperature
+
+        path = Path(path)
+        booster = XGBClassifier()
+        booster.load_model(str(path))
+        classes = json.loads(path.with_suffix(".classes.json").read_text())
+        return cls(classes, booster, temperature=load_temperature(path))
+
+
+class RaagaCNN:
+    """PHASE 2 SEAM (D16). CNN on tonic-normalized mel/CQT, in torch/Lightning.
+    Benchmark target: compIAM `DEEPSRGM`."""
+
+    def __init__(self, *_, **__):
+        raise NotImplementedError("CNN rung — implement after the XGBoost floor lands")

raaga_id/pitch_extract.py

@@ -0,0 +1,82 @@
+"""Inference-time audio -> model feature windows.
+
+Extracts the predominant-melody pitch (essentia PredominantPitchMelodia) and the tonic
+(compiam TonicIndianMultiPitch = the Salamon/Gulati multipitch method, which exploits the
+drone), then builds windowed TDMS (D28) via features.model_windows — the SAME feature the
+model trains on. This is the audio->feature path for a RAW upload; the annotated-corpus path
+(data.iter_pitch_clips) uses each dataset's own pitch+tonic instead.
+
+REQUIRES the numpy<2 inference env (environment-inference.yml): essentia's compute is
+broken under numpy 2.x. essentia/compiam are imported lazily so this module still imports
+(harmlessly) in the numpy-2.x training env.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from . import features
+from .config import INFER_MAX_WINDOWS, INFER_SECONDS, MIN_CLIP_SECONDS, PCD_BINS, TDMS_HOP_S
+
+TONIC_SR = 44100          # essentia's native rate for pitch + tonic
+MELODIA_HOP = 128
+
+_MELODIA = None
+_TONIC = None
+
+
+def _extractors():
+    """Import + instantiate the essentia/compiam extractors ONCE, then reuse. Importing
+    compiam is the slow (~tens of s) one-time cost; instantiating and reusing the
+    algorithms keeps every identify ~3.5s. Call warmup() at startup to pay it upfront."""
+    global _MELODIA, _TONIC
+    if _MELODIA is None:
+        from compiam.melody.tonic_identification.tonic_multipitch import TonicIndianMultiPitch
+        from essentia.standard import PredominantPitchMelodia
+
+        _MELODIA = PredominantPitchMelodia(hopSize=MELODIA_HOP, sampleRate=TONIC_SR)
+        _TONIC = TonicIndianMultiPitch()
+    return _MELODIA, _TONIC
+
+
+def warmup() -> None:
+    """Pre-load the extractors so the first identify isn't slow (call at demo startup)."""
+    _extractors()
+
+
+def audio_to_features(audio, sr, max_seconds: float = INFER_SECONDS, max_windows: int = INFER_MAX_WINDOWS):
+    """Raw mono audio -> (list of model-feature windows, tonic_hz, analysed_seconds, display_pcd).
+
+    The model windows are windowed TDMS (D28), IDENTICAL to training via features.model_windows.
+    display_pcd is the tonic-normalized pitch-class distribution over the whole analysed span —
+    used ONLY for the learner panel's human-readable swara fingerprint, never by the model.
+    analysed_seconds is how much audio (from 0:00) was actually fed to the model — capped at
+    max_seconds — so the UI can tell the user exactly what it heard (D24: legible recognition).
+    Returns ([], None, 0.0, None) when the tonic or pitch can't be estimated (no clear melody/drone).
+    """
+    import librosa
+
+    melodia, tonic_algo = _extractors()
+    y = np.asarray(audio, dtype=np.float32)
+    if y.ndim > 1:
+        y = y.mean(axis=1).astype(np.float32)
+    if sr != TONIC_SR:
+        y = librosa.resample(y, orig_sr=sr, target_sr=TONIC_SR).astype(np.float32)
+    if max_seconds:
+        y = y[: int(max_seconds * TONIC_SR)]
+    if y.size < int(MIN_CLIP_SECONDS * TONIC_SR):
+        return [], None, 0.0, None
+    analysed_seconds = y.size / TONIC_SR
+
+    try:
+        tonic = float(tonic_algo.extract(y, input_sr=TONIC_SR))
+    except Exception:  # noqa: BLE001 — essentia raises "No peak locations" on unclear audio
+        return [], None, 0.0, None
+    if not tonic or tonic <= 0:
+        return [], None, 0.0, None
+
+    f0, _ = melodia(y)
+    times = np.arange(len(f0)) * MELODIA_HOP / TONIC_SR
+    # Overlap windows at inference (hop < window) so a short clip still yields several to average.
+    windows = features.model_windows(times, f0, tonic, max_windows=max_windows, hop_s=TDMS_HOP_S / 2)
+    display_pcd = features.pitch_class_histogram(f0, tonic, n_bins=PCD_BINS)
+    return windows, tonic, analysed_seconds, display_pcd

raaga_id/train.py

@@ -0,0 +1,60 @@
+"""Training entrypoint (PRD §17, build-order step 5).
+
+    python -m raaga_id.train [--datasets saraga_carnatic compmusic_raga]
+
+Floor (D16): a tonic-normalized pitch-class distribution (PCD) over each recording's
+predominant-melody pitch track, windowed (D7), classified by XGBoost. Split is BY
+TRACK (frozen benchmark, no window leakage). Pools any datasets that expose pitch +
+tonic (Saraga, IAMRRD).
+"""
+from __future__ import annotations
+
+import argparse
+
+import numpy as np
+
+from . import data, features
+from .config import MODELS_DIR
+from .model import RaagaXGB
+
+
+def build_features(pclips, max_windows: int | None):
+    """(X, y) of per-window model features (windowed TDMS, D28) labelled with track raaga."""
+    X, y = [], []
+    for pc in pclips:
+        wins = features.model_windows(pc.times, pc.freqs, pc.tonic_hz, max_windows=max_windows)
+        X.extend(wins)
+        y.extend([pc.raaga] * len(wins))
+    if not X:
+        raise SystemExit("No feature windows — is the dataset downloaded (pitch + tonic present)?")
+    return np.vstack(X), np.array(y)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Train the raaga floor (windowed TDMS + XGBoost, D28).")
+    ap.add_argument("--out", default=str(MODELS_DIR / "raaga_xgb.json"))
+    ap.add_argument("--datasets", nargs="+", default=["saraga_carnatic"])
+    ap.add_argument("--max-windows", type=int, default=None, help="cap windows/track (default: config)")
+    ap.add_argument("--test-frac", type=float, default=0.25)
+    args = ap.parse_args()
+
+    pclips = list(data.iter_pitch_clips(only_vocab=True, datasets=tuple(args.datasets)))
+    if not pclips:
+        raise SystemExit("No labelled pitch clips — check datasets / raagas.json.")
+
+    train_ids, test_ids = data.split_by_track(pclips, test_frac=args.test_frac)
+    train_clips = [c for c in pclips if c.track_id in train_ids]
+    print(f"{len(pclips)} clips {args.datasets} -> {len(train_clips)} train / {len(test_ids)} test "
+          f"(frozen: {data.FROZEN_TEST_PATH})")
+
+    X, y = build_features(train_clips, args.max_windows)
+    classes = sorted(set(y))
+    idx = {c: i for i, c in enumerate(classes)}
+    print(f"training on {len(X)} TDMS windows ({X.shape[1]}d) across {len(classes)} raagas: {classes}")
+    model = RaagaXGB(classes).fit(X, np.array([idx[c] for c in y]))
+    path = model.save(args.out)
+    print(f"saved -> {path}\nnext: python -m raaga_id.evaluate --model {path}")
+
+
+if __name__ == "__main__":
+    main()

raaga_profiles.json

@@ -0,0 +1,562 @@
+{
+ "Suraṭi": [
+  0.1025,
+  0.0522,
+  0.0766,
+  0.0564,
+  0.0958,
+  0.0618,
+  0.0901,
+  0.1086,
+  0.0549,
+  0.1432,
+  0.073,
+  0.085
+ ],
+ "Mōhanaṁ": [
+  0.1203,
+  0.0601,
+  0.0813,
+  0.132,
+  0.0673,
+  0.0254,
+  0.0832,
+  0.0966,
+  0.085,
+  0.0801,
+  0.0413,
+  0.1274
+ ],
+ "Tōḍi": [
+  0.1896,
+  0.0846,
+  0.0536,
+  0.0359,
+  0.0745,
+  0.0641,
+  0.0638,
+  0.1383,
+  0.0753,
+  0.0561,
+  0.0466,
+  0.1174
+ ],
+ "Kamās": [
+  0.1235,
+  0.0192,
+  0.0286,
+  0.0638,
+  0.098,
+  0.0415,
+  0.0559,
+  0.0908,
+  0.1025,
+  0.1915,
+  0.0742,
+  0.1104
+ ],
+ "Bēgaḍa": [
+  0.1187,
+  0.0405,
+  0.0627,
+  0.137,
+  0.1023,
+  0.0351,
+  0.0818,
+  0.1246,
+  0.0629,
+  0.0783,
+  0.045,
+  0.1112
+ ],
+ "Behāg": [
+  0.1082,
+  0.0361,
+  0.0431,
+  0.1159,
+  0.1326,
+  0.0608,
+  0.1094,
+  0.0902,
+  0.0408,
+  0.0506,
+  0.0559,
+  0.1564
+ ],
+ "Bhairavi": [
+  0.1315,
+  0.0757,
+  0.1335,
+  0.0534,
+  0.0546,
+  0.0541,
+  0.0694,
+  0.1457,
+  0.0805,
+  0.068,
+  0.038,
+  0.0957
+ ],
+ "Varāḷi": [
+  0.2178,
+  0.092,
+  0.0879,
+  0.0327,
+  0.0149,
+  0.0264,
+  0.1144,
+  0.1356,
+  0.0454,
+  0.02,
+  0.0285,
+  0.1843
+ ],
+ "Harikāmbhōji": [
+  0.1086,
+  0.0398,
+  0.0666,
+  0.1091,
+  0.1079,
+  0.0413,
+  0.0531,
+  0.0869,
+  0.0998,
+  0.1328,
+  0.0544,
+  0.0997
+ ],
+ "Śankarābharaṇaṁ": [
+  0.1398,
+  0.0326,
+  0.0576,
+  0.1566,
+  0.136,
+  0.0386,
+  0.0734,
+  0.1108,
+  0.033,
+  0.0374,
+  0.0384,
+  0.1456
+ ],
+ "Kāpi": [
+  0.1276,
+  0.0631,
+  0.1313,
+  0.0832,
+  0.0938,
+  0.0574,
+  0.0621,
+  0.0983,
+  0.0381,
+  0.0426,
+  0.0524,
+  0.1501
+ ],
+ "Pūrvīkaḷyāṇi": [
+  0.2013,
+  0.04,
+  0.0225,
+  0.0882,
+  0.07,
+  0.0522,
+  0.107,
+  0.1015,
+  0.0595,
+  0.071,
+  0.0416,
+  0.1452
+ ],
+ "Sindhubhairavi": [
+  0.1399,
+  0.0619,
+  0.0986,
+  0.076,
+  0.0673,
+  0.0628,
+  0.0758,
+  0.1595,
+  0.0717,
+  0.0485,
+  0.0477,
+  0.0902
+ ],
+ "Rītigauḷa": [
+  0.1219,
+  0.0605,
+  0.1125,
+  0.0679,
+  0.0962,
+  0.0759,
+  0.0336,
+  0.0474,
+  0.0622,
+  0.1308,
+  0.0691,
+  0.122
+ ],
+ "Sāvēri": [
+  0.2051,
+  0.0495,
+  0.0243,
+  0.0498,
+  0.0784,
+  0.0507,
+  0.1077,
+  0.2043,
+  0.0658,
+  0.0262,
+  0.0238,
+  0.1143
+ ],
+ "Sahānā": [
+  0.1089,
+  0.0545,
+  0.0852,
+  0.0832,
+  0.1427,
+  0.0619,
+  0.0688,
+  0.0971,
+  0.0871,
+  0.079,
+  0.0307,
+  0.1008
+ ],
+ "Ṣanmukhapriya": [
+  0.1082,
+  0.0539,
+  0.1333,
+  0.0446,
+  0.0173,
+  0.0311,
+  0.1316,
+  0.1816,
+  0.0692,
+  0.068,
+  0.0734,
+  0.0877
+ ],
+ "Kalyāṇi": [
+  0.1199,
+  0.0534,
+  0.0666,
+  0.0759,
+  0.0621,
+  0.0438,
+  0.1087,
+  0.0959,
+  0.0485,
+  0.0604,
+  0.076,
+  0.1888
+ ],
+ "Hussēnī": [
+  0.1543,
+  0.0764,
+  0.1021,
+  0.0378,
+  0.0537,
+  0.0565,
+  0.1075,
+  0.1531,
+  0.0602,
+  0.0549,
+  0.0354,
+  0.1081
+ ],
+ "Kāṁbhōji": [
+  0.1205,
+  0.0376,
+  0.0579,
+  0.1163,
+  0.1024,
+  0.0325,
+  0.0733,
+  0.0898,
+  0.089,
+  0.1171,
+  0.0486,
+  0.1151
+ ],
+ "Śrīranjani": [
+  0.1133,
+  0.1038,
+  0.1254,
+  0.0505,
+  0.0754,
+  0.0742,
+  0.0271,
+  0.0388,
+  0.1121,
+  0.121,
+  0.0551,
+  0.1033
+ ],
+ "Kēdāragauḷa": [
+  0.1412,
+  0.0778,
+  0.1213,
+  0.1178,
+  0.0742,
+  0.027,
+  0.0738,
+  0.1192,
+  0.0451,
+  0.0578,
+  0.0371,
+  0.1078
+ ],
+ "Madhyamāvati": [
+  0.161,
+  0.087,
+  0.114,
+  0.0391,
+  0.0463,
+  0.0472,
+  0.0773,
+  0.1156,
+  0.0487,
+  0.0829,
+  0.0574,
+  0.1236
+ ],
+ "Dēvagāndhāri": [
+  0.1192,
+  0.0557,
+  0.1105,
+  0.0839,
+  0.1056,
+  0.0434,
+  0.063,
+  0.0937,
+  0.0556,
+  0.0882,
+  0.059,
+  0.1222
+ ],
+ "Gauḷa": [
+  0.2328,
+  0.0644,
+  0.0243,
+  0.0409,
+  0.1006,
+  0.0681,
+  0.0864,
+  0.0874,
+  0.0151,
+  0.0131,
+  0.0376,
+  0.2292
+ ],
+ "Kānaḍa": [
+  0.1199,
+  0.0774,
+  0.098,
+  0.0653,
+  0.1002,
+  0.0622,
+  0.0567,
+  0.0895,
+  0.076,
+  0.0827,
+  0.0506,
+  0.1213
+ ],
+ "Nāṭa": [
+  0.1459,
+  0.043,
+  0.0954,
+  0.1189,
+  0.1268,
+  0.0787,
+  0.0852,
+  0.0941,
+  0.0133,
+  0.0128,
+  0.0309,
+  0.155
+ ],
+ "Karaharapriya": [
+  0.101,
+  0.0871,
+  0.1594,
+  0.0484,
+  0.061,
+  0.0432,
+  0.0505,
+  0.0757,
+  0.0962,
+  0.1455,
+  0.0429,
+  0.0891
+ ],
+ "Dhanyāsi": [
+  0.1789,
+  0.0496,
+  0.0308,
+  0.0335,
+  0.0828,
+  0.0787,
+  0.1119,
+  0.1598,
+  0.0446,
+  0.0499,
+  0.0449,
+  0.1345
+ ],
+ "Sāma": [
+  0.128,
+  0.0574,
+  0.108,
+  0.0976,
+  0.1445,
+  0.0674,
+  0.0688,
+  0.0837,
+  0.0438,
+  0.0671,
+  0.0301,
+  0.1037
+ ],
+ "Śrī": [
+  0.153,
+  0.1087,
+  0.1445,
+  0.0409,
+  0.0473,
+  0.0477,
+  0.0774,
+  0.114,
+  0.0423,
+  0.0438,
+  0.0457,
+  0.1348
+ ],
+ "Sencuruṭṭi": [
+  0.0798,
+  0.0289,
+  0.0345,
+  0.0209,
+  0.0744,
+  0.091,
+  0.0704,
+  0.0981,
+  0.1827,
+  0.1829,
+  0.0784,
+  0.0579
+ ],
+ "Ānandabhairavi": [
+  0.1223,
+  0.0697,
+  0.1033,
+  0.0551,
+  0.0944,
+  0.0899,
+  0.1063,
+  0.1503,
+  0.0322,
+  0.0405,
+  0.0285,
+  0.1076
+ ],
+ "Kāmavardani": [
+  0.1885,
+  0.0401,
+  0.0203,
+  0.0691,
+  0.051,
+  0.0437,
+  0.1499,
+  0.1655,
+  0.0517,
+  0.0204,
+  0.0335,
+  0.1662
+ ],
+ "Māyāmāḷavagauḷa": [
+  0.1573,
+  0.0318,
+  0.0201,
+  0.0524,
+  0.1612,
+  0.0986,
+  0.091,
+  0.1727,
+  0.0356,
+  0.0157,
+  0.0227,
+  0.1409
+ ],
+ "Aṭāna": [
+  0.1396,
+  0.0467,
+  0.05,
+  0.0269,
+  0.0373,
+  0.0407,
+  0.0936,
+  0.136,
+  0.092,
+  0.1176,
+  0.0633,
+  0.1563
+ ],
+ "Mukhāri": [
+  0.1328,
+  0.0861,
+  0.1355,
+  0.036,
+  0.0529,
+  0.0542,
+  0.0893,
+  0.1576,
+  0.0672,
+  0.0553,
+  0.0285,
+  0.1046
+ ],
+ "Yadukula kāṁbōji": [
+  0.1217,
+  0.0542,
+  0.0837,
+  0.1527,
+  0.0987,
+  0.0372,
+  0.0841,
+  0.1176,
+  0.0578,
+  0.0664,
+  0.0328,
+  0.0931
+ ],
+ "Nāṭakurinji": [
+  0.1571,
+  0.0305,
+  0.0377,
+  0.0777,
+  0.1308,
+  0.0541,
+  0.0188,
+  0.0299,
+  0.1264,
+  0.1488,
+  0.0538,
+  0.1343
+ ],
+ "Bilahari": [
+  0.1193,
+  0.05,
+  0.0703,
+  0.1366,
+  0.0977,
+  0.0262,
+  0.0726,
+  0.0906,
+  0.067,
+  0.0811,
+  0.0531,
+  0.1355
+ ]
+}

raagas.json

@@ -0,0 +1,68 @@
+{
+  "_note": "40-raaga Carnatic set: every raaga in IAMRRD (compmusic_raga / Gulati CMD), deduped by diacritic fold. Saraga pools in where raagas overlap. Regenerate with scratchpad/build_raagas40.py.",
+  "tradition": "carnatic",
+  "canonical": [
+    "Aṭāna",
+    "Behāg",
+    "Bhairavi",
+    "Bilahari",
+    "Bēgaḍa",
+    "Dhanyāsi",
+    "Dēvagāndhāri",
+    "Gauḷa",
+    "Harikāmbhōji",
+    "Hussēnī",
+    "Kalyāṇi",
+    "Kamās",
+    "Karaharapriya",
+    "Kāmavardani",
+    "Kānaḍa",
+    "Kāpi",
+    "Kāṁbhōji",
+    "Kēdāragauḷa",
+    "Madhyamāvati",
+    "Mukhāri",
+    "Māyāmāḷavagauḷa",
+    "Mōhanaṁ",
+    "Nāṭa",
+    "Nāṭakurinji",
+    "Pūrvīkaḷyāṇi",
+    "Rītigauḷa",
+    "Sahānā",
+    "Sencuruṭṭi",
+    "Sindhubhairavi",
+    "Suraṭi",
+    "Sāma",
+    "Sāvēri",
+    "Tōḍi",
+    "Varāḷi",
+    "Yadukula kāṁbōji",
+    "Ānandabhairavi",
+    "Śankarābharaṇaṁ",
+    "Śrī",
+    "Śrīranjani",
+    "Ṣanmukhapriya"
+  ],
+  "aliases": {
+    "Shankarabharanam": [
+      "Dheerasankarabharanam",
+      "Sankarabharanam",
+      "Shankarabharana"
+    ],
+    "Kalyani": [
+      "Mechakalyani",
+      "Yaman"
+    ],
+    "Kamboji": [
+      "Kambhoji",
+      "Khamboji"
+    ],
+    "Mayamalavagowla": [
+      "Mayamalavagoula",
+      "Malahari"
+    ],
+    "Hindolam": [
+      "Malkauns"
+    ]
+  }
+}

requirements-api.txt

@@ -0,0 +1,11 @@
+# Headless inference API deps (numpy<2 for essentia's C-array bridge). Same core as the Gradio
+# Space, minus gradio, plus fastapi/uvicorn/python-multipart.
+numpy<2
+essentia
+compiam
+librosa
+soundfile
+xgboost
+fastapi
+uvicorn[standard]
+python-multipart

schema.py

@@ -0,0 +1,47 @@
+"""The data-commons schema (PRD §18.1).
+
+A `datasets.Features` spec is defined even though v0 has no contributions yet — it
+future-proofs the commons so the v1 contribute/verify loop writes into a stable
+shape. Dataset license: CC-BY-4.0 (D9), kept separate from Saraga-derived artifacts.
+"""
+from __future__ import annotations
+
+from datasets import Audio, Features, Sequence, Value
+
+FEATURES = Features(
+    {
+        "id": Value("string"),
+        "audio": Audio(sampling_rate=16_000),
+        "audio_sha256": Value("string"),      # dedup key (D12)
+        "raaga": Value("string"),             # canonical vocab (raagas.json)
+        "tradition": Value("string"),         # carnatic | hindustani (D3)
+        "contributor_id": Value("string"),    # optional pseudonym, never PII (D12)
+        "is_own_performance": Value("bool"),  # rights gate (§12)
+        "license": Value("string"),
+        "consent_version": Value("string"),
+        "created_at": Value("string"),
+        "label_source": Value("string"),      # model_confirmed | contributor_declared | expert
+        "model_prediction": Value("string"),
+        "model_confidence": Value("float32"),
+        "verification_status": Value("string"),  # unverified | verified | disputed (D13)
+        "split": Value("string"),             # pending | train | test | disputed
+        "votes_agree": Value("int32"),
+        "votes_disagree": Value("int32"),
+        # nice-to-have
+        "tonic_hz": Value("float32"),
+        "tonic_source": Value("string"),
+        "instrument": Value("string"),
+        "voice_type": Value("string"),
+        "form": Value("string"),
+        "tala": Value("string"),
+        "annotations": Sequence(
+            {
+                "type": Value("string"),      # phrase | tonic | swara_boundary
+                "start_s": Value("float32"),
+                "end_s": Value("float32"),
+                "value": Value("string"),
+                "annotator_id": Value("string"),
+            }
+        ),
+    }
+)