sprint42: A.II.1.b Calibration — token_confidences + câblage runner

Suite directe du Sprint 39 (couche de calcul pure). Le runner peut
maintenant calculer ECE/MCE/reliability dès qu'un moteur expose des
confidences au niveau token sur l'EngineResult.

EngineResult.token_confidences (Optional[list[dict[str, Any]]])
- None par défaut → rétrocompat stricte pour TOUS les adapters
historiques (Tesseract, Pero, Mistral OCR, Google Vision, Azure DI).
- Format attendu : [{"token": str, "confidence": float}, …] avec
confidence ∈ [0, 1] ou ∈ [0, 100] (normalisé par le runner).

Modèles étendus
- DocumentResult.calibration_metrics: Optional[dict] (sérialisé dans
as_dict() quand renseigné, libéré par compact()).
- EngineReport.aggregated_calibration: Optional[dict].

Câblage runner
- _calibration_from_engine_result(ground_truth, token_confidences) :
aligne par bag-of-words avec multiplicité (proxy oracle, comme
oracle_token_recall du Sprint 35), normalise les confidences en
pourcentage à [0, 1], ignore les négatives (Tesseract met -1 pour
les non-mots).
- Appelé dans _compute_document_result quand token_confidences est
non-vide ; sinon calibration_metrics reste None.
- _aggregate_calibration combine les bins de tous les docs en somme
pondérée par count, recalcule ECE/MCE micro sur l'ensemble.

L'adaptation de chaque adapter (Tesseract via image_to_data,
Pero via PageLayout, Mistral via confidence, Google Vision via
Word.confidence, Azure DI) à exposer ses confidences natives est
reportée à des sprints dédiés (un par adapter, plus testable
individuellement). Ce sprint pose l'infrastructure complète et la
rend testable de bout-en-bout via mock.

Tests : +17 dans test_sprint42_calibration_runner.py couvrant le
nouveau champ EngineResult, la sérialisation et compact des nouveaux
champs DR/ER, l'helper d'alignement (calibration parfaite quand
conf=accuracy, normalisation %, skip négatifs, bag-of-words avec
multiplicité, skip entrées invalides), l'agrégateur (combinaison de
bins multi-docs avec recalcul ECE/MCE micro), et la rétrocompat
(pas de calcul sans token_confidences).
Suite complète : 1735 → 1752 passed, 2 skipped, 0 failed.

État A.II.1.b (Calibration) : couche de calcul (Sprint 39) + câblage
runner (Sprint 42) livrés. Reste la vue HTML reliability diagram
(Sprint 43 à venir) et l'adaptation effective des engines pour
exposer leurs confidences natives.

CHANGELOG.md

@@ -16,6 +16,40 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 42 — A.II.1.b Calibration : exposition `token_confidences` +
+  câblage runner.** Suite directe du Sprint 39 (couche de calcul). Le
+  runner peut maintenant calculer ECE/MCE/reliability dès qu'un moteur
+  expose des confidences au niveau token.
+  - `EngineResult.token_confidences: Optional[list[dict[str, Any]]]`
+    ajouté. Format attendu : `[{"token": str, "confidence": float}, …]`,
+    confidence ∈ [0, 1] ou ∈ [0, 100] (normalisé par le runner).
+    `None` par défaut → comportement strictement rétrocompat pour tous
+    les adapters historiques (Tesseract, Pero, Mistral OCR, Google
+    Vision, Azure DI). L'adaptation de chaque adapter à exposer ses
+    confidences natives est reportée à des sprints dédiés (un par
+    adapter).
+  - `DocumentResult.calibration_metrics: Optional[dict]` ajouté
+    (sérialisé dans `as_dict` quand renseigné, libéré par `compact()`).
+  - `EngineReport.aggregated_calibration: Optional[dict]` ajouté.
+  - Helper `_calibration_from_engine_result(ground_truth, token_confidences)` :
+    aligne par bag-of-words avec multiplicité (proxy oracle, comme
+    `oracle_token_recall` du Sprint 35), normalise les confidences en
+    pourcentage à `[0, 1]`, ignore les confidences négatives
+    (Tesseract met -1 pour les non-mots), retourne `None` sur entrée
+    vide. Appelé dans `_compute_document_result` quand
+    `EngineResult.token_confidences` est non-vide.
+  - Helper `_aggregate_calibration(doc_results)` : combine les bins de
+    tous les docs en somme pondérée par count, recalcule ECE/MCE micro
+    sur l'ensemble. Renvoie `None` si aucun doc n'a de
+    `calibration_metrics`.
+  - +17 tests dans `test_sprint42_calibration_runner.py` couvrant le
+    nouveau champ EngineResult, la sérialisation et compact des
+    nouveaux champs DR/ER, l'helper d'alignement (calibration parfaite,
+    normalisation %, skip négatifs, bag-of-words avec multiplicité,
+    skip entrées invalides), l'agrégateur (combinaison de bins
+    multi-docs, recalcul ECE/MCE micro), et la rétrocompat
+    (pas de calcul sans token_confidences).
+
 - **Sprint 41 — A.II.1.a NER : vue HTML dédiée (clôture A.II.1.a).**
   Suite directe des Sprints 38-40. Le moteur narratif et le runner ont
   déjà tout ce qu'il faut ; ce sprint rend les chiffres visibles et
@@ -299,13 +333,15 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1735 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
+- 1478 → 1752 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). Aucune régression.
-  **Phase 0 close ; Étape 2 du plan d'évolution : inter-moteurs
-  (A.II.1.c) et NER (A.II.1.a) livrés bout-en-bout calcul → runner
-  → narratif → HTML ; calibration (A.II.1.b) couche de calcul
-  livrée (Sprint 39).**
+  +32 Sprint 39, +16 Sprint 40, +38 Sprint 41, +17 Sprint 42).
+  Aucune régression. **Phase 0 close ; Étape 2 du plan d'évolution :
+  inter-moteurs (A.II.1.c) et NER (A.II.1.a) livrés bout-en-bout
+  calcul → runner → narratif → HTML ; calibration (A.II.1.b) couche
+  de calcul + câblage runner livrés (Sprints 39+42), il manque la vue
+  HTML reliability diagram et l'adaptation des engines pour exposer
+  leurs confidences natives.**
 
 ---
 

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). |
+| 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). |
 | 40 | **Sprint 9 du plan d'évolution 2026 — Étape 2 / axe A.II.1.a : NER backend + câblage runner**. Suite du Sprint 38 (couche de calcul). Nouveau module `picarones/core/ner_backends.py` : `EntityExtractor` (Protocol, tout callable `(text) → list[dict]` est valide), `SpacyEntityExtractor` (lazy-import spaCy, charge le modèle au premier appel, fallback gracieux silencieux + warning explicite si spaCy/modèle absent, mapping par défaut spaCy → conventions HIPE : PERSON→PER, GPE→LOC, etc.), `SPACY_PROFILES` (6 profils nommés), `get_extractor(profile)`, `is_spacy_available()`. `DocumentResult.ner_metrics: Optional[dict]` et `EngineReport.aggregated_ner` ajoutés (sérialisés dans `as_dict` quand renseignés, libérés par `compact()`). `runner.run_benchmark` accepte un nouveau paramètre optionnel `entity_extractor` ; si fourni, helpers `_attach_ner_metrics` et `_aggregate_ner` calculent les métriques en post-process (main process pour éviter de pickler spaCy dans les sous-processus). Rétrocompat stricte : sans `entity_extractor`, aucun calcul ni champ ajouté. Nouveau extra `[ner]` dans `pyproject.toml` (spacy>=3.7.0). +16 tests dans `test_sprint40_ner_runner.py` (fallback sans spaCy + warning, idempotence load, profils + factory, sérialisation nouveaux champs, câblage runner avec mock injecté, agrégation micro-F1, rétrocompat sans extracteur, robustesse à un extracteur qui lève). **Verrou levé** : un benchmark dont le corpus a une GT entités produit maintenant des métriques NER bout-en-bout — il manque uniquement la vue HTML dédiée (Sprint 41 à venir). |
 | 39 | **Sprint 8 du plan d'évolution 2026 — Étape 2 / axe A.II.1.b : Calibration (couche de calcul)**. Nouveau module `picarones/core/calibration.py` avec dataclass `CalibrationBin` (`bin_low/high`, `avg_confidence`, `accuracy`, `count`, propriété `gap`), `reliability_diagram`, `expected_calibration_error` (ECE — moyenne pondérée par bin de `\|conf - accuracy\|`, ∈ [0, 1]), `maximum_calibration_error` (MCE — pire écart sur les bins non vides), `compute_calibration_metrics` (vue agrégée). Calcul d'index de bin par multiplication `int(c * n_bins)` plutôt que division pour éviter le piège IEEE 754 (`0.6 / 0.1 = 5.999…`). Aucune dépendance externe — les listes `confidences` ∈ [0, 1] et `is_correct` ∈ {0,1} sont fournies en entrée ; l'extraction depuis les engines existants est reportée à un sprint dédié. +32 tests couvrant calibration parfaite (ECE = 0), cas extrêmes (sur/sous-confiance → ECE = 0,5), biais constant (ECE = `\|c-a\|`), binning correct (0.6 placé dans le bon bin), bins vides (`gap = None`), garde-fous, monotonie `n_bins` plus fins → ECE ne décroît pas. **Verrou levé** : un workflow patrimonial peut maintenant répondre à *« quand le moteur dit qu'il est sûr, est-il vraiment sûr ? »* — différence entre vérification humaine systématique (100 %) et ciblée (15 %) sur les passages à faible confiance. |
@@ -259,7 +260,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1735 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 calcul → runner → HTML ; Sprint 39 = calibration couche de calcul, vue HTML à venir)
+- **Tests** : 1752 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 calcul → runner → HTML ; Sprints 39+42 = calibration couche de calcul + câblage runner, vue HTML reliability + adaptation engines à venir)
 - **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/results.py

@@ -61,6 +61,15 @@ class DocumentResult:
     le document a un niveau de GT ``ENTITIES`` ET que le runner a reçu
     un ``EntityExtractor``.
     """
+    # Sprint 42 — calibration des confidences moteur (ECE, MCE, bins)
+    calibration_metrics: Optional[dict] = None
+    """Métriques de calibration (Sprint 39+42).
+
+    Format : retour de ``compute_calibration_metrics`` (ece, mce,
+    n_bins, n_predictions, overall_accuracy, overall_confidence, bins).
+    Présent uniquement si le moteur a fourni des ``token_confidences``
+    sur l'``EngineResult``.
+    """
 
     def as_dict(self) -> dict:
         d = {
@@ -92,6 +101,8 @@ class DocumentResult:
             d["hallucination_metrics"] = self.hallucination_metrics
         if self.ner_metrics is not None:
             d["ner_metrics"] = self.ner_metrics
+        if self.calibration_metrics is not None:
+            d["calibration_metrics"] = self.calibration_metrics
         return d
 
     def compact(self) -> None:
@@ -118,6 +129,7 @@ class DocumentResult:
         self.line_metrics = None
         self.hallucination_metrics = None
         self.ner_metrics = None
+        self.calibration_metrics = None
 
 
 @dataclass
@@ -155,6 +167,12 @@ class EngineReport:
     """Métriques NER agrégées sur le corpus : F1 micro/macro globaux et
     par catégorie, total hallucinations/missed.  ``None`` si aucun
     document n'a porté de calcul NER."""
+    # Sprint 42
+    aggregated_calibration: Optional[dict] = None
+    """Calibration agrégée sur le corpus : ECE, MCE, reliability diagram
+    micro recalculé à partir des sommes par bin.  ``None`` si aucun
+    document n'avait de ``calibration_metrics`` (cas par défaut tant que
+    les engines n'exposent pas ``token_confidences``)."""
 
     def __post_init__(self) -> None:
         if not self.aggregated_metrics and self.document_results:
@@ -217,6 +235,8 @@ class EngineReport:
             d["aggregated_hallucination"] = self.aggregated_hallucination
         if self.aggregated_ner is not None:
             d["aggregated_ner"] = self.aggregated_ner
+        if self.aggregated_calibration is not None:
+            d["aggregated_calibration"] = self.aggregated_calibration
         return d
 
 

picarones/core/runner.py

@@ -101,6 +101,67 @@ def _io_doc_worker(
 # Calcul documentaire centralisé
 # ---------------------------------------------------------------------------
 
+
+def _calibration_from_engine_result(
+    ground_truth: str,
+    token_confidences: list,
+) -> Optional[dict]:
+    """Aligne les ``token_confidences`` du moteur sur la GT (bag-of-words)
+    pour produire les listes parallèles ``confidences`` / ``is_correct``,
+    puis appelle ``compute_calibration_metrics`` (Sprint 39).
+
+    Convention d'alignement (proxy bag-of-words avec multiplicité, comme
+    ``oracle_token_recall`` du Sprint 35) : un token de l'hypothèse est
+    "correct" si la GT contient encore une occurrence de ce token.
+    Ce n'est pas un alignement séquentiel ; c'est volontaire pour rester
+    simple et robuste aux décalages d'OCR.
+
+    Les confidences ``> 1.0`` sont supposées en pourcentage et
+    normalisées à ``[0, 1]``.  Les confidences négatives (Tesseract met
+    -1 pour les non-mots) sont ignorées.
+    """
+    from collections import Counter
+
+    from picarones.core.calibration import compute_calibration_metrics
+
+    if not token_confidences:
+        return None
+
+    gt_counter = Counter((ground_truth or "").split())
+    confidences: list[float] = []
+    is_correct: list[int] = []
+
+    for tc in token_confidences:
+        if not isinstance(tc, dict):
+            continue
+        token = str(tc.get("token", ""))
+        if not token:
+            continue
+        try:
+            conf = float(tc.get("confidence"))
+        except (TypeError, ValueError):
+            continue
+        if conf < 0:
+            # -1 = non-mot dans le format Tesseract image_to_data
+            continue
+        if conf > 1.0:
+            conf = conf / 100.0
+        if not 0.0 <= conf <= 1.0:
+            continue
+        if gt_counter[token] > 0:
+            is_correct.append(1)
+            gt_counter[token] -= 1
+        else:
+            is_correct.append(0)
+        confidences.append(conf)
+
+    if not confidences:
+        return None
+    return compute_calibration_metrics(confidences, is_correct)
+
+
+
+
 def _compute_document_result(
     doc_id: str,
     image_path: str,
@@ -204,6 +265,18 @@ def _compute_document_result(
         except Exception as e:
             _logger.warning("[hallucination] fonctionnalité dégradée : %s", e)
 
+    # Sprint 42 — calibration des confidences moteur (en dehors du
+    # ``if ocr_result.success`` puisqu'on peut avoir des confidences même
+    # sur un succès partiel).
+    calibration_data: Optional[dict] = None
+    if ocr_result.token_confidences:
+        try:
+            calibration_data = _calibration_from_engine_result(
+                ground_truth, ocr_result.token_confidences,
+            )
+        except Exception as e:
+            _logger.warning("[calibration] fonctionnalité dégradée : %s", e)
+
     try:
         from picarones.core.image_quality import analyze_image_quality
         iq = analyze_image_quality(image_path)
@@ -229,6 +302,7 @@ def _compute_document_result(
         image_quality=image_quality_data,
         line_metrics=line_metrics_data,
         hallucination_metrics=hallucination_data,
+        calibration_metrics=calibration_data,
     )
 
 
@@ -636,6 +710,7 @@ def run_benchmark(
         agg_image_quality = _aggregate_image_quality(document_results)
         agg_line_metrics = _aggregate_line_metrics(document_results)
         agg_hallucination = _aggregate_hallucination(document_results)
+        agg_calibration = _aggregate_calibration(document_results)
 
         report = EngineReport(
             engine_name=engine.name,
@@ -650,6 +725,7 @@ def run_benchmark(
             aggregated_image_quality=agg_image_quality,
             aggregated_line_metrics=agg_line_metrics,
             aggregated_hallucination=agg_hallucination,
+            aggregated_calibration=agg_calibration,
         )
         engine_reports.append(report)
         logger.info(
@@ -957,6 +1033,102 @@ def _attach_ner_metrics(
         logger.info("[ner] %d documents évalués pour NER.", n_done)
 
 
+def _aggregate_calibration(doc_results: list) -> Optional[dict]:
+    """Agrège la calibration micro sur tous les docs.
+
+    Recalcule ECE/MCE à partir de la **somme des bins** de chaque
+    document : pour chaque bin, on additionne ``count``, on agrège la
+    confiance moyenne pondérée par count, et on agrège l'accuracy
+    pondérée par count.  L'ECE micro est ensuite la moyenne pondérée
+    par bin de ``|conf - acc|``.
+    """
+    relevant = [
+        dr for dr in doc_results
+        if dr.calibration_metrics is not None
+        and (dr.calibration_metrics.get("bins") or [])
+    ]
+    if not relevant:
+        return None
+
+    # Aligne tous les docs sur le même nombre de bins (par sécurité, on
+    # vérifie qu'ils sont cohérents — sinon on prend le 1er en
+    # référence et on saute les incohérents avec un warning).
+    n_bins = relevant[0].calibration_metrics.get("n_bins", 10)
+    sum_conf: list[float] = [0.0] * n_bins
+    sum_acc: list[float] = [0.0] * n_bins
+    counts: list[int] = [0] * n_bins
+    bin_lows: list[float] = [
+        b["bin_low"] for b in relevant[0].calibration_metrics["bins"]
+    ]
+    bin_highs: list[float] = [
+        b["bin_high"] for b in relevant[0].calibration_metrics["bins"]
+    ]
+
+    for dr in relevant:
+        m = dr.calibration_metrics
+        if m.get("n_bins") != n_bins:
+            logger.warning(
+                "[aggregate_calibration] %s : n_bins=%s ≠ %s — ignoré",
+                dr.doc_id, m.get("n_bins"), n_bins,
+            )
+            continue
+        for k, b in enumerate(m["bins"]):
+            n = int(b.get("count") or 0)
+            if n == 0:
+                continue
+            counts[k] += n
+            sum_conf[k] += float(b.get("avg_confidence") or 0.0) * n
+            sum_acc[k] += float(b.get("accuracy") or 0.0) * n
+
+    total = sum(counts)
+    if total == 0:
+        return None
+
+    bins: list[dict] = []
+    ece = 0.0
+    mce = 0.0
+    for k in range(n_bins):
+        n = counts[k]
+        if n == 0:
+            bins.append({
+                "bin_low": bin_lows[k] if k < len(bin_lows) else k / n_bins,
+                "bin_high": bin_highs[k] if k < len(bin_highs) else (k + 1) / n_bins,
+                "avg_confidence": None,
+                "accuracy": None,
+                "count": 0,
+                "gap": None,
+            })
+            continue
+        avg_conf = sum_conf[k] / n
+        accuracy = sum_acc[k] / n
+        gap = abs(avg_conf - accuracy)
+        bins.append({
+            "bin_low": bin_lows[k] if k < len(bin_lows) else k / n_bins,
+            "bin_high": bin_highs[k] if k < len(bin_highs) else (k + 1) / n_bins,
+            "avg_confidence": avg_conf,
+            "accuracy": accuracy,
+            "count": n,
+            "gap": gap,
+        })
+        ece += (n / total) * gap
+        if gap > mce:
+            mce = gap
+
+    overall_acc = sum(sum_acc) / total
+    overall_conf = sum(sum_conf) / total
+
+    return {
+        "ece": ece,
+        "mce": mce,
+        "n_bins": n_bins,
+        "n_predictions": total,
+        "overall_accuracy": overall_acc,
+        "overall_confidence": overall_conf,
+        "bins": bins,
+        "doc_count": len(relevant),
+    }
+
+
 def _aggregate_ner(doc_results: list) -> Optional[dict]:
     """Agrège les métriques NER au niveau du moteur.
 

picarones/engines/base.py

@@ -22,6 +22,13 @@ class EngineResult:
     duration_seconds: float
     error: Optional[str] = None
     metadata: dict = field(default_factory=dict)
+    # Sprint 42 — confidences au niveau token (optionnel).
+    # Format attendu : liste de dicts ``{"token": str, "confidence": float}``
+    # avec ``confidence`` ∈ [0, 1] (ou ∈ [0, 100], normalisé par le runner).
+    # ``None`` si le moteur ne fournit pas ce signal — comportement par
+    # défaut pour tous les adapters historiques.  Quand renseigné,
+    # le runner alimente ``DocumentResult.calibration_metrics``.
+    token_confidences: Optional[list[dict[str, Any]]] = None
 
     @property
     def success(self) -> bool:

tests/test_sprint42_calibration_runner.py

@@ -0,0 +1,284 @@
+"""Tests Sprint 42 — exposition des token_confidences + câblage runner.
+
+Le runner peut maintenant calculer des métriques de calibration
+(ECE / MCE / reliability) dès qu'un moteur expose des
+``token_confidences`` sur l'``EngineResult``.
+
+Couvre :
+
+1. ``EngineResult.token_confidences`` accepte ``None`` (rétrocompat
+   stricte) ou une liste de dicts.
+2. ``DocumentResult.calibration_metrics`` est sérialisé via ``as_dict``
+   uniquement quand renseigné, libéré par ``compact()``.
+3. ``EngineReport.aggregated_calibration`` apparaît dans ``as_dict``
+   quand renseigné.
+4. ``_calibration_from_engine_result`` :
+   - Aligne en bag-of-words avec multiplicité (proxy oracle)
+   - Normalise les confidences en pourcentage (>1) à [0, 1]
+   - Ignore les confidences négatives (Tesseract -1 pour non-mots)
+   - Retourne ``None`` sur entrée vide / ``None``
+5. ``_aggregate_calibration`` :
+   - Combine les bins de plusieurs documents en somme pondérée
+   - Recalcule ECE/MCE micro à partir des sommes
+   - Retourne ``None`` si aucun doc n'a de calibration
+6. Rétrocompat : sans token_confidences sur l'EngineResult, aucun
+   calcul calibration ; ``aggregated_calibration = None``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.core.runner import (
+    _aggregate_calibration,
+    _calibration_from_engine_result,
+)
+from picarones.core.results import DocumentResult, EngineReport
+from picarones.engines.base import EngineResult
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. EngineResult.token_confidences
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestEngineResultExtension:
+    def test_default_is_none(self) -> None:
+        r = EngineResult("e", "/tmp/x.png", "hello", 1.0)
+        assert r.token_confidences is None
+
+    def test_accepts_list_of_dicts(self) -> None:
+        confs = [{"token": "hello", "confidence": 0.95}]
+        r = EngineResult("e", "/tmp/x.png", "hello", 1.0, token_confidences=confs)
+        assert r.token_confidences == confs
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2-3. Modèles : sérialisation et compact
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _make_dr(calibration_metrics: dict | None = None) -> DocumentResult:
+    from picarones.core.metrics import MetricsResult
+
+    return DocumentResult(
+        doc_id="d1", image_path="/tmp/x.png",
+        ground_truth="a b c", hypothesis="a b c",
+        metrics=MetricsResult(
+            cer=0.0, cer_nfc=0.0, cer_caseless=0.0,
+            wer=0.0, wer_normalized=0.0, mer=0.0, wil=0.0,
+            reference_length=5, hypothesis_length=5,
+        ),
+        duration_seconds=0.1,
+        calibration_metrics=calibration_metrics,
+    )
+
+
+class TestModelsSerialization:
+    def test_calibration_metrics_omitted_when_none(self) -> None:
+        d = _make_dr(None).as_dict()
+        assert "calibration_metrics" not in d
+
+    def test_calibration_metrics_present_when_set(self) -> None:
+        d = _make_dr({"ece": 0.05, "mce": 0.1}).as_dict()
+        assert d["calibration_metrics"] == {"ece": 0.05, "mce": 0.1}
+
+    def test_compact_clears_calibration(self) -> None:
+        dr = _make_dr({"ece": 0.05})
+        dr.compact()
+        assert dr.calibration_metrics is None
+
+    def test_engine_report_aggregated_calibration_omitted_when_none(self) -> None:
+        rep = EngineReport(
+            engine_name="t", engine_version="1", engine_config={},
+            document_results=[_make_dr()],
+        )
+        assert "aggregated_calibration" not in rep.as_dict()
+
+    def test_engine_report_aggregated_calibration_included_when_set(self) -> None:
+        rep = EngineReport(
+            engine_name="t", engine_version="1", engine_config={},
+            document_results=[_make_dr()],
+            aggregated_calibration={"ece": 0.05, "n_predictions": 100},
+        )
+        assert rep.as_dict()["aggregated_calibration"] == {
+            "ece": 0.05, "n_predictions": 100,
+        }
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4. Helper d'alignement
+# ───────────────────────────���──────────────────────────────────────────────
+
+
+class TestCalibrationFromEngineResult:
+    def test_returns_none_for_empty_inputs(self) -> None:
+        assert _calibration_from_engine_result("text", None) is None
+        assert _calibration_from_engine_result("text", []) is None
+
+    def test_perfect_calibration_when_conf_matches_accuracy(self) -> None:
+        gt = "a b c d e f g h i j"
+        # 7 tokens dans la GT à conf=0.7, 3 hors de la GT à conf=0.7 → ECE = 0
+        tcs = (
+            [{"token": c, "confidence": 0.7} for c in "abcdefg"]
+            + [{"token": c, "confidence": 0.7} for c in ["X", "Y", "Z"]]
+        )
+        m = _calibration_from_engine_result(gt, tcs)
+        assert m is not None
+        assert m["ece"] == pytest.approx(0.0, abs=1e-9)
+        assert m["overall_accuracy"] == pytest.approx(0.7)
+        assert m["n_predictions"] == 10
+
+    def test_normalizes_percentage_confidences(self) -> None:
+        """Conf > 1 est interprétée en pourcentage et divisée par 100."""
+        m = _calibration_from_engine_result(
+            "hello", [{"token": "hello", "confidence": 95.0}],
+        )
+        assert m is not None
+        # 95/100 = 0.95
+        assert m["overall_confidence"] == 0.95
+
+    def test_skips_negative_confidences(self) -> None:
+        """Tesseract met -1 pour les non-mots ; on les ignore."""
+        m = _calibration_from_engine_result(
+            "hello", [
+                {"token": "hello", "confidence": 0.9},
+                {"token": ".", "confidence": -1.0},
+            ],
+        )
+        assert m is not None
+        assert m["n_predictions"] == 1
+
+    def test_bag_of_words_with_multiplicity(self) -> None:
+        # GT contient deux 'le'. L'hypothèse en a trois → 2 corrects, 1 incorrect.
+        gt = "le chat le chien"
+        tcs = [
+            {"token": "le", "confidence": 0.9},
+            {"token": "le", "confidence": 0.9},
+            {"token": "le", "confidence": 0.9},  # 3e 'le' : pas dans la GT
+            {"token": "chat", "confidence": 0.9},
+            {"token": "chien", "confidence": 0.9},
+        ]
+        m = _calibration_from_engine_result(gt, tcs)
+        # 4 corrects sur 5
+        assert m["overall_accuracy"] == 0.8
+        assert m["n_predictions"] == 5
+
+    def test_skips_invalid_entries(self) -> None:
+        m = _calibration_from_engine_result(
+            "hello", [
+                "not a dict",
+                {"no_token": True, "confidence": 0.5},
+                {"token": "hello"},  # pas de confidence
+                {"token": "hello", "confidence": "abc"},  # conf non numérique
+                {"token": "hello", "confidence": 0.9},  # valide
+            ],
+        )
+        assert m is not None
+        assert m["n_predictions"] == 1
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 5. Agrégateur
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestAggregateCalibration:
+    def test_returns_none_when_no_doc_has_calibration(self) -> None:
+        drs = [_make_dr(None), _make_dr(None)]
+        assert _aggregate_calibration(drs) is None
+
+    def test_combines_bins_across_docs(self) -> None:
+        # Doc 1 : bin [0.5, 0.6) avec 10 prédictions, conf=0.55, acc=0.5
+        # Doc 2 : bin [0.5, 0.6) avec 20 prédictions, conf=0.55, acc=0.7
+        # Agrégat attendu : 30 prédictions dans ce bin, conf moy = 0.55,
+        # acc moy pondérée = (10*0.5 + 20*0.7) / 30 = 19/30 ≈ 0.633
+        empty_bin = lambda lo, hi: {  # noqa: E731
+            "bin_low": lo, "bin_high": hi,
+            "avg_confidence": None, "accuracy": None,
+            "count": 0, "gap": None,
+        }
+        bins1 = [empty_bin(k / 10, (k + 1) / 10) for k in range(10)]
+        bins1[5] = {
+            "bin_low": 0.5, "bin_high": 0.6,
+            "avg_confidence": 0.55, "accuracy": 0.5,
+            "count": 10, "gap": 0.05,
+        }
+        m1 = {
+            "ece": 0.05, "mce": 0.05, "n_bins": 10, "n_predictions": 10,
+            "overall_accuracy": 0.5, "overall_confidence": 0.55, "bins": bins1,
+        }
+        bins2 = [empty_bin(k / 10, (k + 1) / 10) for k in range(10)]
+        bins2[5] = {
+            "bin_low": 0.5, "bin_high": 0.6,
+            "avg_confidence": 0.55, "accuracy": 0.7,
+            "count": 20, "gap": 0.15,
+        }
+        m2 = {
+            "ece": 0.15, "mce": 0.15, "n_bins": 10, "n_predictions": 20,
+            "overall_accuracy": 0.7, "overall_confidence": 0.55, "bins": bins2,
+        }
+        drs = [_make_dr(m1), _make_dr(m2)]
+        agg = _aggregate_calibration(drs)
+        assert agg is not None
+        assert agg["n_predictions"] == 30
+        assert agg["doc_count"] == 2
+        # Accuracy combinée = (10*0.5 + 20*0.7) / 30
+        assert agg["overall_accuracy"] == (10 * 0.5 + 20 * 0.7) / 30
+        # Confidence combinée = 0.55 (constante)
+        assert abs(agg["overall_confidence"] - 0.55) < 1e-9
+        # ECE micro : seul bin non vide (bin 5), avec count=30,
+        # avg_conf=0.55, accuracy=19/30 ≈ 0.633, gap = |0.55 - 0.633|
+        expected_ece = abs(0.55 - 19 / 30)
+        assert abs(agg["ece"] - expected_ece) < 1e-9
+        assert agg["mce"] == agg["ece"]  # un seul bin non vide → MCE = ECE
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 6. Rétrocompat : sans token_confidences, rien ne change
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestBackwardCompat:
+    def test_engine_result_default_no_calibration(self) -> None:
+        # Un EngineResult sans token_confidences → calibration_metrics
+        # ne doit pas être calculée.
+        from picarones.core.runner import _compute_document_result
+        ocr = EngineResult(
+            engine_name="e",
+            image_path="/tmp/x.png",
+            text="a b c",
+            duration_seconds=0.1,
+            token_confidences=None,
+        )
+        dr = _compute_document_result(
+            doc_id="d1", image_path="/tmp/x.png",
+            ground_truth="a b c",
+            ocr_result=ocr,
+            char_exclude=None,
+        )
+        assert dr.calibration_metrics is None
+
+    def test_engine_result_with_confs_triggers_calibration(self) -> None:
+        from picarones.core.runner import _compute_document_result
+        ocr = EngineResult(
+            engine_name="e",
+            image_path="/tmp/x.png",
+            text="a b c",
+            duration_seconds=0.1,
+            token_confidences=[
+                {"token": "a", "confidence": 0.9},
+                {"token": "b", "confidence": 0.9},
+                {"token": "c", "confidence": 0.9},
+            ],
+        )
+        dr = _compute_document_result(
+            doc_id="d1", image_path="/tmp/x.png",
+            ground_truth="a b c",
+            ocr_result=ocr,
+            char_exclude=None,
+        )
+        assert dr.calibration_metrics is not None
+        # 3 tokens, tous corrects, conf 0.9 → accuracy = 1, conf = 0.9
+        assert dr.calibration_metrics["overall_accuracy"] == 1.0
+        assert dr.calibration_metrics["overall_confidence"] == 0.9