Metadata-Version: 2.4
Name: fongbe-g2p
Version: 0.1.0
Summary: Graphème → phonème pour le fongbe (langue du Bénin), à base de règles, avec tons.
License: MIT License
        
        Copyright (c) 2026 Arnel7
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
License-File: NOTICE.md
Keywords: african-languages,fon,fongbe,g2p,phonemes,tone,tts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# fongbe_g2p

Conversion **graphème → phonème** pour le **fongbe**  à base de règles.
Sortie en **IPA avec marques de ton**, prête pour un front-end TTS ou une lexique de
prononciation.

Bibliothèque standard Python uniquement — **aucune dépendance**.

```python
from fongbe_g2p import g2p, apply_sandhi

g2p("gbɛtɔ́")            # 'ɡ͡b ɛ˧ t ɔ˥'      (personne)
g2p("kpɔ́n")             # 'k͡p ɔ̃˥'          (regarder — nasalisation)
g2p("vodúngbe")          # 'v o˧ d ũ˥ ɡ͡b e˧'  (dimanche)
g2p("Mawu", sep="")      # 'm a˧w u˧'
g2p("gbɛtɔ́", with_tone=False)   # 'ɡ͡b ɛ t ɔ'
```

## Ce que fait le module

| | |
|---|---|
| **Digraphes** | `gb → ɡ͡b`, `kp → k͡p`, `ny → ɲ` (segmentation par plus longue correspondance) |
| **Voyelles orales** | `a e ɛ i o ɔ u` |
| **Nasalisation contextuelle** | `Vn → Ṽ` quand `n` clôt la syllabe ; `n` devant voyelle reste une consonne, et `ny` n'est jamais nasalisant |
| **4 tons** | haut `˥` (aigu), moyen `˧` (non marqué), bas `˩` (grave), modulé `˩˥` (caron) |
| **Homoglyphes** | `ε→ɛ`, `Đ/đ/ð→ɖ`, `ọ→ɔ`, `ẹ→ɛ`, `ɩ→i`… normalisés en entrée |
| **`r → l`** | conformément à la note du document source |

Les tons sont lus via une décomposition **NFD** : la voyelle et sa marque de ton sont
traitées séparément, donc rien n'est perdu quel que soit l'encodage de l'entrée.

## Sandhi tonal

`sandhi_fongbe.py` implémente la règle contextuelle la plus déterministe :

> Dans une succession de tons **bas**, seul le **dernier** reste bas ; les autres remontent
> au ton **moyen**.  → `B B B` devient `M M B`

```python
apply_sandhi("è kò nù")   # 'e ko nù'
```

Les résolutions du **ton modulé** (`V→H` ou `V→B`) dépendent du contexte *grammatical*
(impératif, pronom, négation, composition) et ne sont **pas** déductibles de la seule
orthographe : elles sont laissées inchangées, volontairement.

> Cette partie est bien moins mûre que le G2P — voir [Limites connues](#sandhi--un-brouillon-pas-une-implémentation-complète)
> pour son apport réellement mesuré.

Pour valider la règle sur un corpus de paires *citation → réalisé* :

```bash
python -m fongbe_g2p.validate_sandhi mes_paires.tsv
# format : 'citation<TAB>réalisé' ou 'réalisé ---> citation'
```

Le document source n'est pas redistribué ici (voir `NOTICE.md`), il faut donc fournir
son propre fichier.

## Installation

```bash
pip install fongbe-g2p
```

Ou depuis les sources :

```bash
git clone https://github.com/Arnel7/fongbe-g2p.git
cd fongbe-g2p
pip install -e .
```

## Tests

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

33 tests, sans fichier de données : digraphes, nasalisation, les 4 tons, homoglyphes,
robustesse (chaîne vide, caractère inconnu, marque combinante orpheline), couverture de
l'inventaire, sandhi, non-régression.

`pytest` et `ruff` ne servent qu'au développement — le paquet lui-même n'a **aucune
dépendance d'exécution**.

## Couverture mesurée

Sur des corpus fongbe réels (transcriptions de parole, jeux de Q&A, corpus parallèle),
après normalisation NFD :

| corpus | caractères | non gérés |
|---|--:|--:|
| corpus assemblé | 2 423 023 | **0** |
| transcriptions de parole | 105 354 | **0** |
| Q&A | 821 345 | 14 |
| corpus parallèle | 2 095 512 | 15 610 |

Les seuls caractères non traités sont **étrangers au fongbe** (`q`, `œ`, écritures non
latines) : ils proviennent de passages en français ou de bruit de corpus, et sont laissés
tels quels en sortie.

## Limites connues

### ⚠️ `˧` veut dire « moyen » **ou** « aucune information »

Le fongbe note le ton moyen par l'**absence** de marque. Ce module ne peut donc pas
distinguer une voyelle réellement au ton moyen d'une voyelle dont le ton n'a simplement
pas été écrit — les deux sortent en `˧`.

C'est décisif en pratique, parce que beaucoup de texte fongbe est sous-toné. Part des
voyelles émises en `˧` faute de marque, mesurée sur les mêmes corpus :

| corpus | voyelles en `˧` par défaut |
|---|--:|
| transcriptions de parole | 88,5 % |
| corpus parallèle | 78,4 % |
| Q&A | 55,7 % |

**Conséquence** : si vous entraînez un TTS directement sur cette sortie, le modèle apprend
du bruit tonal sur la majorité des voyelles. Faites passer votre texte par une étape de
**restauration de tons** avant le G2P, ou n'utilisez que du texte intégralement toné.

### Sandhi : un brouillon, pas une implémentation complète

Une seule règle est implémentée, et son apport mesuré est modeste : **60,5 % → 62,0 %**
de tons corrects sur 71 paires *citation → réalisé*, soit **+1,5 point**. Les résolutions
du ton modulé, qui dépendent du contexte grammatical, ne sont pas traitées du tout.
À considérer comme une base de travail, pas au même niveau de fiabilité que le G2P.

### Autres

- Les règles viennent d'une **description orthographique**, pas de mesures acoustiques ;
  elles n'ont pas été validées par un locuteur natif. Les retours sont bienvenus.
- L'orthographe fongbe connaît plusieurs traditions : certaines sources notent le ton bas
  par un accent grave, d'autres le laissent non marqué (fusionné avec le moyen). Ce module
  suit la première. Un texte de la seconde tradition sera lu avec des tons moyens là où un
  ton bas est attendu.

## Licence et sources

Code sous licence MIT (`LICENSE`). Voir `NOTICE.md` pour l'attribution des sources
linguistiques.
