--- language: - fon - fr license: cc-by-nc-4.0 library_name: scikit-learn pipeline_tag: text-classification tags: - fon - fongbe - benin - low-resource - nlu - intent-classification - slot-filling - mobile-money - voice-assistant - code-switching - finanfa-tech --- # fon-nlu — compréhension de commandes Mobile Money en fon, français et mélange fon-français **Petit modèle de compréhension (NLU) pour un assistant vocal de paiement mobile** : à partir d'une phrase (la transcription de ce que dit l'utilisateur) en **fon, en français ou en mélange des deux**, il trouve **ce que veut faire l'utilisateur** (l'intention) et en extrait **les informations utiles** (montant, destinataire, numéro de compteur ou de police). **Auteur : AWADEME Ronaldo — [Finanfa Tech](https://huggingface.co/finanfa-tech)** > 🇬🇧 *English summary:* A lightweight intent classifier + rule-based slot extractor for Mobile Money voice commands in Fon (Fongbe), French and Fon–French code-switching (Benin). v1.1.0: 11 intents (money transfer, SBEE electricity and SONEB water bill payment, balance check, airtime purchase, meter/policy number, recipient, yes, no, help/FAQ, and an out-of-scope class), trained on 2,630 examples. Fon amount expressions (e.g. "caki wè" = 2,000 FCFA, "kpowun ko atɔ́ɔ́n" = 625 FCFA) were validated by a native speaker. **Accuracy on unseen phrase forms: 96.0 % for the classifier alone, 97.8 % with a hand-written rule that separates electricity from airtime ('credit' counts as electricity only if SBEE, meter, 'courant' or 'électricité' is said)** – optimistic, because most of the data is template-based (all of it reviewed by the native speaker). Research-grade; never execute a payment without reading back the amount and recipient and asking for confirmation. Non-commercial license (CC-BY-NC-4.0). ## ⚠️ À lire avant d'utiliser - **Ne déclenchez jamais un paiement sans relire à voix haute le montant et le destinataire, et sans confirmation explicite de l'utilisateur.** Le modèle se trompe, et une erreur sur un montant est une erreur financière. - **Précision sur formes inédites : 96,0 % pour le modèle seul (macro-F1 95,7 %), 97,8 % avec la règle de l'électricité** (macro-F1 96,8 %), mesurée en validation croisée où les phrases de même forme restent ensemble. **Ces chiffres sont optimistes** : 1 646 des 2 630 exemples ont été générés pour le projet (puis relus par le locuteur) à partir de gabarits ; les phrases ne sont que 737 formes différentes. Sur des phrases réellement dites par des utilisateurs, attendez-vous à moins. La validation croisée classique donnerait presque 100 %, ce qui serait **trompeur**. - **Règle de l'électricité (écrite à la main, dans `nlu_engine.py`)** : quand le modèle hésite entre `achat_credit` et `paiement_sbee`, la phrase est un **paiement d'électricité seulement si elle contient** SBEE, « compteur » (français ou fon : « kɔ́mtɛ́ɛ́ »…), un numéro de compteur à 11 chiffres, « courant », « électricité » ou « hlɔnhlɔn » ; sinon c'est un **achat de crédit de communication**. Une phrase d'électricité qui ne dit aucun de ces mots sera donc comprise comme du crédit mobile. - **Une classe `inconnu` existe maintenant** (hors sujet), mais elle n'est pas fiable à elle seule : **rejetez aussi en dessous de 0,6 de confiance** et ne traitez jamais `inconnu` comme un ordre. - **« Acheter du crédit de communication » est le point faible du modèle seul** : 65 % de rappel avant la règle (confusion avec l'électricité). La règle ci-dessus corrige cela (rappel 97 %), mais repose sur des mots-clés. Vérifiez toujours le type d'opération avec l'utilisateur avant de payer. - **Texte uniquement** : le modèle reçoit du texte. Il n'a pas été testé sur des transcriptions automatiques de parole, qui contiennent des erreurs. - **Les contacts fournis dans `contact_resolver.py` sont fictifs** (numéros factices). En production, passez toujours la vraie liste de contacts de l'utilisateur. - **Usage non commercial uniquement** (CC-BY-NC-4.0). Fichier `.joblib` : ne le chargez que depuis une source de confiance (format pickle). ## Ce que fait le modèle **11 intentions** (voir la règle de l'électricité plus haut pour `achat_credit` / `paiement_sbee`) : `transfert_argent`, `paiement_sbee` (électricité), `paiement_soneb` (eau), `consulter_solde`, `achat_credit` (crédit de communication), `fournir_compteur` (donner un compteur ou une police en réponse), `fournir_destinataire` (donner le destinataire en réponse), `confirmation_oui`, `annulation_non`, `demande_aide_faq` (aide, frais, limites) et `inconnu` (hors sujet). **Informations extraites** (par des règles, pas par le modèle) : `montant` (en FCFA), `destinataire_nom` (avec résolution des liens de parenté : « nɔ ce » = Maman, « tɔ́ ce » = Papa…), `destinataire_numero`, `numero_compteur` (11 chiffres), `numero_police` (8 chiffres), `compteur_nom` (« compteur maison »…). ### Les montants en fon (validés par le locuteur) Les expressions suivantes ont été relues et validées par AWADEME Ronaldo, locuteur natif du fon. Une même valeur peut s'écrire de plusieurs façons (fon, français, chiffres). | Expression | Valeur | Exemples dans les données | |---|---|---| | kpowun ko | 500 FCFA | 30 | | kpowun ko nukun ɛnɛ | 600 FCFA | 62 | | kpowun ko atɔ́ɔ́n | 625 FCFA | 13 | | caki ɖokpó | 1 000 FCFA | 25 | | mille francs | 1 000 FCFA | 20 | | caki wè | 2 000 FCFA | 27 | | deux mille | 2 000 FCFA | 4 | | deux mille francs | 2 000 FCFA | 2 | | caki atɔn | 3 000 FCFA | 23 | | trois mille francs | 3 000 FCFA | 31 | | caki ɛnɛ | 4 000 FCFA | 13 | | caki atɔ́ɔ́n | 5 000 FCFA | 25 | | cinq mille francs | 5 000 FCFA | 11 | | franc caki atɔ́ɔ́n | 5 000 FCFA | 25 | | caki ayizɛ́n | 6 000 FCFA | 26 | | caki tantɔn | 8 000 FCFA | 12 | | caki wǒ | 10 000 FCFA | 19 | | dix mille | 10 000 FCFA | 15 | | caki afɔtɔ́n | 15 000 FCFA | 23 | | quinze mille francs | 15 000 FCFA | 20 | | caki ko | 20 000 FCFA | 17 | | vingt mille francs | 20 000 FCFA | 23 | | caki kande-wǒ | 50 000 FCFA | 21 | | cinquante mille francs | 50 000 FCFA | 10 | | caki kanweko | 100 000 FCFA | 3 | | cent mille francs | 100 000 FCFA | 27 | | deux cent mille | 200 000 FCFA | 21 | Les chiffres (« 5000 », « 50 000 ») et le français (« cinq mille francs », « quatre vingt mille ») sont aussi compris. ## Utilisation ```bash pip install -r requirements.txt # scikit-learn 1.9.1, numpy, joblib hf download finanfa-tech/fon-nlu --local-dir fon-nlu cd fon-nlu ``` ```python from nlu_engine import VoiceMoMoNLU nlu = VoiceMoMoNLU() r = nlu.parse("Un jló na sɛ́ cinq mille francs dó Femi") print(r["intent"], r["confidence"], r["slots"]) # transfert_argent 0.98 {'montant': {'raw': 'cinq mille francs', 'normalized': 5000}, 'destinataire_nom': {...}} if r["confidence"] < 0.6: pass # phrase non comprise : redemander à l'utilisateur # sinon : relire « {montant} FCFA à {destinataire} » à voix haute et demander une confirmation avant tout paiement ``` Les scripts doivent rester dans le même dossier (le modèle utilise les fonctions `normalize` et `normalize_masked` de `fon_amount_parser.py`). ## Architecture - **Intentions** : caractéristiques TF-IDF sur les mots (1 à 3) et sur les caractères (2 à 5), après suppression des accents et des signes du fon, avec **masquage des nombres** (compteur à 11 chiffres, numéro à 8 chiffres, montant : le modèle apprend la forme, pas la valeur), puis SVM linéaire à probabilités calibrées (scikit-learn). - **Informations** : règles et expressions régulières, un analyseur de montants (fon, français, chiffres), un résolveur de contacts (liens de parenté, correspondance approchée). - Taille : 283 Ko pour le modèle ; environ 4 ms par phrase sur un processeur (mesuré sur un Mac, Python 3.13). ## Données d'entraînement **2 630 exemples** (1 022 en français, 766 en fon, 842 en mélange), **737 formes de phrase**. Tous les exemples ont été **relus par AWADEME Ronaldo, locuteur natif du fon** : - **Jeu 1 : 984 exemples**, gabarits écrits pour le projet, relus et corrigés par lui (au moins 117 exemples modifiés) ; audit des 29 expressions de montants validé par lui. Orthographe harmonisée : « caki » sans « franc », « Kɔ́mtɛ́ɛ́ » pour « compteur ». - **Lot 2 : 720 exemples**, générés pour le projet (le fon vient en partie d'une traduction automatique), puis relus et corrigés par lui (13 exemples modifiés lors de la dernière relecture, 4 supprimés). 116 exemples au fon douteux ont été écartés. - **Lot 3 : 823 exemples**, générés à partir des formes validées du jeu 1 et de dialogues validés (nouveaux montants, noms, numéros), relus par lui. - **Lot 4 : 103 exemples**, variantes des formes qu'il a corrigées dans le lot 2 (achat de crédit « credit caki … », numéros de police « minɛlo … »), avec des montants et numéros différents, relus par lui (7 corrections). Règle de l'auteur : une phrase d'achat de crédit qui commence par « Un ba » ne finit jamais par « nu mi ». - **52 exemples retirés** : ils contenaient « kpataki », un mot qui n'est pas du fon, venu d'un gabarit écrit par erreur. Les noms et numéros sont des valeurs de test. Un seul relecteur. Le jeu de données n'est pas public. Voir la carte du jeu : `finanfa-tech/fon-nlu-data` (privé). ## Évaluation Validation croisée en 5 plis où les phrases de même forme restent ensemble (aucune fuite entre entraînement et test). **Modèle seul, sans la règle de l'électricité** : | Intention | Précision | Rappel | F1 | Exemples | |---|---|---|---|---| | achat_credit | 0.86 | 0.98 | 0.91 | 310 | | annulation_non | 1.00 | 0.98 | 0.99 | 116 | | confirmation_oui | 1.00 | 0.99 | 1.00 | 116 | | consulter_solde | 0.99 | 0.97 | 0.98 | 157 | | demande_aide_faq | 0.93 | 0.94 | 0.94 | 55 | | fournir_compteur | 0.99 | 0.92 | 0.95 | 197 | | fournir_destinataire | 0.91 | 0.92 | 0.91 | 95 | | inconnu | 0.88 | 0.97 | 0.92 | 151 | | paiement_sbee | 0.99 | 0.89 | 0.94 | 424 | | paiement_soneb | 1.00 | 1.00 | 1.00 | 291 | | transfert_argent | 0.98 | 0.98 | 0.98 | 718 | **Modèle seul : précision 96,0 %, F1 macro 95,7 %. Avec la règle de l'électricité : précision 97,8 %, F1 macro 96,8 %** (`achat_credit` : précision 98 %, rappel 98 % ; `paiement_sbee` : précision 100 %, rappel 99,5 %). Sur le seul jeu 1, modèle seul : 96,1 %. **Comparaison avec la version 1.0.0** (8 intentions, jeu 1 seul, modèle seul) : sur 1 289 exemples nouveaux dont l'intention existait déjà, la 1.0.0 obtenait 89,4 % et la 1.1.0 (entraînée sans ces formes) 90,6 % avant retrait de « kpataki » et règle. **Le gain du modèle seul est modeste** ; l'essentiel du progrès vient des 3 nouvelles intentions, de la reconnaissance de l'eau (SONEB, en partie grâce à des exemples très gabarités) et de la règle. Extraction du montant : 1 617 sur 1 617 exacts sur le jeu de développement. Ce chiffre n'est **pas indépendant** (les règles ont été écrites en regardant ces exemples) ; il ne prouve pas que tout montant dit autrement sera bien lu. ## Limites connues - Seulement 737 formes de phrase, dont la plupart sont des variantes de gabarits : une manière de parler différente peut être mal comprise. Plus de phrases réelles, dites naturellement, améliorera surtout le modèle. - Un seul relecteur : des erreurs de fon restent possibles dans l'entraînement. - La confusion entre `achat_credit` et `paiement_sbee` est corrigée par la règle de l'électricité (mots-clés) ; une phrase d'électricité sans mot-clé sera lue comme du crédit mobile. - « Dó Maman » seul n'est pas reconnu avec certitude comme `fournir_destinataire` (confiance faible). - Orthographe et tons du fon variables : le modèle ignore les tons, ce qui fusionne des mots différents. - Un seul relecteur ; système de comptage traditionnel (kpowun, caki, kantaan) validé sur les 29 expressions listées seulement. ## Versions - **1.3.0 (2026-11-16)** : lot 4 (103 variantes des formes corrigées par l'auteur) ; 2 630 exemples ; « caki wǒ atɔn » = 13 000 et « caki ko atɔn » = 23 000 (dizaine + unité) ; **« wɛ » (démonstratif) n'est plus lu comme le chiffre « wè » (2)**. Précision 96,0 % (modèle seul) / 97,8 % (avec la règle de l'électricité). - **1.2.0 (2026-11-16)** : lots 2 et 3 relus par l'auteur ; entraînement de zéro sur 2 527 exemples (orthographe harmonisée : « caki » sans « franc », « Kɔ́mtɛ́ɛ́ »). Précision 93,5 % (modèle seul) / 97,7 % (avec la règle de l'électricité), légèrement plus basse que la 1.1.1 parce que les corrections de l'auteur ajoutent des formes de phrase nouvelles et plus difficiles. - **1.1.1 (2026-11-16)** : retrait de 52 exemples contenant « kpataki » (mot qui n'est pas du fon) ; règle de l'électricité (SBEE / compteur / courant / électricité / hlɔnhlɔn) ; textes corrigés par l'auteur. 2 529 exemples. - **1.1.0 (2026-11-16)** : 11 intentions (ajout de `fournir_destinataire`, `demande_aide_faq`, `inconnu`) ; 2 581 exemples (lots 2 et 3 ajoutés) ; masquage des nombres ; analyseur de montants corrigé (« quatre vingt mille », virgule après un montant fon, « kpowun ko atɔ́ɔ́n » = 625) ; « franc caki » devient « caki ». - **1.0.0 (2026-11-15)** : première version publique. Entraînée sur 991 exemples corrigés ; bug corrigé dans l'analyse des montants (le « un » du fon était compté comme un chiffre : « Un jló na sɛ́ cinq mille » donnait 6 000 au lieu de 5 000) ; « kpowun ko atɔ́ɔ́n » = 625 FCFA ajouté. ## Licence CC-BY-NC-4.0 (usage non commercial, attribution). ## Citation AWADEME Ronaldo, Finanfa Tech. *fon-nlu : compréhension de commandes Mobile Money en fon, français et mélange*, 2026. https://huggingface.co/finanfa-tech/fon-nlu