Add issue reporting for imprecise phonemes and enhance scoring feedback

app/scorer.py

@@ -11,7 +11,7 @@ from typing import Callable, Protocol
 import numpy as np
 
 from .align import GopConfig, ctc_viterbi, edit_distance, greedy_decode, score_tokens
-from .tips import VOWELS, tip_for
+from .tips import VOWELS, sound_name, tip_for
 from .translit import to_hebrew
 
 log = logging.getLogger("ihki.scorer")
@@ -83,6 +83,8 @@ def tokenize(ipa: str, vocab: Vocab) -> list[TargetToken]:
 class ScorerConfig:
     flag_below: float = 50.0        # phoneme score under which a consonant gets a tip
     unrelated_ratio: float = 0.65   # normalised edit distance above which we say "different sentence"
+    issue_below: float = 90.0       # phoneme score under which it is listed as imprecise
+    max_issues: int = 8
     gop: GopConfig = field(default_factory=GopConfig)
 
 
@@ -117,7 +119,7 @@ class Scorer:
         phonemes, tips, seen = [], [], set()
         ar_words = ar.split()
         tr_words = to_hebrew(ipa, ar)
-        for tok, sc in zip(toks, scores):
+        for idx, (tok, sc) in enumerate(zip(toks, scores)):
             heard_ph = "_" if sc.deleted else (self.vocab.i2t.get(sc.competitor) if sc.competitor is not None else None)
             flagged = bool(sc.score < self.cfg.flag_below) and tok.phoneme not in VOWELS
             phonemes.append({"ipa": tok.phoneme, "word": tok.word, "score": sc.score,
@@ -128,6 +130,7 @@ class Scorer:
                     seen.add(tip["key"])
                     tip["word"] = ar_words[tok.word] if tok.word < len(ar_words) else ""
                     tip["word_tr"] = tr_words[tok.word]
+                    tip["idx"] = idx
                     tips.append(tip)
 
         n_words = len(ipa.split("|"))
@@ -144,8 +147,28 @@ class Scorer:
         overall = 0.5 * phone_mean + 0.5 * word_mean  # one wrong consonant must pull the sentence down
         if unrelated:
             overall = min(overall, 30.0)
+        tips = tips[:4]
+
+        # Anything short of 100 must say why: every imprecise sound that did not get a full tip,
+        # weakest first. If nothing is clearly off, name the weakest few.
+        issues = []
+        if round(overall) < 100 and not unrelated:
+            tipped = {t.pop("idx") for t in tips}
+            rest = sorted((i for i in range(len(toks)) if i not in tipped and scores[i].score < 100),
+                          key=lambda i: scores[i].score)
+            picked = [i for i in rest if scores[i].score < self.cfg.issue_below]
+            if not picked and not tips:
+                picked = rest[:3]
+            for i in picked[:self.cfg.max_issues]:
+                tok, sc = toks[i], scores[i]
+                comp = self.vocab.i2t.get(sc.competitor) if sc.competitor is not None else None
+                issues.append({"sound": sound_name(tok.phoneme) or tok.phoneme, "word_tr": tr_words[tok.word],
+                               "score": round(sc.score), "missing": bool(sc.deleted),
+                               "heard": None if sc.deleted else sound_name(comp)})
+        for t in tips:
+            t.pop("idx", None)
         return {"score": round(overall), "variant": {"ar": ar, "tr": " ".join(tr_words), "ipa": ipa}, "heard_ipa": heard,
-                "unrelated": unrelated, "words": words, "tips": tips[:4]}
+                "unrelated": unrelated, "words": words, "tips": tips, "issues": issues}
 
 
 # ---------- real model ----------

app/tips.py

@@ -56,6 +56,19 @@ def with_hebrew(text: str) -> str:
     return _BARE_AR.sub(lambda m: _PAIRED.get(m.group(), m.group()), text)
 
 
+VOWEL_NAMES = {
+    "a": "תנועת אַ", "i": "תנועת אִ", "u": "תנועת אֻ", "e": "תנועת אֶ", "o": "תנועת אוֹ",
+    "aː": "תנועה ארוכה אַא", "iː": "תנועה ארוכה אִי", "uː": "תנועה ארוכה אוּ",
+    "eː": "תנועה ארוכה אֵי", "oː": "תנועה ארוכה אוֹ",
+}
+
+
+def sound_name(phoneme: str | None) -> str | None:
+    """Hebrew name of a phoneme (expected or heard), or None if we have no name for it."""
+    phoneme = HEARD_ALIASES.get(phoneme, phoneme)
+    return NAMES.get(phoneme) or VOWEL_NAMES.get(phoneme)
+
+
 VOWELS = {"a", "i", "u", "e", "o", "aː", "iː", "uː", "eː", "oː"}
 # the urban glottal stop is often dropped by natives too; don't nag about it
 NO_DELETION_TIP = {"ʔ"}

static/index.html

@@ -181,7 +181,14 @@ function render(r){
     const body=document.createElement("span"); body.textContent=t.text;
     li.append(what,body); tips.appendChild(li);
   }
-  if(!r.unrelated && !r.tips.length && s>=85){
+  if(r.issues.length){
+    const li=document.createElement("li");
+    const what=document.createElement("span"); what.className="what"; what.textContent=r.tips.length?"עוד הגאים לא מדויקים":"מה לא היה מדויק";
+    const body=document.createElement("span");
+    body.textContent=r.issues.map(i=>`${i.sound} ב״${i.word_tr}״ (${i.score})`+(i.missing?" – לא נשמעה":i.heard?` – נשמע כמו ${i.heard}`:"")).join(" · ");
+    li.append(what,body); tips.appendChild(li);
+  }
+  if(!r.unrelated && !r.tips.length && !r.issues.length){
     const li=document.createElement("li"); li.innerHTML='<span class="what">כל העיצורים נשמעו נכון</span><span>נסו לומר את המשפט בקצב דיבור טבעי.</span>';
     tips.appendChild(li);
   }

tests/test_scoring.py

@@ -134,3 +134,13 @@ def test_api_end_to_end_with_stub_model():
         r = c.post("/api/score", data={"phrase_id": pid}, files={"audio": ("a.wav", buf.getvalue(), "audio/wav")})
         assert r.status_code == 200, r.text
         assert r.json()["tips"][0]["key"] == "ħ>x"
+
+
+def test_anything_below_100_says_what_was_wrong():
+    for phones in (["w", "eː", "n", "i", "l", "ħ", "a", "m", "aː", "m"],      # clean
+                   ["w", "eː", "n", "i", "l", "χ", "a", "m", "aː", "m"],      # wrong consonant
+                   ["w", "e", "n", "i", "l", "ħ", "a", "m", "a", "m"]):       # short vowels
+        r = scorer_for(emissions(phones)).score(None, TOILET)
+        assert r["score"] == 100 or r["unrelated"] or r["tips"] or r["issues"], phones
+        for i in r["issues"]:
+            assert i["word_tr"] and i["sound"] and not i["sound"].isascii()