Upload 7 files

README.md

@@ -1,14 +1,49 @@
 ---
-title: ReadingCoach
-emoji: 📚
-colorFrom: red
+title: Reading & Pronunciation Coach
+emoji: 🗣️
+colorFrom: indigo
 colorTo: green
 sdk: gradio
-sdk_version: 6.22.0
-python_version: '3.12'
 app_file: app.py
 pinned: false
-short_description: Reading & Pronunciation Coach  Read a passage aloud in Hindi
+short_description: Hindi & English reading practice with pronunciation scoring
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Reading & Pronunciation Coach
+
+Read a passage aloud in Hindi or English and get a word-level error breakdown:
+WER, CER, strict and lenient accuracy, speaking rate, and pause count.
+
+## Configuration
+
+Set these under **Settings → Variables and secrets**.
+
+| Name | Type | Value |
+|---|---|---|
+| `ASR_BACKEND` | Variable | `groq` \| `zerogpu` \| `local` \| `auto` |
+| `GROQ_API_KEY` | **Secret** | required for the `groq` backend |
+| `GROQ_MODEL_HI` | Variable | default `whisper-large-v3` |
+| `GROQ_MODEL_EN` | Variable | default `whisper-large-v3-turbo` |
+| `LOCAL_TIER` | Variable | `fast` \| `balanced` \| `accurate` (local only) |
+
+## Choosing a backend
+
+**`groq` on free CPU hardware** — recommended. Only transcription needs a GPU,
+and Groq rents it per second of audio. Uncomment nothing in `requirements.txt`.
+Trade-off: no per-word confidence, so the "Unclear words" metric is hidden.
+
+**`zerogpu`** — free GPU, `transformers` path. Uncomment the ZeroGPU block in
+`requirements.txt` and select ZeroGPU hardware. Note that `faster-whisper` will
+*not* work here: CTranslate2 does not allocate through PyTorch's CUDA allocator,
+so it cannot see a ZeroGPU-assigned device.
+
+**`local`** — your machine or paid GPU Spaces hardware. The only backend that
+reports per-word ASR confidence, which is a useful mumbling signal. Uncomment
+the `faster-whisper` line.
+
+## Local development
+
+```bash
+pip install -r requirements.txt faster-whisper
+ASR_BACKEND=local LOCAL_TIER=fast python app.py
+```

app.py

@@ -0,0 +1,142 @@
+"""
+Hugging Face Space entrypoint: Hindi / English reading & pronunciation coach.
+
+Set ASR_BACKEND (and GROQ_API_KEY as a Space secret) in Settings -> Variables.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+
+import gradio as gr
+import pandas as pd
+
+from asr_backends import get_backend
+from scoring import score
+
+LANGS = {"हिंदी (Hindi)": "hi", "English": "en"}
+
+SAMPLES = {
+    "hi": "सूरज सुबह जल्दी उठता है और अपनी किताब पढ़ता है। उसे कहानियाँ बहुत पसंद हैं।",
+    "en": "The quick brown fox jumps over the lazy dog while the children watch quietly.",
+}
+
+# ---------------------------------------------------------------------------
+# TTS -- cached, because on a Space every gTTS call is a network round trip
+# ---------------------------------------------------------------------------
+
+TTS_DIR = os.path.join(tempfile.gettempdir(), "coach_tts")
+os.makedirs(TTS_DIR, exist_ok=True)
+
+
+def speak(text: str, lang_label: str, slow: bool):
+    if not (text or "").strip():
+        raise gr.Error("Type or paste a passage first.")
+    lang = LANGS[lang_label]
+    key = hashlib.sha1(f"{lang}|{slow}|{text}".encode()).hexdigest()[:20]
+    path = os.path.join(TTS_DIR, f"{key}.mp3")
+    if not os.path.exists(path):
+        from gtts import gTTS
+
+        try:
+            gTTS(text=text, lang=lang, slow=slow).save(path)
+        except Exception as exc:
+            raise gr.Error(f"Text-to-speech unavailable: {exc}") from exc
+    return path
+
+
+def fill_sample(lang_label: str) -> str:
+    return SAMPLES[LANGS[lang_label]]
+
+
+# ---------------------------------------------------------------------------
+# Evaluation
+# ---------------------------------------------------------------------------
+
+EMPTY = pd.DataFrame(columns=["अपेक्षित / Expected", "सुना गया / Heard",
+                              "प्रकार / Error type", "समानता / Similarity"])
+
+
+def evaluate(audio_path, passage, lang_label, lenient_decoding):
+    if not audio_path:
+        return {"error": "No recording received — record or upload audio first."}, EMPTY
+    if not (passage or "").strip():
+        return {"error": "Paste the passage to read first."}, EMPTY
+
+    lang = LANGS[lang_label]
+    try:
+        backend = get_backend()
+        hint = passage.strip() if lenient_decoding else None
+        tr = backend.transcribe(audio_path, lang, hint=hint)
+    except Exception as exc:
+        return {"error": f"{type(exc).__name__}: {exc}"}, EMPTY
+
+    if not tr.text:
+        return {"error": "Nothing was transcribed. Check the mic level and try again."}, EMPTY
+    return score(passage, tr, lang)
+
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+
+def build() -> gr.Blocks:
+    with gr.Blocks(title="Reading & Pronunciation Coach") as app:
+        gr.Markdown("## 🗣️ Reading & Pronunciation Coach — हिंदी / English")
+        status = gr.Markdown("Resolving ASR backend…")
+
+        with gr.Row():
+            lang = gr.Dropdown(list(LANGS), value="हिंदी (Hindi)", label="Language", scale=2)
+            sample_btn = gr.Button("Load sample passage", scale=1)
+
+        passage = gr.Textbox(
+            label="Passage to read", lines=4,
+            placeholder="यहाँ हिंदी टेक्स्ट लिखें… / Paste English text here…",
+        )
+
+        with gr.Row():
+            slow = gr.Checkbox(label="Slow speech", value=False, scale=1)
+            listen = gr.Button("🔊 Listen", scale=1)
+        tts_audio = gr.Audio(label="Model reading", type="filepath")
+
+        gr.Markdown("### 🎤 Now read it aloud")
+        mic = gr.Audio(sources=["microphone", "upload"], type="filepath",
+                       label="Your recording")
+        lenient = gr.Checkbox(
+            label="Lenient decoding — biases the ASR toward the passage. "
+                  "Scores look better but real mistakes get hidden. Leave off for assessment.",
+            value=False,
+        )
+        submit = gr.Button("✅ Check my reading", variant="primary")
+
+        metrics = gr.JSON(label="Results")
+        table = gr.Dataframe(label="गलती तालिका / Error table", wrap=True)
+
+        gr.Markdown(
+            "**Reading the scores.** *Word accuracy* is strict: a word counts only if it "
+            "matches exactly. *Lenient score* gives partial credit by similarity, so a "
+            "near-miss on a hard word is not treated like a skipped line. *WER* is the "
+            "standard ASR metric and includes extra words, so it can exceed the accuracy gap."
+        )
+
+        def backend_line():
+            try:
+                b = get_backend()
+                extra = "" if b.supports_word_confidence else \
+                    " · per-word confidence unavailable on this backend"
+                return f"**Backend:** {b.describe()}{extra}"
+            except Exception as exc:
+                return f"⚠️ **Backend not ready:** {exc}"
+
+        app.load(backend_line, None, status)
+        sample_btn.click(fill_sample, lang, passage)
+        listen.click(speak, [passage, lang, slow], tts_audio)
+        submit.click(evaluate, [mic, passage, lang, lenient], [metrics, table])
+
+    return app
+
+
+if __name__ == "__main__":
+    build().queue(max_size=12).launch()

asr_backends.py

@@ -0,0 +1,403 @@
+"""
+Pluggable ASR backends.
+
+The whole point of this module: scoring.py must not know or care where the
+transcript came from. Every backend returns the same Transcript object, so you
+can flip ASR_BACKEND and compare error tables across engines with identical
+scoring logic.
+
+    ASR_BACKEND=groq      GROQ_API_KEY=gsk_...     # free CPU Space, per-second billing
+    ASR_BACKEND=zerogpu                            # free ZeroGPU Space, transformers
+    ASR_BACKEND=local                              # your machine / paid GPU Space
+    ASR_BACKEND=auto                               # default: groq > zerogpu > local
+
+Why three: CTranslate2 (the engine under faster-whisper) does not allocate
+through PyTorch's CUDA allocator, so it will not see a GPU under ZeroGPU's
+fork-based allocation. ZeroGPU therefore needs the transformers path.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+# ---------------------------------------------------------------------------
+# Shared data types
+# ---------------------------------------------------------------------------
+
+NAN = float("nan")
+
+
+@dataclass
+class Word:
+    text: str
+    start: float = 0.0
+    end: float = 0.0
+    prob: float = NAN          # NaN when the backend cannot report confidence
+
+
+@dataclass
+class Transcript:
+    text: str
+    words: list[Word] = field(default_factory=list)
+    speech_seconds: float = 0.0     # voiced time, not wall-clock file length
+    backend: str = ""
+    model: str = ""
+    latency_s: float = 0.0
+    has_confidence: bool = False
+
+
+@runtime_checkable
+class ASRBackend(Protocol):
+    name: str
+    supports_word_confidence: bool
+
+    def describe(self) -> str: ...
+
+    def transcribe(self, audio_path: str, lang: str, hint: str | None = None) -> Transcript: ...
+
+
+# ---------------------------------------------------------------------------
+# Audio preprocessing
+# ---------------------------------------------------------------------------
+
+_HAS_FFMPEG = shutil.which("ffmpeg") is not None
+
+
+def to_16k_mono_flac(path: str) -> str:
+    """
+    Downsample to 16 kHz mono FLAC. Whisper resamples to 16 kHz internally
+    anyway, so this is lossless for accuracy but shrinks the upload ~10x --
+    which matters because hosted endpoints cap request size (Groq: 25 MB on
+    the free tier) and a phone recording is often 48 kHz stereo.
+    """
+    if not _HAS_FFMPEG:
+        return path
+    out = tempfile.NamedTemporaryFile(delete=False, suffix=".flac").name
+    try:
+        subprocess.run(
+            ["ffmpeg", "-y", "-loglevel", "error", "-i", path,
+             "-ar", "16000", "-ac", "1", "-c:a", "flac", out],
+            check=True, timeout=120,
+        )
+        return out
+    except Exception:
+        return path
+
+
+def _voiced_from_segments(segments) -> float:
+    total = 0.0
+    for s in segments:
+        start = s.get("start") if isinstance(s, dict) else getattr(s, "start", None)
+        end = s.get("end") if isinstance(s, dict) else getattr(s, "end", None)
+        if start is not None and end is not None:
+            total += max(0.0, float(end) - float(start))
+    return total
+
+
+# ---------------------------------------------------------------------------
+# Backend 1: Groq  (recommended for a free CPU Space)
+# ---------------------------------------------------------------------------
+
+GROQ_URL = "https://api.groq.com/openai/v1/audio/transcriptions"
+
+# large-v3 is meaningfully better than turbo on Hindi; turbo is ~2.8x cheaper
+# and fine for English. Override with GROQ_MODEL_HI / GROQ_MODEL_EN.
+GROQ_MODELS = {
+    "hi": os.getenv("GROQ_MODEL_HI", "whisper-large-v3"),
+    "en": os.getenv("GROQ_MODEL_EN", "whisper-large-v3-turbo"),
+}
+
+
+class GroqBackend:
+    name = "groq"
+    supports_word_confidence = False     # OpenAI-compatible API returns no logprobs
+
+    def __init__(self, api_key: str | None = None, timeout: float = 90.0):
+        self.api_key = api_key or os.environ["GROQ_API_KEY"]
+        self.timeout = timeout
+
+    def describe(self) -> str:
+        return f"Groq API — {GROQ_MODELS['hi']} (hi) / {GROQ_MODELS['en']} (en)"
+
+    def transcribe(self, audio_path: str, lang: str, hint: str | None = None) -> Transcript:
+        import httpx
+
+        model = GROQ_MODELS.get(lang, "whisper-large-v3")
+        sent = to_16k_mono_flac(audio_path)
+        t0 = time.perf_counter()
+
+        data = {
+            "model": model,
+            "language": lang,
+            "response_format": "verbose_json",
+            "timestamp_granularities[]": ["word", "segment"],
+            "temperature": "0",
+        }
+        if hint:
+            data["prompt"] = hint[:220]
+
+        payload = None
+        last_error: Exception | None = None
+        for attempt in range(3):
+            try:
+                with open(sent, "rb") as fh:
+                    resp = httpx.post(
+                        GROQ_URL,
+                        headers={"Authorization": f"Bearer {self.api_key}"},
+                        data=data,
+                        files={"file": (os.path.basename(sent), fh, "audio/flac")},
+                        timeout=self.timeout,
+                    )
+                if resp.status_code in (429, 500, 502, 503):
+                    raise RuntimeError(f"transient {resp.status_code}: {resp.text[:200]}")
+                resp.raise_for_status()
+                payload = resp.json()
+                break
+            except Exception as exc:
+                last_error = exc
+                if attempt == 2:
+                    raise RuntimeError(f"Groq transcription failed: {exc}") from exc
+                time.sleep(1.5 * (attempt + 1))     # backoff; free tier is rate-limited
+        assert payload is not None, last_error
+
+        if sent != audio_path:
+            try:
+                os.unlink(sent)
+            except OSError:
+                pass
+
+        words = [
+            Word(w.get("word", "").strip(), float(w.get("start", 0)), float(w.get("end", 0)))
+            for w in (payload.get("words") or [])
+        ]
+        voiced = _voiced_from_segments(payload.get("segments") or [])
+        if not voiced and words:
+            voiced = words[-1].end - words[0].start
+
+        return Transcript(
+            text=(payload.get("text") or "").strip(),
+            words=words,
+            speech_seconds=voiced,
+            backend=self.name,
+            model=model,
+            latency_s=round(time.perf_counter() - t0, 2),
+            has_confidence=False,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Backend 2: local faster-whisper
+# ---------------------------------------------------------------------------
+
+LOCAL_MODELS = {
+    "hi": {"fast": "small", "balanced": "medium", "accurate": "large-v3"},
+    "en": {"fast": "distil-small.en", "balanced": "distil-medium.en",
+           "accurate": "distil-large-v3"},
+}
+
+
+def _pick_device() -> tuple[str, str]:
+    try:
+        import torch
+
+        if torch.cuda.is_available():
+            major = torch.cuda.get_device_capability()[0]
+            return "cuda", "int8_float16" if major >= 7 else "float16"
+    except Exception:
+        pass
+    return "cpu", "int8"
+
+
+class LocalBackend:
+    name = "local"
+    supports_word_confidence = True       # the reason to keep this backend around
+
+    def __init__(self, tier: str | None = None):
+        self.tier = tier or os.getenv("LOCAL_TIER", "accurate")
+        self.device, self.compute_type = _pick_device()
+        self._cache: dict[str, object] = {}
+        self._lock = threading.Lock()
+
+    def describe(self) -> str:
+        return (f"faster-whisper {self.tier} on {self.device} ({self.compute_type})"
+                f" — word confidence available")
+
+    def _model(self, lang: str):
+        name = LOCAL_MODELS[lang][self.tier]
+        with self._lock:
+            if name not in self._cache:
+                from faster_whisper import WhisperModel
+
+                self._cache[name] = WhisperModel(
+                    name, device=self.device, compute_type=self.compute_type,
+                    cpu_threads=os.cpu_count() or 4,
+                )
+            return self._cache[name], name
+
+    def transcribe(self, audio_path: str, lang: str, hint: str | None = None) -> Transcript:
+        model, name = self._model(lang)
+        t0 = time.perf_counter()
+
+        segments, _info = model.transcribe(
+            audio_path,
+            language=lang,
+            beam_size=1,                        # greedy: ~3x faster, ~1% WER cost
+            word_timestamps=True,
+            condition_on_previous_text=False,   # stop one bad segment poisoning the rest
+            vad_filter=True,                    # skip silence in learner recordings
+            vad_parameters={"min_silence_duration_ms": 400},
+            initial_prompt=hint,
+            temperature=0.0,
+        )
+
+        chunks, words, voiced = [], [], 0.0
+        for seg in segments:                    # generator -- work happens here
+            chunks.append(seg.text)
+            voiced += max(0.0, seg.end - seg.start)
+            for w in (seg.words or []):
+                words.append(Word(w.word.strip(), w.start, w.end,
+                                  getattr(w, "probability", NAN)))
+
+        return Transcript(
+            text=" ".join(chunks).strip(), words=words, speech_seconds=voiced,
+            backend=self.name, model=name,
+            latency_s=round(time.perf_counter() - t0, 2), has_confidence=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Backend 3: ZeroGPU (transformers)
+# ---------------------------------------------------------------------------
+
+try:
+    import spaces  # type: ignore
+
+    _gpu = spaces.GPU
+except Exception:                              # not on a ZeroGPU Space
+    def _gpu(func=None, duration=None):        # no-op passthrough
+        if func is None:
+            return lambda f: f
+        return func
+
+ZERO_MODELS = {
+    "hi": os.getenv("ZERO_MODEL_HI", "openai/whisper-large-v3"),
+    "en": os.getenv("ZERO_MODEL_EN", "distil-whisper/distil-large-v3"),
+}
+
+
+class ZeroGPUBackend:
+    """
+    Loads on CPU at import, moves to CUDA inside the @spaces.GPU call. ZeroGPU
+    forks a GPU-attached process per call, so the .to("cuda") must happen
+    inside the decorated function, not at module scope.
+    """
+
+    name = "zerogpu"
+    supports_word_confidence = False
+
+    def __init__(self):
+        self._cache: dict[str, tuple] = {}
+        self._lock = threading.Lock()
+
+    def describe(self) -> str:
+        return f"ZeroGPU transformers — {ZERO_MODELS['hi']} (hi) / {ZERO_MODELS['en']} (en)"
+
+    def _load(self, lang: str):
+        name = ZERO_MODELS[lang]
+        with self._lock:
+            if name not in self._cache:
+                import torch
+                from transformers import (AutoProcessor,
+                                          WhisperForConditionalGeneration)
+
+                proc = AutoProcessor.from_pretrained(name)
+                model = WhisperForConditionalGeneration.from_pretrained(
+                    name, torch_dtype=torch.float16, low_cpu_mem_usage=True,
+                )
+                self._cache[name] = (model, proc, name)
+            return self._cache[name]
+
+    def transcribe(self, audio_path: str, lang: str, hint: str | None = None) -> Transcript:
+        model, proc, name = self._load(lang)
+        t0 = time.perf_counter()
+        text, words, voiced = self._run(model, proc, audio_path, lang, hint)
+        return Transcript(
+            text=text, words=words, speech_seconds=voiced,
+            backend=self.name, model=name,
+            latency_s=round(time.perf_counter() - t0, 2), has_confidence=False,
+        )
+
+    @staticmethod
+    @_gpu(duration=90)
+    def _run(model, proc, audio_path, lang, hint):
+        import torch
+        from transformers import pipeline
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        dtype = torch.float16 if device == "cuda" else torch.float32
+        model = model.to(device=device, dtype=dtype)
+
+        asr = pipeline(
+            "automatic-speech-recognition",
+            model=model,
+            tokenizer=proc.tokenizer,
+            feature_extractor=proc.feature_extractor,
+            torch_dtype=dtype,
+            device=device,
+            chunk_length_s=30,
+            batch_size=8,           # batched long-form: the big transformers speedup
+        )
+        kwargs = {"language": lang, "task": "transcribe", "num_beams": 1}
+        if hint:
+            kwargs["prompt_ids"] = proc.get_prompt_ids(hint[:220], return_tensors="pt").to(device)
+
+        out = asr(audio_path, return_timestamps="word", generate_kwargs=kwargs)
+
+        words, voiced = [], 0.0
+        for ch in out.get("chunks", []) or []:
+            ts = ch.get("timestamp") or (None, None)
+            start, end = (ts[0] or 0.0), (ts[1] or 0.0)
+            words.append(Word(ch.get("text", "").strip(), float(start), float(end)))
+            voiced += max(0.0, float(end) - float(start))
+        return out.get("text", "").strip(), words, voiced
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+_backend: ASRBackend | None = None
+_factory_lock = threading.Lock()
+
+
+def get_backend() -> ASRBackend:
+    """Resolve once per process. ASR_BACKEND=auto prefers Groq, then ZeroGPU."""
+    global _backend
+    with _factory_lock:
+        if _backend is not None:
+            return _backend
+
+        choice = os.getenv("ASR_BACKEND", "auto").lower()
+        if choice == "auto":
+            if os.getenv("GROQ_API_KEY"):
+                choice = "groq"
+            elif os.getenv("SPACES_ZERO_GPU") or os.getenv("ZEROGPU"):
+                choice = "zerogpu"
+            else:
+                choice = "local"
+
+        _backend = {"groq": GroqBackend, "zerogpu": ZeroGPUBackend,
+                    "local": LocalBackend}[choice]()
+        return _backend
+
+
+def is_nan(x: float) -> bool:
+    return isinstance(x, float) and math.isnan(x)

packages.txt

@@ -0,0 +1 @@
+ffmpeg

raeding coach.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:33247a95d253b79feaa207723b810e956a413e31040a55c4824e1b1299f284c4
+size 12502

requirements.txt

@@ -0,0 +1,18 @@
+# --- core (all backends) ---
+gradio>=5.0
+pandas
+gTTS
+python-Levenshtein
+num2words
+
+# --- Groq backend: httpx only (ships with gradio, pinned here for clarity) ---
+httpx
+
+# --- local faster-whisper backend: uncomment for ASR_BACKEND=local ---
+# faster-whisper>=1.1.0
+
+# --- ZeroGPU backend: uncomment for ASR_BACKEND=zerogpu ---
+# spaces
+# torch
+# transformers>=4.44
+# accelerate

scoring.py

@@ -0,0 +1,288 @@
+"""
+Backend-agnostic scoring. Takes a Transcript from any ASR backend plus the
+reference passage, returns metrics + an error table.
+
+Nothing in here touches a GPU or the network, which is why the app can run on a
+free CPU Space: only transcription needs compute.
+"""
+
+from __future__ import annotations
+
+import re
+import string
+import unicodedata
+from functools import lru_cache
+from typing import Iterable, Sequence
+
+import pandas as pd
+
+from asr_backends import Transcript, is_nan
+
+# ---------------------------------------------------------------------------
+# Optional deps
+# ---------------------------------------------------------------------------
+
+try:
+    from Levenshtein import distance as _lev
+    from Levenshtein import ratio as _ratio
+except ImportError:
+    import difflib
+
+    def _lev(a: str, b: str) -> int:
+        sm = difflib.SequenceMatcher(None, a, b)
+        n = max(len(a), len(b))
+        return n - int(sm.ratio() * n)
+
+    def _ratio(a: str, b: str) -> float:
+        return difflib.SequenceMatcher(None, a, b).ratio()
+
+try:
+    from num2words import num2words
+except ImportError:
+    num2words = None
+
+
+# ---------------------------------------------------------------------------
+# Normalisation -- most "errors" in a naive implementation are encoding noise
+# ---------------------------------------------------------------------------
+
+ZERO_WIDTH = dict.fromkeys(map(ord, "\u200b\u200c\u200d\ufeff"), None)
+DEVANAGARI_DIGITS = {ord(c): str(i) for i, c in enumerate("०१२३४५६७८९")}
+DEV_PUNCT = "।॥"
+MATRAS = re.compile(r"[\u0900-\u0903\u093A-\u094F\u0951-\u0957\u0962\u0963]")
+
+CONTRACTIONS = {
+    "cant": "cannot", "dont": "do not", "wont": "will not", "im": "i am",
+    "ive": "i have", "id": "i would", "ill": "i will", "its": "it is",
+    "lets": "let us", "thats": "that is", "youre": "you are", "hes": "he is",
+    "shes": "she is", "theyre": "they are", "isnt": "is not", "arent": "are not",
+    "wasnt": "was not", "didnt": "did not", "doesnt": "does not",
+    "couldnt": "could not", "wouldnt": "would not", "shouldnt": "should not",
+}
+
+
+def _expand_numbers(text: str, lang: str) -> str:
+    if num2words is None:
+        return text
+
+    def sub(m: re.Match) -> str:
+        try:
+            return num2words(int(m.group()), lang="hi" if lang == "hi" else "en")
+        except Exception:
+            return m.group()
+
+    return re.sub(r"\d+", sub, text)
+
+
+def normalise(text: str, lang: str) -> list[str]:
+    """Canonical token list. Order of operations matters."""
+    text = unicodedata.normalize("NFC", text)      # unifies the two encodings of ड़
+    text = text.translate(ZERO_WIDTH)
+
+    if lang == "hi":
+        text = text.translate(DEVANAGARI_DIGITS)
+        text = text.replace("ॐ", "ओम")
+        text = re.sub(f"[{DEV_PUNCT}]", " ", text)
+        text = text.replace("ँ", "ं")               # chandrabindu ~ anusvara
+    else:
+        text = text.lower().replace("\u2019", "'").replace("-", " ")
+
+    text = _expand_numbers(text, lang)
+    text = text.translate(str.maketrans("", "", string.punctuation))
+    tokens = text.split()
+
+    if lang == "en":
+        tokens = [CONTRACTIONS.get(t, t) for t in tokens]
+        tokens = [w for t in tokens for w in t.split()]
+    return tokens
+
+
+def skeleton(word: str, lang: str) -> str:
+    """Vowel-stripped form: equal skeletons mean same consonants, wrong vowels."""
+    if lang == "hi":
+        return MATRAS.sub("", word)
+    return re.sub(r"[aeiou]", "", word) or word
+
+
+@lru_cache(maxsize=200_000)
+def similarity(a: str, b: str) -> float:
+    return _ratio(a, b)
+
+
+# ---------------------------------------------------------------------------
+# Alignment: Needleman-Wunsch weighted by edit distance
+# ---------------------------------------------------------------------------
+# difflib only matches byte-identical tokens, so बिगडा vs बिगड़ा becomes a
+# delete + insert and the two words are never compared to each other.
+
+GAP_COST = 0.62     # < 1.0 so a near-match always beats delete + insert
+
+
+def align(ref: Sequence[str], hyp: Sequence[str]) -> list[tuple[str | None, str | None]]:
+    n, m = len(ref), len(hyp)
+    dist = [[0.0] * (m + 1) for _ in range(n + 1)]
+    back = [[""] * (m + 1) for _ in range(n + 1)]
+
+    for i in range(1, n + 1):
+        dist[i][0], back[i][0] = i * GAP_COST, "D"
+    for j in range(1, m + 1):
+        dist[0][j], back[0][j] = j * GAP_COST, "I"
+
+    for i in range(1, n + 1):
+        ri = ref[i - 1]
+        for j in range(1, m + 1):
+            sub = dist[i - 1][j - 1] + (1.0 - similarity(ri, hyp[j - 1]))
+            dele = dist[i - 1][j] + GAP_COST
+            ins = dist[i][j - 1] + GAP_COST
+            best = min(sub, dele, ins)
+            dist[i][j] = best
+            back[i][j] = "M" if best == sub else ("D" if best == dele else "I")
+
+    pairs: list[tuple[str | None, str | None]] = []
+    i, j = n, m
+    while i > 0 or j > 0:
+        op = back[i][j] if (i and j) else ("D" if i else "I")
+        if op == "M":
+            pairs.append((ref[i - 1], hyp[j - 1])); i -= 1; j -= 1
+        elif op == "D":
+            pairs.append((ref[i - 1], None)); i -= 1
+        else:
+            pairs.append((None, hyp[j - 1])); j -= 1
+    pairs.reverse()
+    return pairs
+
+
+# ---------------------------------------------------------------------------
+# Error taxonomy
+# ---------------------------------------------------------------------------
+
+SIMILAR_HI = [set("बवभ"), set("सशष"), set("दध"), set("तट"), set("कख"), set("गघ"),
+              set("जझ"), set("पफ"), set("नण"), set("रड़"), set("लर")]
+SIMILAR_EN = [set("bvp"), set("sz"), set("td"), set("kg"), set("fp"), set("lr"),
+              set("mn"), set("jy")]
+
+LABELS = {
+    "extra":         ("अतिरिक्त शब्द", "Extra word"),
+    "omission":      ("छूटा हुआ शब्द", "Omitted word"),
+    "vowel":         ("मात्रा दोष", "Vowel error"),
+    "phonetic":      ("ध्वनि भ्रम", "Confusable sound"),
+    "pronunciation": ("उच्चारण दोष", "Mispronounced"),
+    "order":         ("अक्षर क्रम", "Letter order"),
+    "substitution":  ("गलत शब्द", "Wrong word"),
+}
+
+SEVERITY = {"ok": 0, "vowel": 1, "phonetic": 1, "pronunciation": 2, "order": 2,
+            "omission": 3, "extra": 3, "substitution": 4}
+
+
+def _label(code: str, lang: str) -> str:
+    hi, en = LABELS[code]
+    return f"{hi} / {en}" if lang == "hi" else en
+
+
+def classify(ref: str | None, hyp: str | None, lang: str) -> str:
+    if ref is None:
+        return "extra"
+    if hyp is None:
+        return "omission"
+    if ref == hyp:
+        return "ok"
+
+    ed = _lev(ref, hyp)
+    if skeleton(ref, lang) == skeleton(hyp, lang):
+        return "vowel"
+
+    groups = SIMILAR_HI if lang == "hi" else SIMILAR_EN
+    if ed <= 2 and any((set(ref) & g) and (set(hyp) & g) for g in groups):
+        return "phonetic"
+    if similarity(ref, hyp) >= 0.75 or ed <= 2:
+        return "pronunciation"
+    if sorted(ref) == sorted(hyp):
+        return "order"
+    return "substitution"
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+
+def cer(ref_tokens: Iterable[str], hyp_tokens: Iterable[str]) -> float:
+    r, h = " ".join(ref_tokens), " ".join(hyp_tokens)
+    return _lev(r, h) / max(1, len(r))
+
+
+def score(expected: str, tr: Transcript, lang: str) -> tuple[dict, pd.DataFrame]:
+    ref = normalise(expected, lang)
+    hyp = normalise(tr.text, lang)
+
+    if not ref:
+        return {"error": "The passage is empty."}, pd.DataFrame()
+
+    pairs = align(ref, hyp)
+
+    # map normalised hypothesis token -> ASR confidence, when the backend has it
+    conf: dict[str, float] = {}
+    if tr.has_confidence:
+        for w in tr.words:
+            toks = normalise(w.text, lang)
+            if toks:
+                conf.setdefault(toks[0], w.prob)
+
+    rows, sub, dele, ins, soft = [], 0, 0, 0, 0.0
+    for r, h in pairs:
+        code = classify(r, h, lang)
+        if code == "ok":
+            soft += 1.0
+            continue
+        if code == "extra":
+            ins += 1
+        elif code == "omission":
+            dele += 1
+        else:
+            sub += 1
+            soft += similarity(r, h)          # partial credit for a near miss
+
+        row = {
+            "अपेक्षित / Expected": r or "",
+            "सुना गया / Heard": h or "",
+            "प्रकार / Error type": _label(code, lang),
+            "समानता / Similarity": round(similarity(r or "", h or ""), 2),
+        }
+        if tr.has_confidence:
+            c = conf.get(h) if h else None
+            row["ASR conf."] = None if (c is None or is_nan(c)) else round(c, 2)
+        row["_sev"] = SEVERITY[code]
+        rows.append(row)
+
+    n = len(ref)
+    wer = (sub + dele + ins) / n
+    exact = 100.0 * max(0, n - sub - dele) / n
+    lenient = 100.0 * soft / n
+
+    dur = tr.speech_seconds or (
+        tr.words[-1].end - tr.words[0].start if len(tr.words) > 1 else 0.0)
+    wpm = round(60.0 * len(hyp) / dur, 1) if dur > 0.5 else None
+
+    pauses = sum(1 for a, b in zip(tr.words, tr.words[1:]) if b.start - a.end > 0.7)
+
+    metrics = {
+        "📝 Transcribed": tr.text,
+        "✅ Word accuracy (%)": round(exact, 2),
+        "🎯 Lenient score (%)": round(lenient, 2),
+        "📉 WER (%)": round(100 * wer, 2),
+        "🔤 CER (%)": round(100 * cer(ref, hyp), 2),
+        "⏱️ Speaking rate (wpm)": wpm,
+        "⏸️ Long pauses (>0.7s)": pauses if tr.words else "n/a",
+        "🔢 Errors": {"substitutions": sub, "omissions": dele, "insertions": ins},
+        "⚙️ Backend": f"{tr.backend}:{tr.model} ({tr.latency_s}s)",
+    }
+    if tr.has_confidence:
+        unclear = [w.text for w in tr.words if not is_nan(w.prob) and w.prob < 0.45]
+        metrics["🤔 Unclear words"] = unclear[:10] or "—"
+
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df = (df.sort_values("_sev", ascending=False)
+                .drop(columns="_sev")
+                .reset_index(drop=True))
+    return metrics, df