# Fixtures SentencePiece — découpage de référence

Ce dossier contient les **fixtures de référence** du tokeniseur SentencePiece
maison (`src/Omika.App.Local/Services/SentencePieceTokenizer.cs`).

## À quoi ça sert

Le tokeniseur est réécrit à la main : lecture protobuf minimale, Viterbi
UNIGRAM, BPE, repli octet, normalisation. Son risque n'est pas de lever une
exception — c'est de découper **légèrement autrement** que le modèle, et donc de
dégrader les traductions **sans aucun signal** : pas de plantage, pas de message,
juste des phrases un peu plus mauvaises.

Une fixture transforme ce risque en mesure : pour une série de textes, elle fige
ce que produit la bibliothèque `sentencepiece` de référence.

```json
{
  "modele": "vocab.spm",
  "sentencepieceVersion": "0.2.0",
  "vocabSize": 32000,
  "addDummyPrefix": true,
  "removeExtraWhitespaces": true,
  "escapeWhitespaces": true,
  "normalizerName": "nmt_nfkc",
  "cas": [
    { "texte": "Bonjour le monde.", "ids": [1, 2, 3], "decode": "Bonjour le monde." }
  ]
}
```

- `modele` : nom du fichier `.spm` décrit (modèle cherché dans ce dossier) ;
- `sentencepieceVersion` : version de la référence — elle **date** la
  comparaison, pour qu'une divergence constatée dans six mois ne se confonde pas
  avec un changement de version de la bibliothèque ;
- `vocabSize`, `addDummyPrefix`, `removeExtraWhitespaces`, `escapeWhitespaces`,
  `normalizerName` : les réglages du modèle qui décident du découpage, lus dans
  son `normalizer_spec` — c'est la première chose à comparer quand un découpage
  diverge ;
- `cas` : `ids` vient de `EncodeAsIds(texte)`, `decode` de `DecodeIds(ids)`
  appliqué à **ces** identifiants. La fixture est donc auto-cohérente : le test
  compare le tokeniseur C# à la référence, jamais à une transcription manuelle
  qui figerait une erreur de recopie ;
- un fichier par modèle, nommé `<nomDuModeleSansExtension>.fixtures.json`,
  UTF-8 **sans BOM**, indenté.

Les textes couverts sont construits par le script et comprennent, au minimum :
français accentué, espagnol accentué avec `¿¡`, espaces de tête, de queue et
doubles, chaîne vide, chaîne d'espaces seuls, chiffres et ponctuation, phrase
très longue, casse mêlée, et une écriture non latine (arabe et cyrillique).

## Générer les fixtures

Prérequis : Python 3 et la bibliothèque de référence.

```powershell
pip install sentencepiece
.\scripts\Generer-Fixtures-SentencePiece.ps1 -DossierModeles C:\Chemin\Vers\Les\Modeles
```

Le générateur cherche **récursivement** tous les `*.spm` sous `-DossierModeles`
et écrit un fixture par modèle dans `tests\fixtures\sentencepiece` (ou dans le
dossier passé à `-Sortie`). Relancer le script est sans danger : il réécrit ses
propres fixtures et ne supprime rien d'autre.

Options utiles :

```powershell
# Copie chaque .spm à côté de son fixture : le test cherche le modèle ici.
.\scripts\Generer-Fixtures-SentencePiece.ps1 -DossierModeles C:\Modeles -CopierModeles

# Autre dossier de sortie (utile pour un pack non versionné).
.\scripts\Generer-Fixtures-SentencePiece.ps1 -DossierModeles C:\Modeles -Sortie C:\Temp\fixtures
```

## Où trouver un `.spm`

Le vocabulaire est livré **dans chaque pack de langue**, un fichier par sens de
traduction :

```
langues/{code}/{sens}/vocab.spm        # {code} = es, pt, ar…  {sens} = versFrancais, depuisFrancais
```

Ce chemin est celui du stockage local de l'application (voir
`LanguagePaths` dans `src/Omika.App.Local/Infrastructure`). Deux façons de se
procurer le fichier :

1. le récupérer depuis le poste où le pack a été téléchargé (dossier de données
   de l'application, sous `langues/`) ;
2. le demander à l'API des langues, qui le sert avec le reste du pack.

Un même dossier `langues/{code}/{sens}` peut donc servir de `-DossierModeles`.

## Les `.spm` ne sont pas versionnés

Les fichiers `.spm` (comme les `encoder.onnx`) restent **hors du dépôt** :

- ils pèsent plusieurs centaines de kilo-octets à plusieurs méga-octets chacun,
  multipliés par le nombre de langues et de sens ;
- ce sont des **artefacts de modèle**, produits par un entraînement et soumis à
  leurs propres conditions de licence : leur place est dans un pack de langue
  distribué, pas dans l'historique Git.

Le générateur ne versionne que les **fixtures** (quelques kilo-octets de texte),
qui décrivent le comportement attendu sans embarquer le modèle.

## Comment le test trouve tout ça

`tests/Omika.Tests/Mobile/SentencePieceFixturesTests.cs` :

1. dossier des fixtures : la variable d'environnement `OMIKA_SPM_FIXTURES` si
   elle est définie et existe, sinon `tests/fixtures/sentencepiece` **résolu
   depuis la racine du dépôt** (racine trouvée en remontant depuis l'assembly de
   test jusqu'au dossier contenant `Omika.slnx` — aucun chemin absolu codé en
   dur, aucun recours au dossier courant) ;
2. pour chaque `*.fixtures.json`, le `.spm` annoncé par `modele` est cherché dans
   ce même dossier (nom simple, ou sous-dossier annoncé par la fixture) ;
3. si le `.spm` est **absent**, la fixture est ignorée — jamais un échec ;
4. si le dossier est **absent ou vide**, le test **passe** en expliquant pourquoi
   sur la sortie standard.

C'est délibéré : une suite rouge sur une machine fraîchement clonée, pour de
simples fichiers absents, pousserait à désactiver le test — exactement l'inverse
du but. Ces tests ne font échouer que sur une divergence **réellement mesurée**.

Pour vérifier un pack sans rien copier dans le dépôt :

```powershell
$env:OMIKA_SPM_FIXTURES = 'C:\Chemin\Vers\fixtures-et-spm'
dotnet test tests\Omika.Tests\Omika.Tests.csproj --filter FullyQualifiedName~SentencePieceFixturesTests
```

Deux autres tests de ce fichier s'exécutent même sans fixture : l'idempotence de
l'aller-retour (`Decode(Encode(x))` rejoué donne le même texte — jamais
`Decode(Encode(x)) == x`, qui dépend du vocabulaire), et le fait qu'un fichier
inexploitable lève une `SentencePieceException` **en français** plutôt qu'une
erreur système.

## Lire un échec

Le message d'échec est conçu pour être exploitable seul :

```
Découpage divergent pour le cas « Bonjour le monde. » (fixture vocab.fixtures.json).
Premier écart à l'index 1 : référence 2537 « le », tokeniseur 12 « ▁le ».
Identifiants de référence (4) : 1, 2537, 232, 4
Identifiants obtenus (4)       : 1, 12, 232, 4
Texte reconstruit par la référence : « Bonjour le monde. ».
```

Ce qu'il faut y lire :

- **l'index du premier écart** : les identifiants qui précèdent sont corrects, la
  divergence commence là. Un écart à l'index 0 est un problème de préfixe
  factice ou de normalisation ; un écart en milieu de phrase est un problème de
  segmentation (Viterbi, scores, longueur maximale de pièce) ;
- **les deux identifiants et leur pièce** : `12` contre `2537` dit *quelle* pièce
  le tokeniseur a choisie à la place de celle du modèle. Une pièce très courte
  (`▁`, un caractère) à la place d'une pièce longue signale une table de pièces
  incomplète ou un score mal lu ; l'inverse signale un score trop favorable ;
- **les deux listes** : des tailles différentes signalent une couverture
  incomplète (caractère devenu `<unk>` au lieu d'une pièce) ;
- **`decode`** : « Décodage divergent » n'a rien à voir avec le découpage — le
  décodage est testé sur les identifiants **de la référence**, donc l'erreur est
  dans la reconstruction (marqueur ▁, rognage des bords, reconstitution des
  octets) ;
- les réglages en tête de fixture (`addDummyPrefix`, `normalizerName`…) sont à
  comparer avec `ProfilNormalisation` et `Avertissements` du tokeniseur chargé.

Vérifier aussi que la fixture et le modèle vont bien ensemble : le test échoue
explicitement si la taille de vocabulaire de la fixture ne correspond pas à celle
du `.spm` (mauvais appariement de fichiers, pas divergence de segmentation).

## Que faire d'une divergence

**La signaler. Ne jamais l'absorber.**

- Ne **pas** desserrer la valeur attendue, ne **pas** régénérer la fixture
  « jusqu'à ce que ça passe », ne **pas** supprimer le cas gênant : une fixture
  réécrite pour coller au tokeniseur ne mesure plus rien, et la divergence
  repartira en production sous forme de traductions dégradées.
- Ouvrir une anomalie avec : le nom de la fixture, le texte du cas, l'index du
  premier écart, les deux identifiants et les deux pièces, les deux listes, la
  version `sentencepieceVersion`, et la taille du vocabulaire.
- Regarder d'abord les **limites assumées** documentées dans l'en-tête de
  `SentencePieceTokenizer.cs` : la table de normalisation compilée
  (`precompiled_charsmap`) n'est pas appliquée, et les pièces `USER_DEFINED` sont
  traitées comme des pièces ordinaires. Une divergence sur un texte en pleine
  largeur (`１２３`), une ligature (`fi`), un exposant ou une forme de
  compatibilité vient très souvent de là — la propriété `Avertissements` du
  tokeniseur le dit déjà quand c'est le cas.
  En revanche `add_dummy_prefix`, `escape_whitespaces`,
  `remove_extra_whitespaces` et le **repli octet** sont lus dans le modèle et
  honorés : une divergence sur ces points n'est plus une limite connue, c'est un
  défaut à corriger.
- Vérifier en priorité les cas **« espaces seuls » et espaces de bord** : le
  `Decode` du tokeniseur ne retire que le préfixe factice qu'il a lui-même ajouté,
  alors que la référence applique sa propre règle de rognage. C'est le premier
  écart susceptible d'apparaître sur un run réel.
- Corriger le **tokeniseur** (avec un test qui reproduit le cas), jamais la
  fixture. Si la référence elle-même change de comportement d'une version à
  l'autre, mettre à jour `sentencepieceVersion` et justifier l'écart dans le
  message de commit.

## Fichiers de ce dossier

| Fichier | Contenu |
| --- | --- |
| `LISEZMOI.md` | ce document |
| `<modele>.fixtures.json` | fixtures de référence, régénérables, versionnées |
| `*.spm` | **non versionnés** — modèles, à copier sur le poste de test |