sprint49: Mistral OCR — exposition des token_confidences quand disponibles

Suite des Sprints 47 (Tesseract) et 48 (Pero OCR). Mistral OCR a deux
chemins : endpoint dédié /v1/ocr (modèle mistral-ocr-latest) qui peut
exposer des champs confidence à différents niveaux, et API chat/vision
(pixtral-*) qui ne fournit pas de confidences.

Refactor signatures
- _run_ocr_with_response(image_path) → (text, raw_response). Centralise
les deux chemins.
- _run_ocr_native_api retourne maintenant (text, raw_response_dict)
au lieu de juste text.
- _run_ocr reste rétrocompat : appelle _run_ocr_with_response et
retourne uniquement le texte.
- Le chemin chat/vision (pixtral) retourne (text, None) car aucune
confidence n'est disponible.

Extraction des confidences
- _extract_token_confidences_from_response parse la réponse en
cascade :
1. pages[i].words[j] avec {"text", "confidence"} → extraction
directe
2. pages[i].lines[j] avec {"text", "confidence"} → propagation à
chaque mot (pattern Pero Sprint 48)
3. pages[i].blocks[j] → idem
- Filtrage cohérent avec Tesseract/Pero : texte vide, conf None,
conf négative ignorés.
- Si aucune confidence exploitable n'est trouvée (markdown brut),
retourne None.
- Flag config expose_confidences: false cohérent avec les autres
adapters.

run() surcharge BaseOCREngine.run() pour intégrer l'extraction des
confidences. L'API est appelée une seule fois — aucun overhead
supplémentaire.

Régression corrigée
- tests/test_sprint6_web_interface : test
test_mistral_ocr_latest_routes_to_native_api utilisait un mock qui
retournait juste un string ; mis à jour pour la nouvelle signature
(text, dict).

Tests : +17 dans test_sprint49_mistral_confidences.py couvrant :
- extraction des trois niveaux (words explicites, lines/blocks
propagés)
- combinaison words + lines
- filtrage texte vide / conf None / négative
- cas dégénérés (None, dict vide, pas de pages, markdown sans
confidences, types invalides)
- flag expose_confidences=False
- surcharge run() avec mock du chemin réseau (chat/vision sans
confidences, échec API)
- intégration runner avec calibration_metrics correctement calculée
Suite complète : 1887 → 1904 passed, 2 skipped, 0 failed.

Reste à adapter Google Vision et Azure DI sur le même pattern.

CHANGELOG.md

@@ -16,6 +16,41 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 49 — Adapter Mistral OCR : exposition des
+  `token_confidences` quand l'API les fournit.** Suite des Sprints
+  47 (Tesseract) et 48 (Pero OCR). Mistral OCR a deux chemins :
+  l'endpoint dédié `/v1/ocr` (modèle `mistral-ocr-latest`) qui peut
+  exposer des champs `confidence` à différents niveaux, et l'API
+  chat/vision (`pixtral-*`) qui ne fournit pas de confidences.
+  - Refactor : nouvelle méthode `_run_ocr_with_response(image_path)`
+    retourne `(text, raw_response)`. `_run_ocr_native_api` retourne
+    désormais aussi le JSON brut. Le chemin chat/vision retourne
+    `(text, None)` car aucune confidence n'est disponible.
+  - `_extract_token_confidences_from_response` parse la réponse
+    `/v1/ocr` en cascade :
+    1. `pages[i].words[j]` avec `{"text", "confidence"}` →
+       extraction directe
+    2. `pages[i].lines[j]` avec `{"text", "confidence"}` →
+       propagation de la confidence à chaque mot (pattern Pero
+       Sprint 48)
+    3. `pages[i].blocks[j]` → idem
+  - Filtrage cohérent avec Tesseract/Pero : texte vide, confidence
+    None, confidence négative → ignorés.
+  - Si l'API ne retourne aucun champ `confidence` exploitable
+    (cas courant si Mistral retourne uniquement du markdown), ou si
+    on est sur le chemin chat/vision, `token_confidences = None`.
+  - Nouveau paramètre config `expose_confidences: false` cohérent
+    avec les autres adapters.
+  - L'API est appelée **une seule fois** ; le coût est strictement
+    identique à l'implémentation historique.
+  - +17 tests dans `test_sprint49_mistral_confidences.py` couvrant
+    l'extraction (words explicites, propagation lines/blocks,
+    combinaison, filtrage texte vide / conf None / négative), les
+    cas dégénérés (None, dict vide, pas de pages, markdown sans
+    confidences, types invalides), le flag `expose_confidences=False`,
+    la surcharge `run()` (mock du chemin réseau, chat/vision sans
+    confidences, échec API), et l'intégration runner.
+
 - **Sprint 48 — Adapter Pero OCR : exposition des `token_confidences`
   natifs.** Suite directe du Sprint 47 (Tesseract). Pero OCR fournit
   une confidence par ligne (``transcription_confidence``, probabilité
@@ -541,17 +576,18 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1887 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
+- 1478 → 1904 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
   +27 Sprint 35, +22 Sprint 36, +42 Sprint 37, +19 Sprint 38,
   +32 Sprint 39, +16 Sprint 40, +38 Sprint 41, +17 Sprint 42,
   +43 Sprint 43, +15 Sprint 44, +16 Sprint 45, +38 Sprint 46,
-  +9 Sprint 47, +14 Sprint 48). Aucune régression. **Phase 0
-  close ; Étape 2 du plan d'évolution : inter-moteurs (A.II.1.c),
-  NER (A.II.1.a), calibration (A.II.1.b) et stratification (A.III)
-  livrés bout-en-bout calcul → runner → HTML ; A.I.2 médiane par
-  défaut livré (Sprint 44) ; Tesseract (Sprint 47) et Pero OCR
-  (Sprint 48) adaptés pour exposer leurs `token_confidences`
-  natifs. Reste à adapter Mistral OCR, Google Vision et Azure DI.**
+  +9 Sprint 47, +14 Sprint 48, +17 Sprint 49). Aucune régression.
+  **Phase 0 close ; Étape 2 du plan d'évolution : inter-moteurs
+  (A.II.1.c), NER (A.II.1.a), calibration (A.II.1.b) et
+  stratification (A.III) livrés bout-en-bout calcul → runner →
+  HTML ; A.I.2 médiane par défaut livré (Sprint 44) ; Tesseract
+  (Sprint 47), Pero OCR (Sprint 48) et Mistral OCR (Sprint 49)
+  adaptés pour exposer leurs `token_confidences` natifs. Reste à
+  adapter Google Vision et Azure DI.**
 
 ---
 

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). |
+| 49 | **Sprint 18 du plan d'évolution 2026 — Étape 2 / adaptation engines : Mistral OCR expose ses `token_confidences` quand disponibles**. Mistral OCR a deux chemins : endpoint dédié `/v1/ocr` (qui peut exposer des `confidence` au niveau page/block/line/word selon le modèle) et API chat/vision (`pixtral-*`, sans confidences). Refactor : `_run_ocr_with_response(image_path) → (text, raw_response)` centralise les deux chemins. `_extract_token_confidences_from_response` parse la réponse en cascade — words explicites d'abord, puis propagation depuis lines/blocks (pattern Pero Sprint 48). Filtrage cohérent avec Tesseract/Pero (texte vide, conf None, conf négative ignorés). Si la réponse ne contient aucune confidence exploitable (markdown brut) ou si on est sur chat/vision, `token_confidences = None`. Flag `expose_confidences: false`. L'API est appelée une seule fois — coût identique à l'implémentation historique. +17 tests dans `test_sprint49_mistral_confidences.py` (extraction des trois niveaux, combinaison words+lines, cas dégénérés sur 5 cas, flag, surcharge `run()` avec mocks, chat/vision, échec API, intégration runner). **Verrou levé** : un benchmark Mistral OCR produit automatiquement ECE/MCE/reliability quand l'API expose ses confidences. Reste Google Vision et Azure DI à adapter. |
 | 48 | **Sprint 17 du plan d'évolution 2026 — Étape 2 / adaptation engines : Pero OCR expose ses `token_confidences` natifs**. Suite directe du Sprint 47 (Tesseract). Pero fournit ``line.transcription_confidence`` (probabilité CTC moyenne par ligne) ; l'adapter la propage à chaque mot de la ligne. ``PeroOCREngine.run()`` est surchargé avec un seul appel ``parser.process_page`` qui produit le ``page_layout`` ; texte ET confidences en sont extraits sans coût supplémentaire (vs Tesseract qui doit faire deux appels distincts). Refactor : ``_run_pero_pipeline(image_path) → (text, page_layout)`` centralise l'appel ; ``_run_ocr`` devient un wrapper trivial pour rétrocompat. ``_extract_token_confidences_from_layout`` parcourt regions/lines, applique ``transcription_confidence`` à chaque mot, ignore transcription vide / conf None / conf négative, retourne ``None`` si aucune ligne n'avait de confidence exploitable. Flag ``expose_confidences: false`` cohérent avec Tesseract. +14 tests dans ``test_sprint48_pero_confidences.py`` (extraction layout, multi-lignes, cas dégénérés, surcharge run avec mocks, intégration runner, fallback Pero absent). **Verrou levé** : un benchmark Pero OCR produit désormais automatiquement ECE/MCE et reliability diagram dans le rapport, sans configuration. Reste Mistral OCR, Google Vision et Azure DI à adapter. |
 | 47 | **Sprint 16 du plan d'évolution 2026 — Étape 2 / adaptation engines : Tesseract expose ses `token_confidences` natifs**. Premier des engines adaptés au câblage calibration du Sprint 42. `TesseractEngine.run()` est surchargé : appelle `image_to_string` pour le texte (rétrocompat octet par octet) **et** `image_to_data` pour les confidences mot par mot, retourne un `EngineResult` avec `token_confidences = [{"token": str, "confidence": float}, …]` (confidence ∈ [0, 100], le runner Sprint 42 normalise en [0, 1]). Helper `_extract_token_confidences` séparé : si `image_to_data` lève, l'OCR continue et `token_confidences = None` (warning explicite). Filtrage à la source des non-mots Tesseract (conf = -1), tokens vides, longueurs incompatibles. Nouveau paramètre config `expose_confidences: false` pour désactiver le second appel. Coût additionnel : un appel `image_to_data` par image — le texte d'`image_to_string` n'est jamais reconstruit depuis `image_to_data` (préservation stricte du comportement historique). +9 tests dans `test_sprint47_tesseract_confidences.py` (mock pytesseract, exposition, rétrocompat texte, flag `expose_confidences=False`, fallback gracieux, filtrage, intégration runner). **Verrou levé** : un benchmark Tesseract produit désormais automatiquement ECE/MCE/reliability diagram dans le rapport, sans configuration. Reste Pero, Mistral OCR, Google Vision, Azure DI à adapter. |
 | 46 | **Sprint 15 du plan d'évolution 2026 — Étape 2 / axe A.III : vue HTML stratifiée + détecteur narratif (clôture A.III)**. Suite directe du Sprint 45 (couche backend). Nouveau module `picarones/report/stratification_render.py` : `build_stratified_ranking_html` rend un `<details>` natif (collapsible sans JS) par strate avec tableau moteur × (médiane, moyenne, docs), cellule médiane colorée par gradient vert→rouge, premier `<details>` ouvert par défaut, bandeau d'avertissement en tête si `corpus_homogeneity` fourni. `_build_report_data` expose `available_strata`/`stratified_ranking`/`corpus_homogeneity` au top-level ; `view_ranking.html` insère le bloc après le tableau principal **uniquement si stratification disponible**. Nouveau `FactType.STRATIFICATION_RECOMMENDED` (priority 45, importance MEDIUM ou HIGH selon le gap) + détecteur `detect_stratification_recommended` (seuil 5 points / 10 points de CER inter-strate). Templates FR/EN sans nombres en dur. L'arbitre marque la paire `{GLOBAL_LEADER_CER, STRATIFICATION_RECOMMENDED}` comme complémentaire. +8 clés i18n FR/EN. Anti-injection HTML via `html.escape`. +38 tests dans `test_sprint46_stratification_html.py`. **Verrou levé** : A.III (stratification) est désormais livré bout-en-bout — couche backend (Sprint 45) + vue HTML + détecteur narratif (Sprint 46) ; le lecteur du rapport voit immédiatement quand le corpus est hétérogène et est invité à consulter la vue stratifiée. |
@@ -266,7 +267,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1887 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38+40+41 = NER livré bout-en-bout ; Sprints 39+42+43 = calibration livrée bout-en-bout côté rapport ; Sprint 44 = médiane par défaut ; Sprints 45+46 = stratification A.III livrée bout-en-bout ; Sprints 47+48 = Tesseract et Pero OCR adaptés pour confidences natives)
+- **Tests** : 1904 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38+40+41 = NER livré bout-en-bout ; Sprints 39+42+43 = calibration livrée bout-en-bout côté rapport ; Sprint 44 = médiane par défaut ; Sprints 45+46 = stratification A.III livrée bout-en-bout ; Sprints 47+48+49 = Tesseract, Pero OCR et Mistral OCR adaptés pour confidences natives)
 - **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/engines/mistral_ocr.py

@@ -6,16 +6,31 @@ patrimoniaux via le modèle multimodal Mistral.
 Clé API : variable d'environnement ``MISTRAL_API_KEY``.
 
 Documentation API : https://docs.mistral.ai/
+
+Sprint 49 — exposition des token_confidences
+---------------------------------------------
+L'API ``/v1/ocr`` peut renvoyer des champs ``confidence`` au niveau
+page, block, line ou word selon le modèle.  L'adapter parse la réponse
+brute (``raw_response``) en plus du markdown : il cherche
+récursivement les paires ``(text, confidence)`` exploitables et les
+retourne au format Sprint 42.  Si la réponse ne contient aucun champ
+de confidence (cas de l'API chat/vision pour ``pixtral-*``),
+``token_confidences = None``.
 """
 
 from __future__ import annotations
 
 import base64
+import logging
 import os
+import time
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
+
+from picarones.engines.base import BaseOCREngine, EngineResult
+
 
-from picarones.engines.base import BaseOCREngine
+logger = logging.getLogger(__name__)
 
 
 class MistralOCREngine(BaseOCREngine):
@@ -31,6 +46,10 @@ class MistralOCREngine(BaseOCREngine):
         Prompt envoyé avec l'image. Défaut : instruction générique de transcription.
     max_tokens : int
         Limite de tokens en sortie (défaut : 4096).
+    expose_confidences : bool
+        ``True`` (défaut) : extrait les ``confidence`` de la réponse
+        ``/v1/ocr`` quand elles sont présentes (Sprint 49). ``False`` :
+        désactive complètement l'extraction.
     """
 
     @property
@@ -52,6 +71,20 @@ class MistralOCREngine(BaseOCREngine):
         self._max_tokens = int(self.config.get("max_tokens", 4096))
 
     def _run_ocr(self, image_path: Path) -> str:
+        """API rétrocompat : retourne uniquement le texte."""
+        text, _raw = self._run_ocr_with_response(image_path)
+        return text
+
+    def _run_ocr_with_response(
+        self, image_path: Path,
+    ) -> tuple[str, Optional[dict]]:
+        """Exécute l'OCR et retourne ``(text, raw_response)``.
+
+        ``raw_response`` est le JSON brut de l'API ``/v1/ocr`` (chemin
+        natif) ou ``None`` (chemin chat/vision pour ``pixtral-*``).
+        Centralisé pour que ``run()`` puisse extraire les
+        ``token_confidences`` sans dupliquer la requête API.
+        """
         if not self._api_key:
             raise RuntimeError(
                 "Clé API Mistral manquante — définissez la variable d'environnement MISTRAL_API_KEY"
@@ -69,10 +102,14 @@ class MistralOCREngine(BaseOCREngine):
 
         if "mistral-ocr" in self._model.lower():
             return self._run_ocr_native_api(image_url)
-        return self._run_ocr_vision_api(image_url)
+        return self._run_ocr_vision_api(image_url), None
+
+    def _run_ocr_native_api(self, image_url: str) -> tuple[str, dict]:
+        """Endpoint dédié /v1/ocr (pour mistral-ocr-latest et variantes).
 
-    def _run_ocr_native_api(self, image_url: str) -> str:
-        """Endpoint dédié /v1/ocr (pour mistral-ocr-latest et variantes)."""
+        Retourne ``(text, raw_response_dict)`` pour permettre
+        l'extraction des confidences en post-traitement.
+        """
         import json
         import urllib.request
 
@@ -92,7 +129,8 @@ class MistralOCREngine(BaseOCREngine):
         with urllib.request.urlopen(req, timeout=60) as resp:
             data = json.loads(resp.read().decode())
         pages = data.get("pages", [])
-        return "\n\n".join(p.get("markdown", "") for p in pages).strip()
+        text = "\n\n".join(p.get("markdown", "") for p in pages).strip()
+        return text, data
 
     def _run_ocr_vision_api(self, image_url: str) -> str:
         """API vision/chat Mistral (pour pixtral-12b, pixtral-large, etc.)."""
@@ -121,3 +159,128 @@ class MistralOCREngine(BaseOCREngine):
             max_tokens=self._max_tokens,
         )
         return response.choices[0].message.content or ""
+
+    def _extract_token_confidences_from_response(
+        self, raw_response: Optional[dict],
+    ) -> Optional[list[dict[str, Any]]]:
+        """Extrait les paires ``(token, confidence)`` de la réponse
+        ``/v1/ocr`` quand elles existent.
+
+        Mistral OCR peut exposer ``confidence`` à différents niveaux
+        (page, block, line, word) selon le modèle.  L'extracteur
+        cherche dans les structures suivantes en cascade :
+
+        1. ``pages[i].words[j]`` avec ``{"text", "confidence"}``
+        2. ``pages[i].lines[j]`` avec ``{"text", "confidence"}`` →
+           propage la confidence aux mots de la ligne (comme Pero OCR
+           Sprint 48)
+        3. ``pages[i].blocks[j]`` avec ``{"text", "confidence"}`` →
+           idem, propage à chaque mot
+
+        Retourne ``None`` si aucun champ ``confidence`` exploitable
+        n'est trouvé (cas le plus courant si l'API renvoie uniquement
+        du markdown sans annotation, ou si on est sur le chemin
+        chat/vision ``pixtral-*``).
+
+        Les exceptions sont absorbées en warning (best-effort).
+        """
+        if not self.config.get("expose_confidences", True):
+            return None
+        if not raw_response or not isinstance(raw_response, dict):
+            return None
+        try:
+            out: list[dict[str, Any]] = []
+            pages = raw_response.get("pages") or []
+            for page in pages:
+                if not isinstance(page, dict):
+                    continue
+                # Niveau 1 : words explicites
+                words = page.get("words") or []
+                for w in words:
+                    self._maybe_emit_word(w, out)
+                # Niveau 2 : lines avec confidence propagée
+                lines = page.get("lines") or []
+                for line in lines:
+                    self._emit_lines_or_blocks(line, out)
+                # Niveau 3 : blocks avec confidence propagée
+                blocks = page.get("blocks") or []
+                for block in blocks:
+                    self._emit_lines_or_blocks(block, out)
+            return out or None
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "[mistral_ocr] extraction des token_confidences dégradée : %s",
+                exc,
+            )
+            return None
+
+    @staticmethod
+    def _maybe_emit_word(word: Any, out: list) -> None:
+        if not isinstance(word, dict):
+            return
+        text = (word.get("text") or "").strip()
+        conf = word.get("confidence")
+        if not text or conf is None:
+            return
+        try:
+            conf_val = float(conf)
+        except (TypeError, ValueError):
+            return
+        if conf_val < 0:
+            return
+        out.append({"token": text, "confidence": conf_val})
+
+    @staticmethod
+    def _emit_lines_or_blocks(item: Any, out: list) -> None:
+        """Pour une line/block, propage sa confidence à chaque mot."""
+        if not isinstance(item, dict):
+            return
+        text = (item.get("text") or "").strip()
+        conf = item.get("confidence")
+        if not text or conf is None:
+            return
+        try:
+            conf_val = float(conf)
+        except (TypeError, ValueError):
+            return
+        if conf_val < 0:
+            return
+        for word in text.split():
+            if word:
+                out.append({"token": word, "confidence": conf_val})
+
+    def run(self, image_path: str | Path) -> EngineResult:
+        """Exécute Mistral OCR et expose les ``token_confidences``
+        natifs (Sprint 49).
+
+        L'API ``/v1/ocr`` est appelée une seule fois ; le texte et la
+        réponse brute sont récupérés ensemble. Si la réponse expose
+        des ``confidence`` (par mot/ligne/block), elles sont extraites
+        au format Sprint 42.  Sinon ``token_confidences = None``.
+
+        Le chemin chat/vision (``pixtral-*``) ne fournit pas de
+        confidences ; ``token_confidences`` y est toujours ``None``.
+        """
+        image_path = Path(image_path)
+        start = time.perf_counter()
+        text = ""
+        error: Optional[str] = None
+        token_confidences: Optional[list[dict[str, Any]]] = None
+        try:
+            text, raw_response = self._run_ocr_with_response(image_path)
+        except Exception as exc:  # noqa: BLE001
+            error = str(exc)
+        else:
+            token_confidences = self._extract_token_confidences_from_response(
+                raw_response,
+            )
+        duration = time.perf_counter() - start
+        return EngineResult(
+            engine_name=self.name,
+            image_path=str(image_path),
+            text=text,
+            duration_seconds=round(duration, 4),
+            error=error,
+            metadata={"engine_version": self._safe_version()},
+            token_confidences=token_confidences,
+        )

tests/test_sprint49_mistral_confidences.py

@@ -0,0 +1,301 @@
+"""Tests Sprint 49 — adaptation Mistral OCR pour exposer token_confidences.
+
+Couvre :
+
+1. ``_extract_token_confidences_from_response`` :
+   - extrait les words explicites avec ``{"text", "confidence"}``
+   - propage la confidence d'une ligne / bloc à chaque mot
+   - ignore les entrées sans confidence ou avec confidence négative
+2. Réponse vide / None / sans pages → retourne ``None``.
+3. ``expose_confidences=False`` désactive l'extraction.
+4. ``run()`` appelle ``_run_ocr_with_response`` et stocke les
+   confidences dans ``EngineResult.token_confidences``.
+5. Le chemin chat/vision (``pixtral-*``) renvoie
+   ``raw_response = None`` → ``token_confidences = None``.
+6. Si l'API échoue, ``error`` renseigné, ``text=""``,
+   ``token_confidences = None``.
+7. Intégration bout-en-bout avec ``_compute_document_result``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from picarones.engines.mistral_ocr import MistralOCREngine
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. Extraction depuis une réponse JSON Mistral
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestExtractFromResponse:
+    def test_extract_words_explicit(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "words": [
+                    {"text": "Bonjour", "confidence": 0.95},
+                    {"text": "monde",   "confidence": 0.90},
+                ],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out == [
+            {"token": "Bonjour", "confidence": 0.95},
+            {"token": "monde",   "confidence": 0.90},
+        ]
+
+    def test_lines_propagate_confidence_to_words(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "lines": [
+                    {"text": "première ligne", "confidence": 0.88},
+                    {"text": "seconde",        "confidence": 0.75},
+                ],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out is not None
+        # 3 tokens (2 mots + 1 mot), avec leurs confidences respectives
+        assert {"token": "première", "confidence": 0.88} in out
+        assert {"token": "ligne",    "confidence": 0.88} in out
+        assert {"token": "seconde",  "confidence": 0.75} in out
+
+    def test_blocks_propagate_confidence(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "blocks": [
+                    {"text": "bloc1 mot2", "confidence": 0.82},
+                ],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out == [
+            {"token": "bloc1", "confidence": 0.82},
+            {"token": "mot2",  "confidence": 0.82},
+        ]
+
+    def test_skips_empty_text(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "words": [
+                    {"text": "", "confidence": 0.9},
+                    {"text": "ok", "confidence": 0.9},
+                ],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out == [{"token": "ok", "confidence": 0.9}]
+
+    def test_skips_none_confidence(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "words": [
+                    {"text": "avec_conf", "confidence": 0.85},
+                    {"text": "sans_conf"},
+                    {"text": "explicit_none", "confidence": None},
+                ],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out == [{"token": "avec_conf", "confidence": 0.85}]
+
+    def test_skips_negative_confidence(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "words": [
+                    {"text": "ok", "confidence": 0.9},
+                    {"text": "neg", "confidence": -0.1},
+                ],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out == [{"token": "ok", "confidence": 0.9}]
+
+    def test_combines_words_and_lines(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [{
+                "words": [{"text": "explicit", "confidence": 0.99}],
+                "lines": [{"text": "ligne mots", "confidence": 0.7}],
+            }],
+        }
+        out = engine._extract_token_confidences_from_response(response)
+        assert out is not None
+        assert len(out) == 3  # 1 word explicit + 2 mots de la ligne
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2. Cas dégénérés
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestDegenerateResponses:
+    def test_none_response(self) -> None:
+        engine = MistralOCREngine()
+        assert engine._extract_token_confidences_from_response(None) is None
+
+    def test_empty_dict(self) -> None:
+        engine = MistralOCREngine()
+        assert engine._extract_token_confidences_from_response({}) is None
+
+    def test_no_pages(self) -> None:
+        engine = MistralOCREngine()
+        assert engine._extract_token_confidences_from_response(
+            {"pages": []},
+        ) is None
+
+    def test_pages_without_confidences(self) -> None:
+        engine = MistralOCREngine()
+        response = {
+            "pages": [
+                {"markdown": "Texte sans annotation de confidence"},
+            ],
+        }
+        assert engine._extract_token_confidences_from_response(response) is None
+
+    def test_non_dict_input(self) -> None:
+        engine = MistralOCREngine()
+        assert engine._extract_token_confidences_from_response("not a dict") is None
+        assert engine._extract_token_confidences_from_response([1, 2, 3]) is None
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 3. expose_confidences=False
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestExposeFlag:
+    def test_disabled_returns_none(self) -> None:
+        engine = MistralOCREngine(config={"expose_confidences": False})
+        response = {
+            "pages": [{
+                "words": [{"text": "ok", "confidence": 0.9}],
+            }],
+        }
+        assert engine._extract_token_confidences_from_response(response) is None
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4-6. run() avec mock du chemin réseau
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _mock_run_with_response(
+    monkeypatch: pytest.MonkeyPatch,
+    text: str,
+    raw_response: dict | None,
+    *,
+    raise_exc: Exception | None = None,
+) -> MistralOCREngine:
+    """Patche ``_run_ocr_with_response`` pour ne pas appeler l'API."""
+    engine = MistralOCREngine()
+    # On évite la vérification de la clé API (set artificiellement)
+    engine._api_key = "test-key"
+
+    def _fake(self, image_path):
+        if raise_exc is not None:
+            raise raise_exc
+        return text, raw_response
+
+    monkeypatch.setattr(
+        MistralOCREngine, "_run_ocr_with_response", _fake,
+    )
+    return engine
+
+
+class TestRunOverride:
+    def test_run_exposes_confidences_when_response_has_them(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+    ) -> None:
+        engine = _mock_run_with_response(
+            monkeypatch,
+            "Bonjour le monde",
+            {"pages": [{
+                "words": [
+                    {"text": "Bonjour", "confidence": 0.95},
+                    {"text": "le",      "confidence": 0.92},
+                    {"text": "monde",   "confidence": 0.90},
+                ],
+            }]},
+        )
+        img = tmp_path / "p.png"
+        img.write_bytes(b"x")
+        result = engine.run(img)
+        assert result.text == "Bonjour le monde"
+        assert result.error is None
+        assert result.token_confidences is not None
+        assert len(result.token_confidences) == 3
+
+    def test_run_no_confidences_when_chat_vision(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+    ) -> None:
+        """Chemin pixtral : raw_response = None → token_confidences = None."""
+        engine = _mock_run_with_response(
+            monkeypatch,
+            "Texte produit par pixtral",
+            None,  # le chemin chat/vision ne fournit pas de raw_response
+        )
+        img = tmp_path / "p.png"
+        img.write_bytes(b"x")
+        result = engine.run(img)
+        assert result.text == "Texte produit par pixtral"
+        assert result.token_confidences is None
+
+    def test_run_api_failure_keeps_error(
+        self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+    ) -> None:
+        engine = _mock_run_with_response(
+            monkeypatch,
+            "",
+            None,
+            raise_exc=RuntimeError("API timeout"),
+        )
+        img = tmp_path / "p.png"
+        img.write_bytes(b"x")
+        result = engine.run(img)
+        assert result.error == "API timeout"
+        assert result.text == ""
+        assert result.token_confidences is None
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 7. Intégration runner
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestEndToEndWithRunner:
+    def test_runner_picks_up_mistral_confidences(self) -> None:
+        from picarones.core.runner import _compute_document_result
+        from picarones.engines.base import EngineResult
+
+        ocr = EngineResult(
+            engine_name="mistral_ocr",
+            image_path="/tmp/x.png",
+            text="alpha beta gamma",
+            duration_seconds=0.1,
+            token_confidences=[
+                {"token": "alpha", "confidence": 0.95},
+                {"token": "beta",  "confidence": 0.85},
+                {"token": "gamma", "confidence": 0.95},
+            ],
+        )
+        dr = _compute_document_result(
+            doc_id="d1", image_path="/tmp/x.png",
+            ground_truth="alpha beta gamma",
+            ocr_result=ocr, char_exclude=None,
+        )
+        assert dr.calibration_metrics is not None
+        assert dr.calibration_metrics["overall_accuracy"] == 1.0
+        # confidence moyenne = (0.95 + 0.85 + 0.95) / 3
+        assert dr.calibration_metrics["overall_confidence"] == pytest.approx(
+            (0.95 + 0.85 + 0.95) / 3,
+        )

tests/test_sprint6_web_interface.py

@@ -1278,9 +1278,12 @@ class TestMistralOCRNativeAPI:
         img.write_bytes(b"\xff\xd8\xff\xe0" + b"\x00" * 100)
         native_called = []
         vision_called = []
+        # Sprint 49 — _run_ocr_native_api retourne maintenant
+        # ``(text, raw_response_dict)`` pour permettre l'extraction
+        # des confidences ; on aligne le mock.
         def fake_native(url):
             native_called.append(url)
-            return "texte extrait via OCR natif"
+            return "texte extrait via OCR natif", {}
         def fake_vision(url):
             vision_called.append(url)
             return "texte extrait via vision"