sprint39: A.II.1.b Calibration — couche de calcul (ECE, MCE, reliability)

Deuxième brique des trois métriques prioritaires de l'Étape 2 du plan
d'évolution (axe A — fiabilité). Stratégie identique aux Sprints 35-38 :
couche de calcul d'abord, exposition des token_confidences sur les
EngineResult et câblage runner+narratif+HTML aux sprints suivants.

Pour un workflow patrimonial qui doit vérifier humainement un corpus de
50 000 pages, la différence entre vérifier 100 % vs 15 % du volume est
l'effet de la calibration. Un moteur surconfiant (ECE élevé) annonce
toujours "95 % de confiance" et a tort une fois sur deux — vérification
systématique inévitable. Un moteur calibré (ECE bas) permet de cibler
la vérification sur les passages à faible confiance.

Nouveau picarones/core/calibration.py
- Dataclass CalibrationBin avec propriété gap (None pour bin vide).
- reliability_diagram : binning équidistant avec calcul de la confiance
moyenne, précision moyenne et compte par bin.
- 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 avec ECE, MCE, n_bins,
n_predictions, overall_accuracy, overall_confidence, bins.
- Calcul d'index par multiplication int(c * n_bins) plutôt que
division pour éviter le piège IEEE 754 (0.6 / 0.1 = 5.999... met
0.6 dans le mauvais bin).

Aucune dépendance externe : les listes confidences ∈ [0, 1] et
is_correct ∈ {0, 1} sont fournies en entrée. L'extraction depuis les
engines (Tesseract tsv, Pero PageLayout, Mistral confidence, Google
Vision Word.confidence) est reportée à un sprint dédié.

Tests : +32 dans test_sprint39_calibration.py couvrant calibration
parfaite (ECE = 0), cas extrêmes (sur/sous-confiance → ECE = 0,5),
biais constant (ECE = |c-a|), binning correct y compris pour 0.6 (le
piège classique), bins vides (gap = None), listes vides, garde-fous
(longueurs incompatibles, conf hors [0,1], n_bins ≤ 0), n_bins
paramétrable + monotonie ECE.
Suite complète : 1649 → 1681 passed, 2 skipped, 0 failed.

CHANGELOG.md

@@ -16,6 +16,40 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 39 — A.II.1.b Calibration des moteurs : couche de calcul.**
+  Deuxième brique des trois métriques prioritaires de l'Étape 2 (axe A —
+  fiabilité). Stratégie identique aux Sprints 35-38 : couche de calcul
+  pure, exposition des `token_confidences` sur les `EngineResult` et
+  câblage runner+narratif+HTML aux sprints suivants.
+  - Nouveau module `picarones/core/calibration.py` :
+    - dataclass `CalibrationBin(bin_low, bin_high, avg_confidence,
+      accuracy, count)` avec propriété `gap` (renvoie `None` si bin vide)
+    - `reliability_diagram(confidences, is_correct, n_bins=10)` : binning
+      équidistant de la confiance, calcul de la précision moyenne et de
+      la confiance moyenne par bin
+    - `expected_calibration_error` (ECE) : moyenne pondérée par bin de
+      `|conf - accuracy|`, ∈ [0, 1], 0 = calibration parfaite
+    - `maximum_calibration_error` (MCE) : pire écart sur tous 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 les pièges IEEE 754 (`0.6 / 0.1 =
+    5.999…` en flottant). Cas testé.
+  - Aucune dépendance externe ; les listes `confidences` et `is_correct`
+    sont fournies en entrée. L'extraction depuis les engines existants
+    (Tesseract `tsv`, Pero `PageLayout`, Mistral `confidence`, Google
+    Vision `Word.confidence`) est explicitement reportée à un sprint
+    dédié.
+  - +32 tests dans `test_sprint39_calibration.py` couvrant la
+    calibration parfaite (ECE = 0), les cas extrêmes (sur-confiance et
+    sous-confiance → ECE = 0,5), le biais constant (ECE = `|conf - acc|`),
+    le binning correct (bornes équidistantes, c=1.0 dans le dernier bin,
+    affectation correcte y compris pour 0.6), les bins vides
+    (avg/accuracy/gap = `None`), les listes vides, les garde-fous
+    (longueurs incompatibles, conf hors [0, 1], n_bins ≤ 0), `n_bins`
+    paramétrable + monotonie « ECE ne décroît pas avec un binning plus
+    fin ».
+
 - **Sprint 38 — A.II.1.a NER : couche de calcul.** Première brique
   des trois métriques prioritaires de l'Étape 2 du plan d'évolution
   (axe A — utilité aval). Stratégie de découpage analogue à la
@@ -186,11 +220,12 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1649 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
-  +27 Sprint 35, +22 Sprint 36, +42 Sprint 37, +19 Sprint 38). Aucune
-  régression. **Phase 0 close ; Étape 2 du plan d'évolution : inter-moteurs
-  livrés bout-en-bout (Sprints 35-37) ; NER (axe A.II.1.a) couche de
-  calcul livrée (Sprint 38).**
+- 1478 → 1681 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). Aucune régression. **Phase 0 close ; Étape 2 du plan
+  d'évolution : inter-moteurs livrés bout-en-bout (Sprints 35-37) ;
+  NER (A.II.1.a) et calibration (A.II.1.b) couches de calcul livrées
+  (Sprints 38-39).**
 
 ---
 

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). |
+| 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. |
 | 38 | **Sprint 7 du plan d'évolution 2026 — Étape 2 / axe A.II.1.a : NER (couche de calcul)**. Nouveau module `picarones/core/ner.py` : dataclass `Entity(label, start, end, text)` (validation de span), fonction `compute_ner_metrics(reference, hypothesis, iou_threshold=0.5)` qui aligne par chevauchement IoU (greedy, IoU décroissant, chaque entité matchée au plus une fois) et retourne precision/recall/F1 globaux + par catégorie + listes `hallucinated_entities` / `missed_entities`. Format dict compatible `EntitiesGT` du Sprint 32. Métrique `ner_f1` enregistrée dans le registre typé Sprint 34 pour la jonction `(ENTITIES, ENTITIES)`. Aucune dépendance externe : les listes d'entités sont fournies en entrée — le backend extracteur (spaCy/Stanza/HIPE) suivra dans un sprint dédié. +19 tests dans `test_sprint38_ner_metrics.py` (cas standards, label case-insensitive, IoU sous/sur seuil, multi-catégorie, alignement greedy, cas dégénérés, validation Entity, intégration registre). **Verrou levé** : un benchmark dont le corpus a une GT entités peut maintenant mesurer l'utilité aval pour l'indexation prosopographique — métrique critique pour les bibliothèques numériques. |
 | 37 | **Sprint 6 du plan d'évolution 2026 — Étape 2 / axe A : section inter-moteurs dans le rapport HTML**. Nouveau module `picarones/report/inter_engine_render.py` qui produit deux blocs HTML serveur-side (pas de JS) : `build_divergence_matrix_html` rend une table heatmap CSS inline (gradient blanc → rouge sur le max hors-diagonale, diagonale étiquetée, paire la plus divergente annoncée en sous-titre) ; `build_oracle_gap_html` rend l'encart factuel best engine / recall / oracle / gap absolu+relatif / doc count. Le `ReportGenerator` les calcule et les passe au template `view_analyses.html` qui les affiche dans une `chart-card` à largeur pleine **uniquement si présents** — principe du rapport adaptatif (< 2 moteurs ou pas de taxonomie → section omise). +14 clés i18n FR/EN (`h_inter_engine`, `inter_engine_note`, `divergence_*`, `oracle_*`). Anti-injection HTML via `html.escape`. +42 tests dans `test_sprint37_inter_engine_html.py` couvrant le rendu (valeurs, paire max), le masquage adaptatif sur 4 cas dégénérés, l'anti-injection (engine name `<script>` correctement échappé), l'intégration rapport FR + EN, la complétude i18n sur les 14 clés × 2 langues. **Verrou levé** : ce que le moteur narratif annonce dans la synthèse (« tess et pero ont des profils divergents… ») est maintenant aussi visible dans la vue analyses sous forme de matrice et d'encart factuel — le lecteur peut vérifier visuellement le chiffre. |
 | 36 | **Sprint 5 du plan d'évolution 2026 — Étape 2 / axe A : câblage inter-moteurs au runner et au moteur narratif**. Suite du Sprint 35 : `inter_engine.py` gagne `compute_inter_engine_analysis` (agrégation corpus-wide doc par doc, structure stable consommable par les détecteurs et le rapport HTML — oracle global, recall par moteur, per_doc top 50 trié par gap, matrice de divergence, paire la plus divergente). `BenchmarkResult` expose un nouveau champ optionnel `inter_engine_analysis` ; le runner (`run_benchmark`) collecte les hypothèses brutes par moteur avant `compact()` et calcule l'analyse si ≥ 2 moteurs (sinon `None`). Nouveau `FactType.ENSEMBLE_OPPORTUNITY` (priority 130, importance MEDIUM, HIGH si `relative_gap` ≥ 50 %) avec détecteur `detect_ensemble_opportunity` qui fallback sur `per_engine_recall` quand la divergence taxonomique est absente. Templates FR/EN ajoutés à `narrative/templates/{fr,en}.yaml`. `report_data["inter_engine_analysis"]` exposé pour la consommation par le rapport HTML (matrice de divergence Sprint 37 à venir). +22 tests dans `test_sprint36_ensemble_narrative.py` couvrant l'agrégation, l'exposition `BenchmarkResult.as_dict`, les seuils du détecteur, le fallback paire sans taxonomie, l'intégration `build_synthesis` FR + EN, la traçabilité anti-hallucination (chaque nombre rendu est dans le payload, template sans chiffres en dur). |
@@ -256,7 +257,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1649 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprint 38 = NER couche de calcul)
+- **Tests** : 1681 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38-39 = NER + calibration couches de calcul)
 - **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/calibration.py

@@ -0,0 +1,323 @@
+"""Calibration des moteurs : ECE, MCE, reliability diagram.
+
+Sprint 39 — A.II.1.b du plan d'évolution 2026 : couche de calcul pure.
+
+Pourquoi ce module
+------------------
+Tous les moteurs OCR cibles fournissent une confidence par token ou par
+ligne (Tesseract via le ``tsv``, Pero OCR via le ``PageLayout``,
+Mistral OCR via ``confidence``, Google Vision via ``Word.confidence``).
+La question naturelle pour un workflow patrimonial est : *« quand le
+moteur dit qu'il est sûr, est-il vraiment sûr ? »*.  Pour une équipe
+qui doit vérifier humainement un corpus de 50 000 pages, la différence
+entre vérifier 100 % vs 15 % du volume est l'effet de la calibration.
+
+Ce module fournit les trois mesures classiques :
+
+- **Expected Calibration Error (ECE)** — moyenne pondérée par bin de
+  l'écart absolu entre confiance moyenne et précision moyenne.
+  ``ECE = 0`` ↔ moteur parfaitement calibré ; ``ECE`` élevé ↔ écart
+  systématique entre confiance affichée et fiabilité réelle.
+- **Maximum Calibration Error (MCE)** — max de cet écart sur les bins.
+  Utile pour repérer le pire mensonge du moteur (ex. il dit toujours
+  95 % de confiance et il a tort une fois sur deux).
+- **Reliability diagram** — table ``[(bin_low, bin_high, avg_conf,
+  accuracy, count)]`` qui peut être rendue en SVG côté serveur ou en
+  Chart.js côté navigateur dans un sprint suivant.
+
+Stratégie de découpage
+----------------------
+Comme pour le NER (Sprint 38) et la divergence (Sprints 35-37),
+on découpe :
+
+- **Sprint 39** (ici) — couche de calcul pure : entrée = deux listes
+  parallèles ``confidences`` (∈ [0, 1]) et ``is_correct`` (bool/0-1).
+  Aucune dépendance externe.
+- **Sprint à venir** — exposition de ``token_confidences`` sur
+  ``EngineResult``, alignement caractère/token avec la GT pour produire
+  ``is_correct``, intégration dans le runner et vue HTML reliability.
+
+Ce qui est explicitement hors scope
+-----------------------------------
+Ce sprint ne touche **aucun adaptateur OCR**.  Aucune confiance n'est
+extraite ; on calcule uniquement à partir de séquences de prédictions
+fournies en entrée.  C'est ce qui permet de tester rigoureusement les
+invariants mathématiques (ECE = 0 ↔ calibré, ECE = |bias| pour bias
+constant, etc.) sans dépendre d'un backend.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Iterable
+
+logger = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Modèle de données
+# ──────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class CalibrationBin:
+    """Un bin du reliability diagram.
+
+    Attributs
+    ---------
+    bin_low, bin_high:
+        Bornes du bin sur l'axe de confiance (``[bin_low, bin_high)`` —
+        sauf le dernier bin qui inclut ``1.0``).
+    avg_confidence:
+        Moyenne des confidences des prédictions tombées dans le bin.
+        ``None`` si le bin est vide.
+    accuracy:
+        Fraction de prédictions correctes dans le bin (``∈ [0, 1]``).
+        ``None`` si le bin est vide.
+    count:
+        Nombre de prédictions dans le bin.
+    """
+
+    bin_low: float
+    bin_high: float
+    avg_confidence: float | None
+    accuracy: float | None
+    count: int
+
+    @property
+    def gap(self) -> float | None:
+        """Écart absolu ``|confidence - accuracy|`` ou ``None`` si vide."""
+        if self.avg_confidence is None or self.accuracy is None:
+            return None
+        return abs(self.avg_confidence - self.accuracy)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Validation
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _validate_inputs(
+    confidences: list[float],
+    is_correct: list[bool | int],
+) -> None:
+    if len(confidences) != len(is_correct):
+        raise ValueError(
+            f"Longueurs incompatibles : confidences={len(confidences)} "
+            f"vs is_correct={len(is_correct)}"
+        )
+    for i, c in enumerate(confidences):
+        if not (0.0 <= float(c) <= 1.0):
+            raise ValueError(
+                f"Confiance hors [0, 1] à l'index {i} : {c!r}"
+            )
+
+
+# ──────────────────────────────────────────���───────────────────────────────
+# Reliability diagram (binning)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def reliability_diagram(
+    confidences: Iterable[float],
+    is_correct: Iterable[bool | int],
+    n_bins: int = 10,
+) -> list[CalibrationBin]:
+    """Découpe les prédictions en ``n_bins`` bins équidistants par confiance
+    et calcule pour chacun la confiance moyenne, la précision et le compte.
+
+    Parameters
+    ----------
+    confidences:
+        Confidences des prédictions, ``∈ [0, 1]``.
+    is_correct:
+        Indicateur booléen (1 = prédiction correcte, 0 = incorrecte).
+    n_bins:
+        Nombre de bins (défaut : 10).  Bornes : ``[k/n_bins, (k+1)/n_bins)``
+        sauf le dernier bin qui inclut ``1.0``.
+
+    Returns
+    -------
+    list[CalibrationBin]
+        Liste de ``n_bins`` bins, dans l'ordre croissant des confidences.
+    """
+    if n_bins < 1:
+        raise ValueError(f"n_bins doit être ≥ 1 — reçu {n_bins}")
+
+    confs = [float(c) for c in confidences]
+    correct = [int(bool(x)) for x in is_correct]
+    _validate_inputs(confs, correct)
+
+    bin_width = 1.0 / n_bins
+    sums: list[float] = [0.0] * n_bins
+    correct_counts: list[int] = [0] * n_bins
+    counts: list[int] = [0] * n_bins
+
+    for c, ok in zip(confs, correct):
+        # Calcul du bin index par multiplication ``c * n_bins`` plutôt que
+        # division ``c / bin_width`` pour éviter les pièges de
+        # représentation flottante (ex. ``0.6 / 0.1 = 5.999…`` en IEEE 754
+        # qui placerait 0.6 dans le bin [0.5, 0.6) au lieu de [0.6, 0.7)).
+        if c >= 1.0:
+            idx = n_bins - 1
+        else:
+            idx = int(c * n_bins)
+            # Garde-fou en cas d'arrondi flottant
+            if idx >= n_bins:
+                idx = n_bins - 1
+            elif idx < 0:
+                idx = 0
+        sums[idx] += c
+        correct_counts[idx] += ok
+        counts[idx] += 1
+
+    bins: list[CalibrationBin] = []
+    for k in range(n_bins):
+        low = k * bin_width
+        high = (k + 1) * bin_width
+        n = counts[k]
+        if n == 0:
+            bins.append(CalibrationBin(low, high, None, None, 0))
+        else:
+            bins.append(CalibrationBin(
+                bin_low=low,
+                bin_high=high,
+                avg_confidence=sums[k] / n,
+                accuracy=correct_counts[k] / n,
+                count=n,
+            ))
+    return bins
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# ECE et MCE
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def expected_calibration_error(
+    confidences: Iterable[float],
+    is_correct: Iterable[bool | int],
+    n_bins: int = 10,
+) -> float:
+    """Expected Calibration Error : moyenne pondérée par bin de l'écart
+    absolu confiance ↔ précision.
+
+    ``ECE = sum_k (n_k / N) * |avg_conf_k - accuracy_k|``
+
+    où la somme porte sur les bins non vides.
+
+    Returns
+    -------
+    float
+        ``∈ [0, 1]``.  ``0`` ↔ calibration parfaite.
+    """
+    bins = reliability_diagram(confidences, is_correct, n_bins=n_bins)
+    total = sum(b.count for b in bins)
+    if total == 0:
+        return 0.0
+    ece = 0.0
+    for b in bins:
+        if b.count == 0 or b.gap is None:
+            continue
+        ece += (b.count / total) * b.gap
+    return ece
+
+
+def maximum_calibration_error(
+    confidences: Iterable[float],
+    is_correct: Iterable[bool | int],
+    n_bins: int = 10,
+) -> float:
+    """Maximum Calibration Error : pire écart confiance ↔ précision sur
+    tous les bins non vides.
+
+    Utile pour repérer un mensonge ponctuel du moteur (ex. il dit 95 %
+    de confiance et il a tort une fois sur deux dans ce bin).
+
+    Returns
+    -------
+    float
+        ``∈ [0, 1]``.  ``0`` ↔ calibration parfaite.
+    """
+    bins = reliability_diagram(confidences, is_correct, n_bins=n_bins)
+    gaps = [b.gap for b in bins if b.gap is not None]
+    return max(gaps) if gaps else 0.0
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Vue agrégée
+# ──────────────────────────────────────────────────────────────────────��───
+
+
+def compute_calibration_metrics(
+    confidences: Iterable[float],
+    is_correct: Iterable[bool | int],
+    n_bins: int = 10,
+) -> dict:
+    """Calcule l'ensemble des métriques de calibration en un appel.
+
+    Returns
+    -------
+    dict
+        ``{
+            "ece":   float,
+            "mce":   float,
+            "n_bins": int,
+            "n_predictions": int,
+            "overall_accuracy": float,
+            "overall_confidence": float,
+            "bins": [
+                {"bin_low", "bin_high", "avg_confidence",
+                 "accuracy", "count", "gap"},
+                ...
+            ],
+        }``
+    """
+    confs = list(confidences)
+    correct = list(is_correct)
+    bins = reliability_diagram(confs, correct, n_bins=n_bins)
+    total = sum(b.count for b in bins)
+    overall_acc = (
+        sum(int(bool(x)) for x in correct) / total if total > 0 else 0.0
+    )
+    overall_conf = (
+        sum(float(c) for c in confs) / total if total > 0 else 0.0
+    )
+
+    ece = 0.0
+    if total > 0:
+        for b in bins:
+            if b.gap is None:
+                continue
+            ece += (b.count / total) * b.gap
+    mce = max((b.gap for b in bins if b.gap is not None), default=0.0)
+
+    return {
+        "ece": ece,
+        "mce": mce,
+        "n_bins": n_bins,
+        "n_predictions": total,
+        "overall_accuracy": overall_acc,
+        "overall_confidence": overall_conf,
+        "bins": [
+            {
+                "bin_low": b.bin_low,
+                "bin_high": b.bin_high,
+                "avg_confidence": b.avg_confidence,
+                "accuracy": b.accuracy,
+                "count": b.count,
+                "gap": b.gap,
+            }
+            for b in bins
+        ],
+    }
+
+
+__all__ = [
+    "CalibrationBin",
+    "reliability_diagram",
+    "expected_calibration_error",
+    "maximum_calibration_error",
+    "compute_calibration_metrics",
+]

tests/test_sprint39_calibration.py

@@ -0,0 +1,310 @@
+"""Tests Sprint 39 — métriques de calibration (ECE, MCE, reliability).
+
+Le module ``picarones.core.calibration`` expose :
+
+- ``CalibrationBin`` : un bin du reliability diagram
+- ``reliability_diagram(confidences, is_correct, n_bins=10)``
+- ``expected_calibration_error`` (ECE)
+- ``maximum_calibration_error`` (MCE)
+- ``compute_calibration_metrics`` : vue agrégée
+
+Les tests vérifient :
+
+1. **Calibration parfaite** : confidences uniformes égales à la précision
+   du bin → ECE = MCE = 0.
+2. **Sur-confiance extrême** : confidence = 1.0 mais 50 % correct →
+   ECE = 0.5 et MCE = 0.5.
+3. **Sous-confiance extrême** : confidence = 0.5 mais 100 % correct →
+   ECE = 0.5.
+4. **Calibration constante** : confidence = c, accuracy = a → ECE = |c-a|.
+5. **Reliability diagram** : binning correct, bornes correctes,
+   bin 1.0 inclus dans le dernier bin.
+6. **Bins vides** correctement gérés (avg_confidence/accuracy = None,
+   count = 0, gap = None).
+7. **Listes vides** → ECE = 0, MCE = 0.
+8. **Garde-fous** : longueurs incompatibles → ValueError ;
+   confidence hors [0, 1] → ValueError ; n_bins < 1 → ValueError.
+9. **n_bins paramétrable** : 5 bins vs 20 bins, bornes adaptées.
+10. **compute_calibration_metrics** : structure de retour complète et
+    cohérente avec les fonctions individuelles.
+11. **CalibrationBin.gap** : comportement attendu (None pour bin vide).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.core.calibration import (
+    CalibrationBin,
+    compute_calibration_metrics,
+    expected_calibration_error,
+    maximum_calibration_error,
+    reliability_diagram,
+)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. Calibration parfaite
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestPerfectCalibration:
+    def test_uniform_confidence_matching_accuracy_per_bin(self) -> None:
+        """Toutes les prédictions à confidence 0.75, 75 % correctes.
+        Le seul bin non vide est [0.7, 0.8) avec gap = 0.
+        """
+        confs = [0.75] * 100
+        correct = [1] * 75 + [0] * 25
+        assert expected_calibration_error(confs, correct) == pytest.approx(0.0, abs=1e-9)
+        assert maximum_calibration_error(confs, correct) == pytest.approx(0.0, abs=1e-9)
+
+    def test_two_bins_each_perfectly_calibrated(self) -> None:
+        # Bin [0.2, 0.3) : 25 % correct, 25 % conf
+        # Bin [0.8, 0.9) : 85 % correct, 85 % conf
+        confs = [0.25] * 100 + [0.85] * 100
+        correct = [1] * 25 + [0] * 75 + [1] * 85 + [0] * 15
+        assert expected_calibration_error(confs, correct) == pytest.approx(0.0, abs=1e-9)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2-3. Cas extrêmes
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestExtremeCases:
+    def test_extreme_overconfidence(self) -> None:
+        # Le moteur dit "100 % sûr" mais a tort une fois sur deux
+        confs = [1.0] * 10
+        correct = [1] * 5 + [0] * 5
+        assert expected_calibration_error(confs, correct) == pytest.approx(0.5)
+        assert maximum_calibration_error(confs, correct) == pytest.approx(0.5)
+
+    def test_extreme_underconfidence(self) -> None:
+        # Le moteur dit "50 % sûr" mais a toujours raison
+        confs = [0.5] * 10
+        correct = [1] * 10
+        assert expected_calibration_error(confs, correct) == pytest.approx(0.5)
+        assert maximum_calibration_error(confs, correct) == pytest.approx(0.5)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4. Calibration constante (gap = |c - a|)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestConstantBias:
+    @pytest.mark.parametrize("conf,acc", [(0.6, 0.4), (0.3, 0.7), (0.95, 0.85)])
+    def test_constant_bias_is_absolute_gap(
+        self, conf: float, acc: float
+    ) -> None:
+        """Avec un seul bin non vide, ECE = |conf - acc|."""
+        n = 100
+        confs = [conf] * n
+        n_correct = int(round(acc * n))
+        correct = [1] * n_correct + [0] * (n - n_correct)
+        ece = expected_calibration_error(confs, correct)
+        # acc effective = n_correct/n (peut différer légèrement de acc cible
+        # par arrondi entier)
+        actual_acc = n_correct / n
+        assert ece == pytest.approx(abs(conf - actual_acc), abs=1e-9)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 5. Reliability diagram — binning
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestReliabilityDiagramBinning:
+    def test_default_returns_10_bins(self) -> None:
+        bins = reliability_diagram([0.5], [1])
+        assert len(bins) == 10
+
+    def test_bin_bounds_are_equidistant(self) -> None:
+        bins = reliability_diagram([], [], n_bins=5)
+        widths = [b.bin_high - b.bin_low for b in bins]
+        for w in widths:
+            assert w == pytest.approx(0.2, abs=1e-9)
+        assert bins[0].bin_low == pytest.approx(0.0)
+        assert bins[-1].bin_high == pytest.approx(1.0)
+
+    def test_confidence_1_falls_in_last_bin(self) -> None:
+        bins = reliability_diagram([1.0, 1.0, 1.0], [1, 0, 1], n_bins=10)
+        # Toutes les prédictions doivent être dans le dernier bin
+        assert bins[-1].count == 3
+        assert sum(b.count for b in bins[:-1]) == 0
+
+    def test_predictions_assigned_to_correct_bin(self) -> None:
+        bins = reliability_diagram(
+            [0.05, 0.15, 0.55, 0.95],
+            [0, 1, 1, 0],
+            n_bins=10,
+        )
+        # bin [0.0, 0.1) → 1 prédiction
+        assert bins[0].count == 1
+        # bin [0.1, 0.2) → 1
+        assert bins[1].count == 1
+        # bin [0.5, 0.6) → 1
+        assert bins[5].count == 1
+        # bin [0.9, 1.0] → 1
+        assert bins[9].count == 1
+
+    def test_avg_confidence_and_accuracy_per_bin(self) -> None:
+        # Bin [0.6, 0.7) : confidences 0.6, 0.65 ; correct 1, 0
+        bins = reliability_diagram([0.6, 0.65], [1, 0], n_bins=10)
+        b6 = bins[6]
+        assert b6.count == 2
+        assert b6.avg_confidence == pytest.approx((0.6 + 0.65) / 2)
+        assert b6.accuracy == pytest.approx(0.5)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 6. Bins vides
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestEmptyBins:
+    def test_empty_bin_has_none_avg_and_accuracy(self) -> None:
+        bins = reliability_diagram([0.95], [1], n_bins=10)
+        # Tous les bins sauf le dernier sont vides
+        for b in bins[:-1]:
+            assert b.count == 0
+            assert b.avg_confidence is None
+            assert b.accuracy is None
+            assert b.gap is None
+
+    def test_ece_skips_empty_bins(self) -> None:
+        # Avec un seul bin non vide à gap 0, ECE doit être 0
+        bins = reliability_diagram([0.55] * 10, [1] * 6 + [0] * 4)
+        assert expected_calibration_error([0.55] * 10, [1] * 6 + [0] * 4) == \
+            pytest.approx(0.05)
+        # Confirmer que beaucoup de bins sont vides
+        empty = [b for b in bins if b.count == 0]
+        assert len(empty) == 9
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 7. Listes vides
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestEmptyInputs:
+    def test_empty_lists_return_zero(self) -> None:
+        assert expected_calibration_error([], []) == 0.0
+        assert maximum_calibration_error([], []) == 0.0
+
+    def test_empty_reliability_diagram(self) -> None:
+        bins = reliability_diagram([], [], n_bins=10)
+        assert len(bins) == 10
+        assert all(b.count == 0 for b in bins)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 8. Garde-fous
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestGuards:
+    def test_length_mismatch_raises(self) -> None:
+        with pytest.raises(ValueError, match="Longueurs"):
+            expected_calibration_error([0.5, 0.5], [1])
+
+    def test_confidence_above_one_raises(self) -> None:
+        with pytest.raises(ValueError, match="hors"):
+            expected_calibration_error([1.5], [1])
+
+    def test_negative_confidence_raises(self) -> None:
+        with pytest.raises(ValueError, match="hors"):
+            expected_calibration_error([-0.1], [1])
+
+    def test_invalid_n_bins_raises(self) -> None:
+        with pytest.raises(ValueError, match="n_bins"):
+            reliability_diagram([0.5], [1], n_bins=0)
+
+    def test_n_bins_negative_raises(self) -> None:
+        with pytest.raises(ValueError, match="n_bins"):
+            reliability_diagram([0.5], [1], n_bins=-3)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 9. n_bins paramétrable
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestVariableNBins:
+    @pytest.mark.parametrize("n_bins,expected_width", [
+        (5, 0.2), (10, 0.1), (20, 0.05), (1, 1.0),
+    ])
+    def test_bin_width_scales_with_n_bins(
+        self, n_bins: int, expected_width: float
+    ) -> None:
+        bins = reliability_diagram([], [], n_bins=n_bins)
+        assert len(bins) == n_bins
+        for b in bins:
+            assert (b.bin_high - b.bin_low) == pytest.approx(expected_width)
+
+    def test_finer_bins_can_only_increase_or_keep_ece(self) -> None:
+        """À distribution donnée, n_bins plus grand révèle des écarts
+        masqués par un binning grossier — ECE ne décroît pas."""
+        confs = [0.6, 0.65, 0.7, 0.95, 0.95]
+        correct = [1, 0, 1, 1, 0]
+        ece_5 = expected_calibration_error(confs, correct, n_bins=5)
+        ece_20 = expected_calibration_error(confs, correct, n_bins=20)
+        assert ece_20 >= ece_5 - 1e-9
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 10. compute_calibration_metrics
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestComputeCalibrationMetrics:
+    def test_returns_full_structure(self) -> None:
+        confs = [0.6, 0.7, 0.95, 0.95]
+        correct = [1, 0, 1, 1]
+        out = compute_calibration_metrics(confs, correct, n_bins=10)
+        assert set(out.keys()) >= {
+            "ece", "mce", "n_bins", "n_predictions",
+            "overall_accuracy", "overall_confidence", "bins",
+        }
+        assert out["n_predictions"] == 4
+        assert out["overall_accuracy"] == pytest.approx(3 / 4)
+        assert out["overall_confidence"] == pytest.approx((0.6 + 0.7 + 0.95 + 0.95) / 4)
+        assert len(out["bins"]) == 10
+
+    def test_ece_matches_function(self) -> None:
+        confs = [0.55, 0.65, 0.75, 0.85, 0.95]
+        correct = [1, 0, 1, 0, 1]
+        out = compute_calibration_metrics(confs, correct)
+        assert out["ece"] == pytest.approx(
+            expected_calibration_error(confs, correct), abs=1e-9
+        )
+        assert out["mce"] == pytest.approx(
+            maximum_calibration_error(confs, correct), abs=1e-9
+        )
+
+    def test_bin_dicts_contain_gap(self) -> None:
+        out = compute_calibration_metrics([0.55] * 4, [1, 1, 0, 1])
+        # Bin [0.5, 0.6) : avg_conf = 0.55, accuracy = 0.75, gap = 0.20
+        b5 = out["bins"][5]
+        assert b5["count"] == 4
+        assert b5["gap"] == pytest.approx(0.20, abs=1e-9)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 11. CalibrationBin.gap
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestCalibrationBinGap:
+    def test_gap_for_empty_bin_is_none(self) -> None:
+        b = CalibrationBin(0.0, 0.1, None, None, 0)
+        assert b.gap is None
+
+    def test_gap_is_absolute_difference(self) -> None:
+        b = CalibrationBin(0.5, 0.6, 0.55, 0.30, 10)
+        assert b.gap == pytest.approx(0.25)
+
+    def test_gap_symmetric(self) -> None:
+        b1 = CalibrationBin(0.5, 0.6, 0.55, 0.30, 10)
+        b2 = CalibrationBin(0.5, 0.6, 0.30, 0.55, 10)
+        assert b1.gap == pytest.approx(b2.gap)