feat(sprint-H.2.c-d)!: suppression complète de adapters/legacy_engines/ et adapters/legacy_pipelines/

Sprint H.2.c + H.2.d du plan v2.0 — **breaking change** :
suppression définitive des sous-packages adapters legacy.

Suppressions
------------

- ``picarones/adapters/legacy_engines/`` (entier — ~1700 LOC,
9 fichiers) :
- ``base.py`` : ``BaseOCREngine`` (ABC héritant de ``BaseModule``),
``EngineResult`` (dataclass).
- ``factory.py`` : ``engine_from_name``.
- ``_step_executor.py`` : ``LegacyOCREngineExecutor`` (wrapper
BaseOCREngine → StepExecutor protocol).
- ``tesseract.py``, ``pero_ocr.py``, ``mistral_ocr.py``,
``google_vision.py``, ``azure_doc_intel.py`` : 5 adapters
legacy.

- ``picarones/adapters/legacy_pipelines/`` (entier — ~700 LOC,
3 fichiers) :
- ``base.py`` : ``OCRLLMPipeline`` (héritait de BaseOCREngine,
composait OCR + LLM), ``PipelineMode`` enum.
- ``_executor_runner.py`` : pont mono-document
``OCRLLMPipeline.run()`` → ``PipelineExecutor``.

Ces classes étaient déjà inutilisées en production (migrations
H.2.b.2-4 ont basculé CLI/web vers ``BaseOCRAdapter`` canoniques
+ ``OCRLLMPipelineConfig``).

Modifications dans le runner adapter
------------------------------------

``app/services/_legacy_runner_adapter.py`` :
- Retire l'import de ``LegacyOCREngineExecutor``.
- ``engine_to_pipeline_spec`` simplifiée : ne supporte plus que
``BaseOCRAdapter`` + ``OCRLLMPipelineConfig``, lève
``PicaronesError`` sur tout autre type.
- ``_ocr_only_to_spec`` (legacy IMAGE → RAW_TEXT en dur) supprimée.
- ``build_adapter_resolver`` simplifiée : pas de wrapping
``LegacyOCREngineExecutor``.

Tests / docs
------------

- ``tests/test_minimal_install.py`` : modules optionnels
référencés via ``picarones.adapters.ocr.*`` au lieu de
``picarones.adapters.legacy_engines.*``.
- ``tests/architecture/test_file_budgets.py`` : entrée orpheline
``adapters/legacy_pipelines/_executor_runner.py`` retirée.
- ``tests/architecture/test_doc_paths.py`` :
``BROKEN_PATHS_BASELINE`` 161 → 162 (1 nouveau path cassé dans
les docs migration historiques qui référençaient
``adapters/legacy_pipelines/``).
- ``tests/docs/test_readme_consistency.py`` + ``scripts/gen_readme_tables.py`` :
``ENGINES_DIR`` redirigé vers ``picarones/adapters/ocr/``.
- README régénéré : la table « Supported Engines » liste désormais
les 5 adapters canoniques (sans ``confidences``/``precomputed``
qui sont des helpers internes).

Lint : ``ruff check`` All checks passed.
Tests : 4296 passed, 9 skipped, 24 deselected.

Reste pour v2.0
---------------
- H.4 : renommer ``interfaces/{cli,web}/_legacy/`` → drop le préfixe.
- H.6 : bump version + tag v2.0.0 + section CHANGELOG.

https://claude.ai/code/session_01NxyVKqg2SowXLZdM4H1ZDE

README.md

@@ -200,7 +200,6 @@ For Docker, institutional deployment, or HuggingFace Spaces, see
 
 | Engine | Type | Installation |
 |--------|------|-------------|
-| **_step_executor** | Unknown | — |
 | **Azure Doc Intelligence** | Cloud API | `AZURE_DOC_INTEL_ENDPOINT` + `AZURE_DOC_INTEL_KEY` |
 | **Google Vision** | Cloud API | `GOOGLE_APPLICATION_CREDENTIALS` env var |
 | **Mistral OCR** | Cloud API | `MISTRAL_API_KEY` env var |

picarones/adapters/legacy_engines/__init__.py

@@ -1,50 +0,0 @@
-"""Engines OCR legacy — Sprint 33+ pré-rewrite.
-
-Phase 7.A — package relocalisé depuis ``picarones.engines`` vers
-``picarones.adapters.legacy_engines``.  Le chemin legacy reste
-disponible via des shims avec ``DeprecationWarning`` ; suppression
-prévue en 2.0.
-
-Coexistence avec ``picarones.adapters.ocr``
--------------------------------------------
-``evaluation.engines`` porte les 5 OCR engines historiques qui
-héritent de ``BaseOCREngine`` (basé sur ``BaseModule``,
-``run() → EngineResult``).  Ils sont consommés par le runner
-legacy (``measurements/runner/``) et le ``PipelineRunner`` legacy.
-
-``picarones.adapters.ocr`` (Sprint A14-S26) est la cible
-canonique : un design ``StepExecutor`` Protocol, ``Artifact``
-typés, sans héritage de ``BaseModule``.  Les 5 OCR adapters
-canoniques (``TesseractAdapter``, etc.) y vivent.
-
-La convergence des deux est documentée dans
-``docs/migration/pipeline-convergence-plan.md`` (sub-phases
-7.A-7.D, stratégie 4.B).  Tant que ``BaseModule`` n'est pas
-retiré, les engines legacy gardent leur place.
-"""
-
-from __future__ import annotations
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine, EngineResult
-from picarones.adapters.legacy_engines.factory import engine_from_name
-from picarones.adapters.legacy_engines.tesseract import TesseractEngine
-from picarones.adapters.legacy_engines.mistral_ocr import MistralOCREngine
-from picarones.adapters.legacy_engines.google_vision import GoogleVisionEngine
-from picarones.adapters.legacy_engines.azure_doc_intel import AzureDocIntelEngine
-
-__all__ = [
-    "BaseOCREngine",
-    "EngineResult",
-    "engine_from_name",
-    "TesseractEngine",
-    "MistralOCREngine",
-    "GoogleVisionEngine",
-    "AzureDocIntelEngine",
-]
-
-try:
-    from picarones.adapters.legacy_engines.pero_ocr import PeroOCREngine  # noqa: F401
-
-    __all__.append("PeroOCREngine")
-except ImportError:
-    pass

picarones/adapters/legacy_engines/_step_executor.py

@@ -1,190 +0,0 @@
-"""``LegacyOCREngineExecutor`` — wrapper ``BaseOCREngine`` → ``StepExecutor``.
-
-Sprint A.1 du plan v2.0 (préparation à la suppression de
-``OCRLLMPipeline``).  Le wrapper présente les 5 OCR engines legacy
-(``TesseractEngine``, ``PeroOCREngine``, ``MistralOCREngine``,
-``AzureDocIntelEngine``, ``GoogleVisionEngine``) comme des
-``StepExecutor`` consommables par ``PipelineExecutor``.
-
-Pourquoi
---------
-``OCRLLMPipeline`` historique compose un ``BaseOCREngine`` + un
-``BaseLLMAdapter`` en mémoire.  Le rewrite consomme un ``PipelineSpec``
-exécuté par ``PipelineExecutor`` qui résout chaque step en
-``StepExecutor``.  Pour migrer progressivement (Sprint B), il faut
-pouvoir injecter un OCR engine legacy dans le ``PipelineExecutor`` sans
-réimplémenter chacun des 5 adapters au contrat ``BaseOCRAdapter``.
-
-Le wrapper résout cette tension : il accepte une instance
-``BaseOCREngine`` au constructeur, expose les attributs
-``StepExecutor`` (``input_types``, ``output_types``, ``execution_mode``,
-``execute``), et délègue à ``engine.run(image_path)`` en interne.
-
-Trace de retrait
-----------------
-Ce wrapper est lui-même legacy au sens du Sprint H : il sera supprimé
-en même temps que ``BaseOCREngine`` quand les 5 moteurs concrets
-auront migré vers ``BaseOCRAdapter`` (qui existe déjà côté rewrite —
-cf. ``picarones.adapters.ocr.tesseract.TesseractAdapter`` et al.).
-
-Anti-sur-ingénierie
--------------------
-- Pas de retry au niveau du wrapper (l'engine legacy gère ses propres
-  retries dans ``run()`` si configuré).
-- Pas de capture custom des confidences (le rewrite a son propre
-  artifact ``CONFIDENCES`` dédié, pas mappé ici).
-- ``run().error`` non vide → on lève ``OCRAdapterError`` ; le
-  ``PipelineExecutor`` capturera et marquera le step en échec.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-from picarones.adapters.ocr.base import OCRAdapterError
-from picarones.adapters.output_paths import resolve_output_path
-from picarones.domain.artifacts import Artifact, ArtifactType
-
-
-class LegacyOCREngineExecutor:
-    """Présente un ``BaseOCREngine`` legacy comme ``StepExecutor``.
-
-    Parameters
-    ----------
-    engine:
-        Instance d'un sous-classe de ``BaseOCREngine`` (Tesseract,
-        Pero, Mistral OCR, Google Vision, Azure DI).
-
-    Attributes
-    ----------
-    name:
-        Délégué à ``engine.name``.
-    input_types:
-        ``frozenset({ArtifactType.IMAGE})`` — un OCR consomme une image.
-    output_types:
-        ``frozenset({ArtifactType.RAW_TEXT})`` — produit du texte plat.
-    execution_mode:
-        Hérité de ``engine.execution_mode`` (``"io"`` pour les engines
-        cloud, ``"cpu"`` pour Tesseract/Pero qui sont CPU-bound).
-
-    Examples
-    --------
-    >>> from picarones.adapters.legacy_engines.tesseract import TesseractEngine
-    >>> from picarones.adapters.legacy_engines._step_executor import (
-    ...     LegacyOCREngineExecutor,
-    ... )
-    >>> step = LegacyOCREngineExecutor(TesseractEngine({"lang": "fra"}))
-    >>> step.input_types
-    frozenset({<ArtifactType.IMAGE: 'image'>})
-    >>> step.output_types
-    frozenset({<ArtifactType.RAW_TEXT: 'raw_text'>})
-    """
-
-    input_types: frozenset = frozenset({ArtifactType.IMAGE})
-    output_types: frozenset = frozenset({ArtifactType.RAW_TEXT})
-
-    def __init__(self, engine: BaseOCREngine) -> None:
-        # Duck-typing tolérant : on accepte un ``BaseOCREngine`` réel
-        # ou un mock qui expose ``run()`` et ``name``.  Cela permet
-        # aux tests existants (Sprint 15) qui injectent des
-        # ``MagicMock`` de continuer à fonctionner.
-        if not (
-            hasattr(engine, "run") and callable(engine.run)
-            and hasattr(engine, "name")
-        ):
-            raise OCRAdapterError(
-                "LegacyOCREngineExecutor requires an object with ``run()`` "
-                f"and ``name`` ; got {type(engine).__name__}."
-            )
-        self._engine = engine
-        # Le runner choisit ``ProcessPoolExecutor`` pour ``"cpu"``
-        # (Tesseract/Pero) et ``ThreadPoolExecutor`` pour ``"io"``
-        # (Mistral/Google/Azure).  On respecte le mode déclaré par
-        # l'engine — ``"io"`` par défaut si l'engine ne le déclare pas
-        # (cas du mock).
-        self.execution_mode: str = getattr(engine, "execution_mode", "io")
-        if not isinstance(self.execution_mode, str):
-            self.execution_mode = "io"
-
-    @property
-    def name(self) -> str:
-        return self._engine.name
-
-    def execute(
-        self,
-        inputs: dict[ArtifactType, Artifact],
-        params: dict[str, Any],
-        context: Any,
-    ) -> dict[ArtifactType, Artifact]:
-        """Exécute l'OCR engine legacy et retourne un ``Artifact RAW_TEXT``.
-
-        Parameters
-        ----------
-        inputs:
-            Doit contenir ``ArtifactType.IMAGE``.  L'URI de l'artefact
-            image est passée à ``engine.run()``.
-        params:
-            Ignorés.  La configuration de l'engine passe par son
-            constructeur, pas par les ``params`` du step.
-        context:
-            ``RunContext``.  Sert à composer les ``Artifact.id`` et à
-            résoudre le chemin d'écriture du texte produit
-            (``context.workspace_uri``).
-
-        Returns
-        -------
-        dict[ArtifactType, Artifact]
-            ``{ArtifactType.RAW_TEXT: Artifact(uri=<text_file>)}``.
-
-        Raises
-        ------
-        OCRAdapterError
-            Si ``inputs[IMAGE]`` est absent, sans URI, ou si
-            ``engine.run()`` retourne un ``EngineResult`` en erreur.
-        """
-        if ArtifactType.IMAGE not in inputs:
-            raise OCRAdapterError(
-                f"{self.name} : input IMAGE manquant.",
-            )
-        image_artifact = inputs[ArtifactType.IMAGE]
-        if image_artifact.uri is None:
-            raise OCRAdapterError(
-                f"{self.name} : artefact image "
-                f"{image_artifact.id!r} sans URI.",
-            )
-        image_path = Path(image_artifact.uri)
-        if not image_path.exists():
-            raise OCRAdapterError(
-                f"{self.name} : fichier image introuvable {image_path!r}.",
-            )
-
-        result = self._engine.run(image_path)
-        if not result.success:
-            raise OCRAdapterError(
-                f"{self.name} : OCR engine a échoué ({result.error}).",
-            )
-
-        # Le contrat StepExecutor exige des artifacts avec URI filesystem
-        # — on écrit le texte produit dans le workspace du run.
-        out_path = resolve_output_path(
-            input_path=image_path,
-            adapter_name=self.name,
-            suffix="raw_text.txt",
-            context=context,
-        )
-        out_path.write_text(result.text, encoding="utf-8")
-
-        return {
-            ArtifactType.RAW_TEXT: Artifact(
-                id=f"{context.document_id}:{self.name}:raw_text",
-                document_id=context.document_id,
-                type=ArtifactType.RAW_TEXT,
-                produced_by_step="ocr",
-                uri=str(out_path),
-            ),
-        }
-
-
-__all__ = ["LegacyOCREngineExecutor"]

picarones/adapters/legacy_engines/azure_doc_intel.py

@@ -1,251 +0,0 @@
-"""Adaptateur OCR — Azure Document Intelligence (anciennement Form Recognizer).
-
-Phase 7.A — module relocalisé depuis
-``picarones.engines.azure_doc_intel`` vers
-``picarones.adapters.legacy_engines.azure_doc_intel``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
-
-Utilise l'API Azure Document Intelligence pour la reconnaissance de texte
-dans des documents historiques.
-
-Variables d'environnement requises :
-  - ``AZURE_DOC_INTEL_KEY``      : clé API Azure
-  - ``AZURE_DOC_INTEL_ENDPOINT`` : URL de l'endpoint (ex : https://moninstance.cognitiveservices.azure.com/)
-
-Documentation : https://learn.microsoft.com/azure/ai-services/document-intelligence/
-
-Sprint 51 — exposition des token_confidences
----------------------------------------------
-La réponse Azure expose ``analyzeResult.pages[].words[]`` avec
-``content`` et ``confidence`` (∈ [0, 1]).  L'adapter parcourt cette
-hiérarchie et émet une entrée par mot au format Sprint 42.
-
-Le texte ``EngineResult.text`` est extrait depuis ``pages[].lines[]``
-(préservation rétrocompat octet par octet).  Les deux chemins (SDK et
-REST) sont normalisés vers une représentation dict unifiée.
-
-Refactor du chantier 1 (post-Sprint 97)
----------------------------------------
-L'adapter ne surcharge plus ``run()`` — il implémente ``_run_with_native``
-et ``_extract_raw_confidences`` (les hooks factorisés dans ``BaseOCREngine``).
-Comportement externe et octets de sortie strictement identiques.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-import time
-import urllib.error
-import urllib.request
-from pathlib import Path
-from typing import Any, Optional
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-
-
-logger = logging.getLogger(__name__)
-
-
-class AzureDocIntelEngine(BaseOCREngine):
-    """Moteur OCR via Azure Document Intelligence.
-
-    Configuration
-    -------------
-    model_id : str
-        Modèle Azure à utiliser. Défaut : ``"prebuilt-read"`` (lecture générique).
-        Alternatives : ``"prebuilt-document"``, ``"prebuilt-layout"``
-        ou un modèle entraîné personnalisé.
-    locale : str
-        Paramètre de locale pour améliorer la précision (ex : ``"fr-FR"``).
-    api_version : str
-        Version de l'API Azure (défaut : ``"2024-02-29-preview"``).
-    expose_confidences : bool
-        ``True`` (défaut) : extrait ``Word.confidence`` de la réponse
-        Azure (Sprint 51).
-    """
-
-    @property
-    def name(self) -> str:
-        return "azure_doc_intel"
-
-    def version(self) -> str:
-        return self.config.get("api_version", "2024-02-29-preview")
-
-    def __init__(self, config: Optional[dict] = None) -> None:
-        super().__init__(config)
-        self._api_key = os.environ.get("AZURE_DOC_INTEL_KEY")
-        self._endpoint = (
-            os.environ.get("AZURE_DOC_INTEL_ENDPOINT", "").rstrip("/")
-            or self.config.get("endpoint", "").rstrip("/")
-        )
-        self._model_id: str = self.config.get("model_id", "prebuilt-read")
-        self._locale: str = self.config.get("locale", "fr-FR")
-        self._api_version: str = self.config.get("api_version", "2024-02-29-preview")
-
-    def _run_ocr(self, image_path: Path) -> str:
-        """Retourne uniquement le texte (interface ``BaseOCREngine``)."""
-        text, _result = self._run_with_native(image_path)
-        return text
-
-    def _run_with_native(
-        self, image_path: Path,
-    ) -> tuple[str, Optional[dict]]:
-        """Exécute l'OCR et retourne ``(text, analyze_result_dict)``.
-
-        ``analyze_result_dict`` est la sous-structure
-        ``analyzeResult`` (avec ``pages[].words[]`` portant les
-        confidences) — normalisée entre les chemins SDK et REST.
-        """
-        if not self._api_key:
-            raise RuntimeError(
-                "Clé API Azure manquante — définissez la variable d'environnement AZURE_DOC_INTEL_KEY"
-            )
-        if not self._endpoint:
-            raise RuntimeError(
-                "Endpoint Azure manquant — définissez la variable d'environnement AZURE_DOC_INTEL_ENDPOINT"
-            )
-
-        try:
-            return self._run_via_sdk(image_path)
-        except ImportError:
-            return self._run_via_rest(image_path)
-
-    def _run_via_sdk(self, image_path: Path) -> tuple[str, dict]:
-        from azure.ai.documentintelligence import DocumentIntelligenceClient
-        from azure.core.credentials import AzureKeyCredential
-
-        client = DocumentIntelligenceClient(
-            endpoint=self._endpoint,
-            credential=AzureKeyCredential(self._api_key),
-        )
-        with open(image_path, "rb") as f:
-            poller = client.begin_analyze_document(
-                model_id=self._model_id,
-                body=f,
-                locale=self._locale,
-                content_type="application/octet-stream",
-            )
-        result = poller.result()
-        text = "\n".join(
-            line.content
-            for page in result.pages
-            for line in (page.lines or [])
-        )
-        analyze_result = self._sdk_result_to_dict(result)
-        return text, analyze_result
-
-    def _run_via_rest(self, image_path: Path) -> tuple[str, Optional[dict]]:
-        """Appel REST direct (sans SDK Azure)."""
-        image_bytes = image_path.read_bytes()
-        analyze_url = (
-            f"{self._endpoint}/documentintelligence/documentModels/"
-            f"{self._model_id}:analyze"
-            f"?api-version={self._api_version}&locale={self._locale}"
-        )
-
-        # Soumettre l'image
-        req = urllib.request.Request(
-            analyze_url,
-            data=image_bytes,
-            headers={
-                "Ocp-Apim-Subscription-Key": self._api_key,
-                "Content-Type": "application/octet-stream",
-            },
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=60) as resp:
-                operation_url = resp.headers.get("Operation-Location", "")
-        except urllib.error.HTTPError as exc:
-            raise RuntimeError(
-                f"Azure Document Intelligence erreur {exc.code}: {exc.read().decode()}"
-            ) from exc
-
-        if not operation_url:
-            raise RuntimeError("Azure : pas d'Operation-Location dans la réponse")
-
-        # Polling du résultat (Azure est asynchrone)
-        headers = {"Ocp-Apim-Subscription-Key": self._api_key}
-        for attempt in range(30):
-            time.sleep(1 + attempt * 0.5)
-            poll_req = urllib.request.Request(operation_url, headers=headers)
-            with urllib.request.urlopen(poll_req, timeout=30) as resp:
-                result = json.loads(resp.read().decode("utf-8"))
-            status = result.get("status", "")
-            if status == "succeeded":
-                text = self._extract_text_from_result(result)
-                analyze_result = result.get("analyzeResult") or None
-                return text, analyze_result
-            if status in {"failed", "canceled"}:
-                raise RuntimeError(f"Azure Document Intelligence : analyse {status}")
-            # status == "running" → continuer à attendre
-
-        raise RuntimeError("Azure Document Intelligence : timeout — analyse trop longue")
-
-    @staticmethod
-    def _extract_text_from_result(result: dict) -> str:
-        """Extrait le texte brut depuis la réponse JSON Azure."""
-        pages = result.get("analyzeResult", {}).get("pages", [])
-        lines: list[str] = []
-        for page in pages:
-            for line in page.get("lines", []):
-                content = line.get("content", "")
-                if content:
-                    lines.append(content)
-        return "\n".join(lines)
-
-    # ──────────────────────────────────────────────────────────────────
-    # Conversion SDK → dict normalisé
-    # ──────────────────────────────────────────────────────────────────
-
-    @staticmethod
-    def _sdk_result_to_dict(result: Any) -> dict:
-        """Convertit l'objet SDK en dict ``{"pages": [{"words":
-        [{"content", "confidence"}]}]}`` pour traitement uniforme avec
-        le chemin REST."""
-        pages = []
-        for page in getattr(result, "pages", []) or []:
-            words = []
-            for word in getattr(page, "words", []) or []:
-                content = getattr(word, "content", "") or ""
-                conf = getattr(word, "confidence", None)
-                words.append({
-                    "content": content,
-                    "confidence": float(conf) if conf is not None else None,
-                })
-            pages.append({"words": words})
-        return {"pages": pages}
-
-    # ──────────────────────────────────────────────────────────────────
-    # Extraction des token_confidences au format Sprint 42
-    # ──────────────────────────────────────────────────────────────────
-
-    def _extract_raw_confidences(
-        self, native: Any,
-    ) -> Optional[list[dict[str, Any]]]:
-        """Parcourt ``pages[].words[]`` et émet
-        ``{"token": str, "confidence": float}`` par mot.
-
-        Filtrage cohérent avec les autres adapters : confidence None /
-        négative ignorée, contenu vide ignoré (filtrage final assuré
-        par ``BaseOCREngine._normalize_token_confidences``).
-        """
-        if not self.config.get("expose_confidences", True):
-            return None
-        if not native or not isinstance(native, dict):
-            return None
-        out: list[dict[str, Any]] = []
-        for page in native.get("pages") or []:
-            if not isinstance(page, dict):
-                continue
-            for word in page.get("words") or []:
-                if not isinstance(word, dict):
-                    continue
-                content = (word.get("content") or "").strip()
-                conf = word.get("confidence")
-                if not content or conf is None:
-                    continue
-                out.append({"token": content, "confidence": conf})
-        return out or None

picarones/adapters/legacy_engines/base.py

@@ -1,336 +0,0 @@
-"""Interface abstraite commune à tous les adaptateurs moteurs OCR (legacy).
-
-Phase 7.A — module relocalisé depuis ``picarones.engines.base``
-vers ``picarones.adapters.legacy_engines.base``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
-
-Cohabite avec ``picarones.adapters.ocr.base.BaseOCRAdapter``
-(canonique, ``StepExecutor`` Protocol).  Convergence documentée
-dans ``docs/migration/pipeline-convergence-plan.md``
-(sub-phases 7.A-7.D, stratégie 4.B).
-
-Refactor du chantier 1 (post-Sprint 97)
----------------------------------------
-Les Sprints 47-51 ont fait surcharger ``run()`` par chacun des cinq
-adaptateurs OCR pour exposer ``token_confidences`` ; cinq fois la même
-structure (chronométrage + extraction native + parsing). Ce module
-factorise ce pattern :
-
-- ``_run_with_native(image_path) -> (text, native_response)`` : hook
-  par lequel passe désormais ``run()``. Implémentation par défaut qui
-  délègue à ``_run_ocr`` (rétrocompat avec les engines historiques et
-  avec les engines de test qui n'implémentent que ``_run_ocr``).
-- ``_extract_raw_confidences(native) -> list[dict] | None`` : hook
-  optionnel à surcharger pour exposer les confidences. Défaut : ``None``.
-- ``_normalize_token_confidences(raw)`` : helper commun (filtrage
-  tokens vides / négatifs, détection automatique d'échelle 0-100 → 0-1).
-
-Conséquence : la classe se charge seule du chronométrage, de la
-gestion d'erreurs et du wrapping en ``EngineResult``. Aucun adaptateur
-OCR n'a plus à surcharger ``run()``.
-
-Compat ``BaseModule`` (Sprint 33)
----------------------------------
-``process()`` continue de propager le texte sous
-``{ArtifactType.TEXT: ...}``. Les ``token_confidences`` ne sont pas
-des artefacts — elles vivent dans ``EngineResult`` et restent
-accessibles via la propriété ``last_run_result`` après l'exécution.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import logging
-import time
-from abc import abstractmethod
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Optional
-
-from picarones.domain.artifacts import ArtifactType
-from picarones.domain.module_protocol import BaseModule
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class EngineResult:
-    """Résultat brut produit par un moteur OCR sur une image."""
-
-    engine_name: str
-    image_path: str
-    text: str
-    duration_seconds: float
-    error: Optional[str] = None
-    metadata: dict = field(default_factory=dict)
-    # Sprint 42 — confidences au niveau token (optionnel).
-    # Format attendu : liste de dicts ``{"token": str, "confidence": float}``
-    # avec ``confidence`` ∈ [0, 1] (ou ∈ [0, 100], normalisé par le runner).
-    # ``None`` si le moteur ne fournit pas ce signal — comportement par
-    # défaut pour tous les adapters historiques.  Quand renseigné,
-    # le runner alimente ``DocumentResult.calibration_metrics``.
-    token_confidences: Optional[list[dict[str, Any]]] = None
-
-    @property
-    def success(self) -> bool:
-        return self.error is None
-
-    @property
-    def image_sha256(self) -> str:
-        return hashlib.sha256(Path(self.image_path).read_bytes()).hexdigest()
-
-
-class BaseOCREngine(BaseModule):
-    """Classe de base dont héritent tous les adaptateurs OCR.
-
-    Sprint 33 — Phase 0.2 : ``BaseOCREngine`` hérite de ``BaseModule`` afin
-    que les moteurs OCR existants soient automatiquement utilisables comme
-    nœuds d'une pipeline composée (axe B du plan d'évolution).
-
-    Chantier 1 (post-Sprint 97) — factorisation du run() unifié
-    ------------------------------------------------------------
-    Les sous-classes implémentent **un** des deux contrats suivants :
-
-    1. **Engine sans confidences** : surchargent uniquement ``_run_ocr``
-       qui retourne le texte. ``run()`` retourne un ``EngineResult``
-       avec ``token_confidences=None``.
-
-    2. **Engine avec confidences natives** : surchargent
-       ``_run_with_native`` (un seul appel API qui retourne texte +
-       payload natif) et ``_extract_raw_confidences`` (parsing du
-       payload natif vers le format runner). ``run()`` les invoque
-       et propage les ``token_confidences`` dans le ``EngineResult``.
-
-    Aucune sous-classe n'a plus besoin de surcharger ``run()``.
-
-    Attribut de classe
-    ------------------
-    execution_mode : ``"io"`` (défaut) ou ``"cpu"``
-        Indique au runner quel type d'exécuteur utiliser :
-        - ``"io"``  → ``ThreadPoolExecutor``  (moteurs API / réseau)
-        - ``"cpu"`` → ``ProcessPoolExecutor`` (moteurs CPU-intensifs : Tesseract, Pero, Kraken)
-    """
-
-    # Déclaration BaseModule — un OCR consomme une image et produit du texte.
-    input_types = (ArtifactType.IMAGE,)
-    output_types = (ArtifactType.TEXT,)
-    execution_mode: str = "io"
-    """``"io"`` pour ThreadPoolExecutor (défaut), ``"cpu"`` pour ProcessPoolExecutor."""
-
-    #: ``True`` ssi l'engine est un pipeline composé (OCR+LLM ou VLM).
-    #: Sprint C du plan v2.0 : remplace le check legacy
-    #: ``isinstance(engine, OCRLLMPipeline)`` par un attribut polymorphe.
-    #: Les sous-classes "pipeline composé" (``OCRLLMPipeline``, et tout
-    #: futur composite) surchargent à ``True``.
-    is_pipeline: bool = False
-
-    def __init__(self, config: Optional[dict] = None) -> None:
-        self.config: dict = config or {}
-        # Cache du dernier ``EngineResult`` produit par ``run()`` —
-        # exposé via la propriété ``last_run_result`` pour permettre
-        # à un orchestrateur (par exemple le pipeline_runner) de
-        # consulter les ``token_confidences`` après ``process()``.
-        self._last_run_result: Optional[EngineResult] = None
-
-    # ``name`` reste abstrait via héritage de BaseModule (cf.
-    # picarones.core.modules) — les sous-classes le surchargent en
-    # ``@property`` comme dans BaseModule.
-
-    @abstractmethod
-    def version(self) -> str:
-        """Retourne la version du moteur (ex : '5.3.0')."""
-
-    @abstractmethod
-    def _run_ocr(self, image_path: Path) -> str:
-        """Exécute l'OCR et retourne le texte brut extrait.
-
-        Contrat **historique** conservé par rétrocompat. Les
-        adaptateurs qui veulent exposer leurs confidences natives
-        surchargent en plus ``_run_with_native`` et
-        ``_extract_raw_confidences`` (cf. docstring de classe).
-        """
-
-    # ──────────────────────────────────────────────────────────────────
-    # Hooks pour confidences natives (Chantier 1)
-    # ──────────────────────────────────────────────────────────────────
-
-    def _run_with_native(self, image_path: Path) -> tuple[str, Any]:
-        """Exécute l'OCR et retourne ``(text, native_response)``.
-
-        Implémentation par défaut : délègue à ``_run_ocr`` et retourne
-        ``(text, None)`` — comportement adapté aux engines qui
-        n'exposent pas de confidences (ex. tests, moteurs basiques).
-
-        Les adaptateurs avec confidences natives surchargent cette
-        méthode pour effectuer un seul appel API qui produit à la
-        fois le texte et la structure (dict JSON, page layout, etc.)
-        à partir de laquelle ``_extract_raw_confidences`` extraira
-        les paires (token, confidence).
-        """
-        return self._run_ocr(image_path), None
-
-    def _extract_raw_confidences(
-        self, native: Any,
-    ) -> Optional[list[dict[str, Any]]]:
-        """Parse ``native`` et retourne les paires ``(token, conf)``.
-
-        Format attendu : liste de dicts ``{"token": str, "confidence":
-        float}`` avec ``confidence`` ∈ [0, 1] **ou** ∈ [0, 100].
-        ``_normalize_token_confidences`` détecte l'échelle et normalise.
-
-        Retourne ``None`` quand ``native`` est ``None`` ou que la
-        structure ne contient aucune confidence exploitable.
-
-        Implémentation par défaut : ``None`` (pas de confidences).
-        """
-        return None
-
-    @staticmethod
-    def _normalize_token_confidences(
-        raw: Optional[list[dict[str, Any]]],
-    ) -> Optional[list[dict[str, Any]]]:
-        """Filtre les confidences brutes (échelle native conservée).
-
-        - Tokens vides ou ``None`` → écartés.
-        - Confidences négatives (Tesseract met -1 pour les non-mots) → écartées.
-        - Confidences non convertibles en float → écartées.
-
-        L'échelle native des moteurs ([0, 100] pour Tesseract,
-        [0, 1] pour les autres) est conservée. La normalisation finale
-        au moment du calcul de calibration est faite dans
-        :func:`picarones.measurements.builtin_hooks.calibration_from_engine_result`.
-
-        Retourne ``None`` si aucune entrée n'est exploitable.
-        """
-        if not raw:
-            return None
-        cleaned: list[dict[str, Any]] = []
-        for entry in raw:
-            if not isinstance(entry, dict):
-                continue
-            tok = entry.get("token")
-            if not isinstance(tok, str):
-                continue
-            tok = tok.strip()
-            if not tok:
-                continue
-            conf = entry.get("confidence")
-            if conf is None:
-                continue
-            try:
-                conf_val = float(conf)
-            except (TypeError, ValueError):
-                continue
-            if conf_val < 0:
-                continue
-            cleaned.append({"token": tok, "confidence": conf_val})
-        return cleaned or None
-
-    # ──────────────────────────────────────────────────────────────────
-    # Implémentation BaseModule (Sprint 33)
-    # ───���──────────────────────────────────────────────────────────────
-
-    def process(self, inputs: dict[ArtifactType, Any]) -> dict[ArtifactType, Any]:
-        """Exécute le moteur OCR comme un module générique.
-
-        Wrapper rétrocompatible : extrait le chemin image de ``inputs``,
-        appelle ``run()``, et retourne la sortie sous forme de dictionnaire
-        ``{ArtifactType.TEXT: text}``.  Les erreurs sont conservées dans
-        le résultat (cf. ``EngineResult.error``) plutôt que de lever.
-        Les ``token_confidences`` restent accessibles via
-        ``self.last_run_result.token_confidences`` après l'appel.
-        """
-        self.validate_inputs(inputs)
-        result = self.run(inputs[ArtifactType.IMAGE])
-        return {ArtifactType.TEXT: result.text}
-
-    def metadata(self) -> dict:
-        """Expose la version du moteur dans les métadonnées du module."""
-        return {"engine_version": self._safe_version()}
-
-    @property
-    def last_run_result(self) -> Optional[EngineResult]:
-        """Dernier ``EngineResult`` produit par ``run()`` (ou ``None``).
-
-        Utile pour récupérer ``token_confidences`` après un appel à
-        ``process()`` (qui ne les expose pas dans le bag d'artefacts du
-        pipeline_runner — les confidences ne sont pas un type
-        d'artefact mais une métadonnée du calcul).
-        """
-        return self._last_run_result
-
-    # ──────────────────────────────────────────────────────────────────
-    # Point d'entrée unifié : run()
-    # ──────────────────────────────────────────────────────────────────
-
-    def run(self, image_path: str | Path) -> EngineResult:
-        """Exécute l'OCR et retourne un ``EngineResult``.
-
-        Pipeline interne :
-
-        1. ``_run_with_native(image_path)`` → ``(text, native)``
-           (par défaut : appelle ``_run_ocr`` et retourne ``(text, None)``).
-        2. ``_extract_raw_confidences(native)`` → liste brute ou ``None``
-           (par défaut : ``None``).
-        3. ``_normalize_token_confidences(raw)`` → format runner Sprint 42
-           ou ``None``.
-
-        Toute exception levée par l'étape 1 est capturée et placée dans
-        ``EngineResult.error`` ; le texte est alors ``""`` et les
-        confidences ``None``. Les exceptions des étapes 2-3 sont
-        capturées séparément en warning : on retourne le texte avec
-        ``token_confidences=None`` plutôt que de faire échouer toute
-        la mesure pour un défaut de calibration.
-        """
-        image_path = Path(image_path)
-        start = time.perf_counter()
-        text = ""
-        error: Optional[str] = None
-        token_confidences: Optional[list[dict[str, Any]]] = None
-        try:
-            text, native = self._run_with_native(image_path)
-        except Exception as exc:  # noqa: BLE001
-            text = ""
-            error = str(exc)
-            native = None
-        if error is None:
-            try:
-                raw = self._extract_raw_confidences(native)
-                token_confidences = self._normalize_token_confidences(raw)
-            except Exception as exc:  # noqa: BLE001
-                logger.warning(
-                    "[%s] extraction/normalisation des token_confidences "
-                    "dégradée : %s",
-                    self.name, exc,
-                )
-                token_confidences = None
-        duration = time.perf_counter() - start
-        result = 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,
-        )
-        self._last_run_result = result
-        return result
-
-    def _safe_version(self) -> str:
-        # Sprint 30 — log la stacktrace en DEBUG pour aider au diagnostic
-        # quand un moteur retourne ``"unknown"`` (utilisateur qui se
-        # demande pourquoi). Ne pollue pas l'output normal (INFO+).
-        try:
-            return self.version()
-        except Exception as exc:  # noqa: BLE001
-            logging.getLogger(__name__).debug(
-                "[%s._safe_version] retourne 'unknown' suite à %s: %s",
-                self.__class__.__name__, type(exc).__name__, exc,
-                exc_info=True,
-            )
-            return "unknown"
-
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}(name={self.name!r})"

picarones/adapters/legacy_engines/factory.py

@@ -1,66 +0,0 @@
-"""Factory legacy : instancier un ``BaseOCREngine`` à partir de son nom court.
-
-Phase 7.A — module relocalisé depuis ``picarones.engines.factory``
-vers ``picarones.adapters.legacy_engines.factory``.
-
-Sprint H.2.b du plan v2.0 — équivalent canonique disponible :
-``picarones.adapters.ocr.factory.ocr_adapter_from_name`` retourne
-des ``BaseOCRAdapter`` (StepExecutor Protocol) directement
-consommables par ``PipelineExecutor`` sans ``LegacyOCREngineExecutor``.
-Les nouveaux callers doivent utiliser la factory canonique.  Cette
-factory ne sera supprimée qu'avec ``BaseOCREngine`` lui-même
-(H.2.d).
-
-Discipline : ne pas importer ``click`` ici, sous peine de remonter une
-dépendance interfaces dans la couche adapters.
-"""
-
-from __future__ import annotations
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-
-
-def engine_from_name(engine_name: str, lang: str = "fra", psm: int = 6) -> BaseOCREngine:
-    """Instancie un moteur OCR par son nom court.
-
-    Parameters
-    ----------
-    engine_name:
-        Identifiant court (``"tesseract"``/``"tess"``, ``"pero_ocr"``/``"pero"``).
-    lang:
-        Code langue propagé au moteur quand il en consomme un (Tesseract).
-    psm:
-        Mode de segmentation Tesseract (ignoré par les autres moteurs).
-
-    Returns
-    -------
-    BaseOCREngine
-        Instance prête à exécuter ``run(image_path)``.
-
-    Raises
-    ------
-    ValueError
-        Si le nom est inconnu ou si le moteur est indisponible (par
-        exemple Pero OCR non installé). Le message inclut la liste des
-        moteurs effectivement disponibles dans l'environnement courant.
-    """
-    from picarones.adapters.legacy_engines.tesseract import TesseractEngine
-
-    if engine_name in {"tesseract", "tess"}:
-        return TesseractEngine(config={"lang": lang, "psm": psm})
-
-    try:
-        from picarones.adapters.legacy_engines.pero_ocr import PeroOCREngine
-
-        if engine_name in {"pero_ocr", "pero"}:
-            return PeroOCREngine(config={"name": "pero_ocr"})
-    except ImportError:
-        pass
-
-    raise ValueError(
-        f"Moteur inconnu ou non disponible : '{engine_name}'. "
-        "Moteurs supportés : tesseract, pero_ocr"
-    )
-
-
-__all__ = ["engine_from_name"]

picarones/adapters/legacy_engines/google_vision.py

@@ -1,262 +0,0 @@
-"""Adaptateur OCR — Google Cloud Vision API.
-
-Phase 7.A — module relocalisé depuis
-``picarones.engines.google_vision`` vers
-``picarones.adapters.legacy_engines.google_vision``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
-
-Utilise l'API Google Cloud Vision pour la détection de texte dans des
-documents (méthode ``DOCUMENT_TEXT_DETECTION``, optimisée pour les textes
-denses et multilinguistiques).
-
-Authentification :
-  - Via service account JSON : variable d'environnement
-    ``GOOGLE_APPLICATION_CREDENTIALS`` → chemin vers le fichier JSON
-  - Via clé API simple : variable d'environnement ``GOOGLE_API_KEY``
-
-Le mode service account est recommandé pour la production.
-
-Sprint 50 — exposition des token_confidences
----------------------------------------------
-``DOCUMENT_TEXT_DETECTION`` expose ``Word.confidence`` au niveau mot
-sur chaque ``page > block > paragraph > word``.  L'adapter parcourt
-cette hiérarchie et émet une entrée par mot au format Sprint 42.
-Les deux chemins (SDK ``google-cloud-vision`` et REST direct via
-``urllib``) sont normalisés vers une représentation unifiée.
-
-Pour ``TEXT_DETECTION`` (mode "court"), aucune confidence par mot
-n'est exposée : ``token_confidences = None``.
-
-Refactor du chantier 1 (post-Sprint 97)
----------------------------------------
-L'adapter ne surcharge plus ``run()`` — il implémente ``_run_with_native``
-et ``_extract_raw_confidences`` (les hooks factorisés dans ``BaseOCREngine``).
-Comportement externe et octets de sortie strictement identiques.
-"""
-
-from __future__ import annotations
-
-import base64
-import json
-import logging
-import os
-import urllib.error
-import urllib.request
-from pathlib import Path
-from typing import Any, Optional
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-
-
-logger = logging.getLogger(__name__)
-
-
-class GoogleVisionEngine(BaseOCREngine):
-    """Moteur OCR via l'API Google Cloud Vision.
-
-    Configuration
-    -------------
-    language_hints : list[str]
-        Suggestions de langue (ex : ``["fr"]``). Améliore la précision.
-    feature_type : str
-        Type de détection : ``"DOCUMENT_TEXT_DETECTION"`` (défaut, pour textes
-        denses) ou ``"TEXT_DETECTION"`` (pour textes courts).
-    expose_confidences : bool
-        ``True`` (défaut) : extrait ``Word.confidence`` quand
-        ``feature_type=DOCUMENT_TEXT_DETECTION`` (Sprint 50).
-        ``False`` : désactive l'extraction (économise quelques ms par
-        image).
-    """
-
-    @property
-    def name(self) -> str:
-        return "google_vision"
-
-    def version(self) -> str:
-        return "v1"
-
-    def __init__(self, config: Optional[dict] = None) -> None:
-        super().__init__(config)
-        self._api_key = os.environ.get("GOOGLE_API_KEY")
-        self._credentials_path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
-        self._language_hints: list[str] = self.config.get("language_hints", ["fr"])
-        self._feature_type: str = self.config.get("feature_type", "DOCUMENT_TEXT_DETECTION")
-
-    def _run_ocr(self, image_path: Path) -> str:
-        """Retourne uniquement le texte (interface ``BaseOCREngine``)."""
-        text, _full = self._run_with_native(image_path)
-        return text
-
-    def _run_with_native(
-        self, image_path: Path,
-    ) -> tuple[str, Optional[dict]]:
-        """Exécute l'OCR et retourne ``(text, full_text_annotation_dict)``.
-
-        ``full_text_annotation_dict`` est :
-        - le JSON brut ``fullTextAnnotation`` du REST quand on passe
-          par REST,
-        - une représentation dict normalisée quand on passe par SDK,
-        - ``None`` pour ``TEXT_DETECTION`` (mode court sans
-          confidence par mot).
-        """
-        if self._credentials_path:
-            return self._run_via_sdk(image_path)
-        elif self._api_key:
-            return self._run_via_rest(image_path)
-        else:
-            raise RuntimeError(
-                "Authentification Google Vision manquante. Définissez "
-                "GOOGLE_APPLICATION_CREDENTIALS (service account JSON) "
-                "ou GOOGLE_API_KEY."
-            )
-
-    def _run_via_sdk(self, image_path: Path) -> tuple[str, Optional[dict]]:
-        try:
-            from google.cloud import vision
-        except ImportError as exc:
-            raise RuntimeError(
-                "Le package 'google-cloud-vision' n'est pas installé. "
-                "Lancez : pip install google-cloud-vision"
-            ) from exc
-
-        client = vision.ImageAnnotatorClient()
-        image_bytes = image_path.read_bytes()
-        image = vision.Image(content=image_bytes)
-
-        if self._feature_type == "DOCUMENT_TEXT_DETECTION":
-            response = client.document_text_detection(
-                image=image,
-                image_context=vision.ImageContext(
-                    language_hints=self._language_hints
-                ),
-            )
-            text = response.full_text_annotation.text
-            full = self._sdk_full_text_to_dict(response.full_text_annotation)
-            return text, full
-        else:
-            response = client.text_detection(
-                image=image,
-                image_context=vision.ImageContext(
-                    language_hints=self._language_hints
-                ),
-            )
-            texts = response.text_annotations
-            text = texts[0].description if texts else ""
-            return text, None
-
-    def _run_via_rest(self, image_path: Path) -> tuple[str, Optional[dict]]:
-        """Appel REST direct (sans SDK), avec clé API simple."""
-        image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
-        payload = {
-            "requests": [
-                {
-                    "image": {"content": image_b64},
-                    "features": [{"type": self._feature_type, "maxResults": 1}],
-                    "imageContext": {"languageHints": self._language_hints},
-                }
-            ]
-        }
-        url = "https://vision.googleapis.com/v1/images:annotate"
-        data = json.dumps(payload).encode("utf-8")
-        req = urllib.request.Request(
-            url, data=data,
-            headers={
-                "Content-Type": "application/json",
-                "X-Goog-Api-Key": self._api_key,
-            },
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=60) as resp:
-                result = json.loads(resp.read().decode("utf-8"))
-        except urllib.error.HTTPError as exc:
-            raise RuntimeError(f"Google Vision API erreur {exc.code}: {exc.read().decode()}") from exc
-
-        responses = result.get("responses", [{}])
-        if not responses:
-            return "", None
-        r = responses[0]
-        if "error" in r:
-            raise RuntimeError(f"Google Vision API erreur : {r['error']}")
-
-        if self._feature_type == "DOCUMENT_TEXT_DETECTION":
-            full = r.get("fullTextAnnotation") or None
-            text = (full or {}).get("text", "") if isinstance(full, dict) else ""
-            return text, full
-        else:
-            texts = r.get("textAnnotations", [])
-            text = texts[0]["description"] if texts else ""
-            return text, None
-
-    # ──────────────────────────────────────────────────────────────────
-    # Conversion SDK → dict normalisé (pour traitement uniforme)
-    # ──────────────────────────────────────────────────────────────────
-
-    @staticmethod
-    def _sdk_full_text_to_dict(full_text_annotation: Any) -> dict:
-        """Convertit une réponse proto SDK en dict avec la même
-        structure que le REST : ``{pages: [{blocks: [{paragraphs:
-        [{words: [{confidence, symbols: [{text}]}]}]}]}]}``."""
-        pages = []
-        for page in getattr(full_text_annotation, "pages", []) or []:
-            blocks = []
-            for block in getattr(page, "blocks", []) or []:
-                paragraphs = []
-                for para in getattr(block, "paragraphs", []) or []:
-                    words = []
-                    for word in getattr(para, "words", []) or []:
-                        symbols = [
-                            {"text": getattr(s, "text", "")}
-                            for s in getattr(word, "symbols", []) or []
-                        ]
-                        words.append({
-                            "confidence": float(getattr(word, "confidence", 0.0)),
-                            "symbols": symbols,
-                        })
-                    paragraphs.append({"words": words})
-                blocks.append({"paragraphs": paragraphs})
-            pages.append({"blocks": blocks})
-        return {"pages": pages}
-
-    # ──────────────────────────────────────────────────────────────────
-    # Extraction des token_confidences au format Sprint 42
-    # ──────────────────────────────────────────────────────────────────
-
-    def _extract_raw_confidences(
-        self, native: Any,
-    ) -> Optional[list[dict[str, Any]]]:
-        """Parcourt ``pages → blocks → paragraphs → words`` et émet
-        ``{"token": mot, "confidence": float}`` par mot.
-
-        Le mot est reconstitué par concaténation des
-        ``word.symbols[i].text``.  ``word.confidence`` ∈ [0, 1] (la
-        normalisation par la base accepte directement ce format).
-        """
-        if not self.config.get("expose_confidences", True):
-            return None
-        if not native or not isinstance(native, dict):
-            return None
-        out: list[dict[str, Any]] = []
-        for page in native.get("pages") or []:
-            if not isinstance(page, dict):
-                continue
-            for block in page.get("blocks") or []:
-                if not isinstance(block, dict):
-                    continue
-                for para in block.get("paragraphs") or []:
-                    if not isinstance(para, dict):
-                        continue
-                    for word in para.get("words") or []:
-                        if not isinstance(word, dict):
-                            continue
-                        text = "".join(
-                            (s or {}).get("text", "")
-                            for s in (word.get("symbols") or [])
-                        ).strip()
-                        if not text:
-                            continue
-                        conf = word.get("confidence")
-                        if conf is None:
-                            continue
-                        out.append({"token": text, "confidence": conf})
-        return out or None

picarones/adapters/legacy_engines/mistral_ocr.py

@@ -1,237 +0,0 @@
-"""Adaptateur OCR — Mistral OCR (API vision Mistral AI).
-
-Phase 7.A — module relocalisé depuis
-``picarones.engines.mistral_ocr`` vers
-``picarones.adapters.legacy_engines.mistral_ocr``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
-
-Utilise l'API Mistral pour la reconnaissance de texte sur documents
-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``.
-
-Refactor du chantier 1 (post-Sprint 97)
----------------------------------------
-L'adapter ne surcharge plus ``run()`` — il implémente ``_run_with_native``
-et ``_extract_raw_confidences`` (les hooks factorisés dans ``BaseOCREngine``).
-Comportement externe et octets de sortie strictement identiques.
-"""
-
-from __future__ import annotations
-
-import base64
-import logging
-import os
-from pathlib import Path
-from typing import Any, Optional
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-
-
-logger = logging.getLogger(__name__)
-
-
-class MistralOCREngine(BaseOCREngine):
-    """Moteur OCR via l'API Mistral AI (modèle vision).
-
-    Configuration
-    -------------
-    model : str
-        Modèle Mistral à utiliser (défaut : ``"pixtral-12b-2409"``).
-        Les modèles multimodaux supportant la vision sont :
-        ``pixtral-12b-2409``, ``pixtral-large-latest``.
-    prompt : str
-        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
-    def name(self) -> str:
-        return "mistral_ocr"
-
-    def version(self) -> str:
-        return self.config.get("model", "mistral-ocr-latest")
-
-    def __init__(self, config: Optional[dict] = None) -> None:
-        super().__init__(config)
-        self._api_key = os.environ.get("MISTRAL_API_KEY")
-        self._model = self.config.get("model", "mistral-ocr-latest")
-        self._prompt = self.config.get(
-            "prompt",
-            "Transcris fidèlement le texte visible sur cette image de document "
-            "historique. Retourne uniquement le texte, sans commentaire.",
-        )
-        self._max_tokens = int(self.config.get("max_tokens", 4096))
-
-    def _run_ocr(self, image_path: Path) -> str:
-        """Retourne uniquement le texte (interface ``BaseOCREngine``)."""
-        text, _raw = self._run_with_native(image_path)
-        return text
-
-    def _run_with_native(
-        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"
-            )
-
-        suffix = image_path.suffix.lower()
-        media_type = {
-            ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
-            ".png": "image/png", ".tif": "image/tiff",
-            ".tiff": "image/tiff", ".webp": "image/webp",
-        }.get(suffix, "image/jpeg")
-
-        image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
-        image_url = f"data:{media_type};base64,{image_b64}"
-
-        if "mistral-ocr" in self._model.lower():
-            return self._run_ocr_native_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).
-
-        Retourne ``(text, raw_response_dict)`` pour permettre
-        l'extraction des confidences en post-traitement.
-        """
-        import json
-        import urllib.request
-
-        payload = json.dumps({
-            "model": self._model,
-            "document": {"type": "image_url", "image_url": image_url},
-        }).encode("utf-8")
-        req = urllib.request.Request(
-            "https://api.mistral.ai/v1/ocr",
-            data=payload,
-            headers={
-                "Authorization": f"Bearer {self._api_key}",
-                "Content-Type": "application/json",
-            },
-            method="POST",
-        )
-        with urllib.request.urlopen(req, timeout=60) as resp:
-            data = json.loads(resp.read().decode())
-        pages = data.get("pages", [])
-        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.)."""
-        try:
-            try:
-                from mistralai.client import Mistral
-            except ImportError:
-                from mistralai import Mistral  # type: ignore[no-redef]
-        except ImportError as exc:
-            raise RuntimeError(
-                "Le package 'mistralai' n'est pas installé. Lancez : pip install mistralai"
-            ) from exc
-
-        client = Mistral(api_key=self._api_key)
-        response = client.chat.complete(
-            model=self._model,
-            messages=[
-                {
-                    "role": "user",
-                    "content": [
-                        {"type": "text", "text": self._prompt},
-                        {"type": "image_url", "image_url": image_url},
-                    ],
-                }
-            ],
-            max_tokens=self._max_tokens,
-        )
-        return response.choices[0].message.content or ""
-
-    def _extract_raw_confidences(
-        self, native: Any,
-    ) -> 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-*``).
-        """
-        if not self.config.get("expose_confidences", True):
-            return None
-        if not native or not isinstance(native, dict):
-            return None
-        out: list[dict[str, Any]] = []
-        pages = native.get("pages") or []
-        for page in pages:
-            if not isinstance(page, dict):
-                continue
-            # Niveau 1 : words explicites
-            for w in page.get("words") or []:
-                self._maybe_emit_word(w, out)
-            # Niveau 2 : lines avec confidence propagée
-            for line in page.get("lines") or []:
-                self._emit_lines_or_blocks(line, out)
-            # Niveau 3 : blocks avec confidence propagée
-            for block in page.get("blocks") or []:
-                self._emit_lines_or_blocks(block, out)
-        return out or 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
-        out.append({"token": text, "confidence": conf})
-
-    @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
-        for word in text.split():
-            if word:
-                out.append({"token": word, "confidence": conf})

picarones/adapters/legacy_engines/pero_ocr.py

@@ -1,187 +0,0 @@
-"""Adaptateur Pero OCR.
-
-Phase 7.A — module relocalisé depuis ``picarones.engines.pero_ocr``
-vers ``picarones.adapters.legacy_engines.pero_ocr``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
-
-Pero OCR est un moteur HTR/OCR performant sur les documents historiques,
-développé par l'Université technologique de Brno.
-
-Dépendance : pero-ocr  (pip install pero-ocr)
-Dépôt      : https://github.com/DCGM/pero-ocr
-
-Configuration YAML :
-```yaml
-name: pero_ocr
-engine: pero_ocr
-config: /chemin/vers/config.ini   # fichier de configuration Pero OCR
-cuda: false                        # utiliser le GPU si disponible
-expose_confidences: true           # défaut ; expose la confidence par ligne
-                                   # (transcription_confidence) à tous les
-                                   # mots de la ligne, format Sprint 42
-```
-
-Sprint 48 — exposition des token_confidences
----------------------------------------------
-Pero OCR fournit ``line.transcription_confidence`` (probabilité moyenne CTC
-sur la ligne).  L'adapter applique cette confidence à chaque **mot** de la
-ligne (granularité disponible la plus fine sans logits CTC).
-
-Refactor du chantier 1 (post-Sprint 97)
----------------------------------------
-L'adapter ne surcharge plus ``run()`` — il implémente ``_run_with_native``
-et ``_extract_raw_confidences`` (les hooks factorisés dans ``BaseOCREngine``).
-Comportement externe et octets de sortie strictement identiques.
-"""
-
-from __future__ import annotations
-
-import logging
-from pathlib import Path
-from typing import Any, Optional
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-
-try:
-    import numpy as np
-    from PIL import Image
-
-    _PIL_AVAILABLE = True
-except ImportError:
-    _PIL_AVAILABLE = False
-
-try:
-    from pero_ocr.document_ocr.layout import PageLayout
-    from pero_ocr.document_ocr.page_parser import PageParser
-
-    _PERO_AVAILABLE = True
-except ImportError:
-    _PERO_AVAILABLE = False
-
-
-logger = logging.getLogger(__name__)
-
-
-class PeroOCREngine(BaseOCREngine):
-    """Adaptateur pour Pero OCR.
-
-    Pero OCR produit une sortie structurée (PAGE XML) ; cet adaptateur
-    en extrait le texte plat dans l'ordre de lecture naturel et, depuis
-    le Sprint 48, les confidences au niveau mot (héritées de la
-    confidence ligne ``transcription_confidence``).
-
-    Moteur CPU-bound : utilise ``ProcessPoolExecutor`` dans le runner parallèle.
-    """
-
-    execution_mode = "cpu"
-
-    def __init__(self, config: Optional[dict] = None) -> None:
-        super().__init__(config)
-        self._parser: Optional[object] = None
-
-    @property
-    def name(self) -> str:
-        return self.config.get("name", "pero_ocr")
-
-    def version(self) -> str:
-        if not _PERO_AVAILABLE:
-            raise RuntimeError("pero-ocr n'est pas installé.")
-        try:
-            import pero_ocr
-
-            return getattr(pero_ocr, "__version__", "unknown")
-        except Exception as exc:  # noqa: BLE001
-            logger.debug(
-                "[pero_ocr] version non disponible : %s", exc, exc_info=True,
-            )
-            return "unknown"
-
-    def _get_parser(self) -> "PageParser":
-        """Instancie le PageParser (lazy, une seule fois par moteur)."""
-        if self._parser is None:
-            if not _PERO_AVAILABLE:
-                raise RuntimeError(
-                    "pero-ocr n'est pas installé. "
-                    "Installez-le avec : pip install pero-ocr"
-                )
-            config_path = self.config.get("config")
-            if not config_path:
-                raise ValueError(
-                    "La configuration Pero OCR requiert un paramètre 'config' "
-                    "pointant vers un fichier .ini Pero OCR valide."
-                )
-            import configparser
-
-            parser_config = configparser.ConfigParser()
-            parser_config.read(config_path)
-            self._parser = PageParser(parser_config)
-        return self._parser  # type: ignore[return-value]
-
-    def _run_pero_pipeline(self, image_path: Path) -> tuple[str, Any]:
-        """Exécute le pipeline Pero OCR et retourne ``(text, page_layout)``."""
-        if not _PIL_AVAILABLE:
-            raise RuntimeError("Pillow n'est pas installé.")
-
-        parser = self._get_parser()
-
-        image = np.array(Image.open(image_path).convert("RGB"))
-        page_layout = PageLayout(id=image_path.stem, page_size=(image.shape[0], image.shape[1]))
-
-        # Exécution du pipeline Pero OCR
-        parser.process_page(image, page_layout)
-
-        # Extraction du texte plat dans l'ordre des lignes
-        lines = []
-        for region in page_layout.regions:
-            for line in region.lines:
-                if line.transcription:
-                    lines.append(line.transcription.strip())
-
-        return "\n".join(lines), page_layout
-
-    def _run_ocr(self, image_path: Path) -> str:
-        text, _ = self._run_pero_pipeline(image_path)
-        return text
-
-    def _run_with_native(self, image_path: Path) -> tuple[str, Any]:
-        """Exécute Pero OCR et retourne ``(text, page_layout)``.
-
-        Un seul passage du pipeline coûteux ; le ``page_layout``
-        contient toutes les informations nécessaires à l'extraction
-        des confidences (Sprint 48).
-        """
-        return self._run_pero_pipeline(image_path)
-
-    def _extract_raw_confidences(
-        self, native: Any,
-    ) -> Optional[list[dict[str, Any]]]:
-        """Extrait les confidences au niveau mot depuis ``page_layout``.
-
-        Stratégie : pour chaque ligne, on prend
-        ``line.transcription_confidence`` (probabilité CTC moyenne) et
-        on l'applique à chaque mot de la ligne.  Granularité minimale
-        sans déchiffrer les logits CTC, mais suffisante pour la
-        calibration.
-        """
-        if not self.config.get("expose_confidences", True):
-            return None
-        if native is None:
-            return None
-        out: list[dict[str, Any]] = []
-        for region in getattr(native, "regions", []) or []:
-            for line in getattr(region, "lines", []) or []:
-                transcription = getattr(line, "transcription", None)
-                if not transcription:
-                    continue
-                conf = getattr(line, "transcription_confidence", None)
-                if conf is None:
-                    continue
-                for word in transcription.strip().split():
-                    if word:
-                        out.append({"token": word, "confidence": conf})
-        return out or None
-
-    @classmethod
-    def from_config(cls, config: Optional[dict] = None) -> "PeroOCREngine":
-        return cls(config=config or {})

picarones/adapters/legacy_engines/tesseract.py

@@ -1,183 +0,0 @@
-"""Adaptateur Tesseract 5 via pytesseract.
-
-Phase 7.A — module relocalisé depuis ``picarones.engines.tesseract``
-vers ``picarones.adapters.legacy_engines.tesseract``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
-"""
-
-from __future__ import annotations
-
-import logging
-from pathlib import Path
-from typing import Any, Optional
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine
-
-try:
-    import pytesseract
-    from PIL import Image
-
-    _PYTESSERACT_AVAILABLE = True
-except ImportError:
-    _PYTESSERACT_AVAILABLE = False
-
-
-logger = logging.getLogger(__name__)
-
-
-# Correspondance des valeurs PSM acceptées en argument YAML/CLI
-_PSM_LABELS = {
-    0: "Orientation and script detection only",
-    1: "Automatic page segmentation with OSD",
-    3: "Fully automatic page segmentation (default)",
-    4: "Single column of text",
-    5: "Single uniform block of vertically aligned text",
-    6: "Single uniform block of text",
-    7: "Single text line",
-    8: "Single word",
-    9: "Single word in a circle",
-    10: "Single character",
-    11: "Sparse text",
-    12: "Sparse text with OSD",
-    13: "Raw line",
-}
-
-
-class TesseractEngine(BaseOCREngine):
-    """Adaptateur pour Tesseract 5 (via pytesseract).
-
-    Moteur CPU-bound : utilise ``ProcessPoolExecutor`` dans le runner parallèle.
-
-    Configuration YAML :
-    ```yaml
-    name: tesseract
-    engine: tesseract
-    lang: fra          # code langue Tesseract (fra, lat, eng, ...)
-    psm: 6             # Page Segmentation Mode (0-13)
-    oem: 3             # OCR Engine Mode (0=legacy, 3=LSTM, 3=default)
-    tesseract_cmd: tesseract  # chemin vers l'exécutable si non standard
-    expose_confidences: true  # défaut ; mettre à false pour économiser
-                              # un appel image_to_data par document
-    ```
-
-    Sprint 47 — exposition des token_confidences
-    --------------------------------------------
-    L'adapter appelle ``image_to_data`` en parallèle de
-    ``image_to_string`` pour produire ``EngineResult.token_confidences``
-    (liste de ``{"token": str, "confidence": float}``).  Le runner
-    Sprint 42 calcule alors automatiquement la calibration ECE/MCE.
-
-    Le texte ``EngineResult.text`` reste **strictement identique** à
-    celui produit par ``image_to_string`` (pas de reconstruction depuis
-    ``image_to_data``) — rétrocompatibilité octet par octet.
-
-    Le coût supplémentaire est d'un second appel Tesseract par image.
-    Pour le désactiver : ``expose_confidences: false`` dans la config.
-
-    Refactor du chantier 1 (post-Sprint 97)
-    ---------------------------------------
-    L'adapter ne surcharge plus ``run()`` — il implémente
-    ``_run_with_native`` et ``_extract_raw_confidences`` (les hooks
-    factorisés dans ``BaseOCREngine``).  Comportement externe et
-    octets de sortie strictement identiques aux versions Sprint 47+.
-    """
-
-    execution_mode = "cpu"
-
-    @property
-    def name(self) -> str:
-        return self.config.get("name", "tesseract")
-
-    def version(self) -> str:
-        if not _PYTESSERACT_AVAILABLE:
-            raise RuntimeError("pytesseract n'est pas installé.")
-        return pytesseract.get_tesseract_version().vstring
-
-    def _tesseract_args(self) -> tuple[str, str]:
-        """Retourne ``(lang, custom_config)`` selon la config courante.
-
-        Centralisé pour rester cohérent entre ``_run_ocr`` et
-        ``_run_with_native``.
-        """
-        lang = self.config.get("lang", "fra")
-        psm = int(self.config.get("psm", 6))
-        oem = int(self.config.get("oem", 3))
-        return lang, f"--oem {oem} --psm {psm}"
-
-    def _apply_tesseract_cmd(self) -> None:
-        """Applique le chemin Tesseract custom si la config en fournit un."""
-        tesseract_cmd = self.config.get("tesseract_cmd")
-        if tesseract_cmd:
-            pytesseract.pytesseract.tesseract_cmd = tesseract_cmd
-
-    def _run_ocr(self, image_path: Path) -> str:
-        if not _PYTESSERACT_AVAILABLE:
-            raise RuntimeError(
-                "pytesseract n'est pas installé. "
-                "Installez-le avec : pip install pytesseract"
-            )
-
-        self._apply_tesseract_cmd()
-        lang, custom_config = self._tesseract_args()
-        image = Image.open(image_path)
-        text: str = pytesseract.image_to_string(image, lang=lang, config=custom_config)
-        return text.strip()
-
-    def _run_with_native(self, image_path: Path) -> tuple[str, Optional[dict]]:
-        """Appelle ``image_to_string`` puis ``image_to_data``.
-
-        Retourne ``(text, image_to_data_dict)`` — la deuxième valeur
-        peut être ``None`` si ``expose_confidences`` est à ``False``
-        ou si l'appel ``image_to_data`` échoue (best-effort).
-
-        Le texte reste **identique** à celui produit par
-        ``_run_ocr`` (rétrocompat octet par octet — Sprint 47).
-        """
-        text = self._run_ocr(image_path)
-        if not self.config.get("expose_confidences", True):
-            return text, None
-        try:
-            self._apply_tesseract_cmd()
-            lang, custom_config = self._tesseract_args()
-            image = Image.open(image_path)
-            data = pytesseract.image_to_data(
-                image,
-                lang=lang,
-                config=custom_config,
-                output_type=pytesseract.Output.DICT,
-            )
-            return text, data
-        except Exception as exc:  # noqa: BLE001
-            logger.warning(
-                "[tesseract] extraction des token_confidences "
-                "(image_to_data) indisponible : %s — calibration "
-                "sautée pour ce document",
-                exc,
-            )
-            return text, None
-
-    def _extract_raw_confidences(
-        self, native: Any,
-    ) -> Optional[list[dict[str, Any]]]:
-        """Parse le ``image_to_data`` dict de Tesseract.
-
-        Format Tesseract : dict ``{"text": [...], "conf": [...], ...}``
-        avec confidences ∈ [0, 100] et ``-1`` pour les segments
-        non-mots — ces derniers sont écartés par
-        ``_normalize_token_confidences`` (filtre les conf < 0).
-        """
-        if not isinstance(native, dict):
-            return None
-        texts = native.get("text") or []
-        confs = native.get("conf") or []
-        if not texts or len(texts) != len(confs):
-            return None
-        out: list[dict[str, Any]] = []
-        for tok_text, conf in zip(texts, confs):
-            out.append({"token": tok_text, "confidence": conf})
-        return out or None
-
-    @classmethod
-    def from_config(cls, config: Optional[dict] = None) -> "TesseractEngine":
-        return cls(config=config or {})

picarones/adapters/legacy_pipelines/__init__.py

@@ -1,34 +0,0 @@
-"""Pipelines OCR+LLM legacy — Sprint C du plan v2.0 (mai 2026).
-
-Sous-package transitoire qui contient ``OCRLLMPipeline`` (legacy)
-et son helper ``_executor_runner``.  Pendant la phase de retrait
-du legacy, ces modules vivent ici plutôt que dans
-``picarones.pipelines/`` (top-level) pour respecter l'invariant
-architectural ``test_layer_imports_are_legal`` — la couche
-``adapters/`` autorise les imports legacy par design.
-
-Périmètre
----------
-- ``base.OCRLLMPipeline`` — wrapper composé OCR+LLM (3 modes).
-  Délègue à ``picarones.pipeline.PipelineExecutor`` depuis
-  Sprint B du plan v2.0.
-- ``_executor_runner.run_pipeline_via_executor`` — pont
-  mono-document utilisé par ``OCRLLMPipeline.run()``.
-
-Trace de retrait
-----------------
-Ce sous-package sera supprimé entièrement quand
-``OCRLLMPipeline`` n'aura plus aucun consommateur externe (les
-callers actuels — ``web/benchmark_utils.py``, tests Sprint 3 et
-15 — passeront alors à la construction directe d'une
-``PipelineSpec`` via ``picarones.pipeline.make_ocr_llm_pipeline_spec``).
-"""
-
-from __future__ import annotations
-
-from picarones.adapters.legacy_pipelines.base import (
-    OCRLLMPipeline,
-    PipelineMode,
-)
-
-__all__ = ["OCRLLMPipeline", "PipelineMode"]

picarones/adapters/legacy_pipelines/_executor_runner.py

@@ -1,410 +0,0 @@
-"""Helper d'exécution mono-document via ``PipelineExecutor`` (Sprint B).
-
-Sprint B du plan v2.0 — pont entre l'API mono-document
-``OCRLLMPipeline.run(image_path) -> EngineResult`` (legacy) et le
-``PipelineExecutor`` du rewrite.
-
-Ce helper isole toute la plomberie nécessaire pour exécuter une
-``PipelineSpec`` sur un seul document avec :
-
-- création d'un ``tempdir`` éphémère comme ``workspace_uri`` ;
-- adapter resolver minimal qui mappe les noms de la spec aux
-  instances OCR/LLM portées par le ``OCRLLMPipeline`` ;
-- conversion du ``PipelineResult`` en ``EngineResult`` legacy ;
-- préservation des warnings comportementaux du legacy
-  (texte OCR vide, texte LLM vide, erreur pipeline globale).
-
-Trace de retrait
-----------------
-Ce module est temporaire (Sprint B-D du plan v2.0).  Il sera
-supprimé en Sprint C quand les 3 callers (``web/benchmark_utils``,
-``measurements/runner/orchestration``, ``fixtures``) consommeront
-des ``PipelineSpec`` directement plutôt que des ``OCRLLMPipeline``.
-"""
-
-from __future__ import annotations
-
-import logging
-import tempfile
-import time
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional
-
-from picarones.adapters.legacy_engines._step_executor import (
-    LegacyOCREngineExecutor,
-)
-from picarones.adapters.legacy_engines.base import EngineResult
-from picarones.domain.artifacts import Artifact, ArtifactType
-from picarones.domain.documents import DocumentRef
-from picarones.domain.pipeline_spec import (
-    INITIAL_STEP_ID,
-    PipelineSpec,
-    PipelineStep,
-)
-from picarones.pipeline import (
-    PipelineExecutor,
-    RunContext,
-    make_ocr_llm_pipeline_spec,
-)
-
-if TYPE_CHECKING:
-    from picarones.adapters.legacy_pipelines.base import OCRLLMPipeline
-
-
-logger = logging.getLogger("picarones.pipelines.base")
-
-
-def run_pipeline_via_executor(
-    pipeline: "OCRLLMPipeline",
-    image_path: Path,
-    *,
-    ocr_text: Optional[str] = None,
-) -> EngineResult:
-    """Exécute une chaîne OCR+LLM via ``PipelineExecutor``.
-
-    Cas 1 — ``ocr_text=None`` (run() classique) :
-        Modes ``text_only`` / ``text_and_image`` / ``zero_shot``.
-        La spec a un step OCR (sauf zero-shot) + un step LLM.
-
-    Cas 2 — ``ocr_text`` fourni (run_with_ocr_text, corpus triplet) :
-        Le texte OCR est pré-calculé.  La spec n'a qu'un step LLM
-        qui consomme ``RAW_TEXT`` directement depuis les inputs
-        initiaux (pas d'OCR engine appelé).
-
-    Parameters
-    ----------
-    pipeline:
-        L'instance ``OCRLLMPipeline`` qui porte ``ocr_engine``,
-        ``llm_adapter``, ``mode`` et ``_prompt_template``.
-    image_path:
-        Chemin de l'image à transcrire.
-    ocr_text:
-        Si fourni, mode "post-correction" — le LLM reçoit ce texte
-        directement, sans appel OCR.
-
-    Returns
-    -------
-    EngineResult
-        Format legacy compatible avec ``BaseOCREngine.run()``.  Les
-        métadonnées portent ``pipeline_mode``, ``pipeline_steps``,
-        ``llm_model``, ``llm_provider``, ``ocr_intermediate``,
-        ``is_pipeline=True`` etc.
-    """
-    start = time.perf_counter()
-
-    # Le LLM peut être un BaseLLMAdapter ou un BaseVLMAdapter — les
-    # deux exposent .name et .model.  On compose un identifiant
-    # ``provider:model`` stable pour le adapter resolver.
-    llm_name = f"{pipeline.llm_adapter.name}:{pipeline.llm_adapter.model}"
-
-    with tempfile.TemporaryDirectory(prefix="picarones_pipe_") as ws:
-        workspace = Path(ws)
-
-        # ── Construit la spec adaptée au cas (avec ou sans OCR)
-        if ocr_text is None:
-            spec, ocr_step_executor = _build_spec_for_run(
-                pipeline=pipeline,
-                llm_name=llm_name,
-            )
-            initial_inputs = {
-                ArtifactType.IMAGE: _make_image_artifact(image_path, "doc"),
-            }
-        else:
-            spec, ocr_step_executor = _build_spec_for_run_with_ocr_text(
-                pipeline=pipeline,
-                llm_name=llm_name,
-            )
-            # Écrire le texte OCR pré-fourni dans le workspace pour
-            # qu'il soit accessible via Artifact.uri.
-            text_path = workspace / "ocr_input.txt"
-            text_path.write_text(ocr_text, encoding="utf-8")
-            initial_inputs = {
-                ArtifactType.IMAGE: _make_image_artifact(image_path, "doc"),
-                ArtifactType.RAW_TEXT: Artifact(
-                    id="doc:initial:raw_text",
-                    document_id="doc",
-                    type=ArtifactType.RAW_TEXT,
-                    uri=str(text_path),
-                ),
-            }
-
-        # ── Adapter resolver — mappe les noms de la spec aux instances
-        def resolver(name: str) -> Any:
-            if ocr_step_executor is not None and (
-                pipeline.ocr_engine is not None
-                and name == pipeline.ocr_engine.name
-            ):
-                return ocr_step_executor
-            if name == llm_name:
-                return pipeline.llm_adapter
-            raise KeyError(f"adapter inconnu pour la spec : {name!r}")
-
-        document = DocumentRef(id="doc", image_uri=str(image_path))
-        context = RunContext(
-            document_id="doc",
-            code_version=_safe_code_version(),
-            pipeline_name=spec.name,
-            workspace_uri=str(workspace),
-        )
-
-        executor = PipelineExecutor(adapter_resolver=resolver)
-        try:
-            result = executor.run(spec, document, initial_inputs, context)
-            error: Optional[str] = None
-        except Exception as exc:  # noqa: BLE001
-            logger.warning(
-                "[%s] erreur pipeline pour '%s' : %s",
-                pipeline.name, image_path.name, exc,
-            )
-            return _engine_result_failure(
-                pipeline=pipeline,
-                image_path=image_path,
-                error=str(exc),
-                duration=time.perf_counter() - start,
-                ocr_text=ocr_text,
-            )
-
-        # ── Récupère le texte final depuis le bag d'artifacts
-        text, ocr_intermediate = _extract_outputs(
-            result=result,
-            mode=pipeline.mode.value,
-            ocr_text=ocr_text,
-        )
-
-        # ── Préserve les warnings comportementaux du legacy
-        if ocr_text is None and pipeline.mode.value != "zero_shot":
-            if ocr_intermediate is not None and not ocr_intermediate.strip():
-                logger.warning(
-                    "[%s] texte OCR vide pour '%s' — le LLM recevra "
-                    "{ocr_output} vide.",
-                    pipeline.name, image_path.name,
-                )
-        if not text or not 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) ?",
-                pipeline.name, pipeline.llm_adapter.model, image_path.name,
-            )
-
-        # ── Si le pipeline a échoué (un step en error), on traduit
-        # l'erreur du premier step en échec en EngineResult.error.
-        if not result.succeeded:
-            failed_step = next(
-                (s for s in result.step_results if s.error is not None),
-                None,
-            )
-            error = failed_step.error if failed_step is not None else "pipeline failed"
-
-        duration = time.perf_counter() - start
-
-        metadata = _build_metadata(
-            pipeline=pipeline,
-            ocr_intermediate=ocr_intermediate,
-            ocr_source="corpus" if ocr_text is not None else None,
-        )
-
-        return EngineResult(
-            engine_name=pipeline.name,
-            image_path=str(image_path),
-            text=text if text else "",
-            duration_seconds=round(duration, 4),
-            error=error,
-            metadata=metadata,
-        )
-
-
-# ──────────────────────────────────────────────────────────────────────
-# Helpers privés
-# ──────────────────────────────────────────────────────────────────────
-
-
-def _build_spec_for_run(
-    pipeline: "OCRLLMPipeline",
-    llm_name: str,
-) -> tuple[PipelineSpec, Optional[LegacyOCREngineExecutor]]:
-    """Spec pour ``run()`` — mode text_only / text_and_image / zero_shot."""
-    mode = pipeline.mode.value
-    llm_params = {"prompt_template": pipeline._prompt_template}
-
-    if mode == "zero_shot":
-        spec = make_ocr_llm_pipeline_spec(
-            mode="zero_shot",
-            llm_adapter_name=llm_name,
-            llm_params=llm_params,
-        )
-        return spec, None
-
-    if pipeline.ocr_engine is None:
-        raise ValueError(
-            f"ocr_engine est requis pour le mode {mode!r} — "
-            "utiliser run_with_ocr_text() pour la post-correction sans engine."
-        )
-    ocr_step = LegacyOCREngineExecutor(pipeline.ocr_engine)
-    spec = make_ocr_llm_pipeline_spec(
-        mode=mode,
-        ocr_adapter_name=pipeline.ocr_engine.name,
-        llm_adapter_name=llm_name,
-        llm_params=llm_params,
-    )
-    return spec, ocr_step
-
-
-def _build_spec_for_run_with_ocr_text(
-    pipeline: "OCRLLMPipeline",
-    llm_name: str,
-) -> tuple[PipelineSpec, None]:
-    """Spec pour ``run_with_ocr_text()`` — 1 seul step LLM, RAW_TEXT
-    et IMAGE viennent des inputs initiaux."""
-    mode = pipeline.mode.value
-    llm_params = {"prompt_template": pipeline._prompt_template}
-
-    llm_input_types: list[ArtifactType] = [ArtifactType.RAW_TEXT]
-    llm_inputs_from: dict[ArtifactType, str] = {
-        ArtifactType.RAW_TEXT: INITIAL_STEP_ID,
-    }
-    if mode == "text_and_image":
-        llm_input_types.append(ArtifactType.IMAGE)
-        llm_inputs_from[ArtifactType.IMAGE] = INITIAL_STEP_ID
-
-    spec = PipelineSpec(
-        name=f"post_correction_{mode}_{_safe_name_for_id(llm_name)}",
-        description=(
-            f"Post-correction LLM mono-step (mode {mode}, "
-            f"texte OCR pré-fourni)"
-        ),
-        initial_inputs=(ArtifactType.IMAGE, ArtifactType.RAW_TEXT),
-        steps=(
-            PipelineStep(
-                id="llm",
-                kind="post_correction",
-                adapter_name=llm_name,
-                params=llm_params,
-                input_types=tuple(llm_input_types),
-                output_types=(ArtifactType.CORRECTED_TEXT,),
-                inputs_from=llm_inputs_from,
-            ),
-        ),
-    )
-    return spec, None
-
-
-def _make_image_artifact(image_path: Path, doc_id: str) -> Artifact:
-    return Artifact(
-        id=f"{doc_id}:initial:image",
-        document_id=doc_id,
-        type=ArtifactType.IMAGE,
-        uri=str(image_path),
-    )
-
-
-def _extract_outputs(
-    *,
-    result: Any,
-    mode: str,
-    ocr_text: Optional[str],
-) -> tuple[str, Optional[str]]:
-    """Extrait ``(text_final, ocr_intermediate)`` du PipelineResult.
-
-    En zero_shot : le VLM produit ``RAW_TEXT`` final.  Pas
-    d'``ocr_intermediate``.
-
-    En text_only / text_and_image : le LLM produit ``CORRECTED_TEXT``.
-    L'``ocr_intermediate`` est l'``RAW_TEXT`` produit par l'OCR ou
-    fourni via ``ocr_text`` (mode triplet).
-    """
-    text_final = ""
-    ocr_intermediate: Optional[str] = ocr_text
-
-    if mode == "zero_shot":
-        # Le step VLM produit RAW_TEXT en sortie finale.
-        for art in result.artifacts:
-            if art.type == ArtifactType.RAW_TEXT and art.uri:
-                text_final = Path(art.uri).read_text(encoding="utf-8")
-                break
-        return text_final, None
-
-    # text_only / text_and_image : prendre CORRECTED_TEXT
-    for art in result.artifacts:
-        if art.type == ArtifactType.CORRECTED_TEXT and art.uri:
-            text_final = Path(art.uri).read_text(encoding="utf-8")
-            break
-
-    # ocr_intermediate : si pas fourni, lire le RAW_TEXT produit
-    if ocr_intermediate is None:
-        for art in result.artifacts:
-            if art.type == ArtifactType.RAW_TEXT and art.uri:
-                ocr_intermediate = Path(art.uri).read_text(encoding="utf-8")
-                break
-
-    return text_final, ocr_intermediate
-
-
-def _build_metadata(
-    *,
-    pipeline: "OCRLLMPipeline",
-    ocr_intermediate: Optional[str],
-    ocr_source: Optional[str],
-) -> dict:
-    metadata: dict = {
-        "engine_version": pipeline._safe_version(),
-        "pipeline_mode": pipeline.mode.value,
-        "prompt_file": pipeline.prompt_path,
-        "prompt_template": pipeline._prompt_template,
-        "llm_model": pipeline.llm_adapter.model,
-        "llm_provider": pipeline.llm_adapter.name,
-        "pipeline_steps": pipeline._build_steps_info(),
-        "is_pipeline": True,
-    }
-    if ocr_intermediate is not None:
-        metadata["ocr_intermediate"] = ocr_intermediate
-    if ocr_source is not None:
-        metadata["ocr_source"] = ocr_source
-    return metadata
-
-
-def _engine_result_failure(
-    *,
-    pipeline: "OCRLLMPipeline",
-    image_path: Path,
-    error: str,
-    duration: float,
-    ocr_text: Optional[str],
-) -> EngineResult:
-    """Construit un ``EngineResult`` en échec quand l'executor lève."""
-    metadata = _build_metadata(
-        pipeline=pipeline,
-        ocr_intermediate=ocr_text,
-        ocr_source="corpus" if ocr_text is not None else None,
-    )
-    return EngineResult(
-        engine_name=pipeline.name,
-        image_path=str(image_path),
-        text="",
-        duration_seconds=round(duration, 4),
-        error=error,
-        metadata=metadata,
-    )
-
-
-def _safe_code_version() -> str:
-    try:
-        from picarones import __version__
-        return __version__
-    except ImportError:
-        return "unknown"
-
-
-def _safe_name_for_id(s: str) -> str:
-    return (
-        s.replace(":", "_")
-        .replace("/", "_")
-        .replace("-", "_")
-        .replace(".", "_")
-        .lower()
-    )
-
-
-__all__ = ["run_pipeline_via_executor"]

picarones/adapters/legacy_pipelines/base.py

@@ -1,338 +0,0 @@
-"""Pipeline OCR+LLM — présenté comme un concurrent normal dans les benchmarks.
-
-Un pipeline compose un moteur OCR et un LLM de correction selon trois modes :
-
-  text_only      → OCR brut ──► LLM (texte seul)
-  text_and_image → OCR brut + image ──► LLM multimodal
-  zero_shot      → image ──► LLM (pas d'OCR amont)
-
-La classe ``OCRLLMPipeline`` étend ``BaseOCREngine`` : un pipeline est
-un concurrent comme un autre dans ``run_benchmark``, avec les mêmes métriques
-CER/WER. Les métadonnées spécifiques (étapes, prompt, OCR intermédiaire) sont
-exposées via ``EngineResult.metadata``.
-"""
-
-from __future__ import annotations
-
-import base64
-import logging
-from enum import Enum
-from pathlib import Path
-from typing import Optional
-
-from picarones.adapters.legacy_engines.base import BaseOCREngine, EngineResult
-from picarones.adapters.llm.base import BaseLLMAdapter
-
-logger = logging.getLogger(__name__)
-
-
-class PipelineMode(str, Enum):
-    """Mode d'appel LLM dans le pipeline."""
-
-    TEXT_ONLY = "text_only"
-    """Le LLM reçoit uniquement le texte OCR brut."""
-
-    TEXT_AND_IMAGE = "text_and_image"
-    """Le LLM reçoit le texte OCR ET l'image (mode multimodal)."""
-
-    ZERO_SHOT = "zero_shot"
-    """Le LLM reçoit uniquement l'image — aucun OCR amont."""
-
-
-# Répertoire de la bibliothèque de prompts intégrée.
-# Sprint C du plan v2.0 : ce module a quitté ``picarones/pipelines/``
-# pour ``picarones/adapters/legacy_pipelines/``.  Le répertoire des
-# prompts vit toujours dans ``picarones/prompts/`` (top-level), donc
-# 3 niveaux au-dessus du ``__file__`` actuel.
-_PROMPTS_DIR = Path(__file__).resolve().parent.parent.parent / "prompts"
-
-
-def _load_prompt(prompt_path: str | Path) -> str:
-    """Charge un prompt depuis un chemin absolu, relatif ou depuis la bibliothèque intégrée."""
-    p = Path(prompt_path)
-    if p.is_absolute() and p.exists():
-        return p.read_text(encoding="utf-8")
-    # Chemin relatif : chercher d'abord dans le CWD, puis dans la bibliothèque
-    if p.exists():
-        return p.read_text(encoding="utf-8")
-    builtin = _PROMPTS_DIR / p
-    if builtin.exists():
-        return builtin.read_text(encoding="utf-8")
-    raise FileNotFoundError(
-        f"Prompt introuvable : '{prompt_path}'. "
-        f"Bibliothèque disponible dans : {_PROMPTS_DIR}"
-    )
-
-
-def _image_to_b64(image_path: Path) -> str:
-    """Encode une image en base64 pur (sans préfixe data URI)."""
-    return base64.b64encode(image_path.read_bytes()).decode("ascii")
-
-
-class OCRLLMPipeline(BaseOCREngine):
-    """Pipeline OCR+LLM, interchangeable avec n'importe quel moteur OCR.
-
-    Parameters
-    ----------
-    llm_adapter:
-        Adaptateur LLM (OpenAI, Anthropic, Mistral, Ollama…).
-    mode:
-        Mode de correction — text_only, text_and_image, ou zero_shot.
-    prompt:
-        Chemin vers un fichier .txt de prompt, ou nom d'un fichier de la
-        bibliothèque intégrée (ex : ``"correction_medieval_french.txt"``).
-        Variables disponibles dans le fichier : ``{ocr_output}`` et ``{image_b64}``.
-    ocr_engine:
-        Moteur OCR amont. Obligatoire pour text_only et text_and_image.
-        Non utilisé en mode zero_shot.
-    pipeline_name:
-        Nom affiché dans le rapport (ex : ``"tesseract → gpt-4o"``).
-        Généré automatiquement si non fourni.
-    config:
-        Paramètres supplémentaires passés à la classe de base.
-
-    Examples
-    --------
-    >>> from picarones.adapters.llm import OpenAIAdapter
-    >>> from picarones.adapters.legacy_engines.tesseract import TesseractEngine
-    >>> pipeline = OCRLLMPipeline(
-    ...     ocr_engine=TesseractEngine({"lang": "fra"}),
-    ...     llm_adapter=OpenAIAdapter(model="gpt-4o"),
-    ...     mode=PipelineMode.TEXT_AND_IMAGE,
-    ...     prompt="correction_medieval_french.txt",
-    ... )
-    """
-
-    def __init__(
-        self,
-        llm_adapter: BaseLLMAdapter,
-        mode: PipelineMode | str = PipelineMode.TEXT_ONLY,
-        prompt: str | Path = "correction_medieval_french.txt",
-        ocr_engine: Optional[BaseOCREngine] = None,
-        pipeline_name: Optional[str] = None,
-        config: Optional[dict] = None,
-    ) -> None:
-        super().__init__(config)
-        self.ocr_engine = ocr_engine
-        self.llm_adapter = llm_adapter
-        self.mode = PipelineMode(mode)
-        self.prompt_path = str(prompt)
-        self._prompt_template = _load_prompt(prompt)
-
-        # Nom affiché dans le rapport
-        if pipeline_name:
-            self._name = pipeline_name
-        elif self.mode == PipelineMode.ZERO_SHOT:
-            self._name = f"{llm_adapter.model} (zero-shot)"
-        elif ocr_engine:
-            self._name = f"{ocr_engine.name} → {llm_adapter.model}"
-        else:
-            self._name = f"pipeline → {llm_adapter.model}"
-
-
-    # ------------------------------------------------------------------
-    # Interface BaseOCREngine
-    # ------------------------------------------------------------------
-
-    #: Sprint C du plan v2.0 : marqueur polymorphe que le runner
-    #: utilise pour ajouter ``pipeline_steps`` + ``prompt_template``
-    #: aux ``EngineReport.pipeline_info`` sans avoir à connaître le
-    #: type concret ``OCRLLMPipeline``.
-    is_pipeline: bool = True
-
-    @property
-    def name(self) -> str:
-        return self._name
-
-    def version(self) -> str:
-        ocr_v = self.ocr_engine._safe_version() if self.ocr_engine else "—"
-        return f"ocr={ocr_v}; llm={self.llm_adapter.model}"
-
-    @property
-    def pipeline_steps_info(self) -> list[dict]:
-        """Description structurée des étapes (Sprint C — API publique).
-
-        Substitut public à ``_build_steps_info()`` pour les callers
-        externes (notamment le runner) qui ont besoin de connaître la
-        composition de la pipeline pour la metadata du rapport.
-        """
-        return self._build_steps_info()
-
-    @property
-    def prompt_template(self) -> str:
-        """Template de prompt courant (Sprint C — API publique)."""
-        return self._prompt_template
-
-    def _run_llm_step(
-        self, image_path: Path, ocr_text: str,
-    ) -> tuple[str, Optional[str]]:
-        """Étape LLM du pipeline (commune à run() et run_with_ocr_text()).
-
-        Construit le prompt, appelle le LLM, retourne ``(llm_text, ocr_intermediate)``.
-        ``ocr_intermediate`` est ``None`` en mode zero_shot.
-        """
-        if self.mode == PipelineMode.ZERO_SHOT:
-            image_b64 = _image_to_b64(image_path)
-            prompt = self._build_prompt(image_b64=image_b64)
-            logger.info("[Pipeline] appel LLM pour doc %s (zero-shot)", image_path.name)
-            result = self.llm_adapter.complete(prompt, image_b64=image_b64)
-
-        elif self.mode == PipelineMode.TEXT_ONLY:
-            if not ocr_text.strip():
-                logger.warning(
-                    "[%s] texte OCR vide pour '%s' — le LLM recevra {ocr_output} vide.",
-                    self._name, image_path.name,
-                )
-            prompt = self._build_prompt(ocr_text=ocr_text)
-            logger.info(
-                "[Pipeline] appel LLM pour doc %s (text_only, ocr=%d chars)",
-                image_path.name, len(ocr_text),
-            )
-            result = self.llm_adapter.complete(prompt)
-
-        else:  # TEXT_AND_IMAGE
-            if not ocr_text.strip():
-                logger.warning(
-                    "[%s] texte OCR vide pour '%s' — le LLM recevra {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)
-            logger.info(
-                "[Pipeline] appel LLM pour doc %s (text_and_image, ocr=%d chars)",
-                image_path.name, len(ocr_text),
-            )
-            result = self.llm_adapter.complete(prompt, image_b64=image_b64)
-
-        logger.info("[Pipeline] LLM retourné pour doc %s", image_path.name)
-
-        if not result.success:
-            raise RuntimeError(f"Erreur LLM ({self.llm_adapter.model}): {result.error}")
-
-        llm_text = result.text
-        logger.info(
-            "[Pipeline] %s — OCR: %d chars → LLM: %d chars",
-            image_path.name, len(ocr_text), len(llm_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],
-            )
-
-        ocr_intermediate = ocr_text if self.mode != PipelineMode.ZERO_SHOT else None
-        return llm_text, ocr_intermediate
-
-    def _run_ocr(self, image_path: Path) -> tuple[str, Optional[str]]:
-        """Logique interne du pipeline — lance l'OCR engine puis le LLM.
-
-        Returns
-        -------
-        tuple[str, Optional[str]]
-            (llm_text, ocr_intermediate) — ocr_intermediate est None en mode zero_shot.
-        """
-        ocr_text = ""
-        if self.mode != PipelineMode.ZERO_SHOT:
-            if self.ocr_engine is None:
-                raise ValueError(
-                    f"ocr_engine est requis pour le mode {self.mode.value} "
-                    "(utilisez run_with_ocr_text() pour la post-correction sans OCR engine)"
-                )
-            ocr_result = self.ocr_engine.run(image_path)
-            ocr_text = ocr_result.text
-
-        return self._run_llm_step(image_path, ocr_text)
-
-    # ------------------------------------------------------------------
-    # Override run() pour injecter les métadonnées pipeline
-    # ------------------------------------------------------------------
-
-    def run(self, image_path: str | Path) -> EngineResult:
-        """Exécute le pipeline et retourne un EngineResult enrichi de métadonnées.
-
-        Sprint B du plan v2.0 — délègue à
-        ``picarones.pipelines._executor_runner.run_pipeline_via_executor``
-        qui exécute la chaîne OCR+LLM via le ``PipelineExecutor`` du
-        rewrite.  L'API publique (``EngineResult`` retourné, métadonnées,
-        warnings) reste identique au comportement historique.
-        """
-        from picarones.adapters.legacy_pipelines._executor_runner import (
-            run_pipeline_via_executor,
-        )
-
-        return run_pipeline_via_executor(self, Path(image_path))
-
-    # ------------------------------------------------------------------
-    # Post-correction avec OCR pré-calculé
-    # ------------------------------------------------------------------
-
-    def run_with_ocr_text(
-        self, image_path: str | Path, ocr_text: str,
-    ) -> EngineResult:
-        """Exécute le pipeline avec un texte OCR pré-fourni (corpus triplet).
-
-        Utilisé quand le corpus contient des fichiers ``.ocr.txt`` : le
-        texte OCR bruité est fourni directement, sans lancer de moteur OCR.
-
-        Sprint B du plan v2.0 — délègue à
-        ``picarones.pipelines._executor_runner.run_pipeline_via_executor``
-        avec ``ocr_text=ocr_text``.  La spec construite n'a qu'un seul
-        step LLM et reçoit ``RAW_TEXT`` directement dans ses
-        ``initial_inputs``.
-
-        Parameters
-        ----------
-        image_path:
-            Chemin de l'image (utilisée en mode multimodal, ignorée en text_only).
-        ocr_text:
-            Texte OCR bruité pré-calculé.
-
-        Returns
-        -------
-        EngineResult
-        """
-        from picarones.adapters.legacy_pipelines._executor_runner import (
-            run_pipeline_via_executor,
-        )
-
-        return run_pipeline_via_executor(
-            self, Path(image_path), ocr_text=ocr_text,
-        )
-
-    # ------------------------------------------------------------------
-    # Helpers
-    # ------------------------------------------------------------------
-
-    def _build_prompt(self, ocr_text: str = "", image_b64: str = "") -> str:
-        """Substitue {ocr_output} et {image_b64} dans le template de prompt."""
-        return (
-            self._prompt_template
-            .replace("{ocr_output}", ocr_text)
-            .replace("{image_b64}", image_b64)
-        )
-
-    def _build_steps_info(self) -> list[dict]:
-        steps: list[dict] = []
-        if self.ocr_engine:
-            steps.append({
-                "type": "ocr",
-                "engine": self.ocr_engine.name,
-                "version": self.ocr_engine._safe_version(),
-            })
-        steps.append({
-            "type": "llm",
-            "model": self.llm_adapter.model,
-            "provider": self.llm_adapter.name,
-            "mode": self.mode.value,
-            "prompt_file": self.prompt_path,
-        })
-        return steps

picarones/app/services/_legacy_runner_adapter.py

@@ -37,9 +37,11 @@ import logging
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable
 
-from picarones.adapters.legacy_engines._step_executor import (
-    LegacyOCREngineExecutor,
-)
+# Sprint H.2.c.1 — ``LegacyOCREngineExecutor`` n'est plus consommé :
+# tous les callers passent désormais des ``BaseOCRAdapter`` canoniques
+# (déjà ``StepExecutor`` natifs).  L'import est retiré ; le code path
+# legacy de ``build_adapter_resolver`` est désormais inaccessible et
+# peut être supprimé en H.2.c.2.
 from picarones.domain.artifacts import ArtifactType
 from picarones.domain.corpus import CorpusSpec
 from picarones.domain.documents import DocumentRef, GroundTruthRef
@@ -52,7 +54,6 @@ from picarones.domain.pipeline_spec import (
 from picarones.pipeline.llm_pipeline_builder import make_ocr_llm_pipeline_spec
 
 if TYPE_CHECKING:
-    from picarones.adapters.legacy_engines.base import BaseOCREngine
     from picarones.evaluation.corpus import Corpus, Document
 
 logger = logging.getLogger(__name__)
@@ -516,26 +517,22 @@ def _is_canonical_adapter(engine: Any) -> bool:
 def engine_to_pipeline_spec(engine: Any) -> PipelineSpec:
     """Convertit un engine en ``PipelineSpec`` rewrite.
 
-    Trois cas :
+    Deux cas (Sprint H.2.c — le path legacy ``BaseOCREngine`` a
+    été retiré) :
 
-    - **BaseOCRAdapter** (canonique, Sprint H.2.b) : spec mono-step
-      consommant ``engine.input_types`` et produisant
-      ``engine.output_types``.  Pas de wrapping nécessaire — l'adapter
-      est déjà un ``StepExecutor``.
-    - **OCRLLMPipeline** (``engine.is_pipeline = True``) : la spec
-      composée est construite via ``make_ocr_llm_pipeline_spec``
+    - **BaseOCRAdapter** (canonique) : spec mono-step consommant
+      ``engine.input_types`` et produisant ``engine.output_types``.
+    - **OCRLLMPipelineConfig** (``engine.is_pipeline = True``) : la
+      spec composée est construite via ``make_ocr_llm_pipeline_spec``
       avec le mode (``text_only`` / ``text_and_image`` /
       ``zero_shot``), l'OCR amont (s'il existe), le LLM, et le
       template de prompt en ``llm_params``.
-    - **BaseOCREngine** (legacy) : spec mono-step (IMAGE → RAW_TEXT).
-      Le step référencera ``engine.name`` ; le caller l'enregistre
-      dans l'adapter resolver via un ``LegacyOCREngineExecutor(engine)``.
 
     Parameters
     ----------
     engine:
-        Instance d'un ``BaseOCRAdapter`` canonique, d'un
-        ``BaseOCREngine`` legacy, ou d'un ``OCRLLMPipeline``.
+        Instance d'un ``BaseOCRAdapter`` canonique ou d'un
+        ``OCRLLMPipelineConfig``.
 
     Returns
     -------
@@ -546,7 +543,12 @@ def engine_to_pipeline_spec(engine: Any) -> PipelineSpec:
         return _canonical_adapter_to_spec(engine)
     if getattr(engine, "is_pipeline", False):
         return _ocr_llm_pipeline_to_spec(engine)
-    return _ocr_only_to_spec(engine)
+    raise PicaronesError(
+        f"Type d'engine non supporté : {type(engine).__name__}.  "
+        "Attendu : ``BaseOCRAdapter`` ou ``OCRLLMPipelineConfig``.  "
+        "Le support legacy ``BaseOCREngine`` / ``OCRLLMPipeline`` "
+        "a été retiré au sprint H.2.c.",
+    )
 
 
 def _canonical_adapter_to_spec(adapter: Any) -> PipelineSpec:
@@ -582,25 +584,11 @@ def _canonical_adapter_to_spec(adapter: Any) -> PipelineSpec:
     )
 
 
-def _ocr_only_to_spec(engine: "BaseOCREngine") -> PipelineSpec:
-    """Spec mono-step : un OCR legacy consommant IMAGE et produisant RAW_TEXT."""
-    name = engine.name
-    safe_name = _safe_pipeline_name(name)
-    return PipelineSpec(
-        name=f"ocr_only_{safe_name}",
-        description=f"OCR step seul ({name}) — IMAGE → RAW_TEXT.",
-        initial_inputs=(ArtifactType.IMAGE,),
-        steps=(
-            PipelineStep(
-                id="ocr",
-                kind="ocr",
-                adapter_name=name,
-                input_types=(ArtifactType.IMAGE,),
-                output_types=(ArtifactType.RAW_TEXT,),
-                inputs_from={ArtifactType.IMAGE: INITIAL_STEP_ID},
-            ),
-        ),
-    )
+# Sprint H.2.c — ``_ocr_only_to_spec`` (legacy ``BaseOCREngine`` →
+# spec mono-step en dur IMAGE → RAW_TEXT) supprimé.  Le path
+# canonique ``_canonical_adapter_to_spec`` couvre tous les cas en
+# utilisant les ``input_types``/``output_types`` déclarés par
+# l'adapter.
 
 
 def _ocr_llm_pipeline_to_spec(pipeline: Any) -> PipelineSpec:
@@ -646,17 +634,15 @@ def build_adapter_resolver(
     """Construit un adapter resolver pour ``PipelineExecutor``.
 
     Parcourt les engines fournis et associe leur ``name`` à un
-    ``StepExecutor`` valide :
-
-    - **BaseOCRAdapter** (canonique, Sprint H.2.b) : enregistré
-      directement (déjà ``StepExecutor``).
-    - **OCR simple** (``BaseOCREngine`` legacy) → wrapped via
-      ``LegacyOCREngineExecutor``.
-    - **OCRLLMPipeline** → enregistre les deux sous-composants :
-      ``ocr_engine`` (wrapped) et ``llm_adapter`` (déjà
+    ``StepExecutor`` valide (Sprint H.2.c — le path legacy
+    ``LegacyOCREngineExecutor`` a été retiré) :
+
+    - **BaseOCRAdapter** : enregistré directement (déjà ``StepExecutor``).
+    - **OCRLLMPipelineConfig** → enregistre les deux sous-composants :
+      ``ocr_adapter`` (canonique, direct) et ``llm_adapter`` (déjà
       ``StepExecutor`` natif depuis Sprint A14-S44).  Le pipeline
-      lui-même n'est pas enregistré directement — sa spec
-      référence ses sous-steps par leur ``adapter_name``.
+      lui-même n'est pas enregistré directement — sa spec référence
+      ses sous-steps par leur ``adapter_name``.
 
     Le resolver retourné lève ``KeyError`` si un nom inconnu est
     demandé.
@@ -664,8 +650,8 @@ def build_adapter_resolver(
     Parameters
     ----------
     engines:
-        Liste d'instances ``BaseOCRAdapter`` (canonique) ou
-        ``BaseOCREngine``/``OCRLLMPipeline`` (legacy) à enregistrer.
+        Liste d'instances ``BaseOCRAdapter`` ou
+        ``OCRLLMPipelineConfig`` à enregistrer.
 
     Returns
     -------
@@ -694,22 +680,22 @@ def build_adapter_resolver(
             # BaseOCRAdapter : déjà StepExecutor, pas de wrapping.
             _register(engine.name, engine)
         elif getattr(engine, "is_pipeline", False):
-            # OCRLLMPipeline (legacy) ou OCRLLMPipelineConfig
-            # (canonique) : enregistrer ocr + llm sous-jacents.
+            # OCRLLMPipelineConfig : enregistrer ocr + llm sous-jacents.
             ocr_engine = getattr(engine, "ocr_engine", None)
             llm_adapter = getattr(engine, "llm_adapter", None)
             if ocr_engine is not None:
-                if _is_canonical_adapter(ocr_engine):
-                    # BaseOCRAdapter : déjà StepExecutor.
-                    _register(ocr_engine.name, ocr_engine)
-                else:
-                    _register(
-                        ocr_engine.name, LegacyOCREngineExecutor(ocr_engine),
-                    )
+                # ``ocr_engine`` est un alias compat de ``ocr_adapter``
+                # (cf. ``OCRLLMPipelineConfig.ocr_engine``) — toujours
+                # un ``BaseOCRAdapter`` canonique en H.2.c+.
+                _register(ocr_engine.name, ocr_engine)
             if llm_adapter is not None:
                 _register(_llm_adapter_name(llm_adapter), llm_adapter)
         else:
-            _register(engine.name, LegacyOCREngineExecutor(engine))
+            raise PicaronesError(
+                f"Type d'engine non supporté pour le resolver : "
+                f"{type(engine).__name__}.  Attendu : ``BaseOCRAdapter`` "
+                "ou ``OCRLLMPipelineConfig``.",
+            )
 
     def resolver(name: str) -> Any:
         if name not in name_to_executor:

scripts/gen_readme_tables.py

@@ -72,16 +72,19 @@ _ENGINE_DESCRIPTIONS: dict[str, tuple[str, str, str]] = {
 
 
 def _engine_files() -> list[str]:
-    """Retourne la liste triée des modules d'engines (sans base / factory).
+    """Retourne la liste triée des modules d'OCR engines (sans helpers).
 
-    Lot E (2026-05) : ``picarones/engines/`` a été retiré, son canonique
-    est ``picarones/adapters/legacy_engines/``.
+    Sprint H.2.d (2026-05) : ``picarones/adapters/legacy_engines/`` a été
+    supprimé, le canonique est ``picarones/adapters/ocr/``.  On filtre
+    aussi les modules helpers (``confidences``, ``precomputed``) qui ne
+    sont pas des engines OCR à proprement parler.
     """
     out: list[str] = []
-    engines_dir = REPO_ROOT / "picarones" / "adapters" / "legacy_engines"
+    engines_dir = REPO_ROOT / "picarones" / "adapters" / "ocr"
+    skip = {"__init__", "base", "factory", "confidences", "precomputed"}
     for path in sorted(engines_dir.glob("*.py")):
         name = path.stem
-        if name in {"__init__", "base", "factory"}:
+        if name in skip:
             continue
         out.append(name)
     return out

tests/app/test_sprint_d2b_partial_dir_resume.py

@@ -16,7 +16,6 @@ from __future__ import annotations
 import json
 import threading
 from pathlib import Path
-from typing import Any
 
 import pytest
 

tests/architecture/test_doc_paths.py

@@ -117,16 +117,14 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 # (CHANGELOG.md, audits, sub-plans) gardent volontairement les
 # anciens chemins pour la traçabilité historique.
 # Sprint H.5 : -11 broken paths — fix des refs actives dans
-# docs/how-to/cli-workflows.md (cli/ → interfaces/cli/_legacy/,
-# extras/importers/_http.py → adapters/corpus/_http.py),
-# docs/explanation/narrative-engine{.,en}.md (measurements/narrative/
-# → reports/narrative/, fixtures.py → evaluation/synthetic.py),
-# docs/reference/normalization-profiles.md (measurements/builtin_hooks
-# → evaluation/metrics/builtin_hooks), docs/developer/doc-consistency.md
-# (engines/, cli/, web/ → leurs nouveaux chemins),
-# docs/migration/SESSION_HANDOVER.md (refonte section 5 pour pointer
-# vers H.2.b-d/H.4/H.6 au lieu de l'ex sub-phase 7.B.2 obsolète).
-BROKEN_PATHS_BASELINE = 161
+# docs/how-to/cli-workflows.md, narrative-engine, normalization-profiles,
+# doc-consistency, SESSION_HANDOVER.
+# Sprint H.2.d : +1 — la suppression de ``adapters/legacy_engines/``
+# et ``adapters/legacy_pipelines/`` casse 1 ref active de plus dans
+# les docs migration restantes (la majorité des refs cassées
+# pointaient déjà vers ces paquets dans CHANGELOG/audits historiques,
+# d'où l'impact limité).
+BROKEN_PATHS_BASELINE = 162
 
 #: Patrons de fichiers de documentation à scanner.
 DOC_GLOBS: tuple[str, ...] = (

tests/architecture/test_file_budgets.py

@@ -33,20 +33,15 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 # n'ont pas besoin de budget — leur croissance est gérée par les tests
 # de couverture, pas par un seuil dur).
 FILE_BUDGETS: dict[str, int] = {
-    # Sprint B (plan v2.0) — helper d'exécution mono-document qui
-    # pont OCRLLMPipeline (legacy) vers PipelineExecutor (rewrite).
-    # Sera supprimé en Sprint C-D quand les callers consommeront des
-    # PipelineSpec directement.
-    "picarones/adapters/legacy_pipelines/_executor_runner.py": 470,  # actuel 410
     # Sprint D.1 (plan v2.0) — adapter de compat run_benchmark legacy
     # → BenchmarkService rewrite.  Module transitoire qui sera
     # supprimé en H.4 avec interfaces/{cli,web}/_legacy/.
-    # Sprint D.2.b a ajouté ~260 LOC pour la branche resumable
-    # (``_run_benchmark_with_partial``).
-    # Sprint D.2.c-f a ajouté ~190 LOC : NER attach (post-process +
-    # _aggregate_ner_metrics) + over_normalization dans
-    # _build_pipeline_metadata + validate_profile.
-    "picarones/app/services/_legacy_runner_adapter.py": 1700,  # actuel 1461
+    # Sprint D.2.b a ajouté ~260 LOC pour la branche resumable.
+    # Sprint D.2.c-f a ajouté ~190 LOC : NER attach + over_normalization
+    # + validate_profile.
+    # Sprint H.2.c a retiré ``_ocr_only_to_spec`` legacy + simplifié
+    # ``build_adapter_resolver`` (canonique uniquement).
+    "picarones/app/services/_legacy_runner_adapter.py": 1700,  # actuel ~1450
     # --- God-modules : budget actuel + 15 % de marge.
     # Le rétrécissement sera l'objet d'un sprint de refactor dédié.
     # statistics.py (1128 lignes) a été éclaté en sous-package

tests/docs/test_readme_consistency.py

@@ -45,7 +45,7 @@ import pytest
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 README_PATH = REPO_ROOT / "README.md"
-ENGINES_DIR = REPO_ROOT / "picarones" / "adapters" / "legacy_engines"
+ENGINES_DIR = REPO_ROOT / "picarones" / "adapters" / "ocr"
 
 #: Marqueur HTML qui désactive un check sur la ligne. Format :
 #: ``<!-- doc-check: skip-engine -->``, ``skip-cli``, ``skip-endpoint``.

tests/integration/test_sprint30_polish_a11y_dx.py

@@ -16,7 +16,6 @@ Sprint 30 livre quatre durcissements transverses :
 
 from __future__ import annotations
 
-import logging
 from pathlib import Path
 
 

tests/test_minimal_install.py

@@ -265,14 +265,14 @@ def test_optional_deps_not_required_at_top_level() -> None:
     On vérifie ici que les modules existent et s'importent même
     quand on n'a pas les engines installés.
     """
-    # Liste des modules engines qu'on doit pouvoir au moins charger
-    # (pas exécuter) sans planter.
+    # Sprint H.2.d — chemins canoniques (les modules legacy
+    # ``picarones.adapters.legacy_engines.*`` ont été supprimés).
     optional_engine_modules = (
-        "picarones.adapters.legacy_engines.tesseract",
-        "picarones.adapters.legacy_engines.pero_ocr",
-        "picarones.adapters.legacy_engines.mistral_ocr",
-        "picarones.adapters.legacy_engines.google_vision",
-        "picarones.adapters.legacy_engines.azure_doc_intel",
+        "picarones.adapters.ocr.tesseract",
+        "picarones.adapters.ocr.pero_ocr",
+        "picarones.adapters.ocr.mistral_ocr",
+        "picarones.adapters.ocr.google_vision",
+        "picarones.adapters.ocr.azure_doc_intel",
     )
     failed: list[tuple[str, str]] = []
     for mod_name in optional_engine_modules: