Metadata-Version: 2.4
Name: lectura-graphemiseur
Version: 4.0.0
Summary: Graphémiseur neural du français (IPA → orthographe) — P2G + POS + Morpho (BiLSTM multi-tâche)
Author-email: Max Carriere <contact@lec-tu-ra.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://www.lec-tu-ra.com/solutions/outils/modules/
Project-URL: Repository, https://github.com/maxcarriere/lectura-modules/tree/main/P2G
Project-URL: Issues, https://github.com/maxcarriere/lectura-modules/issues
Keywords: p2g,french,nlp,phonétique,orthographe,pos-tagging,morphologie
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: French
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.16; extra == "onnx"
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Provides-Extra: train
Requires-Dist: torch>=2.0; extra == "train"
Requires-Dist: onnx>=1.14; extra == "train"
Requires-Dist: onnxruntime>=1.16; extra == "train"
Provides-Extra: all
Requires-Dist: onnxruntime>=1.16; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"
Dynamic: license-file

# Lectura Graphemiseur

**Graphemiseur neural du francais : P2G + POS + Morphologie (IPA → orthographe)**

> Anciennement `lectura-p2g` (pip) / `lectura_p2g` (import).
> Renomme `lectura-graphemiseur` / `lectura_graphemiseur` a partir de la v4.0.0.

Un seul modèle BiLSTM char-level multi-tête avec word feedback et features lexicales (ONNX INT8) qui prédit simultanément :

- **P2G** : transcription IPA vers orthographe (93.1% word accuracy, 2.2% CER)
- **POS** : étiquetage morpho-syntaxique — 19 tags (98.3% accuracy)
- **Morphologie** : genre, nombre, temps, mode, personne, forme verbale (94.7-99.7%)

Quatre backends d'inférence : ONNX Runtime, NumPy, pur Python (zéro dépendance), ou API serveur.

## Démarrage rapide

### Installation

```bash
pip install lectura-graphemiseur             # zéro dépendance (backend pur Python)
pip install lectura-graphemiseur[numpy]      # backend NumPy
pip install lectura-graphemiseur[onnx]       # backend ONNX Runtime (le plus rapide)
```

### Utilisation rapide (factory — recommande)

```python
from lectura_graphemiseur import creer_engine

# Mode auto : utilise les modeles locaux si presents, sinon l'API
engine = creer_engine()

result = engine.analyser(["le", "ɑ̃fɑ̃", "sɔ̃", "aʁive", "a", "la", "mɛzɔ̃"])

print(result["ortho"])   # ['les', 'enfants', 'sont', 'arrives', 'a', 'la', 'maison']
print(result["pos"])     # ['ART:def', 'NOM', 'AUX', 'VER', 'PRE', 'ART:def', 'NOM']
print(result["morpho"])  # {'Number': ['Plur', 'Plur', ...], 'Gender': [...], ...}
```

Modes disponibles : `"auto"` (defaut), `"local"`, `"api"`, `"onnx"`, `"numpy"`, `"pure"`.

## Mode API (zero config)

Sans modeles locaux, `creer_engine()` utilise automatiquement l'API Lectura :

```python
engine = creer_engine()  # mode="auto" → API si pas de modeles locaux
# ou explicitement :
engine = creer_engine(mode="api", api_url="https://api.lec-tu-ra.com")
```

Variables d'environnement : `LECTURA_API_URL`, `LECTURA_API_KEY`.

## Modeles locaux (licence commerciale)

Pour utiliser l'inference locale sans API, achetez les modeles sur
https://www.lec-tu-ra.com/solutions/services/

Installez les modeles dans `~/.lectura/models/p2g/` :

```bash
mkdir -p ~/.lectura/models/p2g
cp unifie_p2g_v3_int8.onnx unifie_p2g_v3_vocab.json ~/.lectura/models/p2g/
```

Ou via variable d'environnement :

```bash
export LECTURA_MODELS_DIR=/path/to/models
```

`creer_engine()` detecte automatiquement les modeles locaux.

## Poids NumPy / Pure Python (optionnel)

Les backends **NumPy** et **Pure Python** necessitent les poids JSON depuis GitHub :

```bash
curl -L -o unifie_p2g_v3_weights.json \
  https://github.com/maxcarriere/lectura-modules/raw/main/Graphemiseur/modeles_numpy/unifie_p2g_v3_weights.json
```

```python
engine = creer_engine(mode="numpy")
result = engine.analyser(["bɔ̃ʒuʁ", "lə", "mɔ̃d"])
```

## Backends d'inférence

| Backend | Dépendances | Vitesse | Usage |
|---------|------------|---------|-------|
| **API** | aucune | ~100 ms/phrase | Defaut (Niveau 1), zero config |
| **ONNX Runtime** | `onnxruntime` | ~2 ms/phrase | Production locale |
| **NumPy** | `numpy` | ~50 ms/phrase | Leger |
| **Pur Python** | aucune | ~200 ms/phrase | Embarque, portabilite max |

Les backends locaux (ONNX, NumPy, Pure) produisent des résultats identiques.

## Features lexicales (optionnel)

Le modele V3 accepte en entree optionnelle un vecteur de 24 dimensions par mot, construit a partir d'un lexique de candidats POS. Cela ameliore la prediction POS et la morphologie, ce qui ameliore aussi la reconstruction orthographique via le word feedback.

Le lexique est detecte automatiquement si present dans le dossier modeles (`lexique_pos_candidates.json`), ou via le parametre `lexicon_path` de `creer_engine()`. Sans lexique, le modele fonctionne normalement (features = zeros).

```python
# Avec lexique (automatique si disponible)
engine = creer_engine()

# Desactiver les features lexicales
result = engine.analyser(ipa_words, use_lex=False)
```

## Benchmarks (dev set, modele V3 avec features lexicales)

| Tâche | Métrique | Score |
|-------|----------|-------|
| **P2G** | Word Accuracy | **93.1%** |
| **P2G** | CER (Character Error Rate) | **2.2%** |
| **POS** | Accuracy | **98.3%** |
| **Morpho** — Number | Accuracy | **94.7%** |
| **Morpho** — Gender | Accuracy | **97.6%** |
| **Morpho** — VerbForm | Accuracy | **99.5%** |
| **Morpho** — Mood | Accuracy | **99.7%** |
| **Morpho** — Tense | Accuracy | **99.7%** |
| **Morpho** — Person | Accuracy | **99.6%** |

Voir [EVALUATION.md](EVALUATION.md) pour les résultats détaillés et la comparaison v1/v2/v3.

## API

### `creer_engine(mode, models_dir, api_url, api_key, lexicon_path)`

Factory pour creer un engine d'inference. Modes : `"auto"`, `"local"`, `"api"`, `"onnx"`, `"numpy"`, `"pure"`.
`models_dir` permet de specifier le dossier des modeles (sinon cascade automatique).

### `engine.analyser(ipa_words, *, use_lex=True) -> dict`

Analyse une liste de mots IPA et retourne un dictionnaire :
- `ipa_words` : liste des mots IPA d'entrée
- `ortho` : orthographe reconstruite par mot
- `pos` : étiquette POS par mot
- `morpho` : dict de listes par trait (`Number`, `Gender`, `VerbForm`, `Mood`, `Tense`, `Person`)

Le parametre `use_lex=False` desactive les features lexicales (utile pour le benchmarking).

### `tokeniser_ipa(text) -> list[str]`

Tokenise une phrase IPA (split sur espaces).

### `corriger_phrase_v2(ortho_words, pos_tags, lexique) -> list[str]`

Post-traitement contextuel inter-mots : accord déterminant-nom, sujet-verbe.

## Architecture du modèle (V3)

```
Phrase IPA → Char Embedding (64d) → Shared BiLSTM (2×160h → 320d)
                                          │
                  ┌───────────────────────┼────────────────────┐
                  ↓                                             ↓
        Word representations                Word repr (320d) + Lex Features (24d)
        (fwd[last] || bwd[first])                          │
                                                 Word BiLSTM (192h → 384d)
                                                       │
                                         ┌─────────────┼──────────────┐
                                         ↓             ↓              ↓
                                        POS       Morpho (×6)    Word Feedback
                                                                 (broadcast → char)
                                                                      │
                                                                      ↓
                                                           P2G Head (704d → 1198)
                                                           char_out + word_out
```

- **Entrée** : séquence de caractères IPA avec `<BOS>`, `<SEP>`, `<EOS>`
- **Lex Features** : 24d par mot (21 POS one-hot + known + n_candidates + unambiguous)
- **Word Feedback** : les représentations mot sont diffusées aux positions char correspondantes
- **P2G** : prédiction par caractère IPA avec labels `_CONT` (continuation pour marques combinantes)

## Limites connues

- Le P2G est intrinsèquement ambigu pour les homophones (est/et, a/à, ses/ces) — résolution partielle par le contexte phrastique
- Les marques morphologiques muettes (-s pluriel, -e féminin) restent la principale source d'erreur (~30%)
- Le modèle ne gère pas la ponctuation ni la casse (entrée = IPA pur)
- Performance sur mots hors-vocabulaire plus basse qu'en contexte

## Licence

Ce module est distribue sous licence **AGPL-3.0** (non commerciale) — voir [LICENCE.txt](LICENCE.txt).

Pour un usage commercial, contacter [contact@lec-tu-ra.com](mailto:contact@lec-tu-ra.com).

Voir aussi [ATTRIBUTION.md](ATTRIBUTION.md) pour les credits.
