misheard 0.1.0__py3-none-any.whl

misheard/__init__.py

@@ -0,0 +1,16 @@
+"""
+misheard: match Indian names and places by how they sound.
+
+    >>> from misheard import distance, best_match, to_roman
+    >>> to_roman("बाड़मेर")
+    'baaṛmer'
+    >>> distance("Barmer", "बाड़मेर") < distance("Mohan", "Rohan")
+    True
+"""
+from .distance import distance, sound_length, sound_range, tokenize
+from .explain import Explanation, Step, explain
+from .match import Match, Matcher, best_match
+from .translit import UnsupportedScriptError, plain, script_of, to_roman
+
+__all__ = ["distance", "explain", "Explanation", "Step", "best_match", "Match", "Matcher", "to_roman", "plain", "script_of", "tokenize", "sound_length", "sound_range", "UnsupportedScriptError"]
+__version__ = "0.1.0"

misheard/data/confusions.csv

@@ -0,0 +1,22 @@
+a,b,cost,why
+r,ṛ,0.15,"retroflex flap ड़ is heard and written as r (Baadmer/Barmer)"
+ḍ,ṛ,0.20,"the flap is a nukta form of ड; STT and spellings mix them"
+d,ṛ,0.35,"Roman spelling of the flap as d"
+r,d,0.35,"follows from the two rows above"
+t,ṭ,0.20,"Roman script has no dental/retroflex distinction"
+th,ṭh,0.20,"same"
+d,ḍ,0.20,"same"
+dh,ḍh,0.20,"same"
+n,ṇ,0.15,"same"
+l,ḷ,0.15,"same"
+zh,ḷ,0.25,"Tamil ழ and ள are close and both romanise as l"
+zh,l,0.30,"Tamil ழ is often written l (Ilango)"
+v,w,0.15,"no phonemic v/w contrast in most Indian languages"
+v,b,0.45,"b for Sanskrit v in Bihar, Bengal, Odisha and Assam (Binod/Vinod, Bishnoi/Vishnoi); also a real spelling, so keep it moderate"
+sh,s,0.30,"sh/s merge in many dialects and in Tamil"
+j,z,0.35,"z is often pronounced j"
+ph,f,0.15,"फ is often pronounced f"
+k,g,0.25,"Tamil uses one letter for both"
+p,b,0.25,"Tamil uses one letter for both"
+t,ḍ,0.30,"Tamil ட is voiced between vowels but romanised t (Natarajan, Venkatesh)"
+ch,s,0.35,"Tamil ச is s between vowels"

misheard/distance.py

@@ -0,0 +1,376 @@
+"""
+Phoneme-weighted distance for Indian names and places.
+
+Plain edit distance treats every letter swap as equally bad. For speech that
+is wrong in both directions:
+
+  - "Barmer" vs "Baadmer" are the same place: a vowel-length change plus the
+    retroflex flap (ड़) written two different ways. Should be cheap.
+  - "Mohan" vs "Rohan" are different people: m and r sound nothing alike,
+    even though only one letter differs. Should be expensive.
+
+So each sound carries articulatory features (where and how it is made,
+voicing, aspiration; vowel height, backness, length), and substituting one
+sound for another costs the weighted difference of those features. A small
+table of confusions specific to Indian languages (data/confusions.csv)
+overrides the feature cost where linguistics says two sounds are routinely
+mixed up.
+"""
+import csv
+import io
+import re
+from functools import lru_cache
+from itertools import permutations, product
+from typing import NamedTuple
+from importlib.resources import files
+
+from .translit import plain, to_roman
+
+# ---- sound inventory -------------------------------------------------------
+
+# consonants: (place, manner, voiced, aspirated)
+#   place: 0 bilabial, 1 labiodental, 2 dental/alveolar, 3 retroflex,
+#          4 palatal, 5 velar, 6 glottal
+#   manner: 0 stop, 1 nasal, 2 fricative, 3 approximant, 4 trill/flap, 5 affricate
+CONSONANTS = {
+    "p": (0, 0, 0, 0), "ph": (0, 0, 0, 1), "b": (0, 0, 1, 0), "bh": (0, 0, 1, 1), "m": (0, 1, 1, 0),
+    "f": (1, 2, 0, 0), "v": (1, 3, 1, 0), "w": (0, 3, 1, 0),
+    "t": (2, 0, 0, 0), "th": (2, 0, 0, 1), "d": (2, 0, 1, 0), "dh": (2, 0, 1, 1),
+    "n": (2, 1, 1, 0), "s": (2, 2, 0, 0), "z": (2, 2, 1, 0), "l": (2, 3, 1, 0), "r": (2, 4, 1, 0),
+    "ṭ": (3, 0, 0, 0), "ṭh": (3, 0, 0, 1), "ḍ": (3, 0, 1, 0), "ḍh": (3, 0, 1, 1),
+    "ṇ": (3, 1, 1, 0), "ḷ": (3, 3, 1, 0), "ṛ": (3, 4, 1, 0), "ṛh": (3, 4, 1, 1), "zh": (3, 3, 1, 0),
+    "ch": (4, 5, 0, 0), "chh": (4, 5, 0, 1), "j": (4, 5, 1, 0), "jh": (4, 5, 1, 1),
+    "sh": (4, 2, 0, 0), "y": (4, 3, 1, 0),
+    "k": (5, 0, 0, 0), "kh": (5, 0, 0, 1), "g": (5, 0, 1, 0), "gh": (5, 0, 1, 1),
+    "h": (6, 2, 0, 0),
+}
+# vowels: (height 0 low..2 high, backness 0 front..2 back, length 0 short/1 long)
+VOWELS = {
+    "a": (0, 1, 0), "aa": (0, 1, 1),
+    "i": (2, 0, 0), "ee": (2, 0, 1),
+    "u": (2, 2, 0), "oo": (2, 2, 1),
+    "e": (1, 0, 0), "ai": (1, 0, 1),
+    "o": (1, 2, 0), "au": (1, 2, 1),
+}
+
+W_PLACE, W_MANNER, W_VOICE, W_ASP = 0.45, 0.45, 0.25, 0.15
+W_HEIGHT, W_BACK, W_LEN = 0.35, 0.35, 0.25
+CROSS_CLASS = 1.8          # a vowel replaced by a consonant
+INDEL = 0.85               # a consonant missing or added
+INDEL_CHEAP = {"a": 0.4, "h": 0.4, "y": 0.5}   # silent schwa, aspiration spellings
+INDEL_VOWEL = 0.6
+
+_TOKENS = sorted(set(CONSONANTS) | set(VOWELS), key=len, reverse=True)
+
+def _load_confusions() -> list[dict]:
+    text = files(__package__).joinpath("data", "confusions.csv").read_text(encoding="utf-8")
+    return list(csv.DictReader(io.StringIO(text)))
+
+
+_CONFUSION_ROWS = _load_confusions()
+CONFUSIONS = {frozenset((r["a"], r["b"])): float(r["cost"]) for r in _CONFUSION_ROWS}
+CONFUSION_NOTES = {frozenset((r["a"], r["b"])): r["why"] for r in _CONFUSION_ROWS}
+
+# ---- tokenizer -------------------------------------------------------------
+
+# English-style spellings of Indian names, folded before tokenizing.
+_SPELLING = [
+    ("ck", "k"), ("x", "ks"), ("q", "k"), ("ii", "ee"), ("uu", "oo"),
+    ("ou", "au"),
+]
+
+
+def _fold(word: str) -> str:
+    w = word.lower()
+    for a, b in _SPELLING:
+        w = w.replace(a, b)
+    if w.endswith("ow"):                      # Lucknow
+        w = w[:-2] + "au"
+    if w.endswith("ey"):                      # Pandey, Dubey
+        w = w[:-2] + "e"
+    w = re.sub(r"ay(?=[^aeiou]|$)", "ai", w)   # Sanjay/संजय, Jaipur/जयपुर
+    # c without h is k (Vincent, Deepcika); keep ch
+    w = "".join("k" if c == "c" and not w[i + 1:i + 2] == "h" else c for i, c in enumerate(w))
+    # doubled consonants are not contrastive in romanised names (Pillai/Pilai)
+    out = []
+    for c in w:
+        if out and c == out[-1] and c not in "aeo":
+            continue
+        out.append(c)
+    return "".join(out)
+
+
+@lru_cache(maxsize=50_000)
+def tokenize(word: str) -> tuple[str, ...]:
+    """One word in any script -> tuple of sounds, greedy longest match."""
+    s = _fold(to_roman(word))
+    i, out = 0, []
+    while i < len(s):
+        for tok in _TOKENS:
+            if s.startswith(tok, i):
+                out.append(tok)
+                i += len(tok)
+                break
+        else:
+            i += 1                            # digits, punctuation, unknown marks
+    return tuple(out)
+
+
+# ---- costs -----------------------------------------------------------------
+
+def sub_cost(a: str, b: str) -> float:
+    if a == b:
+        return 0.0
+    override = CONFUSIONS.get(frozenset((a, b)))
+    if override is not None:
+        return override
+    a_vowel, b_vowel = a in VOWELS, b in VOWELS
+    if a_vowel != b_vowel:
+        return CROSS_CLASS
+    if a_vowel:
+        h1, k1, l1 = VOWELS[a]
+        h2, k2, l2 = VOWELS[b]
+        return W_HEIGHT * abs(h1 - h2) + W_BACK * abs(k1 - k2) + W_LEN * abs(l1 - l2)
+    p1, m1, v1, s1 = CONSONANTS[a]
+    p2, m2, v2, s2 = CONSONANTS[b]
+    return W_PLACE * abs(p1 - p2) + W_MANNER * min(abs(m1 - m2), 2) + W_VOICE * abs(v1 - v2) + W_ASP * abs(s1 - s2)
+
+
+def indel_cost(tok: str) -> float:
+    if tok in INDEL_CHEAP:
+        return INDEL_CHEAP[tok]
+    return INDEL_VOWEL if tok in VOWELS else INDEL
+
+
+# The DP runs on integer ids with the costs precomputed, so the inner loop is
+# list indexing only. This is also the boundary a compiled kernel would
+# replace (PLAN.md 3.4).
+_ID = {tok: i for i, tok in enumerate(_TOKENS)}
+_SUB = [[sub_cost(a, b) for b in _TOKENS] for a in _TOKENS]
+_INDEL = [indel_cost(t) for t in _TOKENS]
+INF = float("inf")
+
+
+def _ids(sounds: tuple[str, ...]) -> tuple[int, ...]:
+    return tuple(_ID[t] for t in sounds)
+
+
+def _seq(ia: tuple[int, ...], ib: tuple[int, ...], cutoff: float = INF) -> float:
+    """
+    Weighted edit distance over token ids.
+
+    Stops early once every cell of a row exceeds `cutoff`: the result is then
+    some value above `cutoff`, not the exact distance.
+    """
+    sub, indel = _SUB, _INDEL
+    prev = [0.0]
+    acc = 0.0
+    for y in ib:
+        acc += indel[y]
+        prev.append(acc)
+    for x in ia:
+        row, dx = sub[x], indel[x]
+        left = prev[0] + dx
+        cur = [left]
+        row_min = left
+        for j, y in enumerate(ib):
+            d = prev[j] + row[y]
+            t = prev[j + 1] + dx
+            if t < d:
+                d = t
+            t = left + indel[y]
+            if t < d:
+                d = t
+            cur.append(d)
+            left = d
+            if d < row_min:
+                row_min = d
+        if row_min > cutoff:
+            return row_min
+        prev = cur
+    return prev[-1]
+
+
+def sequence_distance(pa: tuple[str, ...], pb: tuple[str, ...]) -> float:
+    """Weighted edit distance between two sound sequences."""
+    return _seq(_ids(pa), _ids(pb))
+
+
+# ---- words -----------------------------------------------------------------
+#
+# A spoken name is more than its sounds: people add titles ("Shri Mohan Lal"),
+# honorifics ("Mohan ji", "Rameshbhai"), use initials ("R. Kumar") and change
+# word order ("Kumar Ramesh Singh"). Each name is expanded into a few
+# variants, each with a small penalty, and the cheapest pairing wins.
+
+# Dropped whenever another word remains. Listed in any script; they are
+# compared after romanising, so श्री, Shri and Sri all match.
+TITLES = [
+    "shri", "shree", "sri", "sree", "sh", "shrimati", "srimati", "smt", "dr", "doctor",
+    "mr", "mrs", "ms", "miss", "thiru", "tiru", "thirumathi", "tirumathi",
+    "श्री", "श्रीमती", "डॉ", "डॉक्टर", "திரு", "திருமதி", "ஸ்ரீ",
+]
+# Honorific words, said after (or before) a name. Also dropped.
+HONORIFICS = [
+    "ji", "jee", "sahab", "saheb", "sahib", "sir", "madam", "bhai", "bhaiya", "ben", "behen", "didi",
+    "जी", "साहब", "भाई", "भैया", "बहन", "बेन", "दीदी",
+]
+# Honorifics written joined to the name (Gujarati Rameshbhai, Hansaben).
+# Optional, because the joined form can be the whole name. "ji" is not here:
+# Balaji, Shivaji.
+SUFFIXES = ["bhai", "ben", "भाई", "बेन"]
+SUFFIX_PENALTY = 0.1
+# Often part of a legal name and often left out when spoken.
+OPTIONAL_WORDS = ["devi", "kumar", "kumari", "देवी", "कुमार", "कुमारी", "தேவி", "குமார்", "குமாரி"]
+OPTIONAL_PENALTY = 0.5
+
+INITIAL_COST = 0.3         # "R." standing for a word starting with r
+INITIAL_MISMATCH = 1.5     # an initial against a word starting with another letter
+SWAP_PENALTY = 0.2         # words in a different order
+MAX_PERMUTED_WORDS = 4     # up to 4! = 24 orders
+
+
+def _key(word: str) -> str:
+    """Romanised, folded, unmarked letters only: for comparing with the word lists above."""
+    return re.sub(r"[^a-z]", "", plain(_fold(to_roman(word))))
+
+
+_TITLES = {_key(w) for w in TITLES} | {_key(w) for w in HONORIFICS}
+_SUFFIXES = sorted({_key(w) for w in SUFFIXES}, key=len, reverse=True)
+_OPTIONAL = {_key(w) for w in OPTIONAL_WORDS}
+
+
+class _Word(NamedTuple):
+    sounds: tuple[str, ...]
+    ids: tuple[int, ...]
+    initial: str | None     # the letter, when the word is an initial like "R."
+    first: str              # first letter of the romanised word
+
+
+def _word(text: str) -> _Word | None:
+    sounds = tokenize(text)
+    if not sounds:
+        return None
+    is_initial = len(text) == 1 and text.isascii() and text.isalpha()
+    key = _key(text)
+    return _Word(sounds, _ids(sounds), text.lower() if is_initial else None, key[:1])
+
+
+# A note says what a variant changed: (word as written, kind, cost), kind
+# being "title", "optional" (Devi, Kumar) or "suffix" (Rameshbhai).
+Note = tuple[str, str, float]
+
+
+@lru_cache(maxsize=50_000)
+def _variants_detailed(text: str) -> tuple[tuple[float, tuple["_Word", ...], tuple[Note, ...]], ...]:
+    """The ways a name may be said, each with its penalty and what was changed."""
+    raw = text.replace(".", " ").split()                 # "R.K. Narayan" -> R K Narayan
+    raw = [w for w in raw if _word(w)]
+    core = [w for w in raw if _key(w) not in _TITLES] or raw
+    dropped = tuple((w, "title", 0.0) for w in raw if w not in core)
+    options: list[list[tuple[float, _Word | None, Note | None]]] = []
+    for w in core:
+        word = _word(w)
+        choices: list[tuple[float, _Word | None, Note | None]] = [(0.0, word, None)]
+        key = _key(w)
+        if key in _OPTIONAL and len(core) > 1:
+            choices.append((OPTIONAL_PENALTY, None, (w, "optional", OPTIONAL_PENALTY)))
+        elif word.initial is None:
+            roman = _fold(to_roman(w))
+            for suf in _SUFFIXES:
+                if key.endswith(suf) and len(key) - len(suf) >= 3 and plain(roman).endswith(suf):
+                    stem = _word(roman[: len(roman) - len(suf)])
+                    if stem:
+                        choices.append((SUFFIX_PENALTY, stem, (w, "suffix", SUFFIX_PENALTY)))
+                    break
+        options.append(choices)
+    out: dict = {}
+    for combo in product(*options):
+        words = tuple(w for _, w, _ in combo if w is not None)
+        if words:
+            pen = round(sum(p for p, _, _ in combo), 6)
+            if words not in out or out[words][0] > pen:
+                out[words] = (pen, dropped + tuple(n for _, _, n in combo if n))
+    return tuple((p, w, notes) for w, (p, notes) in out.items())
+
+
+@lru_cache(maxsize=50_000)
+def _variants(text: str) -> "Variants":
+    """The ways a name may be said, each with its penalty."""
+    return tuple((p, w) for p, w, _ in _variants_detailed(text))
+
+
+def _word_cost(x: _Word, y: _Word, cutoff: float = INF) -> float:
+    if x.initial or y.initial:
+        if x.initial and y.initial:
+            return 0.0 if x.initial == y.initial else INITIAL_MISMATCH
+        letter, other = (x.initial, y) if x.initial else (y.initial, x)
+        return INITIAL_COST if other.first == letter else INITIAL_MISMATCH
+    return _seq(x.ids, y.ids, cutoff)
+
+
+def _words_distance(wa: tuple[_Word, ...], wb: tuple[_Word, ...], cutoff: float = INF) -> float:
+    n = len(wa)
+    if n == len(wb):
+        cost = [[_word_cost(x, y, cutoff) for y in wb] for x in wa]
+        best = sum(cost[i][i] for i in range(n))
+        if 1 < n <= MAX_PERMUTED_WORDS:
+            for perm in permutations(range(n)):
+                best = min(best, sum(cost[i][p] for i, p in enumerate(perm)) + SWAP_PENALTY)
+        return best
+    # A different number of words (a dropped surname, "Meenakshisundaram" as
+    # one word): compare as one joined sequence, so every missing sound costs.
+    return _seq(tuple(t for w in wa for t in w.ids), tuple(t for w in wb for t in w.ids), cutoff)
+
+
+Variants = tuple[tuple[float, tuple[_Word, ...]], ...]
+
+
+def _variants_distance(va: Variants, vb: Variants, cutoff: float = INF) -> float:
+    """Cheapest pairing of two names' variants. Above `cutoff`, only a lower bound."""
+    best = INF
+    for pa, wa in va:
+        for pb, wb in vb:
+            limit = min(best, cutoff) - pa - pb
+            d = pa + pb + _words_distance(wa, wb, limit)
+            if d < best:
+                best = d
+    return best
+
+
+def distance(a: str, b: str) -> float:
+    """
+    Distance between two names of one or more words, in any mix of scripts.
+
+    Titles and honorifics are ignored (Shri, Smt, Dr, ji, sahab, bhai), joined
+    honorifics (Rameshbhai) and words like Devi or Kumar may be left out for a
+    small penalty, initials match words that start with the same letter, and
+    words may come in any order for a small penalty.
+    """
+    va, vb = _variants(a), _variants(b)
+    if not va or not vb:
+        return INF
+    return round(_variants_distance(va, vb), 6)       # 1.8, not 1.7999999999999998
+
+
+@lru_cache(maxsize=50_000)
+def sound_length(text: str) -> int:
+    """Number of sounds in a name or place, all words together."""
+    return sum(len(tokenize(w)) for w in text.split())
+
+
+@lru_cache(maxsize=50_000)
+def sound_range(text: str) -> tuple[int, float]:
+    """
+    Fewest and most sounds any variant of `text` can stand for.
+
+    An initial stands for a word of any length, so a name with one has no
+    upper bound. `best_match` uses this to skip references that cannot be
+    close.
+    """
+    lo, hi = float("inf"), 0.0
+    for _, words in _variants(text):
+        n = sum(len(w.sounds) for w in words)
+        lo = min(lo, n)
+        hi = max(hi, float("inf") if any(w.initial for w in words) else n)
+    return (int(lo), hi) if lo != float("inf") else (0, 0.0)

misheard/explain.py

@@ -0,0 +1,165 @@
+"""
+Why two names are as close as they are.
+
+    >>> print(explain("Barmer", "बाड़मेर"))
+    Barmer ↔ बाड़मेर (baaṛmer)   distance 0.4
+      b  =  b
+      a  →  aa    0.25  vowel length
+      r  →  ṛ     0.15  retroflex flap ड़ is heard and written as r (Baadmer/Barmer)
+      m  =  m
+      e  =  e
+      r  =  r
+
+`explain` returns the same distance as `distance`, broken into steps: each
+sound kept, swapped, added or dropped, plus word-level steps (a title
+ignored, Devi left out, an initial, a change of word order). The step costs
+add up to the distance.
+"""
+from dataclasses import dataclass
+from itertools import permutations
+
+from .distance import (
+    CONFUSION_NOTES, CONSONANTS, INDEL_CHEAP, INF, INITIAL_COST, MAX_PERMUTED_WORDS,
+    SWAP_PENALTY, VOWELS, _variants_detailed, _Word, _word_cost, indel_cost, sub_cost,
+)
+from .translit import to_roman
+
+
+@dataclass(frozen=True)
+class Step:
+    kind: str       # same, swap, add, drop, initial, reorder, title, optional, suffix
+    a: str          # sound or word on the first side ("" if none)
+    b: str          # sound or word on the second side ("" if none)
+    cost: float
+    why: str = ""   # human-readable reason, when there is one
+
+
+@dataclass(frozen=True)
+class Explanation:
+    a: str
+    b: str
+    distance: float
+    steps: tuple[Step, ...]
+
+    def __str__(self) -> str:
+        def label(text: str) -> str:
+            roman = to_roman(text)
+            return text if roman == text.lower() else f"{text} ({roman})"
+
+        lines = [f"{label(self.a)} ↔ {label(self.b)}   distance {self.distance:g}"]
+        sym = {"same": "=", "swap": "→", "add": "+", "drop": "-", "initial": "≈"}
+        width = max([len(s.a) for s in self.steps if s.kind in sym] + [1])
+        for s in self.steps:
+            if s.kind in sym:
+                cost = f"{s.cost:g}" if s.cost else ""
+                lines.append(f"  {s.a or '·':<{width}}  {sym[s.kind]}  {s.b or '·':<{width}}  {cost:>5}  {s.why}".rstrip())
+            else:
+                lines.append(f"  [{s.kind}] {s.why}  {s.cost:g}".rstrip())
+        return "\n".join(lines)
+
+
+def _sub_why(a: str, b: str) -> str:
+    note = CONFUSION_NOTES.get(frozenset((a, b)))
+    if note:
+        return note
+    if (a in VOWELS) != (b in VOWELS):
+        return "vowel for consonant"
+    if a in VOWELS:
+        names = ("height", "front/back", "length")
+        diff = [n for n, x, y in zip(names, VOWELS[a], VOWELS[b]) if x != y]
+        return "vowel " + ", ".join(diff)
+    names = ("place", "manner", "voicing", "aspiration")
+    return ", ".join(n for n, x, y in zip(names, CONSONANTS[a], CONSONANTS[b]) if x != y)
+
+
+def _indel_why(tok: str) -> str:
+    if tok == "a":
+        return "short a (often silent)"
+    if tok in INDEL_CHEAP:
+        return "often silent or only in spelling"
+    return ""
+
+
+def _align(pa: tuple[str, ...], pb: tuple[str, ...]) -> list[Step]:
+    """Backtrace of the weighted edit distance, same arithmetic as the matcher."""
+    n, m = len(pa), len(pb)
+    d = [[0.0] * (m + 1) for _ in range(n + 1)]
+    for j in range(1, m + 1):
+        d[0][j] = d[0][j - 1] + indel_cost(pb[j - 1])
+    for i in range(1, n + 1):
+        d[i][0] = d[i - 1][0] + indel_cost(pa[i - 1])
+        for j in range(1, m + 1):
+            d[i][j] = min(
+                d[i - 1][j - 1] + sub_cost(pa[i - 1], pb[j - 1]),
+                d[i - 1][j] + indel_cost(pa[i - 1]),
+                d[i][j - 1] + indel_cost(pb[j - 1]),
+            )
+    steps: list[Step] = []
+    i, j = n, m
+    while i or j:
+        if i and j and d[i][j] == d[i - 1][j - 1] + sub_cost(pa[i - 1], pb[j - 1]):
+            x, y = pa[i - 1], pb[j - 1]
+            c = sub_cost(x, y)
+            steps.append(Step("same", x, y, 0.0) if x == y else Step("swap", x, y, c, _sub_why(x, y)))
+            i, j = i - 1, j - 1
+        elif i and d[i][j] == d[i - 1][j] + indel_cost(pa[i - 1]):
+            steps.append(Step("drop", pa[i - 1], "", indel_cost(pa[i - 1]), _indel_why(pa[i - 1])))
+            i -= 1
+        else:
+            steps.append(Step("add", "", pb[j - 1], indel_cost(pb[j - 1]), _indel_why(pb[j - 1])))
+            j -= 1
+    return steps[::-1]
+
+
+def _word_steps(x: _Word, y: _Word) -> list[Step]:
+    if x.initial or y.initial:
+        c = _word_cost(x, y)
+        a, b = "".join(x.sounds), "".join(y.sounds)
+        why = "initial" if c in (0.0, INITIAL_COST) else "initial with a different letter"
+        return [Step("initial", a, b, c, why)]
+    return _align(x.sounds, y.sounds)
+
+
+def _words_steps(wa: tuple[_Word, ...], wb: tuple[_Word, ...]) -> tuple[float, list[Step]]:
+    n = len(wa)
+    if n != len(wb):
+        joined = _align(tuple(t for w in wa for t in w.sounds), tuple(t for w in wb for t in w.sounds))
+        return sum(s.cost for s in joined), joined
+    cost = [[_word_cost(x, y) for y in wb] for x in wa]
+    best, best_perm = sum(cost[i][i] for i in range(n)), tuple(range(n))
+    if 1 < n <= MAX_PERMUTED_WORDS:
+        for perm in permutations(range(n)):
+            c = sum(cost[i][p] for i, p in enumerate(perm)) + SWAP_PENALTY
+            if c < best:
+                best, best_perm = c, perm
+    steps: list[Step] = []
+    if best_perm != tuple(range(n)):
+        order = " ".join("".join(wb[p].sounds) for p in best_perm)
+        steps.append(Step("reorder", "", "", SWAP_PENALTY, f"words in a different order: {order}"))
+    for i, p in enumerate(best_perm):
+        steps.extend(_word_steps(wa[i], wb[p]))
+    return best, steps
+
+
+def _note_steps(notes, side: str) -> list[Step]:
+    what = {"title": "title or honorific ignored", "optional": "left out", "suffix": "honorific suffix split off"}
+    return [Step(kind, w if side == "a" else "", w if side == "b" else "", cost, f"{w}: {what[kind]}")
+            for w, kind, cost in notes]
+
+
+def explain(a: str, b: str) -> Explanation:
+    """The steps that make up `distance(a, b)`, cheapest alignment first."""
+    va, vb = _variants_detailed(a), _variants_detailed(b)
+    if not va or not vb:
+        return Explanation(a, b, INF, ())
+    best, best_steps = INF, []
+    for pa, wa, na in va:
+        for pb, wb, nb in vb:
+            d, steps = _words_steps(wa, wb)
+            if pa + pb + d < best:
+                best = pa + pb + d
+                best_steps = _note_steps(na, "a") + _note_steps(nb, "b") + steps
+    return Explanation(a, b, round(best, 6), tuple(best_steps))
+
+
+__all__ = ["explain", "Explanation", "Step"]

misheard/match.py

@@ -0,0 +1,111 @@
+"""
+Find the closest references to something heard.
+
+    m = Matcher(districts)          # once
+    m.best_match("Baadmer")         # per utterance
+
+`Matcher` holds a list of references (names, places, anything spoken),
+prepared once, and ranks them by phonetic distance to the heard text,
+returning the closest few. `best_match` does the same for a one-off list. It does not
+decide whether the best one is "good enough": that depends on the
+application, so the distances and the gap between the first and second
+match are returned for the caller to judge.
+
+Every sound missing from one side costs at least the cheapest deletion, so a
+reference much longer or shorter than what was heard cannot beat matches
+already found. Lengths are ranges (a dropped "Devi", an initial standing for
+a whole word), and the gap between the two ranges gives the lower bound.
+References are visited in order of that gap and the search stops once the
+bound exceeds the current `top`-th best. Each distance computation also
+stops early once it can't beat that. The result is exactly what scoring
+every reference would give, with far fewer computations.
+"""
+from bisect import insort
+from collections.abc import Hashable, Iterable
+from dataclasses import dataclass
+
+from .distance import INDEL_CHEAP, INF, _variants, _variants_distance, sound_range
+
+_FLOOR = min(INDEL_CHEAP.values())      # cheapest cost of one missing sound
+_EPS = 1e-6                             # distances are rounded to 6 places
+
+
+@dataclass(frozen=True)
+class Match:
+    key: Hashable       # the key given with the reference, or the text itself
+    text: str           # the reference text
+    distance: float     # phonetic distance from what was heard; 0 is identical
+
+
+Reference = str | tuple[Hashable, str]
+
+
+class Matcher:
+    """
+    A list of references, prepared once for many lookups.
+
+    references: plain strings, or (key, text) pairs when several texts lead
+    to one thing (an id for a person, aliases for one city). With pairs,
+    each key appears at most once in a result, at its best distance.
+
+    Raises UnsupportedScriptError if a reference is in a script the library
+    can't read, so bad data shows up when the list is loaded, not mid-call.
+    """
+
+    def __init__(self, references: Iterable[Reference]):
+        self._refs = []
+        order: dict[Hashable, int] = {}
+        for r in references:
+            key, text = (r, r) if isinstance(r, str) else (r[0], r[1])
+            variants = _variants(text)
+            if variants:
+                rank = order.setdefault(key, len(order))   # equal distances keep list order
+                self._refs.append((key, text, variants, sound_range(text), rank))
+
+    def __len__(self) -> int:
+        return len(self._refs)
+
+    def best_match(self, heard: str, top: int = 3) -> list[Match]:
+        """The `top` references closest to `heard`, nearest first; ties in list order."""
+        if top < 1:
+            raise ValueError("top must be at least 1")
+        heard_variants = _variants(heard)
+        if not heard_variants or not self._refs:
+            return []
+        lo, hi = sound_range(heard)
+
+        def gap(ref) -> float:
+            r_lo, r_hi = ref[3]
+            return max(0, r_lo - hi, lo - r_hi)
+
+        best: dict[Hashable, Match] = {}
+        ranked: list[tuple[float, int, Hashable]] = []
+        for ref in sorted(self._refs, key=gap):
+            key, text, variants, _, rank = ref
+            full = len(ranked) >= top
+            cutoff = ranked[-1][0] if full else INF
+            if full and _FLOOR * gap(ref) > cutoff + _EPS:
+                break
+            d = _variants_distance(heard_variants, variants, cutoff + _EPS)
+            if d > cutoff + _EPS:
+                continue
+            d = round(d, 6)
+            if key in best and best[key].distance <= d:
+                continue
+            best[key] = Match(key, text, d)
+            ranked = [e for e in ranked if e[2] != key]
+            insort(ranked, (d, rank, key))
+            del ranked[top:]
+        return [best[k] for _, _, k in ranked]
+
+
+def best_match(heard: str, references: Iterable[Reference], top: int = 3) -> list[Match]:
+    """
+    The `top` references closest to `heard`, nearest first.
+
+    A shortcut for `Matcher(references).best_match(heard, top)`. When matching
+    many utterances against one list, build the Matcher once.
+    """
+    if top < 1:
+        raise ValueError("top must be at least 1")
+    return Matcher(references).best_match(heard, top)

misheard/translit.py

@@ -0,0 +1,254 @@
+"""
+Native script -> phonetic Roman.
+
+Speech-to-text returns Hindi and Marathi in Devanagari and Tamil in Tamil
+script, but customer records are stored in Roman letters. Everything is
+compared in one phonetic Roman space, so this module converts native script
+into it.
+
+The output is plain lowercase Roman with long vowels doubled (aa, ee, oo)
+and retroflex consonants marked with a dot below (ṭ ḍ ṇ ḷ ṛ). The phonetic
+matcher reads those marks; `plain()` strips them for anything that wants
+ordinary letters.
+
+Hindi needs schwa deletion: the inherent "a" written in every consonant is
+often silent (मोहन is "mohan", not "mohana"; बाड़मेर is "baaṛmer"). Tamil has
+no silent schwa but voices stops between vowels and after nasals
+(முருகன் is "murugan", not "murukan").
+"""
+import re
+import unicodedata
+
+# ---------------------------------------------------------------- Devanagari
+
+_DEV_CONS = {
+    "क": "k", "ख": "kh", "ग": "g", "घ": "gh", "ङ": "n",
+    "च": "ch", "छ": "chh", "ज": "j", "झ": "jh", "ञ": "n",
+    "ट": "ṭ", "ठ": "ṭh", "ड": "ḍ", "ढ": "ḍh", "ण": "ṇ",
+    "त": "t", "थ": "th", "द": "d", "ध": "dh", "न": "n",
+    "प": "p", "फ": "ph", "ब": "b", "भ": "bh", "म": "m",
+    "य": "y", "र": "r", "ल": "l", "ळ": "ḷ", "व": "v",
+    "श": "sh", "ष": "sh", "स": "s", "ह": "h",
+}
+# consonant + nukta, as precomposed characters or base + U+093C
+_DEV_NUKTA = {"क": "q", "ख": "kh", "ग": "g", "ज": "z", "ड": "ṛ", "ढ": "ṛh", "फ": "f", "य": "y", "र": "r"}
+_DEV_VOWELS = {
+    "अ": "a", "आ": "aa", "इ": "i", "ई": "ee", "उ": "u", "ऊ": "oo", "ऋ": "ri",
+    "ए": "e", "ऐ": "ai", "ओ": "o", "औ": "au", "ऑ": "o", "ॲ": "e",
+}
+_DEV_MATRAS = {
+    "ा": "aa", "ि": "i", "ी": "ee", "ु": "u", "ू": "oo", "ृ": "ri",
+    "े": "e", "ै": "ai", "ो": "o", "ौ": "au", "ॉ": "o", "ॅ": "e",
+}
+_VIRAMA, _NUKTA, _ANUSVARA, _CHANDRABINDU, _VISARGA = "्", "़", "ं", "ँ", "ः"
+_DEV_DIGITS = {chr(0x0966 + i): str(i) for i in range(10)}
+
+
+def _devanagari_word(word: str) -> str:
+    # Split the word into units: (consonant cluster, vowel, vowel_is_inherent).
+    word = unicodedata.normalize("NFD", word)
+    word = word.replace("ज्ञ", "ग्य")           # ज्ञ is spoken gy in Hindi (ज्ञान = gyaan)
+    units: list[list] = []
+    cluster: list[str] = []
+    i = 0
+    while i < len(word):
+        ch = word[i]
+        nxt = word[i + 1] if i + 1 < len(word) else ""
+        if ch in _DEV_CONS:
+            sound = _DEV_NUKTA.get(ch, _DEV_CONS[ch]) if nxt == _NUKTA else _DEV_CONS[ch]
+            if nxt == _NUKTA:
+                i += 1
+                nxt = word[i + 1] if i + 1 < len(word) else ""
+            cluster.append(sound)
+            if nxt == _VIRAMA:              # half consonant: joins the next one
+                i += 2
+                continue
+            if nxt in _DEV_MATRAS:
+                units.append([cluster, _DEV_MATRAS[nxt], False])
+                i += 2
+            else:
+                units.append([cluster, "a", True])
+                i += 1
+            cluster = []
+            continue
+        if ch in _DEV_VOWELS:
+            units.append([[], _DEV_VOWELS[ch], False])
+        elif ch == _ANUSVARA:
+            if units:
+                units[-1][1] += _NASAL      # resolved below by the next consonant
+        elif ch == _CHANDRABINDU:
+            if units:
+                units[-1][1] += "n"         # nasalised vowel
+        elif ch in _DEV_DIGITS:
+            units.append([[], _DEV_DIGITS[ch], False])
+        i += 1
+    if cluster:                             # word ends in a half consonant
+        units.append([cluster, "", False])
+
+    # Schwa deletion, right to left (Ohala's rule, simplified):
+    #  - a final inherent "a" is dropped unless it follows a conjunct (मिश्र)
+    #  - a medial inherent "a" is dropped in V C _ C V, i.e. when it sits on a
+    #    single consonant, between two syllables that keep their vowels.
+    keep = [True] * len(units)
+    for k in range(len(units) - 1, 0, -1):
+        cons, vowel, inherent = units[k]
+        if not inherent:
+            continue
+        if k == len(units) - 1:
+            if len(cons) == 1:
+                keep[k] = False
+            continue
+        nxt_cons, nxt_vowel, _ = units[k + 1]
+        if len(cons) == 1 and len(nxt_cons) == 1 and keep[k + 1] and keep[k - 1] and nxt_vowel:
+            keep[k] = False
+
+    out = []
+    for (cons, vowel, inherent), kept in zip(units, keep):
+        out.append("".join(cons))
+        if kept or not inherent:
+            out.append(vowel)
+        elif vowel.endswith(("n", _NASAL)) and vowel != "a":
+            out.append(vowel[-1])
+    return _resolve_anusvara("".join(out))
+
+
+_NASAL = "\x00"
+
+
+def _resolve_anusvara(word: str) -> str:
+    # Anusvara takes the place of the consonant after it: m before labials
+    # (चंपा = champa), ng before h (सिंह = singh), n otherwise (संत = sant;
+    # before k and g that already spells ng: गंगा = ganga).
+    word = re.sub(_NASAL + r"(?=[pbm])", "m", word)
+    word = re.sub(_NASAL + r"(?=h)", "ng", word)
+    return word.replace(_NASAL, "n")
+
+
+# ---------------------------------------------------------------- Tamil
+
+_TA_CONS = {
+    "க": "k", "ங": "ng", "ச": "ch", "ஞ": "nj", "ட": "ṭ", "ண": "ṇ",
+    "த": "t", "ந": "n", "ப": "p", "ம": "m", "ய": "y", "ர": "r",
+    "ல": "l", "வ": "v", "ழ": "zh", "ள": "ḷ", "ற": "r", "ன": "n",
+    "ஜ": "j", "ஷ": "sh", "ஸ": "s", "ஹ": "h",
+}
+_TA_VOWELS = {
+    "அ": "a", "ஆ": "aa", "இ": "i", "ஈ": "ee", "உ": "u", "ஊ": "oo",
+    "எ": "e", "ஏ": "e", "ஐ": "ai", "ஒ": "o", "ஓ": "o", "ஔ": "au",
+}
+_TA_MATRAS = {
+    "ா": "aa", "ி": "i", "ீ": "ee", "ு": "u", "ூ": "oo",
+    "ெ": "e", "ே": "e", "ை": "ai", "ொ": "o", "ோ": "o", "ௌ": "au",
+}
+_TA_PULLI = "்"
+_TA_VOICED = {"k": "g", "t": "d", "ṭ": "ḍ", "p": "b", "ch": "s"}
+_NASALS = {"ng", "nj", "ṇ", "n", "m"}
+
+
+def _tamil_word(word: str) -> str:
+    # Tamil writes vowel signs (ொ ோ ௌ) as two code points in some input;
+    # NFC folds them back into one.
+    word = unicodedata.normalize("NFC", word)
+    word = word.replace("ட்ச", "க்ஷ")       # Tamil spells क्ष as ட்ச (லட்சுமி = Lakshmi)
+    sounds: list[tuple[str, str]] = []      # (consonant or "", vowel or "")
+    i = 0
+    while i < len(word):
+        ch = word[i]
+        nxt = word[i + 1] if i + 1 < len(word) else ""
+        if ch in _TA_CONS:
+            if nxt == _TA_PULLI:
+                sounds.append((_TA_CONS[ch], ""))
+                i += 2
+            elif nxt in _TA_MATRAS:
+                sounds.append((_TA_CONS[ch], _TA_MATRAS[nxt]))
+                i += 2
+            else:
+                sounds.append((_TA_CONS[ch], "a"))
+                i += 1
+            continue
+        if ch in _TA_VOWELS:
+            sounds.append(("", _TA_VOWELS[ch]))
+        i += 1
+
+    out = []
+    for idx, (cons, vowel) in enumerate(sounds):
+        prev = sounds[idx - 1] if idx else ("", "")
+        nxt = sounds[idx + 1] if idx + 1 < len(sounds) else ("", "")
+        if cons in _TA_VOICED:
+            after_vowel = idx > 0 and prev[1] != ""
+            after_nasal = idx > 0 and prev[0] in _NASALS and prev[1] == ""
+            geminate = (prev[0] == cons and prev[1] == "") or (vowel == "" and nxt[0] == cons)
+            if idx == 0 and cons == "ch":
+                cons = "s"                  # சரவணன் -> saravanan
+            elif vowel and not geminate and (after_vowel or after_nasal):
+                # a single stop between vowels or after a nasal is voiced
+                cons = "j" if (cons == "ch" and after_nasal) else _TA_VOICED[cons]
+        if cons in ("ng", "nj") and not vowel and nxt[0]:
+            cons = "n"                      # ங்க = ng, ஞ்ச = nj: the next letter carries g/j
+        out.append(cons + vowel)
+    return "".join(out)
+
+
+# ---------------------------------------------------------------- public API
+
+_DEVANAGARI = re.compile(r"[ऀ-ॿ]")
+_TAMIL = re.compile(r"[஀-௿]")
+_SUPPORTED = {"LATIN", "DEVANAGARI", "TAMIL"}
+
+
+class UnsupportedScriptError(ValueError):
+    """Text contains letters from a script this library can't read yet."""
+
+    def __init__(self, script: str, text: str):
+        self.script = script
+        super().__init__(
+            f"{script.title()} script is not supported yet (in {text!r}). "
+            "Supported: Devanagari, Tamil, Latin."
+        )
+
+
+def _foreign_script(word: str) -> str | None:
+    for ch in word:
+        if unicodedata.category(ch).startswith(("L", "M")):
+            script = unicodedata.name(ch, "UNKNOWN").split()[0]
+            if script not in _SUPPORTED and script != "COMBINING":
+                return script
+    return None
+
+
+def script_of(text: str) -> str:
+    """"devanagari", "tamil" or "latin"; for other scripts their lowercase name ("telugu")."""
+    if _DEVANAGARI.search(text):
+        return "devanagari"
+    if _TAMIL.search(text):
+        return "tamil"
+    foreign = _foreign_script(text)
+    return foreign.lower() if foreign else "latin"
+
+
+def to_roman(text: str) -> str:
+    """
+    Convert any mix of Devanagari, Tamil and Latin to phonetic Roman.
+
+    Raises UnsupportedScriptError for other scripts (Telugu, Bengali, …)
+    rather than silently dropping them.
+    """
+    words = []
+    for word in text.split():
+        foreign = _foreign_script(word)
+        if foreign:
+            raise UnsupportedScriptError(foreign, word)
+        script = script_of(word)
+        if script == "devanagari":
+            words.append(_devanagari_word(word))
+        elif script == "tamil":
+            words.append(_tamil_word(word))
+        else:
+            words.append(word.lower())
+    return " ".join(w for w in words if w)
+
+
+def plain(text: str) -> str:
+    """Drop the retroflex marks: 'baaṛmer' -> 'baarmer'."""
+    decomposed = unicodedata.normalize("NFD", text)
+    return "".join(c for c in decomposed if not unicodedata.combining(c))

misheard-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: misheard
+Version: 0.1.0
+Summary: Match Indian names and places by how they sound, across Devanagari, Tamil and Roman script
+Project-URL: Homepage, https://github.com/trivedi-aman/misheard
+Project-URL: Changelog, https://github.com/trivedi-aman/misheard/blob/main/CHANGELOG.md
+Project-URL: Roadmap, https://github.com/trivedi-aman/misheard/blob/main/PLAN.md
+Project-URL: Issues, https://github.com/trivedi-aman/misheard/issues
+Author-email: Aman Trivedi <amantrivedi2003@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fuzzy matching,hindi,indic,names,phonetic,speech,tamil,transliteration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Hindi
+Classifier: Natural Language :: Marathi
+Classifier: Natural Language :: Tamil
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: bench
+Requires-Dist: jellyfish>=1; extra == 'bench'
+Requires-Dist: rapidfuzz>=3; extra == 'bench'
+Provides-Extra: demo
+Requires-Dist: gradio>=6; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# misheard
+
+Match Indian names and places by how they **sound**, not how they are spelled, across Devanagari, Tamil and Roman script. Pure Python, no dependencies.
+
+*Formerly published as [`indic-phonetic`](https://pypi.org/project/indic-phonetic/).*
+
+```python
+from misheard import distance, best_match, to_roman
+
+to_roman("बाड़मेर")                  # 'baaṛmer'
+to_roman("முருகன்")                  # 'murugan'
+
+distance("Barmer", "बाड़मेर")         # 0.4   same place
+distance("Barmer", "Baadmer")         # 0.6   same place, different spelling
+distance("Mohan", "Rohan")            # 1.7   different people
+
+best_match("Rohun Varma", [("C1", "Rohan Verma"), ("C2", "Mohan Verma"), ("C3", "Sohan Verma")])
+# [Match(key='C1', text='Rohan Verma', distance=1.7),
+#  Match(key='C3', text='Sohan Verma', distance=2.85),
+#  Match(key='C2', text='Mohan Verma', distance=3.4)]
+```
+
+```bash
+pip install misheard
+```
+
+> **Status: alpha (0.1).** The API may still change before 1.0. Known gaps and the roadmap are in [PLAN.md](https://github.com/trivedi-aman/misheard/blob/main/PLAN.md).
+
+## Try it
+
+From a clone of the repository:
+
+```bash
+pip install -e '.[demo]'
+python demo/app.py          # opens http://127.0.0.1:7860
+```
+
+Type a name or place as it was heard, in any supported script, and see the closest matches from Indian districts or a sample list of people, why the top one matched, and what a voice agent might do with it (accept, read back, ask again). A second tab compares two names step by step.
+
+## Why
+
+Speech-to-text and hand-typed records spell Indian names in many ways: *Barmer / Baadmer / बाड़मेर*, *Lakshmi / Laxmi / லட்சுமி*, *Vikram / Wikram*. Edit distance counts every letter change as equally bad, so it is wrong in both directions:
+
+- **Barmer** and **Baadmer** are the same place: a long vowel plus the retroflex flap ड़ spelled two ways. That should be cheap.
+- **Mohan** and **Rohan** are different people: *m* and *r* sound nothing alike, even though only one letter differs. That should be expensive.
+
+English phonetic codes (Soundex, Metaphone) follow English spelling rules and don't know about retroflex consonants, aspiration or the silent *a* in Hindi.
+
+## How it works
+
+1. **Transliterate** Devanagari and Tamil into one phonetic Roman form. Hindi drops the silent *a* (schwa deletion: मोहन → *mohan*). Tamil voices stops between vowels (முருகன் → *murugan*). Retroflex sounds stay marked (ṭ ḍ ṇ ḷ ṛ).
+2. **Tokenize** into sounds, folding English-style spellings first (*x→ks*, *-ey→e*, doubled letters).
+3. **Score substitutions by articulatory features**: place and manner of articulation, voicing and aspiration for consonants; height, backness and length for vowels. A swap between similar sounds is cheap, a swap between unrelated sounds is expensive.
+4. **Override with known confusions** ([`data/confusions.csv`](https://github.com/trivedi-aman/misheard/blob/main/src/misheard/data/confusions.csv)): v/w, t/ṭ, ph/f, Tamil k/g, and so on. Each row says why it's there.
+5. **Weighted edit distance** over the sounds. Dropping a silent *a* or an *h* costs little.
+6. **Words as people say them.** Titles and honorifics are ignored (*Shri*, *Smt*, *Dr*, *ji*, *sahab*). A joined honorific (*Rameshbhai*) costs 0.1 to drop, and *Devi* or *Kumar* cost 0.5. An initial matches a word with the same first letter (*R. Kumar* / *Ramesh Kumar* = 0.3). Words may come in any order (*Kumar Ramesh Singh*) for 0.2.
+
+`best_match` skips references whose length alone rules them out. It gives the same result as scoring every reference, with far fewer comparisons.
+
+## API
+
+| | |
+| --- | --- |
+| `distance(a, b) -> float` | Phonetic distance between two names, in any mix of scripts. 0 means the same sounds. |
+| `Matcher(references)` | Prepare a reference list once. References are strings or `(key, text)` pairs; keys group aliases (*Bangalore*, *Bengaluru*) under one result. |
+| `Matcher.best_match(heard, top=3) -> list[Match]` | Closest references, nearest first; equal distances keep list order. |
+| `best_match(heard, references, top=3)` | Shortcut for a one-off list. |
+| `explain(a, b) -> Explanation` | The steps behind a distance: each sound kept, swapped, added or dropped, with the reason from the confusion table, plus titles ignored, words left out, initials and reordering. `print()` it for a readable table. |
+| `to_roman(text) -> str` | Devanagari / Tamil / Latin → phonetic Roman. |
+| `plain(text) -> str` | Remove the retroflex marks: *baaṛmer* → *baarmer*. |
+| `script_of(text) -> str` | `"devanagari"`, `"tamil"` or `"latin"`. |
+| `tokenize(word) -> tuple[str, ...]` | The sounds the distance is computed over. |
+
+The library does not decide whether a match is good enough, because that threshold depends on your application. A voice agent might accept a match below about 0.8 when it is at least 1.0 ahead of the next candidate, read back anything below 1.8, and ask again otherwise. Those values come from the project this library was extracted from; tune them on your own data.
+
+## Benchmark
+
+782 items: 300 synthetic people, and 745 Indian districts plus aliases. Run it with `python benchmarks/run.py`. Full results are in [benchmarks/results/latest.md](https://github.com/trivedi-aman/misheard/blob/main/benchmarks/results/latest.md).
+
+| Source | Kind | Items | Levenshtein top-1 | Metaphone top-1 | misheard top-1 |
+| --- | --- | --- | --- | --- | --- |
+| handwritten | name | 62 | 96.8% | 96.8% | 100.0% |
+| handwritten | place | 50 | 92.0% | 74.0% | 100.0% |
+| native script | name | 254 | 97.6% | 97.6% | 100.0% |
+| rule-generated | name | 246 | 99.6% | 96.3% | 100.0% |
+| rule-generated | place | 170 | 97.6% | 90.0% | 100.0% |
+
+**Read these numbers with care.** None of the items are real speech-to-text output yet. The rule-generated variants use the same confusions the engine models, and the handwritten ones were written by the author. Building a benchmark from data the engine wasn't designed around is the top item in [PLAN.md](https://github.com/trivedi-aman/misheard/blob/main/PLAN.md). Speed is still behind: about 5 ms per lookup against 780 places with a `Matcher`, compared with 0.1 ms for Levenshtein. A compiled core is planned.
+
+## Scope
+
+- **Scripts:** Devanagari (Hindi, Marathi, …), Tamil, Latin. Other scripts are not supported yet and raise `UnsupportedScriptError`.
+- **Made for:** names of people and places, short spoken phrases. It is not a general transliterator: use [indic-transliteration](https://pypi.org/project/indic-transliteration/) or [IndicXlit](https://github.com/AI4Bharat/IndicXlit) for running text.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev,bench]'
+pytest                     # tests marked xfail are known gaps from PLAN.md
+python benchmarks/run.py
+```
+
+## License
+
+MIT. The district list in `benchmarks/data` is derived from India Post's public pincode directory. All people in `benchmarks/data/people.csv` are synthetic.

misheard-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+misheard/__init__.py,sha256=asqLUr0BtoJLTHx757niznzooeo2S4HW64yGQI8DL0w,728
+misheard/distance.py,sha256=LITtM4MqsVvsvrFc7j43s3AR-gPqZasuDe4kdIeDB1A,14857
+misheard/explain.py,sha256=xdx1ge7krh8RIJf1XEnCcAdZszfq0sDWBPU2cZJqA1s,6472
+misheard/match.py,sha256=wpvcTsGWtVzqxQZf6Lqma2l03pDZA0svZoyaUHihVfE,4503
+misheard/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+misheard/translit.py,sha256=RYNcShbOu7O-99f9n_2k1lNq7i7xGHkTEdr2L3VSXZE,10208
+misheard/data/confusions.csv,sha256=nVffeSt4Q4X38qtL1rNAeGi417BOoi6bzspw1FUqIqQ,1062
+misheard-0.1.0.dist-info/METADATA,sha256=MA-zuVmz8MuNgvjTIsfE6zqpmf9u-95LG3YnKZM72Qs,8578
+misheard-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+misheard-0.1.0.dist-info/licenses/LICENSE,sha256=d9CMrNZPd8-E7_fJnCy2BnjqPf0pjpy7OHItMmfb_LE,1069
+misheard-0.1.0.dist-info/RECORD,,

misheard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

misheard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aman Trivedi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.