Metadata-Version: 2.4
Name: oro-g2p
Version: 0.1.0
Summary: Research-grade Yoruba Grapheme-to-Phoneme (G2P) converter and Kokoro TTS frontend
Author: Oro Contributors
License: MIT
Project-URL: Homepage, https://github.com/Akintunde102/oro-g2p
Project-URL: Repository, https://github.com/Akintunde102/oro-g2p
Project-URL: Issues, https://github.com/Akintunde102/oro-g2p/issues
Keywords: yoruba,g2p,tts,kokoro,phonemes,african-nlp,speech-synthesis,phonology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# oro-g2p 🗣️

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)

**`oro-g2p`** is a zero-dependency, research-grade Yoruba Grapheme-to-Phoneme (G2P) engine and phonetic tokenizer designed for speech synthesis (TTS), automatic speech recognition (ASR), and forced alignment.

It provides out-of-the-box native token mapping for **[Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)** and **StyleTTS2**.

---

## Key Features

1. **Deterministic Linguistic Engine:** Pure, rule-based Yoruba phonology — zero hallucinations, reproducible output.
2. **Post-Nasal Harmony:** Automatically captures unwritten phonetic nasalization on vowels following nasal consonants `m` and `n` (*ọmọ* → `/ɔˉmɔ̃ˉ/`, *inú* → `/iˉnũˊ/`).
3. **Chameleon Syllabic Nasals:** Dynamically applies homorganic place assimilation to `ń` and `ǹ`:
   - Labials (`b`, `f`): `/m/` (*Mo ń bọ̀* → `moˉ mˊ bɔˋ`)
   - Alveolars (`d`, `t`, `s`, `ṣ`): `/n/` (*Mo ń ṣe* → `moˉ nˊ ʃeˉ`)
   - Velars & Glides (`l`, `k`, `g`): `/ŋ/` (*Mo ń lọ* → `moˉ ŋˊ lɔˉ`)
4. **Typo Resilience:** Seamlessly normalizes Turkish cedillas (`ş`), combining vertical lines (`\u0329`), and out-of-order diacritic keystrokes into canonical Yoruba underdots (`ẹ`, `ọ`, `ṣ`).
5. **Contour Glides:** Expands carons (`ǎ` → `àá` Low-High) and circumflexes (`â` → `áà` High-Low).
6. **Native Kokoro Alignment:** Maps 100% of Yoruba phonemes and tones directly into Kokoro-82M's 178-token embedding table with **0 missing tokens**.

---

## Installation

```bash
pip install oro-g2p
```

---

## Quickstart

### 1. Basic G2P Conversion
```python
from oro_g2p import g2p

# Converts Yoruba text to tone-marked IPA
phonemes = g2p("Ẹ kú àárọ̀, ọmọ Yorùbá!")
print(phonemes)
# Output: 'ɛˉ kuˊ aˋaˊɾɔˋ, ɔˉmɔ̃ˉ joˉɾuˋbaˊ!'
```

### 2. Kokoro-82M Tokenization
```python
from oro_g2p import yoruba_to_kokoro

text = "Ẹ kú àárọ̀"
ipa_str, token_ids, missing = yoruba_to_kokoro(text)

print(f"IPA:       {ipa_str}")
print(f"Token IDs: {token_ids}")
print(f"Missing:   {missing}")  # [] -> 100% coverage!
```

---

## Architecture: Kokoro-82M Token Mapping

Kokoro has a fixed embedding matrix size of `178` (`0` to `177`). While 114 slots were occupied by Western languages, 64 slots were unassigned.

`oro-g2p` resolves Yoruba without modifying any pre-trained weights or embedding tensor dimensions:
- **High Tone (Mí):** Assigned to Vacant Slot `7` (`ˊ`)
- **Mid Tone (Ré):** Assigned to Vacant Slot `8` (`ˉ`)
- **Low Tone (Dò):** Assigned to Vacant Slot `26` (`ˋ`)
- **Nasal Vowels:** Decomposed into `(vowel + \u0303)`, cleanly utilizing Kokoro's native Room `17`.

---

## Running Tests

```bash
python -m pytest tests/
```

---

## License

MIT License. Free for academic, personal, and commercial speech technology research.
