docuracy/symphonym-v7

Symphonym v7 — Universal Phonetic Embeddings for Cross-Script Toponym Matching


## ⚠️ Superseded by Symphonym v8 v7 remains available and unchanged, and this card still describes it accurately except where noted below. New work should start from v8 (DOI 10.5281/zenodo.22767194), which raises MEHDIE R@1 85.2% → 89.3% and MRR 90.8% → 92.8%, and nearly doubles script coverage (20 → 37 script ids, 113,280 → 114,845 characters). 🛑 v8 is a retrain from scratch, not a fine-tune. Weights and vocabularies must be replaced together: a v8 checkpoint paired with v7 vocabularies raises no error and produces meaningless embeddings. Embeddings are not comparable across versions — a v7 query vector scored against a v8 index returns confident nonsense. Re-embed the corpus, and upgrade any client that generates query vectors in the same change. ### One claim on this page is now known to be wrong Under Limitations, this card attributes low CJK–Hiragana similarity to "a genuine phonological mismatch, not a model deficiency". That explanation was incorrect. v7's IPA for Chinese Han toponyms was generated under a defective language tag, so the model learned Chinese characters with Japanese readings attached; the similarity structure was an artefact of G2P dispatch, not a phonological fact. v8 fixes the tag, and its CJK–Hiragana mean similarity falls to 0.320 — which is the correct direction, because Chinese Han and Japanese Hiragana genuinely do not sound alike. Two further v8 findings qualify claims made here: v8's discrimination AUC is slightly lower (0.9324 → 0.9270), and letter order counts for far less than this card's framing implies. Both are documented on the v8 card.

Symphonym maps toponyms (place names) from 20 writing systems into a unified 128-dimensional phonetic embedding space, enabling direct cross-script similarity comparison without runtime phonetic conversion or language identification.

"London" / "Лондон" / "伦敦" / "لندن" → [0.12, -0.34, …] (all nearby)

Intended Use

• —Cross-script toponym matching in geographic databases and gazetteers
• —Phonetic search — retrieve results for a place name entered in any script
• —Historical record linkage — match pre-standardisation spelling variants
• —Multilingual named entity linking in NLP pipelines
• —Digital humanities — reconciling place references across archival sources

The model operates on phonetic similarity, not semantic or orthographic similarity. It is designed as a candidate retrieval component within a larger reconciliation pipeline, where candidates are subsequently filtered by geographic proximity and other constraints.

Quick Start

from inference import SymphonymModel

model = SymphonymModel()   # loads weights from this directory

# Single similarity score
sim = model.similarity("London", "en", "Лондон", "ru")
print(f"London / Лондон: {sim:.3f}")   # → 0.991

# Batch embeddings  (N × 128 numpy array)
embeddings = model.batch_embed([
    ("London",   "en"),
    ("Лондон",   "ru"),
    ("伦敦",     "zh"),
    ("لندن",     "ar"),
    ("ლონდონი",  "ka"),
])

With HuggingFace huggingface_hub

from huggingface_hub import snapshot_download

model_dir = snapshot_download("docuracy/symphonym-v7")

from inference import SymphonymModel
model = SymphonymModel(model_dir=model_dir)

Representative Cross-Script Similarities

Model Architecture

Symphonym uses a Teacher–Student knowledge distillation framework.

Teacher (PhoneticEncoder) — training only

• —Input: IPA transcriptions via Epitran (+ 102 extensions), Phonikud, CharsiuG2P
• —Representation: PanPhon192 — 24-dim articulatory feature vectors, 8-bin positional pooling → 192-dim fixed-length input
• —Architecture: BiLSTM → Self-Attention → Attention Pooling → 128-dim projection

Student (UniversalEncoder) — deployed model

• —Input: raw Unicode characters + script ID + language ID + length bucket
• —Vocabulary: 113,280 tokens across 20 scripts, 1,944 language codes
• —Architecture: Character/Script/Language/Length embeddings → Input projection → BiLSTM → Self-Attention (residual) → Attention Pooling → 128-dim projection → L2 normalisation
• —Parameters: ~8.3M

The length bucket embedding (16 buckets, 8-dim) conditions every character representation on sequence length, mitigating spurious matches between short toponyms and long compound strings.

Three-Phase Training Curriculum

Evaluation

MEHDIE Hebrew–Arabic Historical Benchmark (Sagi et al., 2025)

Independent evaluation on medieval Hebrew and Arabic geographical sources — not in training data.

The PanPhon192 ablation (raw articulatory features, no neural training) achieves only 45.0% MRR — less than half Symphonym's score and below the string baselines — confirming that performance derives from the training curriculum, not the phonetic features alone.

Cross-Script Pair Validation (11,723 pairs, 170+ script combinations)

Systematically sampled from training data (up to 10 pairs per script-pair bin); these test embedding retrieval quality over the full 67M-toponym index, not generalisation to unseen sources.

Best-performing script pairs: Hiragana–Katakana (0.981), Devanagari–Kannada (0.976), Devanagari–Telugu (0.976), Cyrillic–Latin (0.923, n=1,334), Arabic–Latin (0.898, n=800).

v7 Changes

v6 exhibited 0% IPA coverage for Hiragana (151,980 toponyms) and Katakana (340,555 toponyms) despite both being natively supported by Epitran (jpn-Hira, jpn-Kana). The pipeline was dispatching by language first (lang=ja), routing all Japanese toponyms to CharsiuG2P which only processes CJK/Kanji. v7 fixes this by dispatching on detected script before language code, restoring IPA coverage for 492,535 toponyms. The model was retrained from scratch.

Training Data

Trained on 66.9 million unique toponyms from:

54.0% of training-namespace toponyms received IPA transcription; the remainder contribute to the Student's character-level learning via distillation.

Repository Contents

model.safetensors          Student (UniversalEncoder) weights
config.json                Architecture hyperparameters
inference.py               Self-contained inference module
requirements.txt           Dependencies
vocab/
  char_vocab.json          113,280-character vocabulary
  lang_vocab.json          1,944 ISO language codes
  script_vocab.json        20 script categories
evaluation/
  mehdie_results_v7_ranking.json
  symphonym_v7_pairs_test_report.json
training_stats/
  coverage_stats.json      IPA coverage by script and language
  phase{1,2,3}_metrics.json
epitran_extensions/        102 custom CSV G2P files

Limitations

• —Phonetic similarity only: The model does not use geographic coordinates, semantic information, or entity types. Phonetically similar but geographically unrelated names (Austria/Australia: 0.883) will score highly.
• —Training bias: Sources over-represent populated places with official names in high-resource languages. Performance on under-represented scripts and mundane places may be weaker.
• —Tonal languages: PanPhon encodes segmental articulatory features but not tone. Tonal minimal pairs in place names are rare in practice.
• —CJK–Hiragana pairs: Mean similarity 0.437, reflecting that CharsiuG2P produces Mandarin phonetics for Kanji while Epitran produces Japanese readings for Hiragana — a genuine phonological mismatch, not a model deficiency.

Citation

If you use Symphonym in your research, please cite the preprint and the Zenodo dataset:

@misc{symphonym2025,
    author       = {Gadd, Stephen},
    title        = {Symphonym: Universal Phonetic Embeddings for Cross-Script Name Matching},
    year         = {2026},
    eprint       = {2601.06932},
    archivePrefix = {arXiv},
    primaryClass = {cs.CL},
    url          = {https://arxiv.org/abs/2601.06932},
    doi          = {10.48550/arXiv.2601.06932}
}

@dataset{symphonym_v7_zenodo,
    title   = {Symphonym v7 — Universal Phonetic Embeddings for Cross-Script Toponym Matching},
    year    = {2026},
    doi     = {10.5281/zenodo.18682017},
    url     = {https://doi.org/10.5281/zenodo.18682017}
}