indic-phonetic 0.1.0__tar.gz

indic_phonetic-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store

indic_phonetic-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 (2026-11-13)
+
+First release on PyPI.
+
+- Web demo (`demo/app.py`, Gradio): match against districts, people or your own list; compare two names.
+- New `explain(a, b)`: the steps and reasons behind a distance.
+- New `Matcher` class: prepare references once, match many times. About 5× faster (25 ms → 5 ms against 780 places).
+- Equal distances now keep the order of the reference list.
+- Fix: anusvara before h is ng (सिंह = singh) and before labials m (चंपा = champa).
+- Fix: ज्ञ is gy (ज्ञान = gyaan).
+- Fix: Tamil ங்க and ஞ்ச no longer double the consonant (வெங்கடேஷ் = vengaḍesh, was venggaḍesh).
+- New confusion row t/ḍ for Tamil ட romanised t (Natarajan, Venkatesh).
+- Unsupported scripts raise `UnsupportedScriptError` instead of being silently dropped; `script_of` names them.
+- Titles and honorifics are ignored (Shri, Smt, Dr, ji, sahab, bhai, திரு, श्री…); joined honorifics (Rameshbhai) and Devi/Kumar/Kumari are optional for a small penalty.
+- Initials match words with the same first letter (R. Kumar / Ramesh Kumar).
+- Names of up to 4 words are compared in any order (was: 2).
+- `distance` is rounded to 6 decimal places.
+- New `sound_range`; `best_match` pruning uses it and stays exact.
+
+## 0.0.1 (not published)
+
+- Extracted from Vaani: transliteration (Devanagari, Tamil → phonetic Roman) and feature-weighted phonetic distance.
+- `best_match` with exact length-bound pruning and key-grouped aliases.
+- Benchmark against Levenshtein and Metaphone.

indic_phonetic-0.1.0/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.

indic_phonetic-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: indic-phonetic
+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/indic-phonetic
+Project-URL: Changelog, https://github.com/trivedi-aman/indic-phonetic/blob/main/CHANGELOG.md
+Project-URL: Roadmap, https://github.com/trivedi-aman/indic-phonetic/blob/main/PLAN.md
+Project-URL: Issues, https://github.com/trivedi-aman/indic-phonetic/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
+
+# indic-phonetic
+
+Match Indian names and places by how they **sound**, not how they are spelled, across Devanagari, Tamil and Roman script. Pure Python, no dependencies.
+
+```python
+from indic_phonetic 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 indic-phonetic
+```
+
+> **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/indic-phonetic/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/indic-phonetic/blob/main/src/indic_phonetic/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/indic-phonetic/blob/main/benchmarks/results/latest.md).
+
+| Source | Kind | Items | Levenshtein top-1 | Metaphone top-1 | indic-phonetic 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/indic-phonetic/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.

indic_phonetic-0.1.0/PLAN.md

@@ -0,0 +1,107 @@
+# Plan
+
+Where the library is going, in order. Tick items off as they land; each phase ends with a release.
+
+The engine was extracted from Vaani, a multilingual voice agent, where it matched spoken customer names and districts. Vaani-specific code (confidence thresholds, pincode cross-checks, customer data) stayed behind.
+
+## Phase 0: Extraction ✅ (0.0.1)
+
+- [x] Copy `translit.py` and `phonetic.py` (now `distance.py`) out of Vaani; load `confusions.csv` as package data
+- [x] Generic `best_match` with length-bound pruning, `(key, text)` pairs for aliases and ids
+- [x] Tests ported; known gaps recorded as strict `xfail` tests
+- [x] Benchmark against Levenshtein and Metaphone, reproducing Vaani's numbers
+
+## Phase 1: Correctness fixes (0.1.0)
+
+Each one has an `xfail` test. Remove the marker when it's fixed. 1.3, 1.5 and 1.11 carry over to 0.2.0: 1.3 and 1.5 need the phase 2 data to judge.
+
+- [x] **1.1 Anusvara before ह / fricatives.** `सिंह` → `sinh`, should be `singh` (distance to *Singh* is 1.25 today). Anusvara takes the place of the following consonant: ng before velars and h, m before labials, n otherwise.
+- [x] **1.2 ज्ञ.** `ज्ञान` → `jnaan`, distance 2.85 to *Gyan*. Map ज्ञ to `gy`. Marathi says `dny` (*Dnyaneshwar*), so either add a confusion row gy/dny or take a language hint. *Done for Hindi; Marathi `dny` left to the language hint (4.4).*
+- [ ] **1.3 Final-syllable vowels in surnames.** *Patil* / *Patel* = 0.35, the one false accept in Vaani's eval. Options: weight vowel changes higher in the last syllable, or add confusion rows that make specific pairs more expensive. Check that this doesn't break *Gupta/Gupt* or *Amit/Amita*.
+- [x] **1.4 Fail loudly on unsupported scripts.** Telugu, Kannada, Bengali, … are silently dropped today. Raise an error, or return a result that says what was dropped. *Now raises `UnsupportedScriptError` (a `ValueError`) naming the script.*
+- [ ] **1.5 Audit `_fold`.** The English-spelling rules (`-ey`, `-ow`, `c→k`) were written for the names in Vaani. Collect counterexamples. Found so far: *Verma* / वर्मा = 0.95 (English writes the schwa as *e*; also *Varma*), so the same name spelled two ways only gets a read-back.
+- [x] **1.6 Tamil nasal + stop clusters.** `வெங்கடேஷ்` → `venggaḍesh` (distance 0.95 to *Venkatesh*, should be near 0): ங் gives `ng` and the following க is voiced to `g` as well. Check ஞ்ச, ந்த, ண்ட, ம்ப too. *Fixed ங்க and ஞ்ச (the others were already right); added confusion row t/ḍ 0.30 for Tamil voiced ட written t, so Venkatesh/வெங்கடேஷ் is 0.55.*
+- [x] **1.7 Titles and honorifics.** *Shri Mohan Lal* vs *Mohan Lal* was 2.3, worse than *Mohan* vs *Rohan* (1.7). Titles (Shri, Smt, Dr, திரு, …) and honorific words (ji, sahab, bhai, …) are now dropped; joined honorifics (*Rameshbhai*, *Hansaben*) cost 0.1 to drop; *Devi*, *Kumar*, *Kumari* cost 0.5 to drop. Joined *ji* is kept (*Balaji*, *Shivaji*).
+- [x] **1.8 Word order beyond two words.** *Kumar Ramesh Singh* vs *Ramesh Kumar Singh* was 10.2. Names of up to 4 words are now compared in every order, with a 0.2 penalty for any reorder.
+- [x] **1.9 Initials.** *R. Kumar* vs *Ramesh Kumar* was 2.7. An initial now matches a word starting with the same letter for 0.3 (1.5 otherwise); *R.K.* splits into two initials. `best_match` pruning uses length ranges so it stays exact.
+- [x] **1.10 Round `distance`.** It returned 1.7999999999999998; now rounded to 6 places like `best_match`.
+- [ ] **1.11 Property tests** (Hypothesis): symmetry, `distance(a, a) == 0`, `to_roman` never raises on random Unicode, `best_match` equals brute force on random lists. Also the safety net for the Rust kernel (3.4).
+
+## Phase 2: Honest benchmark (0.2.0)
+
+This phase decides whether the library is actually better, so it matters more than any feature.
+
+- [ ] **2.1 Real speech-to-text data.** Record or collect 100+ spoken names and places (Hindi, Marathi, Tamil, Indian English), run them through one or two STT services (Sarvam, Google, Whisper), and keep the transcripts with the intended name. Store the transcripts, not the audio.
+- [ ] **2.2 Real spelling variants.** Find a public source of name variants (electoral rolls are not OK; look for open datasets, Wikipedia/Wikidata labels in several scripts, census place names).
+- [ ] **2.3 Non-match test.** Names that are *not* in the reference list should get no close match. Report the distribution of best distances for them (Vaani's eval did this; port it).
+- [ ] **2.4 Report precision at a threshold**, not just top-1. A matcher that always returns something looks good on top-1.
+- [ ] **2.5 Compare against stronger baselines:** Jaro-Winkler, libindic soundex, and transliterate-then-Levenshtein using IndicXlit.
+
+## Phase 3: Speed (0.3.0)
+
+Was 25 ms per lookup against 780 places; 3.1, 3.2 and 4.1 brought it to about 5 ms (Levenshtein: 0.1 ms).
+
+- [x] **3.1 Profile.** The biggest cost was `best_match` re-sorting all results after every reference (quadratic), then the DP and `sub_cost` lookups. Now: top-k kept incrementally, a token → int index with a dense cost matrix, and the DP stops early once it can't beat the current top-k.
+- [x] **3.2 Cache tokenized references** inside `best_match` (or a `Matcher` object built once from the references).
+- [ ] **3.3 Blocking for large lists** (10⁵+ names): index the first consonant classes or a coarse phonetic key, and only score that bucket.
+- [ ] **3.4 Rust kernel (PyO3 + maturin).** Compile only the hot loop: weighted edit distance over int token ids, the word-swap logic, and batch scoring with pruning over a `Matcher`'s references. Cost tables are passed in as arrays, so tuning weights or learning them (phase 5) never touches Rust. Transliteration, folding and tokenizing stay in Python: they change often, contributors can fix them without Rust, and with 3.2 they run once per reference. Ship `abi3` wheels (Linux/macOS/Windows, x86 and ARM) from CI. The pure-Python kernel stays as the fallback and as the reference: a property test checks both give identical distances on random inputs. Not C/C++: Rust's packaging via maturin is simpler and the parser input is untrusted.
+
+Order: 3.1 and 3.2 first (they define the kernel boundary), then 3.4, then 3.3. Blocking removes most comparisons, the kernel makes the rest about 100× cheaper; large lists need both.
+
+## Phase 4: API and configurability (0.4.0)
+
+- [x] **4.1 `Matcher` class** holding prepared references: `Matcher(refs).best_match(heard)`. `best_match` remains as a shortcut. Costs and confusions as parameters come with 4.2 / 5.1.
+- [ ] **4.2 Custom confusion tables**: merge with or replace the defaults.
+- [x] **4.3 `explain(a, b)`** that returns the alignment and each step's cost. Useful for debugging and for the README, and required by 5.4: learning counts substitutions from these alignments.
+- [ ] **4.4 Language hint** (`lang="mr"`) for Marathi ज्ञ, Bengali v→b, and similar.
+- [ ] **4.5 Decide on confidence grading.** Either keep it out (current choice) or offer `grade(matches, high=..., margin=...)` as an optional helper.
+- [ ] **4.6 Command-line tool.** `python -m indic_phonetic Barmer बाड़मेर` prints the distance (and the alignment, once 4.3 exists); `python -m indic_phonetic --refs places.txt Baadmer` prints the best matches. For trying the library without writing code.
+
+## Phase 5: Context and learned costs (0.5.0)
+
+The engine is already a small model: feature weights and confusion costs, set by hand. Accents reach this library as systematic speech-to-text errors (Bengali v→b, Tamil voicing, sh/s in Bihar and eastern UP), which are exactly what those parameters describe. So learn the parameters from data and select them with metadata, rather than replacing the engine with a neural model. It stays fast, explainable and deterministic.
+
+Depends on 4.1/4.2 (costs as a parameter object), 4.3 (alignments) and phase 2 data.
+
+Regional patterns to start the profiles from (already in `confusions.csv` with one all-India cost; a profile makes them cheaper where they're common and leaves them alone elsewhere):
+
+| Pattern | Where | Examples |
+| --- | --- | --- |
+| v → b | Bihar, Bengal, Odisha, Assam | Vinod/Binod, Vikas/Bikash, Vishnoi/Bishnoi |
+| ड़ / ड / र | Bihar, eastern UP | ghoḍa/ghora, paḍhai/parhai, saḍak/sarak |
+| sh → s | Bihar, eastern UP, Tamil | Shyam/Syam, Shiva/Siva |
+| voiced/unvoiced stops | Tamil | Kannan/Gannan, Palani/Balani |
+
+- [ ] **5.1 `Costs` object.** Feature weights, indel costs and confusions in one versioned, serialisable object. `Costs.default()` reproduces today's numbers exactly.
+- [ ] **5.2 Profiles selected by metadata.** `Matcher(refs, profile=...)` or per call: conversation language (`hi`, `mr`, `ta`, `bn`, …), caller region, and STT engine. Each STT engine has its own error patterns, so an engine profile may matter as much as an accent profile. Profiles layer on the default; unknown or missing metadata falls back to it.
+- [ ] **5.3 Priors over references.** `best_match(heard, prior={key: weight})` for session context (caller's state or district, a name said earlier). **Soft, not a filter:** the prior's effect is capped so wrong metadata (a migrant from Bihar giving a Bengaluru address) costs a little ranking, never the correct match.
+- [ ] **5.4 `Costs.fit(pairs, base=...)`.** Learn weights and confusion costs from confirmed (transcript, true name) pairs, regularised towards `base` so a few hundred pairs are enough. Align each pair with `explain` and count substitutions per profile (record *Vinod*, heard *Binod*, confirmed → one v→b observation in that region). Also learn from **corrected** read-backs as negatives, otherwise costs only ever go down: in Bihar and Bengal *Binod* is a real name, and a list holding both a Vinod and a Binod needs v/b to stay distinguishable. Output is a plain table that can be read and diffed.
+- [ ] **5.5 Benchmark with metadata.** Run each item with correct, wrong, and no metadata. Ship a profile only if it helps with correct metadata and hurts little with wrong metadata.
+- [ ] **5.6 Data collection (in Vaani, not here).** Log confirmed and corrected read-backs ("Did you say Barmer?" → yes / no, Baadmer) as labelled pairs, with consent and minimal fields. The library never collects data or learns at runtime.
+- [ ] **5.7 Per-person aliases (in the app, documented here).** If customer C17 is recorded as *Vinod* and confirms *Binod*, the app stores *Binod* as an alias under C17's key. `best_match` already groups `(key, text)` aliases, so the next call matches at distance 0 without touching any weights. Document this pattern in the README; it's the safe form of learning per session.
+
+Not planned: learning live inside a session. One call has too few names to learn from, labels are noisy (an uncorrected wrong match looks like a confirmation), a few odd sessions could shift weights for everyone, and the inputs are personal data. Session context goes in through 5.2 and 5.3 instead. A neural model is worth trying only if learned tables plateau on the phase 2 benchmark.
+
+## Phase 6: More scripts (0.6.0+)
+
+Each script needs a transliterator, tests with real names, and benchmark rows.
+
+- [ ] Telugu, Kannada (close to Tamil's structure, but voiced stops are written)
+- [ ] Bengali (inherent vowel is *o*; v→b)
+- [ ] Gujarati, Gurmukhi (close to Devanagari)
+- [ ] Malayalam
+
+## Phase 7: Publish (1.0.0)
+
+- [ ] GitHub repo, CI (pytest on 3.10–3.13, benchmark on PR)
+- [ ] Type-check with mypy/pyright, lint with ruff
+- [ ] Docs page: how the costs work, with the confusions table rendered
+- [ ] Publish to PyPI (name `indic-phonetic` was free as of 2026-11-13)
+- [ ] Write-up: blog post or short paper on the method and benchmark
+- [ ] Switch Vaani to depend on the library instead of its own copy
+
+## Open questions
+
+- **Name.** `indic-phonetic` is descriptive and easy to find in search. A more memorable name (*dhvani* is taken on PyPI) could come later.
+- **Units.** Distances are unbounded floats. Normalising by length (0–1) would make thresholds portable across short and long names, but it changes every number.
+- **Weights.** The feature weights were set by hand. Learning them is planned in phase 5 (`Costs.fit`), once phase 2 data exists.

indic_phonetic-0.1.0/README.md

@@ -0,0 +1,104 @@
+# indic-phonetic
+
+Match Indian names and places by how they **sound**, not how they are spelled, across Devanagari, Tamil and Roman script. Pure Python, no dependencies.
+
+```python
+from indic_phonetic 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 indic-phonetic
+```
+
+> **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/indic-phonetic/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/indic-phonetic/blob/main/src/indic_phonetic/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/indic-phonetic/blob/main/benchmarks/results/latest.md).
+
+| Source | Kind | Items | Levenshtein top-1 | Metaphone top-1 | indic-phonetic 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/indic-phonetic/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.

indic_phonetic-0.1.0/benchmarks/data/README.md

@@ -0,0 +1,8 @@
+# Benchmark data
+
+| File | What | Source |
+| --- | --- | --- |
+| `districts.csv` | 745 Indian districts with state | Derived from India Post's public all-India pincode directory |
+| `place_aliases.csv` | Common city names that differ from the district name (Bangalore, Trichy) | Hand-written |
+| `people.csv` | 300 full names, with Devanagari or Tamil spelling for most | Synthetic, built from common first names and surnames; not real people |
+| `handwritten_variants.csv` | ~110 heard → expected pairs: STT-style misspellings, surname first, old city names, native script | Hand-written |