sprint35: métriques inter-moteurs (couche de calcul)

Premier sprint de l'Étape 2 du plan d'évolution 2026 (axe A —
enrichissement métrique). Pose les fonctions pures qui répondent à deux
questions complémentaires que le rapport ne sait pas répondre
aujourd'hui :

(a) à quel point les moteurs font-ils des erreurs de natures
différentes ? → divergence taxonomique
(b) quel CER serait atteignable si on combinait les moteurs ?
→ complémentarité (oracle token recall)

Nouveau module picarones/core/inter_engine.py :
- Divergence : kl_divergence, jensen_shannon_divergence (symétrique,
bornée [0, 1]), taxonomy_divergence_matrix (triangulaire, JS ou KL).
Lissage epsilon des zéros pour éviter log(0).
- Complémentarité : oracle_token_recall (proxy bag-of-words,
documenté comme borne supérieure optimiste — la vraie borne
séquentielle reste à faire), complementarity_gap qui retourne aussi
best_single_recall, best_engine, absolute_gap, relative_gap (fraction
des erreurs du meilleur moteur récupérable par ensemble),
pairwise_disagreement_rate.

Fonctions pures, sans I/O ni intégration runner. Le câblage narratif
(détecteur ENSEMBLE_OPPORTUNITY) et la matrice de divergence dans le
rapport HTML suivent au Sprint 36 — ce sprint livre la couche de calcul
indépendamment, prête à être consommée.

Tests : +27 dans test_sprint35_inter_engine.py 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 ressortent comme candidats à un ensemble, complémentarité
parfaite atteint oracle = 1), et les garde-fous (référence vide,
hypothèses vides, métrique inconnue).
Suite complète : 1539 → 1566 passed, 2 skipped, 0 failed.

CHANGELOG.md

@@ -16,6 +16,31 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 35 — Étape 2 du plan d'évolution : métriques inter-moteurs
+  (couche de calcul).** Nouveau module `picarones/core/inter_engine.py`
+  qui expose deux familles de mesures qui ne dépendent que des données
+  déjà produites par le runner :
+  - **Divergence taxonomique** : `kl_divergence`,
+    `jensen_shannon_divergence` (symétrique, bornée dans `[0, 1]`),
+    `taxonomy_divergence_matrix` qui construit la matrice triangulaire
+    inter-moteurs sur les distributions de classes d'erreur (issues de
+    `taxonomy.py`). Lissage epsilon des zéros pour éviter `log(0)`.
+  - **Complémentarité** : `oracle_token_recall` (borne supérieure
+    bag-of-words du recall atteignable par voting), `complementarity_gap`
+    qui retourne aussi `best_single_recall` / `absolute_gap` /
+    `relative_gap` / `best_engine`, `pairwise_disagreement_rate` pour
+    quantifier le potentiel d'ensemble entre deux moteurs spécifiques.
+  - Fonctions pures, sans I/O ni intégration runner — la couche de calcul
+    est livrable indépendamment ; le câblage au moteur narratif
+    (`ENSEMBLE_OPPORTUNITY`) et au rapport HTML (matrice de divergence,
+    badge oracle gap) suit au Sprint 36.
+  - +27 tests dans `tests/test_sprint35_inter_engine.py` couvrant les
+    invariants mathématiques (KL ≥ 0, KL(p,p) = 0, JS symétrique et
+    bornée, oracle ≥ best_single), les cas concrets (moteurs
+    spécialisés ressortent comme candidats à un ensemble, complémentarité
+    parfaite atteint oracle = 1), les garde-fous (référence vide,
+    hypothèses vides, métrique inconnue).
+
 - **Sprint 34 — Phase 0.3 : registre typé de métriques (clôture Phase 0).**
   Nouveaux modules `picarones/core/metric_registry.py` et
   `picarones/core/builtin_metrics.py` :
@@ -83,8 +108,9 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1539 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34). Aucune
-  régression sur la suite existante. **Phase 0 du plan d'évolution close.**
+- 1478 → 1566 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
+  +27 Sprint 35). Aucune régression. **Phase 0 close ; Étape 2 démarrée
+  (couche de calcul des métriques inter-moteurs).**
 
 ---
 

CLAUDE.md

@@ -206,6 +206,7 @@ AZURE_DOC_INTEL_KEY=...
 | 32 | **Sprint 1 du plan d'évolution 2026 — Phase 0.1 : GT multi-niveaux**. Refonte de `picarones/core/corpus.py` pour porter une vérité terrain à plusieurs niveaux (`GTLevel.{TEXT,ALTO,PAGE,ENTITIES,READING_ORDER}`), payloads typés (`TextGT`, `AltoGT`, `PageGT`, `EntitiesGT`, `ReadingOrderGT`) avec `source_path` traçable. Le champ `Document.ground_truth: str` reste la source de vérité historique et est synchronisé automatiquement avec `Document.ground_truths[GTLevel.TEXT]` — rétrocompatibilité stricte (1478 tests existants passent sans modification). Le loader détecte automatiquement `.gt.alto.xml`, `.gt.page.xml`, `.gt.entities.json`, `.gt.reading_order.json` à côté de l'image. `Corpus.gt_level_coverage()` et `Corpus.available_gt_levels` exposent la couverture. Erreurs de parse dégradées en `logger.warning` (jamais `except: pass`). +17 tests dans `test_sprint32_multi_level_gt.py`. **Verrou levé** : ce sprint débloque l'évaluation des modules qui produisent ou consomment ALTO/PAGE/entités (axe B du plan, à venir Sprint 35+) et plusieurs métriques de l'axe A (Layout F1, reading order F1, NER). |
 | 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). |
 
 ---
 
@@ -252,7 +253,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1539 passed, 2 skipped (Sprints 32-34 — Phase 0 du plan d'évolution 2026 close)
+- **Tests** : 1566 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprint 35 = couche de calcul inter-moteurs)
 - **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/inter_engine.py

@@ -0,0 +1,316 @@
+"""Métriques inter-moteurs (Sprint 35 — Étape 2 du plan d'évolution).
+
+Deux familles de mesures qui répondent à des questions différentes mais
+liées :
+
+1. **Divergence taxonomique** (`kl_divergence`, `jensen_shannon_divergence`,
+   `taxonomy_divergence_matrix`) — *à quel point les moteurs font-ils des
+   erreurs de natures différentes ?*  Une divergence élevée signale des
+   moteurs spécialisés sur des classes d'erreurs distinctes (visual vs
+   abréviation vs casse) et donc des candidats pour un voting ensemble.
+
+2. **Complémentarité** (`oracle_token_recall`, `complementarity_gap`,
+   `pairwise_disagreement_rate`) — *quel CER serait atteignable si on
+   combinait les moteurs ?*  La borne inférieure du CER atteignable par
+   un voting majoritaire token-level est ``1 - oracle_token_recall``.
+   Si elle est très inférieure au CER du meilleur moteur seul, l'effort
+   d'un pipeline d'ensemble se justifie.  Sinon non.
+
+Convention de typage
+--------------------
+Toutes les fonctions sont enregistrables dans le registre Sprint 34 si
+on les wrappe par un adaptateur ``(input_types=(TEXT, TEXT))``.  Pour
+limiter le bruit, on ne les enregistre **pas** automatiquement : ce sont
+des métriques d'agrégation (multi-moteurs ou multi-documents) qui ne
+correspondent pas au modèle « une jonction = une métrique » du runner.
+Elles sont consommées par les détecteurs narratifs et le rapport HTML.
+
+Note sur l'oracle
+-----------------
+La métrique ``oracle_token_recall`` retournée ici utilise un alignement
+bag-of-words pondéré par multiplicité.  Ce n'est **pas** une vraie
+borne atteignable par voting majoritaire séquentiel — c'est une borne
+supérieure (proxy optimiste).  La vraie borne demanderait un
+alignement séquentiel des hypothèses, ce qui est plus coûteux.  Pour
+le diagnostic « ensemble vaut-il le coup ? », le proxy suffit
+largement ; on documente clairement la limite dans le glossaire et le
+rapport.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from collections import Counter
+
+logger = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Divergence taxonomique (KL / Jensen-Shannon)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _smoothed_distribution(
+    distribution: dict[str, float],
+    keys: list[str],
+    epsilon: float = 1e-12,
+) -> list[float]:
+    """Aligne une distribution sur l'ordre de ``keys`` et lisse les zéros.
+
+    Le lissage évite ``log(0)`` dans la KL.  ``epsilon`` est volontairement
+    minuscule pour ne pas modifier le résultat de manière sensible.
+    """
+    smoothed = [max(distribution.get(k, 0.0), epsilon) for k in keys]
+    total = sum(smoothed)
+    return [v / total for v in smoothed]
+
+
+def kl_divergence(p: dict[str, float], q: dict[str, float]) -> float:
+    """KL-divergence ``D(P||Q)`` en bits, sur l'union des clés.
+
+    Les distributions n'ont pas besoin de partager exactement les mêmes
+    clés ; les clés manquantes sont lissées à ``epsilon`` puis
+    renormalisées.
+
+    Returns
+    -------
+    float
+        ``D(P||Q) ≥ 0``.  Vaut 0 si et seulement si P == Q.  N'est pas
+        symétrique : ``kl(p, q) != kl(q, p)`` en général.
+    """
+    keys = sorted(set(p.keys()) | set(q.keys()))
+    if not keys:
+        return 0.0
+    p_vec = _smoothed_distribution(p, keys)
+    q_vec = _smoothed_distribution(q, keys)
+    return sum(pi * math.log2(pi / qi) for pi, qi in zip(p_vec, q_vec))
+
+
+def jensen_shannon_divergence(
+    p: dict[str, float],
+    q: dict[str, float],
+) -> float:
+    """JS-divergence symétrique en bits, bornée dans ``[0, 1]``.
+
+    ``JS(P, Q) = ½ D(P||M) + ½ D(Q||M)`` avec ``M = (P + Q) / 2``.
+    Symétrique et bornée — préférable à la KL pour construire une
+    matrice triangulaire de divergences entre moteurs.
+    """
+    keys = sorted(set(p.keys()) | set(q.keys()))
+    if not keys:
+        return 0.0
+    p_vec = _smoothed_distribution(p, keys)
+    q_vec = _smoothed_distribution(q, keys)
+    m_vec = [(pi + qi) / 2.0 for pi, qi in zip(p_vec, q_vec)]
+
+    def _kl(a: list[float], b: list[float]) -> float:
+        return sum(ai * math.log2(ai / bi) for ai, bi in zip(a, b) if ai > 0)
+
+    js = 0.5 * _kl(p_vec, m_vec) + 0.5 * _kl(q_vec, m_vec)
+    # Borne théorique : JS ∈ [0, 1] en bits.  Clamp pour absorber les
+    # erreurs d'arrondi flottant.
+    return max(0.0, min(1.0, js))
+
+
+def taxonomy_divergence_matrix(
+    distributions: dict[str, dict[str, float]],
+    metric: str = "js",
+) -> dict[str, dict[str, float]]:
+    """Construit la matrice de divergence triangulaire entre moteurs.
+
+    Parameters
+    ----------
+    distributions:
+        ``{engine_name: {error_class: probability}}``.  Chaque
+        distribution doit sommer à environ 1 (pas de validation stricte
+        — les distributions taxonomiques de Picarones sont déjà
+        normalisées par ``aggregate_taxonomy``).
+    metric:
+        ``"js"`` (défaut, symétrique) ou ``"kl"`` (asymétrique).
+
+    Returns
+    -------
+    dict[str, dict[str, float]]
+        Matrice ``{engine_a: {engine_b: divergence}}`` symétrique pour
+        ``js``, asymétrique pour ``kl``.  La diagonale vaut 0.
+    """
+    if metric not in ("js", "kl"):
+        raise ValueError(f"metric doit être 'js' ou 'kl' — reçu {metric!r}")
+    fn = jensen_shannon_divergence if metric == "js" else kl_divergence
+
+    engines = sorted(distributions.keys())
+    matrix: dict[str, dict[str, float]] = {a: {} for a in engines}
+    for a in engines:
+        for b in engines:
+            if a == b:
+                matrix[a][b] = 0.0
+            elif metric == "js" and b in matrix and a in matrix[b]:
+                # Symétrique : recopie pour éviter de recalculer
+                matrix[a][b] = matrix[b][a]
+            else:
+                matrix[a][b] = fn(distributions[a], distributions[b])
+    return matrix
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Complémentarité (oracle token recall)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _word_multiset(text: str) -> Counter[str]:
+    """Décomposition en multiset de tokens (séparateur whitespace)."""
+    return Counter(tok for tok in text.split() if tok)
+
+
+def oracle_token_recall(
+    reference: str,
+    hypotheses: dict[str, str],
+) -> float:
+    """Borne supérieure (proxy bag-of-words) du token-recall atteignable
+    par un voting majoritaire entre tous les moteurs fournis.
+
+    Pour chaque token de la référence (avec sa multiplicité), on
+    considère qu'il est "préservé" par l'ensemble si au moins un moteur
+    en produit une occurrence non encore comptée.  Le score est le ratio
+    d'occurrences GT préservées sur le total.
+
+    Parameters
+    ----------
+    reference:
+        Texte GT.
+    hypotheses:
+        ``{engine_name: hypothesis_text}``.
+
+    Returns
+    -------
+    float
+        Ratio dans ``[0, 1]``.  ``1.0`` = chaque token GT est présent
+        dans au moins une hypothèse à hauteur de sa multiplicité.
+
+    Note
+    ----
+    Cette borne est **optimiste** (supérieure à la vraie borne par
+    voting séquentiel) car elle ignore l'ordre d'apparition.  Pour le
+    diagnostic « un voting vaut-il l'effort ? » le proxy suffit ; pour
+    une vraie borne il faudrait un alignement séquentiel.
+    """
+    ref_counter = _word_multiset(reference)
+    if not ref_counter or not hypotheses:
+        return 1.0 if not ref_counter else 0.0
+
+    hyp_counters = [_word_multiset(h) for h in hypotheses.values()]
+    total_ref = sum(ref_counter.values())
+    preserved = 0
+    for token, gt_count in ref_counter.items():
+        # Pour chaque moteur, le nombre d'occurrences disponibles, plafonné
+        # à la multiplicité GT.  L'oracle prend le max sur les moteurs.
+        best = max((min(gt_count, hc.get(token, 0)) for hc in hyp_counters), default=0)
+        preserved += best
+    return preserved / total_ref
+
+
+def complementarity_gap(
+    reference: str,
+    hypotheses: dict[str, str],
+) -> dict[str, float]:
+    """Compare l'oracle au meilleur moteur seul.
+
+    Returns
+    -------
+    dict
+        ``{
+            "oracle_recall": float,        # bag-of-words recall de l'oracle
+            "best_single_recall": float,   # meilleur recall token d'un moteur seul
+            "best_engine": str,            # nom du moteur correspondant
+            "absolute_gap": float,         # oracle - best_single (toujours ≥ 0)
+            "relative_gap": float,         # absolute_gap / (1 - best_single + ε)
+                                           # = fraction des erreurs encore évitables
+                                           # par un ensemble
+        }``
+    """
+    ref_counter = _word_multiset(reference)
+    total = sum(ref_counter.values())
+    if not total:
+        return {
+            "oracle_recall": 1.0,
+            "best_single_recall": 1.0,
+            "best_engine": "",
+            "absolute_gap": 0.0,
+            "relative_gap": 0.0,
+        }
+
+    def _single_recall(hyp_text: str) -> float:
+        hc = _word_multiset(hyp_text)
+        preserved = sum(min(gt, hc.get(tok, 0)) for tok, gt in ref_counter.items())
+        return preserved / total
+
+    if not hypotheses:
+        return {
+            "oracle_recall": 0.0,
+            "best_single_recall": 0.0,
+            "best_engine": "",
+            "absolute_gap": 0.0,
+            "relative_gap": 0.0,
+        }
+
+    per_engine = {name: _single_recall(h) for name, h in hypotheses.items()}
+    best_engine, best_recall = max(per_engine.items(), key=lambda kv: kv[1])
+    oracle = oracle_token_recall(reference, hypotheses)
+
+    absolute_gap = max(0.0, oracle - best_recall)
+    # relative_gap : fraction des erreurs du meilleur moteur que l'ensemble
+    # serait théoriquement capable de récupérer (∈ [0, 1])
+    headroom = max(1.0 - best_recall, 1e-12)
+    relative_gap = min(1.0, absolute_gap / headroom)
+
+    return {
+        "oracle_recall": oracle,
+        "best_single_recall": best_recall,
+        "best_engine": best_engine,
+        "absolute_gap": absolute_gap,
+        "relative_gap": relative_gap,
+    }
+
+
+def pairwise_disagreement_rate(
+    reference: str,
+    hyp_a: str,
+    hyp_b: str,
+) -> float:
+    """Fraction de tokens GT pour lesquels A et B sont en désaccord.
+
+    Un désaccord = (l'un préserve le token, l'autre non) OU
+    (les deux le ratent mais avec des substitutions différentes — non
+    capturé ici, on reste sur la version simple présence/absence).
+
+    Returns
+    -------
+    float
+        Ratio dans ``[0, 1]``.  ``0`` = A et B font les mêmes choix
+        (pas de gain d'ensemble).  ``1`` = A et B sont toujours en
+        désaccord (gain d'ensemble maximal).
+    """
+    ref_counter = _word_multiset(reference)
+    if not ref_counter:
+        return 0.0
+    a = _word_multiset(hyp_a)
+    b = _word_multiset(hyp_b)
+    total = sum(ref_counter.values())
+    disagree = 0
+    for tok, gt_count in ref_counter.items():
+        a_pres = min(gt_count, a.get(tok, 0))
+        b_pres = min(gt_count, b.get(tok, 0))
+        # Compte les positions où A et B donnent une réponse différente
+        disagree += abs(a_pres - b_pres)
+    return disagree / total
+
+
+__all__ = [
+    "kl_divergence",
+    "jensen_shannon_divergence",
+    "taxonomy_divergence_matrix",
+    "oracle_token_recall",
+    "complementarity_gap",
+    "pairwise_disagreement_rate",
+]

tests/test_sprint35_inter_engine.py

@@ -0,0 +1,268 @@
+"""Tests Sprint 35 — métriques inter-moteurs (Étape 2 du plan).
+
+Couvre les deux familles de mesures du module ``picarones.core.inter_engine`` :
+
+1. **Divergence taxonomique** : KL et JS-divergence sur les
+   distributions de classes d'erreur, plus la matrice triangulaire
+   inter-moteurs.  Tests : invariants mathématiques (positivité, JS
+   symétrique et bornée, KL(p,p)=0), comportement sur clés disjointes.
+
+2. **Complémentarité** : oracle token recall, gap absolu/relatif vs
+   meilleur moteur seul, taux de désaccord par paire.  Tests : cas
+   parfait (oracle = best = 1), cas où un ensemble apporte un vrai gain,
+   cas d'égalité parfaite (gap = 0), garde-fous (référence vide,
+   hypothèses vides).
+
+Les fonctions sont pures ; pas besoin de fixtures d'I/O ni de moteurs
+réels.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pytest
+
+from picarones.core.inter_engine import (
+    complementarity_gap,
+    jensen_shannon_divergence,
+    kl_divergence,
+    oracle_token_recall,
+    pairwise_disagreement_rate,
+    taxonomy_divergence_matrix,
+)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. KL-divergence
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestKLDivergence:
+    def test_self_divergence_is_zero(self) -> None:
+        p = {"a": 0.4, "b": 0.3, "c": 0.3}
+        assert kl_divergence(p, p) == pytest.approx(0.0, abs=1e-9)
+
+    def test_kl_is_non_negative(self) -> None:
+        p = {"a": 0.7, "b": 0.2, "c": 0.1}
+        q = {"a": 0.1, "b": 0.4, "c": 0.5}
+        assert kl_divergence(p, q) > 0
+        assert kl_divergence(q, p) > 0
+
+    def test_kl_is_asymmetric_in_general(self) -> None:
+        # Choix asymétrique non symétrique par permutation
+        p = {"a": 0.9, "b": 0.05, "c": 0.05}
+        q = {"a": 0.4, "b": 0.4, "c": 0.2}
+        assert kl_divergence(p, q) != pytest.approx(kl_divergence(q, p), abs=1e-3)
+
+    def test_disjoint_keys_handled(self) -> None:
+        # Pas de clé en commun : doit retourner une valeur finie grâce
+        # au lissage epsilon.
+        p = {"a": 1.0}
+        q = {"b": 1.0}
+        kl = kl_divergence(p, q)
+        assert math.isfinite(kl)
+        assert kl > 0
+
+    def test_empty_distributions_return_zero(self) -> None:
+        assert kl_divergence({}, {}) == 0.0
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2. Jensen-Shannon divergence
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestJensenShannonDivergence:
+    def test_self_divergence_is_zero(self) -> None:
+        p = {"a": 0.4, "b": 0.3, "c": 0.3}
+        assert jensen_shannon_divergence(p, p) == pytest.approx(0.0, abs=1e-9)
+
+    def test_symmetric(self) -> None:
+        p = {"a": 0.7, "b": 0.2, "c": 0.1}
+        q = {"a": 0.1, "b": 0.4, "c": 0.5}
+        assert jensen_shannon_divergence(p, q) == pytest.approx(
+            jensen_shannon_divergence(q, p), abs=1e-9
+        )
+
+    def test_bounded_in_unit_interval(self) -> None:
+        # JS en bits ∈ [0, 1].  Distributions extrêmes : disjointes.
+        p = {"a": 1.0}
+        q = {"b": 1.0}
+        js = jensen_shannon_divergence(p, q)
+        assert 0.0 <= js <= 1.0
+        # Les distributions disjointes donnent une JS proche de 1 (la
+        # borne est atteinte asymptotiquement).
+        assert js > 0.5
+
+    def test_close_distributions_have_small_js(self) -> None:
+        p = {"a": 0.5, "b": 0.5}
+        q = {"a": 0.51, "b": 0.49}
+        assert jensen_shannon_divergence(p, q) < 0.01
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 3. Matrice de divergence inter-moteurs
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestDivergenceMatrix:
+    @pytest.fixture
+    def engines(self) -> dict[str, dict[str, float]]:
+        return {
+            "tesseract": {"visual": 0.5, "casse": 0.3, "abbrev": 0.2},
+            "pero": {"visual": 0.2, "casse": 0.3, "abbrev": 0.5},
+            "mistral": {"visual": 0.4, "casse": 0.4, "abbrev": 0.2},
+        }
+
+    def test_diagonal_is_zero(
+        self, engines: dict[str, dict[str, float]]
+    ) -> None:
+        mat = taxonomy_divergence_matrix(engines)
+        for name in engines:
+            assert mat[name][name] == pytest.approx(0.0, abs=1e-9)
+
+    def test_js_matrix_is_symmetric(
+        self, engines: dict[str, dict[str, float]]
+    ) -> None:
+        mat = taxonomy_divergence_matrix(engines, metric="js")
+        for a in engines:
+            for b in engines:
+                assert mat[a][b] == pytest.approx(mat[b][a], abs=1e-9)
+
+    def test_kl_matrix_is_asymmetric(
+        self, engines: dict[str, dict[str, float]]
+    ) -> None:
+        mat = taxonomy_divergence_matrix(engines, metric="kl")
+        # Au moins une paire doit être asymétrique
+        asymmetric_found = any(
+            abs(mat[a][b] - mat[b][a]) > 1e-6
+            for a in engines for b in engines if a != b
+        )
+        assert asymmetric_found
+
+    def test_unknown_metric_raises(
+        self, engines: dict[str, dict[str, float]]
+    ) -> None:
+        with pytest.raises(ValueError, match="metric"):
+            taxonomy_divergence_matrix(engines, metric="hellinger")
+
+    def test_distinguishes_specialized_engines(self) -> None:
+        """Deux moteurs avec profils opposés doivent ressortir comme
+        candidats à un ensemble (JS élevée)."""
+        engines = {
+            "visual_specialist": {"visual": 0.9, "casse": 0.05, "abbrev": 0.05},
+            "abbrev_specialist": {"visual": 0.05, "casse": 0.05, "abbrev": 0.9},
+            "balanced": {"visual": 0.33, "casse": 0.33, "abbrev": 0.34},
+        }
+        mat = taxonomy_divergence_matrix(engines, metric="js")
+        # Les deux spécialistes doivent diverger plus l'un de l'autre que
+        # n'importe lequel d'eux du moteur balanced.
+        assert mat["visual_specialist"]["abbrev_specialist"] > mat["visual_specialist"]["balanced"]
+        assert mat["visual_specialist"]["abbrev_specialist"] > mat["abbrev_specialist"]["balanced"]
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4. Oracle token recall
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestOracleTokenRecall:
+    def test_perfect_engine_oracle_is_one(self) -> None:
+        ref = "le manuscrit est ancien"
+        hyps = {"perfect": ref}
+        assert oracle_token_recall(ref, hyps) == pytest.approx(1.0)
+
+    def test_no_engine_recovers_anything(self) -> None:
+        ref = "alpha beta gamma"
+        hyps = {"a": "x y z", "b": "x y z"}
+        assert oracle_token_recall(ref, hyps) == pytest.approx(0.0)
+
+    def test_complementarity_pays_off(self) -> None:
+        """A et B se complètent : aucun ne fait tout, ensemble ils font tout."""
+        ref = "alpha beta gamma delta"
+        hyps = {
+            "a": "alpha beta x y",       # alpha + beta seulement
+            "b": "x y gamma delta",      # gamma + delta seulement
+        }
+        assert oracle_token_recall(ref, hyps) == pytest.approx(1.0)
+        # Et chacun seul ne fait que la moitié
+        from picarones.core.inter_engine import complementarity_gap
+        gap = complementarity_gap(ref, hyps)
+        assert gap["best_single_recall"] == pytest.approx(0.5)
+        assert gap["oracle_recall"] == pytest.approx(1.0)
+        assert gap["absolute_gap"] == pytest.approx(0.5)
+        # Tout l'écart restant est récupérable → relative_gap = 1
+        assert gap["relative_gap"] == pytest.approx(1.0)
+
+    def test_multiplicity_is_respected(self) -> None:
+        """Si la GT a deux 'le' et le moteur n'en produit qu'un, recall = 0.5
+        sur ce token."""
+        ref = "le chat le chien"  # 2× 'le', 1× 'chat', 1× 'chien'
+        hyps = {"a": "le chat le chien"}  # parfait
+        assert oracle_token_recall(ref, hyps) == pytest.approx(1.0)
+        hyps2 = {"a": "le chat chien"}  # un seul 'le'
+        assert oracle_token_recall(ref, hyps2) == pytest.approx(3 / 4)
+
+    def test_empty_reference_returns_one(self) -> None:
+        assert oracle_token_recall("", {"a": "anything"}) == pytest.approx(1.0)
+
+    def test_no_hypotheses_returns_zero(self) -> None:
+        assert oracle_token_recall("alpha", {}) == pytest.approx(0.0)
+
+    def test_oracle_is_at_least_best_single(self) -> None:
+        """Invariant : l'oracle est toujours ≥ au meilleur moteur seul."""
+        ref = "alpha beta gamma delta epsilon"
+        hyps = {
+            "a": "alpha beta gamma x y",
+            "b": "alpha x gamma delta z",
+            "c": "x y z delta epsilon",
+        }
+        gap = complementarity_gap(ref, hyps)
+        assert gap["oracle_recall"] >= gap["best_single_recall"]
+
+
+# ──────────────��───────────────────────────────────────────────────────────
+# 5. Gap et désaccord par paire
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestComplementarityGap:
+    def test_no_gap_when_engines_are_redundant(self) -> None:
+        ref = "alpha beta gamma"
+        hyps = {"a": "alpha beta x", "b": "alpha beta x"}  # redondants
+        gap = complementarity_gap(ref, hyps)
+        # Les deux ratent le même token → oracle = best_single
+        assert gap["absolute_gap"] == pytest.approx(0.0)
+        assert gap["relative_gap"] == pytest.approx(0.0)
+
+    def test_best_engine_named(self) -> None:
+        ref = "alpha beta gamma"
+        hyps = {
+            "tesseract": "alpha x x",  # 1/3
+            "pero": "alpha beta x",    # 2/3
+        }
+        gap = complementarity_gap(ref, hyps)
+        assert gap["best_engine"] == "pero"
+
+    def test_empty_reference(self) -> None:
+        gap = complementarity_gap("", {"a": "anything"})
+        assert gap["oracle_recall"] == 1.0
+        assert gap["best_single_recall"] == 1.0
+        assert gap["absolute_gap"] == 0.0
+
+
+class TestPairwiseDisagreement:
+    def test_identical_hypotheses_zero_disagreement(self) -> None:
+        ref = "alpha beta gamma"
+        h = "alpha beta x"
+        assert pairwise_disagreement_rate(ref, h, h) == pytest.approx(0.0)
+
+    def test_complete_disagreement_when_complementary(self) -> None:
+        ref = "alpha beta"
+        # A préserve alpha, B préserve beta — désaccord sur les deux
+        rate = pairwise_disagreement_rate(ref, "alpha x", "x beta")
+        assert rate == pytest.approx(1.0)
+
+    def test_empty_reference_returns_zero(self) -> None:
+        assert pairwise_disagreement_rate("", "x", "y") == 0.0