Metadata-Version: 2.4
Name: amt-phonetic
Version: 1.0.0
Summary: Articulatory Moment Transform — language-agnostic phonetic name matching
Author: Khaled Sameer
License: MIT
Project-URL: Homepage, https://github.com/KhaledSMQ/amt-phonetic
Project-URL: Documentation, https://github.com/KhaledSMQ/amt-phonetic/blob/main/README.md
Project-URL: Repository, https://github.com/KhaledSMQ/amt-phonetic
Project-URL: Issues, https://github.com/KhaledSMQ/amt-phonetic/issues
Project-URL: Changelog, https://github.com/KhaledSMQ/amt-phonetic/blob/main/CHANGELOG.md
Keywords: phonetic,name-matching,fuzzy-search,arabic,soundex,metaphone
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: mypy>=1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# AMT (Python)

Articulatory Moment Transform — language-agnostic phonetic name matching.

## Install

```bash
pip install amt-phonetic
```

Or from source:

```bash
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

```python
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:

```python
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

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

## Algorithm

See the [whitepaper](../AMT_Whitepaper.md) for the full mathematical treatment,
benchmark methodology, and comparisons against Soundex, Metaphone, Double
Metaphone, NYSIIS, and Beider-Morse.

## License

MIT
