sprint44: A.I.2 médiane par défaut + détecteur d'asymétrie

Réponse à la critique structurelle 2 du plan d'évolution : sur les
corpus patrimoniaux, la moyenne CER est tirée par quelques documents
catastrophiques et masque les performances réelles. La médiane est
plus représentative ; cohérente aussi avec le test de Friedman qui
travaille déjà sur les rangs (Sprint 18).

Modèles
- EngineReport.median_cer : nouvelle propriété qui lit
aggregated_metrics["cer"]["median"].
- BenchmarkResult.ranking() : inclut median_cer dans chaque entrée
et trie par médiane CER croissante par défaut. Fallback sur
mean_cer quand la médiane est absente (cas pathologique).

Détecteur narratif
- Nouveau FactType.MEDIAN_MEAN_GAP_WARNING (priority 140) qui se
déclenche pour le moteur leader quand
|mean - median| / median > 30 %. Importance HIGH si gap relatif
≥ 100 %, sinon MEDIUM. Garde-fou : ne déclenche pas si médiane
nulle (corpus parfait pour ce moteur).
- Templates FR/EN sans nombres en dur (vérifié par test).
- L'arbitre marque la paire {GLOBAL_LEADER_CER,
MEDIAN_MEAN_GAP_WARNING} comme complémentaire : les deux phrases
peuvent coexister dans la synthèse pour nuancer le leader plutôt
que de l'écraser.

Tests : +15 dans test_sprint44_median_default.py couvrant la
propriété median_cer, le tri sur un cas asymétrique réaliste
(80 % à 0.03 + 20 % à 0.40 → A bat B sur la médiane mais perd sur
la moyenne), le fallback mean quand median absent, le déclenchement
du détecteur sur 4 cas dégénérés (symétrique, asymétrique modéré,
asymétrique fort, médiane nulle), la traçabilité anti-hallucination
FR + EN, l'absence de chiffres en dur dans les templates, et
l'intégration dans build_synthesis.
Suite complète : 1795 → 1810 passed, 2 skipped, 0 failed.

CHANGELOG.md

@@ -16,6 +16,36 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 44 — A.I.2 : tri par médiane CER par défaut + détecteur
+  d'asymétrie.** Réponse à la critique structurelle 2 du plan
+  d'évolution : sur les corpus patrimoniaux, la moyenne est facilement
+  tirée par quelques documents catastrophiques et masque les
+  performances réelles ; la médiane est plus représentative.
+  - `EngineReport.median_cer` : nouvelle propriété qui lit
+    `aggregated_metrics["cer"]["median"]`.
+  - `BenchmarkResult.ranking()` :
+    - inclut désormais `median_cer` dans chaque entrée (additif)
+    - **trie par médiane CER croissante par défaut** (et non plus
+      par moyenne)
+    - retombe sur `mean_cer` quand `median_cer` est absent
+      (rétrocompat pour le cas pathologique)
+  - Nouveau `FactType.MEDIAN_MEAN_GAP_WARNING` et détecteur
+    `detect_median_mean_gap_warning` (priority 140) : émet un Fact
+    quand `|mean - median| / median > 30 %` pour le moteur leader.
+    Importance MEDIUM par défaut, HIGH si gap relatif ≥ 100 %.
+    Garde-fou : ne déclenche pas si la médiane est nulle.
+  - Templates FR/EN — aucun nombre en dur, tout vient du payload
+    (vérifié par test).
+  - L'arbitre marque la paire `{GLOBAL_LEADER_CER,
+    MEDIAN_MEAN_GAP_WARNING}` comme **complémentaire** : les deux
+    phrases peuvent coexister dans la synthèse pour nuancer le
+    leader.
+  - +15 tests dans `test_sprint44_median_default.py` (propriété
+    median_cer, tri par médiane sur cas asymétrique réaliste,
+    fallback sur la moyenne, déclenchement du détecteur sur 4 cas
+    dégénérés, importance MEDIUM/HIGH selon gap, traçabilité
+    anti-hallucination FR + EN, intégration via build_synthesis).
+
 - **Sprint 43 — A.II.1.b Calibration : vue HTML reliability diagram +
   tableau ECE/MCE (clôture A.II.1.b côté rapport).** Suite directe du
   Sprint 42 (câblage runner). Les chiffres de calibration sont
@@ -374,12 +404,13 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1795 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
+- 1478 → 1810 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
   +27 Sprint 35, +22 Sprint 36, +42 Sprint 37, +19 Sprint 38,
   +32 Sprint 39, +16 Sprint 40, +38 Sprint 41, +17 Sprint 42,
-  +43 Sprint 43). Aucune régression. **Phase 0 close ; Étape 2 du
-  plan d'évolution : inter-moteurs (A.II.1.c), NER (A.II.1.a) et
-  calibration (A.II.1.b) livrés bout-en-bout calcul → runner → HTML.
+  +43 Sprint 43, +15 Sprint 44). Aucune régression. **Phase 0
+  close ; Étape 2 du plan d'évolution : inter-moteurs (A.II.1.c),
+  NER (A.II.1.a) et calibration (A.II.1.b) livrés bout-en-bout
+  calcul → runner → HTML ; A.I.2 médiane par défaut livré (Sprint 44).
   Reste l'adaptation effective des engines pour exposer leurs
   confidences natives (un sprint par adapter).**
 

CLAUDE.md

@@ -207,6 +207,7 @@ AZURE_DOC_INTEL_KEY=...
 | 33 | **Sprint 2 du plan d'évolution 2026 — Phase 0.2 : interface module générique**. Nouveau module `picarones/core/modules.py` avec l'enum `ArtifactType` (IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER) et la classe abstraite `BaseModule` qui déclare `input_types`/`output_types`, `execution_mode` (`"io"`/`"cpu"`), une méthode `process(dict[ArtifactType, Any]) → dict[ArtifactType, Any]`, et des helpers `validate_inputs`/`validate_outputs`. `BaseOCREngine` (`picarones/engines/base.py`) hérite désormais de `BaseModule` avec `input_types=(IMAGE,)` et `output_types=(TEXT,)` ; sa nouvelle méthode `process` wrappe l'API historique `run()`. Aucun adaptateur OCR existant n'est touché — `test_engines.py` passe à 20/20 sans modification. +23 tests dans `test_sprint33_module_interface.py` (contrat, validation, MockModule TEXT→ALTO démonstratif comme demandé par le plan, délégation `BaseOCREngine.process → run`, cohérence ArtifactType/GTLevel). **Verrou levé** : un même runner peut maintenant exécuter un OCR (image→texte), un mappeur VLM→ALTO, un rewriter ALTO→ALTO, un module NER (texte→entités), etc. — fondation directe pour l'axe B du plan. |
 | 34 | **Sprint 3 du plan d'évolution 2026 — Phase 0.3 : registre typé de métriques (clôture Phase 0)**. Nouveaux modules `picarones/core/metric_registry.py` (`MetricSpec`, `@register_metric`, `select_metrics`, `compute_at_junction`) et `picarones/core/builtin_metrics.py` qui enregistre `cer`, `wer`, `mer`, `wil` sur `(TEXT, TEXT)` plus un stub `text_preservation_after_reconstruction` sur `(TEXT, ALTO)` comme preuve de concept de jonction hétérogène. **Approche strictement additive** : ni `metrics.py` ni `compute_metrics` ne sont modifiés, le rapport HTML reste identique octet par octet. La sélection par signature de types est exacte (pas de coercion). +21 tests dans `test_sprint34_metric_registry.py`, dont une parité numérique CER/WER/MER/WIL avec `compute_metrics` legacy à 1e-9 près sur 4 paires de textes. **Verrou levé** : le runner d'une pipeline composée peut maintenant calculer automatiquement la métrique adéquate à chaque jonction de son DAG selon les types d'artefacts produits/attendus — fondation directe pour la métrique d'absorption d'erreur (acte B.3) et toutes les métriques structurelles à venir (Layout F1, reading order F1, NER). |
 | 35 | **Sprint 4 du plan d'évolution 2026 — Étape 2 / axe A : métriques inter-moteurs (couche de calcul)**. Nouveau module `picarones/core/inter_engine.py` qui répond à deux questions distinctes mais liées : *(a) à quel point les moteurs font-ils des erreurs de natures différentes ?* via `kl_divergence`, `jensen_shannon_divergence` (symétrique, bornée `[0, 1]`), et `taxonomy_divergence_matrix` qui construit la matrice triangulaire inter-moteurs ; *(b) quel CER serait atteignable si on combinait les moteurs ?* via `oracle_token_recall` (proxy bag-of-words, borne supérieure du recall atteignable), `complementarity_gap` (oracle vs meilleur moteur seul, gap absolu/relatif), et `pairwise_disagreement_rate`. Fonctions pures, sans I/O ni intégration runner — la couche de calcul est livrée indépendamment, le câblage narratif (`ENSEMBLE_OPPORTUNITY`) et HTML (matrice de divergence, badge oracle) suit au Sprint 36. +27 tests couvrant les invariants mathématiques (KL ≥ 0, KL(p,p) = 0, JS symétrique et bornée, oracle ≥ best_single, multiplicité respectée), les cas concrets (deux moteurs spécialisés sortent comme candidats ensemble, complémentarité parfaite atteint oracle = 1), et les garde-fous (référence vide, hypothèses vides, métrique inconnue). |
+| 44 | **Sprint 13 du plan d'évolution 2026 — Étape 2 / axe A.I.2 : tri par médiane par défaut + détecteur d'asymétrie**. Réponse à la critique structurelle 2 du plan : sur les corpus patrimoniaux, la moyenne est tirée par quelques documents catastrophiques et masque les performances réelles. `EngineReport.median_cer` ajouté (lit `aggregated_metrics["cer"]["median"]`). `BenchmarkResult.ranking()` inclut désormais `median_cer` dans chaque entrée et **trie par médiane CER croissante par défaut** (fallback sur `mean_cer` si médiane absente). Nouveau `FactType.MEDIAN_MEAN_GAP_WARNING` + détecteur `detect_median_mean_gap_warning` (priority 140) : émet un Fact quand `\|mean - median\| / median > 30 %` pour le moteur leader, importance HIGH si gap relatif ≥ 100 % (sinon MEDIUM). Garde-fou : ne déclenche pas si médiane nulle. Templates FR/EN sans nombres en dur (vérifié). L'arbitre marque la paire `{GLOBAL_LEADER_CER, MEDIAN_MEAN_GAP_WARNING}` comme **complémentaire** : les deux phrases peuvent coexister dans la synthèse pour nuancer le leader. +15 tests dans `test_sprint44_median_default.py` (propriété, tri sur cas asymétrique réaliste, fallback, déclenchement détecteur sur 4 cas dégénérés, importance, traçabilité anti-hallucination FR + EN, intégration build_synthesis). **Verrou levé** : la critique « le rapport classe sur la moyenne alors que les distributions patrimoniales sont asymétriques » est résolue ; le lecteur voit immédiatement le moteur le plus représentatif et est averti quand l'écart médiane/moyenne est suspect. |
 | 43 | **Sprint 12 du plan d'évolution 2026 — Étape 2 / axe A.II.1.b : vue HTML calibration (clôture A.II.1.b côté rapport)**. Nouveau module `picarones/report/calibration_render.py` : `build_calibration_summary_html` rend un tableau résumé (ECE, MCE, accuracy moyenne, confidence moyenne, n_predictions, doc_count) avec cellule ECE colorée par gradient vert (bien calibré) → rouge (mal calibré) ; `build_reliability_diagram_svg` rend un SVG par moteur avec barres d'accuracy par bin, ligne reliant les points `(avg_confidence, accuracy)`, diagonale en pointillé pour la calibration parfaite, axes annotés (graduations 0/0.5/1) ; `build_reliability_diagrams_grid_html` génère une grille auto-fit (un SVG par moteur ayant `aggregated_calibration`). Rendu strictement server-side, pas de JS, déterministe. `_build_report_data` expose `aggregated_calibration` par moteur ; `ReportGenerator.generate` calcule les blocs et les passe à `view_analyses.html` qui les affiche **uniquement si ≥ 1 moteur a un `aggregated_calibration`** (rapport adaptatif). Anti-injection HTML via `html.escape`. +13 clés i18n FR/EN. +43 tests dans `test_sprint43_calibration_html.py` couvrant le rendu (résumé, SVG, grille), le masquage adaptatif, l'anti-injection, l'intégration FR + EN, la complétude i18n. **Verrou levé** : A.II.1.b (calibration) est désormais visible bout-en-bout dans le rapport — il manque uniquement l'adaptation effective des engines pour exposer leurs confidences natives (un sprint par adapter : Tesseract `image_to_data`, Pero `PageLayout`, Mistral `confidence`, Google Vision `Word.confidence`, Azure DI). |
 | 42 | **Sprint 11 du plan d'évolution 2026 — Étape 2 / axe A.II.1.b : exposition `token_confidences` + câblage runner**. Suite du Sprint 39 (couche de calcul). `EngineResult` gagne un champ optionnel `token_confidences: Optional[list[dict[str, Any]]]` (`None` par défaut → rétrocompat stricte). `DocumentResult.calibration_metrics` et `EngineReport.aggregated_calibration` ajoutés (sérialisation dans `as_dict` conditionnelle, libérés par `compact()`). Nouveau helper `_calibration_from_engine_result` qui aligne par bag-of-words avec multiplicité (proxy oracle, comme `oracle_token_recall`), normalise les confidences en pourcentage à `[0, 1]`, ignore les confidences négatives (Tesseract met -1 pour les non-mots) ; appelé dans `_compute_document_result` quand `token_confidences` est non-vide. Helper `_aggregate_calibration` combine les bins de tous les docs en somme pondérée par count, recalcule ECE/MCE micro. **L'adaptation de chaque adapter (Tesseract, Pero OCR, Mistral OCR, Google Vision, Azure DI) à exposer ses confidences natives est reportée à des sprints dédiés** : ce sprint pose l'infrastructure complète et la teste avec un mock. +17 tests dans `test_sprint42_calibration_runner.py` (champ EngineResult, sérialisation/compact, helper d'alignement avec calibration parfaite + normalisation % + skip négatifs + bag-of-words multiplicité, agrégation multi-docs, rétrocompat sans confidences). **Verrou levé** : un moteur qui expose ses confidences (cas réel à venir) verra automatiquement ses métriques de calibration calculées et agrégées par le runner — il manque uniquement la vue HTML reliability et l'adaptation des engines un par un. |
 | 41 | **Sprint 10 du plan d'évolution 2026 — Étape 2 / axe A.II.1.a : vue HTML NER (clôture A.II.1.a)**. Nouveau module `picarones/report/ner_render.py` : `build_ner_summary_html` rend un tableau résumé (F1 global, P, R, docs évalués, hallucinations, missed) avec cellule F1 colorée par gradient rouge → jaune → vert ; `build_ner_per_category_html` rend la heatmap moteur × catégorie d'entité (PER, LOC, ORG, DATE, MISC…) avec tooltip `support=N`, cellule vide marquée `—` pour les catégories non observées. Rendu server-side, pas de JS, déterministe. Anti-injection HTML via `html.escape`. `_build_report_data` expose `aggregated_ner` par moteur. `ReportGenerator.generate` calcule les deux blocs et les passe au template `view_analyses.html` qui les affiche dans une `chart-card` à largeur pleine **uniquement si ≥ 1 moteur a un `aggregated_ner`**. +12 clés i18n FR/EN. +38 tests dans `test_sprint41_ner_html.py` (rendu, masquage adaptatif, anti-injection, intégration FR + EN, complétude i18n). **Verrou levé** : A.II.1.a (NER) est désormais livré bout-en-bout — couche de calcul (Sprint 38) + backend + câblage runner (Sprint 40) + vue HTML (Sprint 41). Reste la calibration A.II.1.b à finir bout-en-bout (extraction des token_confidences depuis les engines + vue HTML reliability diagram). |
@@ -261,7 +262,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1795 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38+40+41 = NER livré bout-en-bout ; Sprints 39+42+43 = calibration livrée bout-en-bout calcul → runner → HTML, adaptation engines à venir)
+- **Tests** : 1810 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38+40+41 = NER livré bout-en-bout ; Sprints 39+42+43 = calibration livrée bout-en-bout côté rapport ; Sprint 44 = médiane par défaut)
 - **Plan d'évolution actif** : [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md)
 - **Branche active** : `claude/analyze-project-evolution-KOA56`
 - **Transcript de la conversation de développement** :

picarones/core/narrative/arbiter.py

@@ -64,6 +64,7 @@ _FALLBACK_TYPE_ORDER: tuple[FactType, ...] = (
     FactType.COST_OUTLIER,
     FactType.CONFIDENCE_WARNING,
     FactType.ENSEMBLE_OPPORTUNITY,
+    FactType.MEDIAN_MEAN_GAP_WARNING,
 )
 
 
@@ -86,6 +87,9 @@ _COMPLEMENTARY_PAIRS: frozenset[frozenset[FactType]] = frozenset({
     frozenset({FactType.GLOBAL_LEADER_CER, FactType.SPEED_WINNER}),
     frozenset({FactType.GLOBAL_LEADER_CER, FactType.CONFIDENCE_WARNING}),
     frozenset({FactType.STATISTICAL_TIE, FactType.SPEED_WINNER}),
+    # Sprint 44 — l'avertissement d'asymétrie nuance le leader
+    # plutôt que de le doubler : on veut les deux phrases ensemble.
+    frozenset({FactType.GLOBAL_LEADER_CER, FactType.MEDIAN_MEAN_GAP_WARNING}),
 })
 
 

picarones/core/narrative/detectors.py

@@ -717,6 +717,65 @@ def detect_confidence_warning(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+# ---------------------------------------------------------------------------
+# Détecteur Sprint 44 — distribution asymétrique (médiane vs moyenne)
+# ---------------------------------------------------------------------------
+
+@register_detector(
+    FactType.MEDIAN_MEAN_GAP_WARNING,
+    priority=140,
+    importance=FactImportance.MEDIUM,
+)
+def detect_median_mean_gap_warning(benchmark_data: dict) -> list[Fact]:
+    """Avertit quand le ratio ``|moyenne - médiane| / médiane`` du leader
+    dépasse 30 %, ce qui indique une distribution fortement asymétrique
+    où la moyenne masque les performances réelles.
+
+    Sprint 44 — A.I.2 du plan d'évolution. Cohérent avec le passage du
+    tri par défaut sur la médiane : si la moyenne du leader diverge
+    fortement de la médiane, l'utilisateur doit le savoir pour
+    interpréter correctement les chiffres.
+    """
+    ranking = benchmark_data.get("ranking") or []
+    valid = [
+        r for r in ranking
+        if r.get("median_cer") is not None
+        and r.get("mean_cer") is not None
+    ]
+    if not valid:
+        return []
+
+    leader = valid[0]
+    median_cer = float(leader["median_cer"])
+    mean_cer = float(leader["mean_cer"])
+
+    if median_cer <= 0:
+        # Médiane nulle (corpus très facile pour ce moteur) — l'écart
+        # relatif n'est pas calculable de manière utile, on s'abstient.
+        return []
+
+    relative_gap = abs(mean_cer - median_cer) / median_cer
+    if relative_gap < 0.30:
+        return []
+
+    importance = (
+        FactImportance.HIGH if relative_gap >= 1.0 else FactImportance.MEDIUM
+    )
+
+    return [Fact(
+        type=FactType.MEDIAN_MEAN_GAP_WARNING,
+        importance=importance,
+        payload={
+            "engine": leader["engine"],
+            "median_cer_pct": round(median_cer * 100, 2),
+            "mean_cer_pct": round(mean_cer * 100, 2),
+            "relative_gap_pct": round(relative_gap * 100, 1),
+            "n_docs": int(leader.get("documents") or 0),
+        },
+        engines_involved=(leader["engine"],),
+    )]
+
+
 # ---------------------------------------------------------------------------
 # Détecteur Sprint 36 — opportunité d'ensemble (complémentarité)
 # ---------------------------------------------------------------------------

picarones/core/narrative/facts.py

@@ -64,6 +64,12 @@ class FactType(str, Enum):
     """Deux moteurs sont fortement complémentaires : un voting majoritaire
     pourrait améliorer significativement le CER (Sprint 36)."""
 
+    MEDIAN_MEAN_GAP_WARNING = "median_mean_gap_warning"
+    """Distribution des CER fortement asymétrique sur le corpus —
+    la moyenne du leader est tirée par quelques documents catastrophiques
+    et masque les performances réelles. La médiane (utilisée pour le tri
+    par défaut depuis Sprint 44) est plus représentative."""
+
 
 class FactImportance(int, Enum):
     """Score d'importance d'un fait — décide l'ordre et la sélection."""

picarones/core/narrative/templates/en.yaml

@@ -61,3 +61,10 @@ ensemble_opportunity: >-
   among the engines would preserve {oracle_recall_pct} % — i.e.
   {absolute_gap_pct} points recoverable ({relative_gap_pct} % of the best
   engine's errors).
+
+median_mean_gap_warning: >-
+  Asymmetric distribution for {engine}: median CER {median_cer_pct} %
+  vs mean {mean_cer_pct} % across {n_docs} documents (relative gap
+  {relative_gap_pct} %). The mean is pulled by a few catastrophic
+  documents — the median (now used for default ranking) is more
+  representative.

picarones/core/narrative/templates/fr.yaml

@@ -65,3 +65,10 @@ ensemble_opportunity: >-
   entre les moteurs en préserverait {oracle_recall_pct} %, soit
   {absolute_gap_pct} points récupérables ({relative_gap_pct} % des erreurs
   du meilleur moteur).
+
+median_mean_gap_warning: >-
+  Distribution asymétrique pour {engine} : médiane CER {median_cer_pct} %
+  vs moyenne {mean_cer_pct} % sur {n_docs} documents (écart relatif
+  {relative_gap_pct} %). La moyenne est tirée par quelques documents
+  catastrophiques — la médiane (utilisée pour le tri par défaut) est
+  plus représentative.

picarones/core/results.py

@@ -185,6 +185,18 @@ class EngineReport:
         cer_stats = self.aggregated_metrics.get("cer", {})
         return cer_stats.get("mean")
 
+    @property
+    def median_cer(self) -> Optional[float]:
+        """CER médian sur le corpus.
+
+        Sprint 44 — devient le critère de tri par défaut du ``ranking()``
+        car la moyenne est facilement tirée par quelques documents
+        catastrophiques sur une distribution asymétrique (typique des
+        corpus patrimoniaux).
+        """
+        cer_stats = self.aggregated_metrics.get("cer", {})
+        return cer_stats.get("median")
+
     @property
     def mean_wer(self) -> Optional[float]:
         wer_stats = self.aggregated_metrics.get("wer", {})
@@ -258,22 +270,43 @@ class BenchmarkResult:
     inter_engine_analysis: Optional[dict] = None
 
     def ranking(self) -> list[dict]:
-        """Retourne le classement des moteurs trié par CER croissant."""
+        """Retourne le classement des moteurs trié par **médiane CER** croissante.
+
+        Sprint 44 — A.I.2 du plan d'évolution : le tri par défaut bascule
+        de la moyenne vers la médiane.  Sur des distributions
+        asymétriques (typique des corpus patrimoniaux : 80 % des docs
+        à 3 % de CER, 20 % à 40 %), la moyenne est tirée par quelques
+        documents catastrophiques et masque les performances réelles.
+        La médiane est plus représentative ; cohérente aussi avec le
+        test de Friedman qui travaille déjà sur les rangs (Sprint 18).
+
+        Le champ ``mean_cer`` est conservé dans chaque entrée pour
+        rétrocompatibilité — les consommateurs (CLI, détecteurs
+        narratifs, vue HTML) continuent à pouvoir l'afficher en colonne
+        secondaire.  Le tri prend ``median_cer`` quand disponible et
+        retombe sur ``mean_cer`` sinon.
+        """
         ranked = []
         for report in self.engine_reports:
             ranked.append(
                 {
                     "engine": report.engine_name,
                     "mean_cer": report.mean_cer,
+                    "median_cer": report.median_cer,
                     "mean_wer": report.mean_wer,
                     "documents": len(report.document_results),
                     "failed": report.aggregated_metrics.get("failed_count", 0),
                 }
             )
-        return sorted(
-            ranked,
-            key=lambda x: (x["mean_cer"] is None, x["mean_cer"] or float("inf")),
-        )
+
+        def _sort_key(entry: dict) -> tuple:
+            # Priorité : médiane si disponible, sinon moyenne, sinon +∞
+            primary = entry.get("median_cer")
+            if primary is None:
+                primary = entry.get("mean_cer")
+            return (primary is None, primary if primary is not None else float("inf"))
+
+        return sorted(ranked, key=_sort_key)
 
     def as_dict(self) -> dict:
         d = {

tests/test_sprint44_median_default.py

@@ -0,0 +1,261 @@
+"""Tests Sprint 44 — médiane par défaut + détecteur d'asymétrie.
+
+Couvre :
+
+1. ``EngineReport.median_cer`` lit ``aggregated_metrics["cer"]["median"]``.
+2. ``BenchmarkResult.ranking()`` :
+   - inclut ``median_cer`` dans chaque entrée
+   - trie sur la médiane par défaut (et non plus la moyenne)
+   - retombe sur la moyenne si la médiane est absente
+3. Détecteur ``MEDIAN_MEAN_GAP_WARNING`` :
+   - se déclenche quand le ratio ``|moyenne - médiane| / médiane > 30%``
+   - ne se déclenche pas quand symétrique
+   - ne se déclenche pas si la médiane est nulle (corpus parfait)
+   - importance HIGH si gap relatif ≥ 100 %
+4. Anti-hallucination : chaque nombre rendu est dans le payload.
+5. Rétrocompat : les consommateurs qui lisent ``mean_cer`` continuent
+   à fonctionner.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from picarones.core.metrics import MetricsResult
+from picarones.core.narrative.detectors import detect_median_mean_gap_warning
+from picarones.core.narrative.facts import FactImportance, FactType
+from picarones.core.narrative.renderer import extract_numbers, render_fact
+from picarones.core.results import BenchmarkResult, DocumentResult, EngineReport
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _make_dr(cer: float, doc_id: str = "d") -> DocumentResult:
+    return DocumentResult(
+        doc_id=doc_id, image_path="/tmp/x.png",
+        ground_truth="x", hypothesis="x",
+        metrics=MetricsResult(
+            cer=cer, cer_nfc=cer, cer_caseless=cer,
+            wer=cer, wer_normalized=cer, mer=cer, wil=cer,
+            reference_length=1, hypothesis_length=1,
+        ),
+        duration_seconds=0.1,
+    )
+
+
+def _make_engine_report(name: str, cers: list[float]) -> EngineReport:
+    drs = [_make_dr(c, doc_id=f"d{i}") for i, c in enumerate(cers)]
+    return EngineReport(
+        engine_name=name, engine_version="1", engine_config={},
+        document_results=drs,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. EngineReport.median_cer
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestMedianCerProperty:
+    def test_returns_median_from_aggregated(self) -> None:
+        rep = _make_engine_report("e", [0.0, 0.0, 0.0, 1.0, 1.0])
+        # Médiane de [0,0,0,1,1] = 0
+        assert rep.median_cer == pytest.approx(0.0)
+
+    def test_returns_none_when_no_docs(self) -> None:
+        rep = EngineReport(
+            engine_name="e", engine_version="1", engine_config={},
+            document_results=[],
+        )
+        # Pas de docs → aggregated_metrics vide → mean/median = None
+        assert rep.median_cer is None
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2. ranking() — tri par médiane
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestRankingByMedian:
+    def test_includes_median_cer(self) -> None:
+        bench = BenchmarkResult(
+            corpus_name="c", corpus_source=None, document_count=3,
+            engine_reports=[_make_engine_report("a", [0.1, 0.2, 0.3])],
+        )
+        ranking = bench.ranking()
+        assert "median_cer" in ranking[0]
+        assert ranking[0]["median_cer"] == pytest.approx(0.2)
+
+    def test_sorts_by_median_not_mean(self) -> None:
+        # Moteur A : 80 % à 0,03 + 20 % à 0,40 → moyenne ≈ 0,11, médiane = 0,03
+        # Moteur B : 100 % à 0,05                 → moyenne = 0,05, médiane = 0,05
+        # Tri par moyenne :   B (0.05) < A (0.11) → A est 2e
+        # Tri par médiane :   A (0.03) < B (0.05) → A est 1er
+        ers = [
+            _make_engine_report(
+                "A_asymmetric",
+                [0.03] * 8 + [0.40] * 2,
+            ),
+            _make_engine_report(
+                "B_steady",
+                [0.05] * 10,
+            ),
+        ]
+        bench = BenchmarkResult(
+            corpus_name="c", corpus_source=None, document_count=10,
+            engine_reports=ers,
+        )
+        ranking = bench.ranking()
+        # Le moteur A doit gagner sur la médiane même si sa moyenne est pire
+        assert ranking[0]["engine"] == "A_asymmetric"
+        assert ranking[0]["mean_cer"] > ranking[1]["mean_cer"]
+        assert ranking[0]["median_cer"] < ranking[1]["median_cer"]
+
+    def test_falls_back_to_mean_when_median_missing(self) -> None:
+        """Si median_cer est None, le tri retombe sur mean_cer.
+
+        On reproduit ici la clé de tri utilisée par
+        ``BenchmarkResult.ranking()`` pour valider sa logique sur des
+        entrées synthétiques (impossible à produire via vrais
+        ``EngineReport`` car ``aggregate_metrics`` calcule toujours
+        une médiane quand il y a au moins un doc).
+        """
+        ranked = [
+            {"engine": "x", "mean_cer": 0.10, "median_cer": None,
+             "mean_wer": 0.0, "documents": 1, "failed": 0},
+            {"engine": "y", "mean_cer": 0.05, "median_cer": None,
+             "mean_wer": 0.0, "documents": 1, "failed": 0},
+        ]
+
+        def _key(e: dict) -> tuple:
+            p = e.get("median_cer") if e.get("median_cer") is not None else e.get("mean_cer")
+            return (p is None, p if p is not None else float("inf"))
+
+        ranking = sorted(ranked, key=_key)
+        # y (mean=0.05) doit passer avant x (mean=0.10)
+        assert ranking[0]["engine"] == "y"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 3. Détecteur MEDIAN_MEAN_GAP_WARNING
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestMedianMeanGapDetector:
+    def test_no_fact_when_distribution_symmetric(self) -> None:
+        data = {"ranking": [{
+            "engine": "tess", "median_cer": 0.05, "mean_cer": 0.055,
+            "documents": 100,
+        }]}
+        # Gap relatif = 10% → en dessous du seuil 30%
+        assert detect_median_mean_gap_warning(data) == []
+
+    def test_emits_fact_when_asymmetric(self) -> None:
+        data = {"ranking": [{
+            "engine": "tess", "median_cer": 0.03, "mean_cer": 0.07,
+            "documents": 100,
+        }]}
+        # Gap relatif = 133% → au-dessus du seuil
+        facts = detect_median_mean_gap_warning(data)
+        assert len(facts) == 1
+        assert facts[0].type is FactType.MEDIAN_MEAN_GAP_WARNING
+        assert facts[0].importance is FactImportance.HIGH  # >= 100 %
+        assert facts[0].payload["engine"] == "tess"
+
+    def test_medium_importance_when_moderate_gap(self) -> None:
+        data = {"ranking": [{
+            "engine": "tess", "median_cer": 0.05, "mean_cer": 0.075,
+            "documents": 100,
+        }]}
+        # Gap relatif = 50% → au-dessus du seuil mais < 100 %
+        facts = detect_median_mean_gap_warning(data)
+        assert facts[0].importance is FactImportance.MEDIUM
+
+    def test_no_fact_when_median_zero(self) -> None:
+        """Médiane nulle → ratio non calculable → on s'abstient."""
+        data = {"ranking": [{
+            "engine": "tess", "median_cer": 0.0, "mean_cer": 0.05,
+            "documents": 100,
+        }]}
+        assert detect_median_mean_gap_warning(data) == []
+
+    def test_no_fact_when_no_ranking(self) -> None:
+        assert detect_median_mean_gap_warning({}) == []
+        assert detect_median_mean_gap_warning({"ranking": []}) == []
+        assert detect_median_mean_gap_warning({"ranking": [{
+            "engine": "x", "mean_cer": None, "median_cer": None,
+        }]}) == []
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4. Traçabilité anti-hallucination
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestTraceability:
+    @pytest.mark.parametrize("lang", ["fr", "en"])
+    def test_every_rendered_number_is_in_payload(self, lang: str) -> None:
+        data = {"ranking": [{
+            "engine": "tess", "median_cer": 0.03, "mean_cer": 0.07,
+            "documents": 100,
+        }]}
+        facts = detect_median_mean_gap_warning(data)
+        sentence = render_fact(facts[0], lang)
+
+        # Whitelist : aucune constante de template n'est attendue ici
+        whitelist: set[str] = set()
+        # Recompute payload representations
+        payload_nums: set[str] = set()
+        for v in facts[0].payload.values():
+            if isinstance(v, (int, float)):
+                payload_nums.add(str(v))
+                if isinstance(v, float) and v.is_integer():
+                    payload_nums.add(str(int(v)))
+
+        for num in extract_numbers(sentence):
+            normalized = num.replace(",", ".")
+            assert normalized in payload_nums | whitelist, (
+                f"Nombre {normalized!r} dans la phrase rendue n'est pas "
+                f"traçable au payload {facts[0].payload!r}"
+            )
+
+    def test_template_has_no_hardcoded_numbers(self) -> None:
+        from picarones.core.narrative.renderer import _load_templates
+        for lang in ("fr", "en"):
+            tpl = _load_templates(lang).get("median_mean_gap_warning", "")
+            assert tpl, f"Template absent pour {lang}"
+            # Enlever les placeholders {x} avant de chercher des chiffres
+            cleaned = re.sub(r"\{[^}]+\}", "", tpl)
+            digits = re.findall(r"\d", cleaned)
+            assert not digits, f"Template {lang} contient des chiffres en dur : {digits}"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 5. Intégration via build_synthesis
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestSynthesisIntegration:
+    def test_detector_registered_by_default(self) -> None:
+        from picarones.core.narrative.registry import iter_detectors
+        types = {entry.fact_type for entry in iter_detectors()}
+        assert FactType.MEDIAN_MEAN_GAP_WARNING in types
+
+    def test_synthesis_includes_warning_when_asymmetric(self) -> None:
+        from picarones.core.narrative import build_synthesis
+        data = {"ranking": [{
+            "engine": "tess", "median_cer": 0.03, "mean_cer": 0.07,
+            "documents": 100,
+        }]}
+        out = build_synthesis(data, lang="fr", max_facts=5)
+        sentences = out["sentences"]
+        # Au moins une phrase doit mentionner l'asymétrie
+        assert any(
+            "asymétrique" in s.lower() or "médiane" in s.lower()
+            for s in sentences
+        )