amt-phonetic 1.0.0

Articulatory Moment Transform — language-agnostic phonetic name matching

AMT (Python)

Articulatory Moment Transform — language-agnostic phonetic name matching.

Install

pip install amt-phonetic

Or from source:

git clone https://github.com/KhaledSMQ/amt-phonetic
cd amt-phonetic/python
pip install -e .

No runtime dependencies (just the Python standard library, 3.10+).

Quick start

import amt

# Encode any name to a pair (32-bit spectral key, 64-bit bloom signature)
sp, bl, classes = amt.encode_token("Khaled")

# Test whether two names match
assert amt.matches("Khaled", "Khalid")       # transliteration variants
assert amt.matches("Khaled", "خالد")         # Latin ↔ Arabic script
assert amt.matches("Gamal", "Jamal")         # Egyptian ↔ Standard Arabic G↔J
assert not amt.matches("Khaled", "Robert")

# Graded similarity in [0, 1]
amt.similarity("Khaled Sameer", "khaled samir")   # → ≈ 1.0
amt.similarity("Khaled", "Ahmed")                 # → low

# Build a fuzzy-searchable index (BK-tree, O(log N) typical)
index = amt.BKTree[str]()
for name in customer_names:
    sp, _, _ = amt.encode_token(name)
    for key in sp:
        index.add(key, name)

# Query: radius-4 returns near-matches on Hamming distance
query_sp, _, _ = amt.encode_token("Khaleed")
hits = index.query(query_sp[0], radius=4)
# hits = [(distance, name), ...] sorted by distance

Extending to new scripts

AMT ships with Latin and Arabic. Add other scripts by registering character → sonority-class mappings:

amt.register_character("ц", 3)   # Cyrillic tse → fricative
amt.register_character("ж", 3)   # Cyrillic zhe → fricative
amt.register_character("ш", 3)   # Cyrillic sha → fricative

See amt/sonority.py for the 8-class scheme used by the algorithm.

API

Function	Purpose
encode_token(token)	Encode single token → (spectrals, blooms, classes)
encode(name)	Encode multi-token name → list[Code]
encode_batch(names)	Encode an iterable of names
matches(a, b)	Fast boolean match test
similarity(a, b)	Graded similarity score in [0, 1]
token_distance(code_a, code_b)	Token-level distance
BKTree()	Metric tree for fuzzy search
LSHIndex(bands=4)	Banded LSH index for very large corpora
register_character(char, cls)	Extend the sonority map

Benchmarks

On a single CPython 3.12 thread:

Encoded 200,000 tokens in 3,200 ms
Throughput: 62,000 tokens/sec
Latency:    16 µs/token

Testing

pip install -e ".[dev]"
pytest tests/

Algorithm

See the whitepaper for the full mathematical treatment, benchmark methodology, and comparisons against Soundex, Metaphone, Double Metaphone, NYSIIS, and Beider-Morse.

License

MIT