fix(pipeline/metrics): 3 bugs pipelines OCR+LLM

Bug 2 — CER 0.00% pour hypothèse vide (root cause)
metrics.py : ajout d'une garde explicite avant les appels jiwer.
Si l'hypothèse est vide (ou uniquement des espaces) avec une référence
non vide, retourne immédiatement CER=WER=MER=WIL=1.0.
jiwer.wer("ref", "") lève ZeroDivisionError ; l'ancien except retournait
silencieusement cer=0.0 au lieu de 1.0.

Bug 1 — Sortie LLM vide sans avertissement
mistral_adapter.py :
- WARNING logu si response.choices[0].message.content est vide ou None
- DEBUG logs : longueur prompt, longueur réponse, extrait réponse
- Constante _TEXT_ONLY_MODELS pour ministral-3b/8b-latest et équivalents
- WARNING + neutralisation de l'image si modèle text-only reçoit image_b64
pipelines/base.py :
- WARNING si le LLM retourne un texte vide (avec conseils de diagnostic)
- WARNING si le moteur OCR produit un texte vide avant l'envoi au LLM
- DEBUG logs : longueur texte OCR, longueur réponse LLM, extrait

Bug 3 — Divergence runner/rapport
Résolu par le fix Bug 2 : le DocumentResult stocke désormais CER=1.0
(via compute_metrics) pour toute hypothèse vide, garantissant la
cohérence entre le log runner et l'affichage dans le rapport HTML.

Tests : +20 tests (test_metrics.py +4, test_sprint15_llm_pipeline_bugs.py +16)
890 tests passent.

https://claude.ai/code/session_017gXea9mxBQqDTAsSQd7aAq

picarones/core/metrics.py

@@ -152,6 +152,18 @@ def compute_metrics(
             error="jiwer n'est pas installé (pip install jiwer)",
         )
 
+    # Hypothèse vide avec référence non vide = erreur totale (toutes les
+    # métriques jiwer lèvent une ZeroDivisionError sur hypothèse vide).
+    ref_stripped = reference.strip()
+    hyp_stripped = hypothesis.strip() if hypothesis else ""
+    if ref_stripped and not hyp_stripped:
+        return MetricsResult(
+            cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
+            wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
+            reference_length=len(reference),
+            hypothesis_length=0,
+        )
+
     try:
         # Exclusion de caractères avant tout calcul
         if char_exclude:

picarones/llm/mistral_adapter.py

@@ -2,11 +2,25 @@
 
 from __future__ import annotations
 
+import logging
 import os
 from typing import Optional
 
 from picarones.llm.base import BaseLLMAdapter
 
+logger = logging.getLogger(__name__)
+
+# Modèles Mistral qui NE supportent PAS l'API chat/completions multimodale.
+# Ces petits modèles sont text-only; le passer avec une image provoque une erreur.
+_TEXT_ONLY_MODELS = frozenset({
+    "ministral-3b-latest",
+    "ministral-8b-latest",
+    "mistral-tiny",
+    "mistral-tiny-latest",
+    "open-mistral-7b",
+    "open-mixtral-8x7b",
+})
+
 
 class MistralAdapter(BaseLLMAdapter):
     """Adaptateur pour les modèles Mistral AI.
@@ -15,6 +29,11 @@ class MistralAdapter(BaseLLMAdapter):
 
     Modes supportés : text_only (tous modèles), text_and_image et zero_shot
     avec les modèles multimodaux (pixtral-12b, pixtral-large).
+
+    Note
+    ----
+    Les modèles ``ministral-3b-latest`` et ``ministral-8b-latest`` ne supportent
+    pas le mode multimodal — utiliser ``PipelineMode.TEXT_ONLY`` avec ces modèles.
     """
 
     @property
@@ -32,6 +51,11 @@ class MistralAdapter(BaseLLMAdapter):
     ) -> None:
         super().__init__(model, config)
         self._api_key = os.environ.get("MISTRAL_API_KEY")
+        if self.model in _TEXT_ONLY_MODELS:
+            logger.info(
+                "[MistralAdapter] modèle '%s' : text-only (pas de support multimodal).",
+                self.model,
+            )
 
     def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
         if not self._api_key:
@@ -49,6 +73,15 @@ class MistralAdapter(BaseLLMAdapter):
         temperature = float(self.config.get("temperature", 0.0))
         max_tokens = int(self.config.get("max_tokens", 4096))
 
+        # Les modèles text-only ne supportent pas les images
+        if image_b64 and self.model in _TEXT_ONLY_MODELS:
+            logger.warning(
+                "[MistralAdapter] modèle '%s' ne supporte pas les images — "
+                "image ignorée, appel en mode texte seul.",
+                self.model,
+            )
+            image_b64 = None
+
         if image_b64:
             content: list | str = [
                 {"type": "text", "text": prompt},
@@ -60,10 +93,32 @@ class MistralAdapter(BaseLLMAdapter):
         else:
             content = prompt
 
+        logger.debug(
+            "[MistralAdapter] appel %s — longueur prompt : %d caractères, image : %s",
+            self.model, len(prompt), "oui" if image_b64 else "non",
+        )
+
         response = client.chat.complete(
             model=self.model,
             messages=[{"role": "user", "content": content}],
             temperature=temperature,
             max_tokens=max_tokens,
         )
-        return response.choices[0].message.content or ""
+        raw = response.choices[0].message.content
+        text = raw or ""
+
+        if not text or not text.strip():
+            logger.warning(
+                "[MistralAdapter] réponse vide reçue du modèle '%s' "
+                "(longueur brute : %s). "
+                "Vérifier que le modèle supporte l'API chat/completions et "
+                "que le prompt contient bien {ocr_output}.",
+                self.model, len(raw) if raw is not None else "None",
+            )
+        else:
+            logger.debug(
+                "[MistralAdapter] réponse reçue — %d caractères, extrait : %r",
+                len(text), text[:120],
+            )
+
+        return text

picarones/pipelines/base.py

@@ -15,6 +15,7 @@ exposées via ``EngineResult.metadata``.
 from __future__ import annotations
 
 import base64
+import logging
 import time
 from enum import Enum
 from pathlib import Path
@@ -23,6 +24,8 @@ from typing import Optional
 from picarones.engines.base import BaseOCREngine, EngineResult
 from picarones.llm.base import BaseLLMAdapter
 
+logger = logging.getLogger(__name__)
+
 
 class PipelineMode(str, Enum):
     """Mode d'appel LLM dans le pipeline."""
@@ -146,6 +149,9 @@ class OCRLLMPipeline(BaseOCREngine):
         if self.mode == PipelineMode.ZERO_SHOT:
             image_b64 = _image_to_b64(image_path)
             prompt = self._build_prompt(image_b64=image_b64)
+            logger.debug(
+                "[%s] zero-shot — longueur prompt : %d car.", self._name, len(prompt)
+            )
             result = self.llm_adapter.complete(prompt, image_b64=image_b64)
 
         elif self.mode == PipelineMode.TEXT_ONLY:
@@ -154,6 +160,16 @@ class OCRLLMPipeline(BaseOCREngine):
             ocr_result = self.ocr_engine.run(image_path)
             ocr_text = ocr_result.text
             self._last_ocr_text = ocr_text
+            logger.debug(
+                "[%s] texte OCR : %d car. → envoi au LLM.",
+                self._name, len(ocr_text),
+            )
+            if not ocr_text.strip():
+                logger.warning(
+                    "[%s] le moteur OCR a produit un texte vide pour '%s'. "
+                    "Le LLM recevra un prompt sans texte OCR ({ocr_output} vide).",
+                    self._name, image_path.name,
+                )
             prompt = self._build_prompt(ocr_text=ocr_text)
             result = self.llm_adapter.complete(prompt)
 
@@ -163,6 +179,16 @@ class OCRLLMPipeline(BaseOCREngine):
             ocr_result = self.ocr_engine.run(image_path)
             ocr_text = ocr_result.text
             self._last_ocr_text = ocr_text
+            logger.debug(
+                "[%s] texte OCR : %d car. + image → envoi au LLM.",
+                self._name, len(ocr_text),
+            )
+            if not ocr_text.strip():
+                logger.warning(
+                    "[%s] le moteur OCR a produit un texte vide pour '%s'. "
+                    "Le LLM recevra un prompt sans texte OCR ({ocr_output} vide).",
+                    self._name, image_path.name,
+                )
             image_b64 = _image_to_b64(image_path)
             prompt = self._build_prompt(ocr_text=ocr_text, image_b64=image_b64)
             result = self.llm_adapter.complete(prompt, image_b64=image_b64)
@@ -170,7 +196,23 @@ class OCRLLMPipeline(BaseOCREngine):
         if not result.success:
             raise RuntimeError(f"Erreur LLM ({self.llm_adapter.model}): {result.error}")
 
-        return result.text
+        llm_text = result.text
+        if not llm_text or not llm_text.strip():
+            logger.warning(
+                "[%s] le LLM ('%s') a retourné un texte vide pour '%s'. "
+                "CER sera calculé à 1.0 (100%%). "
+                "Vérifier : (1) le prompt contient-il {ocr_output} ? "
+                "(2) le modèle supporte-t-il ce mode d'appel ? "
+                "(3) la réponse n'est-elle pas tronquée (max_tokens) ?",
+                self._name, self.llm_adapter.model, image_path.name,
+            )
+        else:
+            logger.debug(
+                "[%s] réponse LLM : %d car., extrait : %r",
+                self._name, len(llm_text), llm_text[:120],
+            )
+
+        return llm_text
 
     # ------------------------------------------------------------------
     # Override run() pour injecter les métadonnées pipeline

tests/test_metrics.py

@@ -74,6 +74,34 @@ class TestComputeMetrics:
         result = compute_metrics("abcd", "abce")
         assert result.cer_percent == pytest.approx(25.0, rel=1e-2)
 
+    # ── Bug fix : hypothèse vide → CER doit être 1.0, pas 0.0 (bug sprint 13) ──
+
+    def test_empty_hypothesis_cer_is_one(self):
+        """Hypothèse vide avec référence non vide doit donner CER=1.0."""
+        result = compute_metrics("Bonjour le monde", "")
+        assert result.cer == pytest.approx(1.0), (
+            f"CER attendu 1.0 pour hypothèse vide, obtenu {result.cer}"
+        )
+        assert result.error is None
+
+    def test_empty_hypothesis_wer_is_one(self):
+        """WER doit être 1.0 pour hypothèse vide (pas de ZeroDivisionError)."""
+        result = compute_metrics("hello world", "")
+        assert result.wer == pytest.approx(1.0)
+        assert result.mer == pytest.approx(1.0)
+        assert result.wil == pytest.approx(1.0)
+        assert result.error is None
+
+    def test_empty_hypothesis_whitespace_is_treated_as_empty(self):
+        """Hypothèse avec uniquement des espaces est traitée comme vide."""
+        result = compute_metrics("Bonjour", "   ")
+        assert result.cer == pytest.approx(1.0)
+
+    def test_empty_hypothesis_hypothesis_length_is_zero(self):
+        """hypothesis_length doit être 0 pour hypothèse vide."""
+        result = compute_metrics("Bonjour le monde", "")
+        assert result.hypothesis_length == 0
+
 
 class TestAggregateMetrics:
     """Tests de aggregate_metrics."""

tests/test_sprint15_llm_pipeline_bugs.py

@@ -0,0 +1,291 @@
+"""Tests pour le sprint 15 — Correction des bugs dans les pipelines OCR+LLM.
+
+Bug 1 : Sortie LLM vide → WARNING logué + pas de crash
+Bug 2 : CER 0.00% pour hypothèse vide → doit être 1.0 (100%)
+Bug 3 : Divergence runner/rapport → cohérence des métriques
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Bug 2 — compute_metrics : hypothèse vide
+# ---------------------------------------------------------------------------
+
+class TestEmptyHypothesisMetrics:
+    """compute_metrics doit retourner CER=1.0, pas 0.0, pour hypothèse vide."""
+
+    def test_empty_hypothesis_cer_is_one(self):
+        from picarones.core.metrics import compute_metrics
+        result = compute_metrics("Bonjour le monde", "")
+        assert result.cer == pytest.approx(1.0)
+        assert result.error is None
+
+    def test_empty_hypothesis_all_metrics_are_one(self):
+        from picarones.core.metrics import compute_metrics
+        result = compute_metrics("hello world", "")
+        assert result.cer == pytest.approx(1.0)
+        assert result.wer == pytest.approx(1.0)
+        assert result.mer == pytest.approx(1.0)
+        assert result.wil == pytest.approx(1.0)
+
+    def test_whitespace_only_hypothesis_cer_is_one(self):
+        from picarones.core.metrics import compute_metrics
+        result = compute_metrics("Bonjour", "   \t\n")
+        assert result.cer == pytest.approx(1.0)
+
+    def test_none_hypothesis_guarded(self):
+        """compute_metrics ne doit pas planter si hypothesis=None."""
+        from picarones.core.metrics import compute_metrics
+        # None ne sera jamais passé en pratique, mais on teste la robustesse
+        # via une chaîne vide (le runner convertit None → "")
+        result = compute_metrics("test", "")
+        assert result.cer == pytest.approx(1.0)
+
+    def test_both_empty_cer_is_zero(self):
+        """Référence ET hypothèse vides → CER=0.0 (pas d'erreur à mesurer)."""
+        from picarones.core.metrics import compute_metrics
+        result = compute_metrics("", "")
+        assert result.cer == pytest.approx(0.0)
+
+    def test_empty_reference_nonempty_hypothesis(self):
+        """Référence vide avec hypothèse non vide → CER=1.0 (comportement existant)."""
+        from picarones.core.metrics import compute_metrics
+        result = compute_metrics("", "something")
+        assert result.cer == pytest.approx(1.0)
+
+    def test_normal_case_unchanged(self):
+        """Un cas normal ne doit pas être affecté par le guard."""
+        from picarones.core.metrics import compute_metrics
+        result = compute_metrics("abcd", "abce")
+        assert result.cer == pytest.approx(0.25)
+        assert result.error is None
+
+
+# ---------------------------------------------------------------------------
+# Bug 1 — MistralAdapter : WARNING pour réponse vide
+# ---------------------------------------------------------------------------
+
+class TestMistralAdapterLogging:
+    """MistralAdapter doit loguer un WARNING si la réponse LLM est vide."""
+
+    def _make_mock_mistral_module(self, content: str | None):
+        """Retourne un module mistralai simulé avec la réponse donnée."""
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = content
+
+        mock_client = MagicMock()
+        mock_client.chat.complete.return_value = mock_response
+
+        MockMistralClass = MagicMock(return_value=mock_client)
+
+        import types
+        fake_module = types.ModuleType("mistralai")
+        fake_module.Mistral = MockMistralClass
+        return fake_module, mock_client
+
+    def _run_adapter(self, adapter, fake_mod, prompt="test prompt", image_b64=None):
+        """Exécute l'adapter avec le module mistralai simulé."""
+        import sys
+        with patch.dict(sys.modules, {"mistralai": fake_mod}):
+            adapter._api_key = "fake-key"  # injecter la clé directement
+            return adapter.complete(prompt, image_b64=image_b64)
+
+    def test_warning_on_empty_response(self, caplog):
+        """Un WARNING doit être émis si le LLM retourne une chaîne vide."""
+        from picarones.llm.mistral_adapter import MistralAdapter
+
+        fake_mod, _ = self._make_mock_mistral_module("")
+        adapter = MistralAdapter(model="ministral-3b-latest")
+
+        with caplog.at_level(logging.WARNING, logger="picarones.llm.mistral_adapter"):
+            result = self._run_adapter(adapter, fake_mod)
+
+        assert result.text == ""
+        assert any(
+            "vide" in rec.message.lower() or "empty" in rec.message.lower()
+            for rec in caplog.records
+            if rec.levelno >= logging.WARNING
+        ), f"WARNING attendu, messages : {[r.message for r in caplog.records]}"
+
+    def test_no_warning_on_normal_response(self, caplog):
+        """Aucun WARNING ne doit être émis pour une réponse normale."""
+        from picarones.llm.mistral_adapter import MistralAdapter
+
+        fake_mod, _ = self._make_mock_mistral_module("Texte OCR corrigé")
+        adapter = MistralAdapter(model="ministral-3b-latest")
+
+        with caplog.at_level(logging.WARNING, logger="picarones.llm.mistral_adapter"):
+            result = self._run_adapter(adapter, fake_mod)
+
+        assert result.text == "Texte OCR corrigé"
+        assert not any(rec.levelno >= logging.WARNING for rec in caplog.records)
+
+    def test_warning_on_none_response_content(self, caplog):
+        """WARNING doit être émis si message.content est None."""
+        from picarones.llm.mistral_adapter import MistralAdapter
+
+        fake_mod, _ = self._make_mock_mistral_module(None)
+        adapter = MistralAdapter(model="ministral-3b-latest")
+
+        with caplog.at_level(logging.WARNING, logger="picarones.llm.mistral_adapter"):
+            result = self._run_adapter(adapter, fake_mod)
+
+        assert result.text == ""
+        assert any(rec.levelno >= logging.WARNING for rec in caplog.records)
+
+    def test_text_only_models_set_exists(self):
+        """La liste des modèles text-only doit contenir ministral-3b."""
+        from picarones.llm.mistral_adapter import _TEXT_ONLY_MODELS
+        assert "ministral-3b-latest" in _TEXT_ONLY_MODELS
+
+    def test_image_ignored_for_text_only_model(self, caplog):
+        """L'image doit être ignorée (avec WARNING) pour un modèle text-only."""
+        from picarones.llm.mistral_adapter import MistralAdapter
+
+        fake_mod, mock_client = self._make_mock_mistral_module("résultat")
+        adapter = MistralAdapter(model="ministral-3b-latest")
+
+        with caplog.at_level(logging.WARNING, logger="picarones.llm.mistral_adapter"):
+            result = self._run_adapter(adapter, fake_mod, image_b64="fake_b64")
+
+        # L'appel doit avoir été fait SANS image (modèle text-only)
+        call_kwargs = mock_client.chat.complete.call_args
+        _, kwargs = call_kwargs
+        msg_content = kwargs.get("messages", [{}])[0].get("content", "")
+        assert isinstance(msg_content, str), "Image aurait dû être ignorée (content doit être str)"
+        # Au moins un WARNING doit mentionner l'image ignorée
+        assert any("ignor" in rec.message.lower() for rec in caplog.records
+                   if rec.levelno >= logging.WARNING)
+
+
+# ---------------------------------------------------------------------------
+# Bug 1 — OCRLLMPipeline : WARNING quand le LLM retourne texte vide
+# ---------------------------------------------------------------------------
+
+class TestPipelineEmptyLLMResponse:
+    """Le pipeline doit loguer un WARNING si le LLM retourne un texte vide."""
+
+    def _make_pipeline(self, llm_text: str):
+        """Crée un pipeline dont le LLM retourne llm_text."""
+        from picarones.pipelines.base import OCRLLMPipeline, PipelineMode
+        from picarones.llm.base import LLMResult
+
+        mock_ocr = MagicMock()
+        mock_ocr.name = "mock_ocr"
+        mock_ocr.run.return_value = MagicMock(text="texte ocr brut", error=None, success=True)
+        mock_ocr._safe_version.return_value = "1.0"
+
+        mock_llm = MagicMock()
+        mock_llm.name = "mock_llm"
+        mock_llm.model = "mock-model"
+        mock_llm.complete.return_value = LLMResult(
+            model_id="mock-model", text=llm_text, duration_seconds=0.1,
+        )
+
+        return OCRLLMPipeline(
+            ocr_engine=mock_ocr,
+            llm_adapter=mock_llm,
+            mode=PipelineMode.TEXT_ONLY,
+            prompt="correction_medieval_french.txt",
+        )
+
+    def test_warning_on_empty_llm_output(self, tmp_path, caplog):
+        """WARNING doit être logu si le LLM retourne une chaîne vide."""
+        import shutil
+        # Créer une fausse image
+        img_path = tmp_path / "test.png"
+        img_path.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
+
+        pipeline = self._make_pipeline("")
+        with caplog.at_level(logging.WARNING, logger="picarones.pipelines.base"):
+            result = pipeline.run(img_path)
+
+        assert result.text == ""
+        assert any(
+            "vide" in rec.message.lower() or "empty" in rec.message.lower()
+            for rec in caplog.records
+            if rec.levelno >= logging.WARNING
+        ), f"WARNING attendu, messages : {[r.message for r in caplog.records]}"
+
+    def test_no_warning_on_normal_llm_output(self, tmp_path, caplog):
+        """Aucun WARNING ne doit être émis pour une sortie LLM normale."""
+        img_path = tmp_path / "test.png"
+        img_path.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
+
+        pipeline = self._make_pipeline("Texte corrigé par le LLM")
+        with caplog.at_level(logging.WARNING, logger="picarones.pipelines.base"):
+            result = pipeline.run(img_path)
+
+        assert result.text == "Texte corrigé par le LLM"
+        assert not any(
+            "vide" in rec.message.lower()
+            for rec in caplog.records
+            if rec.levelno >= logging.WARNING
+        )
+
+
+# ---------------------------------------------------------------------------
+# Bug 3 — Cohérence runner/rapport : empty hypothesis → CER 1.0 dans DocumentResult
+# ---------------------------------------------------------------------------
+
+class TestRunnerDocumentResultCohérence:
+    """Le DocumentResult doit stocker CER=1.0 pour une hypothèse vide."""
+
+    def test_empty_hypothesis_stored_as_cer_one(self):
+        """_compute_document_result avec text="" → metrics.cer = 1.0."""
+        from picarones.core.runner import _compute_document_result
+        from picarones.engines.base import EngineResult
+
+        ocr_result = EngineResult(
+            engine_name="TestEngine",
+            image_path="fake.png",
+            text="",       # ← sortie vide
+            duration_seconds=1.0,
+            error=None,    # ← pas d'erreur technique
+        )
+
+        doc_result = _compute_document_result(
+            doc_id="doc1",
+            image_path="fake.png",
+            ground_truth="Bonjour le monde",
+            ocr_result=ocr_result,
+            char_exclude=None,
+        )
+
+        assert doc_result.metrics.cer == pytest.approx(1.0), (
+            f"CER attendu 1.0 pour hypothèse vide, obtenu {doc_result.metrics.cer}"
+        )
+        assert doc_result.metrics.error is None, (
+            "L'erreur ne devrait pas être renseignée — c'est une hypothèse vide, pas une erreur technique"
+        )
+
+    def test_engine_error_also_gives_cer_one(self):
+        """EngineResult avec error → metrics.cer = 1.0 (comportement existant)."""
+        from picarones.core.runner import _compute_document_result
+        from picarones.engines.base import EngineResult
+
+        ocr_result = EngineResult(
+            engine_name="TestEngine",
+            image_path="fake.png",
+            text="",
+            duration_seconds=0.0,
+            error="Moteur en erreur",
+        )
+
+        doc_result = _compute_document_result(
+            doc_id="doc1",
+            image_path="fake.png",
+            ground_truth="Bonjour le monde",
+            ocr_result=ocr_result,
+            char_exclude=None,
+        )
+
+        assert doc_result.metrics.cer == pytest.approx(1.0)
+        assert doc_result.metrics.error is not None