docuracy/symphonym-v7

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

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

Pair	Scripts	Similarity
London / Лондон	Latin–Cyrillic	0.991
Athens / Αθήνα	Latin–Greek	0.980
Beijing / 北京	Latin–CJK	0.955
Baghdad / بغداد	Latin–Arabic	0.969
Jerusalem / ירושלים	Latin–Hebrew	0.892
Tokyo / とうきょう	Latin–Hiragana	~0.94
London / Londres	Latin–Latin	0.474 (correct: phonetically distinct)

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

Phase	Objective	Epochs	Notes
1	Teacher: triplet margin loss on PanPhon192 features	50	val_loss 0.0056
2	Student–Teacher distillation: α·MSE + (1−α)·cosine	50	α=0.5, Student-Teacher cosine 0.942
3	Hard negative fine-tuning (triplet, margin=0.3)	30	val_loss 0.02122

Evaluation

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

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

Method	R@1	R@5	R@10	MRR
PanPhon192 (ablation)	41.1%	48.2%	52.3%	45.0%
Levenshtein + AnyAscii	81.5%	97.5%	99.4%	88.5%
Jaro-Winkler + AnyAscii	78.5%	96.2%	97.8%	86.3%
Symphonym v7	85.2%	97.0%	97.6%	90.8%

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.

Metric	v6	v7
Pass rate (≥0.75 cosine)	—	90.7%
Embedding coverage	~98%	100%
Hiragana↔Katakana mean similarity	0.000	0.981

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:

Source	License
GeoNames	CC BY 4.0
Wikidata	CC0
Getty TGN	ODC-By 1.0

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}
}