Metadata-Version: 2.4
Name: mjpn
Version: 6.0.0
Summary: Moroccan Jewish Phonetic Names (MJPN): phonetic root computation for Moroccan Jewish surnames, the engine behind yahasra.org
Author-email: Dr Yohanan Ouaknine <contact@yahasra.org>
License: MIT
Project-URL: Homepage, https://yahasra.org
Project-URL: Documentation, https://yahasra.org/about
Keywords: onomastics,phonetic,surnames,genealogy,jewish,morocco,sephardic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Sociology :: Genealogy
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl>=3.0
Dynamic: license-file

# MJPN — Moroccan Jewish Phonetic Names

Phonetic root computation for Moroccan Jewish surnames — the exact engine
behind [yahasra.org](https://yahasra.org)'s search across 32,000+ burial
records from Jewish cemeteries in Morocco.

Moroccan Jewish surnames were written down by French, Spanish and Hebrew
scribes, each with their own orthography: the same family appears as
*Ouaknine, Vaknin, Aknin, Boaknin, Oiknine…* MJPN reduces every variant to a
stable phonetic root (`AKNN`), so records that belong together can be found
together.

## Install

```
pip install mjpn
```

## Command line

```
mjpn myfile.xlsx            # xlsx with a "Names" column (case-insensitive)
mjpn                        # first .xlsx found in the current script folder
mjpn --name COHEN OUAKNINE "LEVY BENCHETON"
mjpn --selftest
```

The xlsx run writes `<input>_mjpn.xlsx` next to the input, with:

- sheet **MJPN** — `name, root, root2, subroot, subroot2, special_mapping, status`
  (`status` is `ok` / `compound` / `invalid` / `empty`)
- sheet **Stats** — totals, family-size distribution, top families,
  roots split by v4 subroot

and prints the stats summary to stdout.

## Python API

```python
from mjpn import normalize_to_phonetic, compute_compound_indices_v4

normalize_to_phonetic("OUAKNINE")          # 'AKNN'
normalize_to_phonetic("BENARROCH")         # 'HRSH'
compute_compound_indices_v4("levy bencheton")
# ('LB', 'SHTN', 'LB~A', 'SHTN~AO')  — compound dual index + v4 subroots
```

## How it works

Four normalization stages (engine v3.5.2, v4 subroot chain):

1. **Start patterns** — Berber orthographic variants (OI→A) before anything else.
2. **Prefix stripping** — patronymic prefixes (BEN, IBN, OU, HA, EL…) with
   structural-name exception lists so *Hamou* or *Elfassy* keep their prefix.
3. **Phonetic rules** — digraphs (CH→SH…), context-dependent C, V/W→B,
   Spanish plural -IAS→-IA, smart vowel-pair handling (based on Beider's
   *A Dictionary of Jewish Surnames from Maghreb*, 2017).
4. **Consonant skeleton** — the root; a vowel-class signature on top yields
   the v4 *subroot* that keeps genuinely different families apart.

Plus 149 exact and 2 regex special mappings for families whose variants defy
the rules (Abuhatzeira, Azoulay, Zrihen…), curated from the yahasra.org
adjudication process.

`mjpn/mjpn_tool.py` is **generated** from the production engine and verified
against it: identical output on all 3,933 distinct surnames of the yahasra.org
burials database (0 mismatches).

## Citation

If you use MJPN in academic work, please cite:

> Ouaknine, Y. (2026). MJPN: Moroccan Jewish Phonetic Names — the phonetic
> indexing engine of yahasra.org, the Moroccan Jewish cemeteries database.
> https://yahasra.org

## License

MIT © Dr Yohanan Ouaknine

## Provenance and AI disclosure

The engine (`app/phonetic_normalizer.py` in the Yahasra codebase) encodes
orthographic rules authored and adjudicated by Dr Yohanan Ouaknine, tuned
against Beider (2017) with page references recorded per rule. This package is
generated mechanically from that engine by `scripts/build_mjpn_tool.py` — no
hand-maintained copy exists — and each release is parity-checked against the
full live corpus (5,314 distinct surnames, zero mismatches required).

Portions of the engine's implementation code and this package's build
tooling were produced with assistive AI (Anthropic Claude: Sonnet 4.x and
Opus 4.x/5, 2025-06 through 2026-08) under human direction and review; all
linguistic rules, special mappings and adjudications are human decisions.
This disclosure follows the AI policy of the Journal of Cultural Analytics.

## Version

Package 6.0.0 wraps engine 6.0.0 (v4 chain: subroots + compound dual
indexing), generated 2026-11-16 with 98 exact + 1 regex special mappings.
