feat(adapters): Sprint A14-S26 — BaseOCRAdapter natif + PrecomputedTextAdapter

Premier adapter du nouveau monde, écrit en partant de zéro selon le
contrat propre du rewrite — pas de shim sur le legacy
``picarones.engines.base.BaseOCREngine``, pas de dette technique.

Pourquoi pas de shim
--------------------
Le legacy ``BaseOCREngine`` a un contrat historique
(``run(image_path) → EngineResult``, ``ArtifactType.TEXT``,
``EngineResult`` wrapper) qui ne correspond pas au contrat propre
du nouveau monde (``execute(inputs, params, context) →
dict[ArtifactType, Artifact]``, ``ArtifactType.RAW_TEXT``,
exceptions directes). Pontuiller via un adapter d'adapter
introduirait de la dette : chaque divergence de comportement
entre legacy et nouveau créerait des cas spéciaux.

Le rewrite écrit les adapters OCR depuis zéro, sprint par sprint,
chacun natif au nouveau contrat. Le legacy reste utilisable via
la CLI legacy historique tant qu'il a des consommateurs.

Contrat ``BaseOCRAdapter`` (``picarones/adapters/ocr/base.py``)
--------------------------------------------------------------
ABC du nouveau monde :

- Propriété abstraite ``name`` (identifiant lisible).
- Méthode abstraite
``execute(inputs, params, context) → dict[ArtifactType, Artifact]``.
- Attributs de classe par défaut : ``input_types`` (IMAGE),
``output_types`` (RAW_TEXT), ``execution_mode`` ("io"). Une
sous-classe surcharge si besoin (ex : moteur structuré qui
produit IMAGE → ALTO_XML).
- Erreur typée ``OCRAdapterError`` que le ``PipelineExecutor``
capture en step en échec.

Pas hérité de ``BaseModule`` (legacy core) — le rewrite redéfinit
ses propres abstractions.

Premier adapter livré : ``PrecomputedTextAdapter``
--------------------------------------------------
Lit du texte OCR pré-calculé depuis le filesystem selon une
convention de nommage :

::

folio_001.png
folio_001.tesseract.txt # source 1
folio_001.gpt4v.txt # source 2
folio_001.gt.txt # vérité terrain

Cas d'usage BnF concret : *« j'ai déjà fait tourner Tesseract,
GPT-4v, Pero OCR et un service cloud sur mon corpus. J'ai 4
répertoires de fichiers .txt à côté de mes images. Je veux
comparer ces 4 sorties dans Picarones — je n'ai pas besoin de
re-lancer un OCR. »*

Plusieurs ``PrecomputedTextAdapter`` peuvent coexister dans une
même YAML avec des ``source_label`` distincts ; chacun lit son
propre fichier.

Politique sur fichier manquant :

- ``"raise"`` (défaut) → ``OCRAdapterError``, le step est marqué
failed pour ce document, le benchmark continue.
- ``"empty"`` → fichier vide créé pour cohérence (toujours une
``Artifact.uri`` lisible) ; permet de mesurer ce que produirait
une source partiellement disponible.

Validation stricte du ``source_label`` (alphanumérique + ``_``
``-``), refus encodage non-UTF-8.

Bug fix annexe ``_build_pipelines``
-----------------------------------
La résolution d'``adapter_name`` dans ``picarones/app/cli/run.py``
disambiguait sur la classe seule. Or 3 ``PrecomputedTextAdapter``
instanciés avec des ``source_label`` différents partageaient la
**même** instance d'adapter (cache par nom de step partagé) — toutes
les pipelines recevaient le texte de la première source.

Fix : disambiguation sur ``(class, kwargs_signature)``. Deux
steps avec les mêmes class+kwargs partagent l'instance ; deux
steps avec class identique mais kwargs différents reçoivent des
``adapter_name`` distincts (préfixés par le nom de pipeline).

Tests (20 nouveaux)
-------------------
``tests/adapters/test_sprint_a14_s26_ocr_adapter.py`` :

- **Contrat ``BaseOCRAdapter``** (3 tests) : instanciation directe
rejetée, sous-classe minimale fonctionne, override des
attributs IO mode / types fonctionne.
- **Validation ``PrecomputedTextAdapter`` à l'init** (6 tests) :
source_label vide/whitespace/chars invalides rejetés ; libellés
valides acceptés ; missing_text_policy invalide rejeté ;
défaut ``"raise"``.
- **Exécution** (8 tests) : lecture par convention, fichier
manquant → raise (défaut), policy ``"empty"`` crée fichier vide,
encodage non-UTF-8 rejeté, IMAGE manquant / sans URI rejetés,
isolation 2 sources dans même répertoire, extensions
``.png/.jpg/.jpeg/.tif/.tiff`` toutes gérées.
- **Pipeline executor** (1 test) : adapter consommé directement
par ``PipelineExecutor.run`` — preuve que le contrat
``BaseOCRAdapter`` satisfait le ``StepExecutor``.
- **CLI E2E BnF** (2 tests) : YAML déclarant 3 sources
pré-calculées (tesseract / gpt4v / pero) → 3 pipelines exécutés
via ``picarones-rewrite run`` → 6 ViewResults dans TextView
avec gradient de CER (tesseract 0 < gpt4v < pero) ; cas fichier
manquant produit step en échec sans crash global.

554 tests sprint_a14 passent (534 S1-S25 + 20 S26).

L'utilisateur BnF peut désormais :
``picarones-rewrite run --spec my_run.yaml`` avec ses propres
sorties OCR déjà calculées, **sans aucun OCR engine installé**,
et obtenir un rapport HTML comparant N transcriptions.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

picarones/adapters/ocr/__init__.py

@@ -1,16 +1,29 @@
-"""Adaptateurs OCR — Sprint S11.
+"""Adapters OCR du nouveau monde — Sprint A14-S26.
 
-Cible : déplacement (sans modification logique) de
-``picarones.engines.{tesseract,pero_ocr,mistral_ocr,google_vision,
-azure_doc_intel}``.  Chaque adapter implémente le protocole
-``StepExecutor`` du package ``pipeline``.
+Contrat ``BaseOCRAdapter`` natif au rewrite : pas hérité du legacy
+``picarones.engines.base.BaseOCREngine``, exprimé directement en
+termes du nouveau ``ArtifactType`` et de l'interface
+``execute(inputs, params, context)`` du ``PipelineExecutor``.
 
-Règle : un adapter OCR produit un artefact ``RAW_TEXT`` (et
-optionnellement ``ALTO_XML`` / ``token_confidences``).  Il ne
-calcule **rien** sur ce texte — pas de CER, pas de normalisation,
-pas d'analyse linguistique.  Tout ça est dans ``evaluation/``.
+Implémentations livrées
+-----------------------
+- ``PrecomputedTextAdapter`` — lit un texte OCR pré-calculé depuis
+  le filesystem.  Cas BnF : comparer N transcriptions déjà produites
+  par d'autres outils sans relancer d'OCR.
+
+Adapters concrets pour Tesseract / Pero OCR / Mistral OCR / Google
+Vision / Azure DI : à écrire au cas par cas dans des sprints
+dédiés, **natifs** au nouveau contrat (pas de shim sur le legacy
+``picarones.engines``).
 """
 
 from __future__ import annotations
 
-__all__: list[str] = []
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.ocr.precomputed import PrecomputedTextAdapter
+
+__all__ = [
+    "BaseOCRAdapter",
+    "OCRAdapterError",
+    "PrecomputedTextAdapter",
+]

picarones/adapters/ocr/base.py

@@ -0,0 +1,167 @@
+"""``BaseOCRAdapter`` — contrat natif du nouveau monde pour un adapter OCR.
+
+Sprint A14-S26 du rewrite ciblé.
+
+Ce module définit le contrat **propre** auquel un adapter OCR du
+nouveau monde doit se conformer pour être utilisable comme step
+d'une pipeline ``picarones.pipeline``.  Pas hérité du legacy
+``picarones.engines.base.BaseOCREngine`` — c'est un nouveau contrat,
+sans dette technique, exprimé en termes du nouveau ``ArtifactType``.
+
+Contrat
+-------
+Un adapter OCR :
+
+- Déclare ses ``input_types`` (typiquement
+  ``frozenset({ArtifactType.IMAGE})``).
+- Déclare ses ``output_types`` (typiquement
+  ``frozenset({ArtifactType.RAW_TEXT})``, ou plus pour les moteurs
+  structurés).
+- Déclare son ``execution_mode`` : ``"io"`` (défaut, ThreadPool) ou
+  ``"cpu"`` (ProcessPool).
+- Implémente
+  ``execute(inputs, params, context) -> dict[ArtifactType, Artifact]``.
+
+Le ``Artifact`` retourné porte une ``uri`` filesystem — c'est la
+convention du nouveau monde pour permettre au ``payload_loader`` de
+le lire ultérieurement (Sprint S25 — la projection a un payload
+direct, mais les artefacts produits par les adapters sont stockés
+sur disque pour traçabilité et streaming).
+
+Différences avec le legacy
+--------------------------
+- ``ArtifactType.RAW_TEXT`` (10 valeurs) au lieu de
+  ``ArtifactType.TEXT`` (6 valeurs legacy).
+- Pas de ``run(image_path)`` historique — un seul point d'entrée
+  ``execute()``.
+- Pas de wrapper ``EngineResult`` — les erreurs lèvent directement,
+  le ``PipelineExecutor`` les capture en step en échec.
+- Pas de ``_run_ocr`` / ``_run_with_native`` / ``_extract_raw_confidences``
+  — les confidences (S42 legacy) sont reportées à un sprint dédié
+  où l'on définira un ``ConfidenceArtifact`` typé.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de hiérarchie d'erreurs.  Un adapter qui échoue lève
+  ``OCRAdapterError`` (ou laisse passer une exception).  Le
+  ``PipelineExecutor`` (S7) catch et marque le step en échec.
+- Pas de cache au niveau de l'ABC.  Si un adapter veut cacher ses
+  résultats, c'est dans son implémentation (compose ``ArtifactStore``
+  S7 si besoin).
+- Pas de retry.  Idem.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class OCRAdapterError(Exception):
+    """Erreur typée pour un échec d'adapter OCR du nouveau monde.
+
+    Le ``PipelineExecutor`` capture cette exception (et toute autre)
+    et marque le step correspondant comme failed avec
+    ``StepResult.error`` renseigné.  Les callers downstream
+    (``BenchmarkService``, vues) verront le pipeline en échec sans
+    crash global.
+    """
+
+
+class BaseOCRAdapter(ABC):
+    """Classe de base pour un adapter OCR du nouveau monde.
+
+    Toute sous-classe doit :
+
+    1. Surcharger la propriété ``name`` (identifiant lisible, utilisé
+       dans les ``Artifact.id`` et le run_manifest).
+    2. Implémenter ``execute(inputs, params, context)``.
+
+    Les attributs de classe ``input_types`` / ``output_types`` /
+    ``execution_mode`` sont fournis par défaut pour le cas le plus
+    courant (image → texte, IO-bound).  Une sous-classe qui produit
+    de l'ALTO surcharge ``output_types``, etc.
+
+    Exemple
+    -------
+
+    ::
+
+        class MyOCRAdapter(BaseOCRAdapter):
+            @property
+            def name(self) -> str:
+                return "my_ocr"
+
+            def execute(self, inputs, params, context):
+                image_artifact = inputs[ArtifactType.IMAGE]
+                # ... appel OCR sur image_artifact.uri ...
+                # ... écriture du résultat sur disque ...
+                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),
+                    ),
+                }
+    """
+
+    #: Types d'artefacts attendus en entrée.  Le ``PipelineExecutor``
+    #: utilise cette info pour valider la compatibilité des steps
+    #: enchaînés.
+    input_types: frozenset[ArtifactType] = frozenset({ArtifactType.IMAGE})
+
+    #: Types d'artefacts produits.  Validés à la sortie de ``execute``.
+    output_types: frozenset[ArtifactType] = frozenset({ArtifactType.RAW_TEXT})
+
+    #: ``"io"`` (ThreadPool) ou ``"cpu"`` (ProcessPool).  Indique au
+    #: runner quel type de pool utiliser pour la concurrence.
+    execution_mode: str = "io"
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Identifiant lisible de l'adapter (ex : ``"tesseract"``,
+        ``"precomputed_text"``).  Utilisé dans les ``Artifact.id`` du
+        nouveau monde et dans le ``run_manifest``."""
+
+    @abstractmethod
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute l'OCR sur les entrées et retourne les artefacts produits.
+
+        Parameters
+        ----------
+        inputs:
+            Map ``ArtifactType → Artifact`` avec au minimum les types
+            déclarés dans ``self.input_types``.  L'adapter peut
+            ignorer les entrées surnuméraires.
+        params:
+            Paramètres dynamiques du step (typiquement vides — la
+            configuration de l'adapter passe par son constructeur).
+        context:
+            ``RunContext`` du run en cours (porte ``document_id``,
+            ``code_version``, ``pipeline_name``).
+
+        Returns
+        -------
+        dict[ArtifactType, Artifact]
+            Map des artefacts produits.  Doit contenir au moins les
+            types déclarés dans ``self.output_types``.
+
+        Raises
+        ------
+        OCRAdapterError
+            Erreur typée pour signaler un échec côté adapter (input
+            invalide, fichier introuvable, etc.).
+        """
+
+
+__all__ = ["BaseOCRAdapter", "OCRAdapterError"]

picarones/adapters/ocr/precomputed.py

@@ -0,0 +1,219 @@
+"""``PrecomputedTextAdapter`` — premier adapter natif du nouveau monde.
+
+Sprint A14-S26 du rewrite ciblé.
+
+Cas d'usage BnF
+---------------
+*« J'ai déjà fait tourner Tesseract, GPT-4-vision, Pero OCR et un
+service cloud sur mon corpus.  J'ai 4 répertoires de fichiers
+``.txt`` à côté de mes images.  Je veux comparer ces 4 sorties dans
+Picarones — je n'ai pas besoin de re-lancer un OCR, j'ai juste besoin
+de la machinerie d'évaluation. »*
+
+Ce besoin est légitime et fréquent à la BnF : une part importante
+du travail de comparaison se fait sur des transcriptions déjà
+produites par d'autres outils.  Ré-exécuter un OCR à chaque
+benchmark est gaspillage.
+
+Convention de nommage
+---------------------
+Pour une image ``<stem>.png`` (ou ``.jpg``, ``.tif``, etc.), le
+texte pré-calculé est lu depuis :
+
+::
+
+    <stem>.<source_label>.txt
+
+dans le **même répertoire** que l'image.  Exemple avec deux
+sources concurrentes :
+
+::
+
+    folio_001.png
+    folio_001.tesseract.txt    # produit par Tesseract
+    folio_001.pero.txt         # produit par Pero OCR
+    folio_001.gpt4v.txt        # produit par GPT-4 Vision
+    folio_001.gt.txt           # vérité terrain
+
+Plusieurs ``PrecomputedTextAdapter`` peuvent coexister dans une
+même YAML avec des ``source_label`` distincts — chacun lit son
+propre fichier, le ``BenchmarkService`` les traite en parallèle.
+
+Configuration YAML
+------------------
+
+::
+
+    pipelines:
+      - name: tesseract_baseline
+        initial_inputs: [image]
+        steps:
+          - id: ocr
+            adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+            adapter_kwargs:
+              source_label: tesseract
+            input_types: [image]
+            output_types: [raw_text]
+
+      - name: gpt4v_alternative
+        initial_inputs: [image]
+        steps:
+          - id: ocr
+            adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+            adapter_kwargs:
+              source_label: gpt4v
+            input_types: [image]
+            output_types: [raw_text]
+
+Comportement « fichier manquant »
+---------------------------------
+Par défaut, si le fichier ``<stem>.<source_label>.txt`` est absent,
+l'adapter lève ``OCRAdapterError`` — le pipeline executor marque le
+step comme failed pour ce document, et le ``BenchmarkService`` le
+voit en ``failed_metrics``.  Pas de fallback silencieux qui
+mentirait sur la couverture du benchmark.
+
+L'option ``missing_text_policy="empty"`` permet, à la demande
+explicite du caller, de remplacer un fichier absent par une chaîne
+vide — utile pour mesurer ce qui se passerait si une source était
+indisponible sur certains documents.  Par défaut : ``"raise"``.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de découverte automatique de tous les ``source_label``
+  présents dans un répertoire.  Le caller déclare explicitement
+  les sources qu'il veut comparer.
+- Pas de cache.  Le filesystem fait son boulot.
+- Pas de validation d'encodage exotique.  ``utf-8`` strict ; un
+  fichier mal encodé lève une erreur lisible.
+- Pas d'extraction structurelle.  Cet adapter sort du ``RAW_TEXT``,
+  point.  Pour comparer des ALTO_XML pré-calculés, c'est un
+  ``PrecomputedAltoAdapter`` futur (pattern identique).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class PrecomputedTextAdapter(BaseOCRAdapter):
+    """Adapter qui lit du texte OCR pré-calculé depuis le filesystem.
+
+    Parameters
+    ----------
+    source_label:
+        Étiquette identifiant la source du texte pré-calculé
+        (ex : ``"tesseract"``, ``"gpt4v"``, ``"pero"``).  Doit être
+        composée uniquement de caractères alphanumériques, ``_`` et
+        ``-`` — c'est un composant de nom de fichier.
+    missing_text_policy:
+        ``"raise"`` (défaut) → fichier absent lève ``OCRAdapterError``.
+        ``"empty"`` → fichier absent remplacé par chaîne vide
+        (l'adapter produit alors un ``Artifact`` pointant sur un
+        fichier vide).
+
+    Raises
+    ------
+    OCRAdapterError
+        Si ``source_label`` est invalide.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        source_label: str,
+        missing_text_policy: Literal["raise", "empty"] = "raise",
+    ) -> None:
+        if not source_label or not source_label.strip():
+            raise OCRAdapterError(
+                "PrecomputedTextAdapter : source_label vide.",
+            )
+        if not all(
+            c.isalnum() or c in "_-" for c in source_label
+        ):
+            raise OCRAdapterError(
+                f"PrecomputedTextAdapter : source_label invalide "
+                f"{source_label!r} — alphanumérique + _ - uniquement.",
+            )
+        if missing_text_policy not in ("raise", "empty"):
+            raise OCRAdapterError(
+                f"missing_text_policy doit être 'raise' ou 'empty', "
+                f"reçu {missing_text_policy!r}.",
+            )
+        self._source_label = source_label
+        self._missing_policy = missing_text_policy
+
+    @property
+    def name(self) -> str:
+        return f"precomputed_{self._source_label}"
+
+    @property
+    def source_label(self) -> str:
+        return self._source_label
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        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)
+        text_path = (
+            image_path.parent / f"{image_path.stem}.{self._source_label}.txt"
+        )
+
+        if not text_path.exists():
+            if self._missing_policy == "empty":
+                # On crée le fichier vide pour rester cohérent : tout
+                # ``Artifact`` produit a une URI vers un fichier
+                # lisible.
+                text_path.write_text("", encoding="utf-8")
+            else:
+                raise OCRAdapterError(
+                    f"{self.name} : fichier pré-calculé introuvable "
+                    f"pour {image_path.name!r} : "
+                    f"{text_path.name!r} attendu dans "
+                    f"{image_path.parent!r}.",
+                )
+
+        # Validation rapide de l'encodage UTF-8 (lecture qui leverait
+        # si encodage exotique).
+        try:
+            text_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : {text_path!r} n'est pas en UTF-8 : "
+                f"{exc}",
+            ) from exc
+
+        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(text_path),
+            ),
+        }
+
+
+__all__ = ["PrecomputedTextAdapter"]

picarones/app/cli/run.py

@@ -248,26 +248,46 @@ def _build_pipelines(spec: RunSpec) -> tuple[
     """Construit les ``PipelineSpec`` + un ``adapter_resolver`` qui
     instancie les adapters au besoin.
 
-    Le resolver maintient un cache instance-par-nom (un adapter est
-    instancié une seule fois pour tout le run).
+    Disambiguation des steps :
+
+    - Deux steps qui ont la même ``(class, kwargs)`` partagent la
+      même instance d'adapter (cache).
+    - Deux steps qui ont la même ``id`` mais une ``class`` ou des
+      ``kwargs`` différents reçoivent des ``adapter_name`` distincts
+      (préfixés par le nom de pipeline).
+
+    C'est essentiel pour le cas BnF où plusieurs pipelines utilisent
+    la **même classe** avec des **kwargs différents** (ex :
+    ``PrecomputedTextAdapter`` instancié 3 fois avec
+    ``source_label`` distincts).
     """
     instance_cache: dict[str, object] = {}
+    # ``adapter_name`` → ``(class, kwargs_signature)`` pour valider
+    # qu'on n'écrase pas un adapter avec un autre.
+    registered: dict[str, tuple[type, str]] = {}
     name_to_class: dict[str, type] = {}
     name_to_kwargs: dict[str, dict] = {}
 
+    def _kwargs_signature(kwargs: dict) -> str:
+        # Signature stable : ordre de tri sur les clés.  ``str(value)``
+        # suffit pour comparer — les types JSON-serializable seront
+        # déterministes.
+        return "|".join(f"{k}={kwargs[k]!r}" for k in sorted(kwargs))
+
     pipeline_specs: list[PipelineSpec] = []
     for p in spec.pipelines:
         steps = []
         for s in p.steps:
             cls = resolve_adapter_class(s.adapter_class)
+            kwargs_sig = _kwargs_signature(s.adapter_kwargs)
             adapter_name = s.id
-            # Si le même step.id apparaît dans deux pipelines avec
-            # des classes différentes, on disambiguë par la pipeline.
-            if (
-                adapter_name in name_to_class
-                and name_to_class[adapter_name] is not cls
-            ):
+            # Si le step.id existe déjà mais avec une autre signature
+            # (class ou kwargs distincts), on disambigue en préfixant
+            # par le nom de la pipeline.
+            existing = registered.get(adapter_name)
+            if existing is not None and existing != (cls, kwargs_sig):
                 adapter_name = f"{p.name}__{s.id}"
+            registered[adapter_name] = (cls, kwargs_sig)
             name_to_class[adapter_name] = cls
             name_to_kwargs[adapter_name] = s.adapter_kwargs
             steps.append(PipelineStep(

tests/adapters/test_sprint_a14_s26_ocr_adapter.py

@@ -0,0 +1,533 @@
+"""Sprint A14-S26 — ``BaseOCRAdapter`` + ``PrecomputedTextAdapter``.
+
+Couverture :
+
+- **Contrat** : un ``BaseOCRAdapter`` est instanciable, expose
+  ``name`` / ``input_types`` / ``output_types`` / ``execution_mode``,
+  son ``execute()`` est abstrait.
+- **PrecomputedTextAdapter** : validation du ``source_label``,
+  lecture filesystem par convention de nommage, politique
+  ``"raise"`` vs ``"empty"`` sur fichier manquant, validation
+  UTF-8, isolation entre instances de sources distinctes.
+- **Pipeline executor** : un ``PrecomputedTextAdapter`` est consommé
+  directement par le ``PipelineExecutor`` (S7) — preuve que le
+  contrat ``BaseOCRAdapter`` satisfait ``StepExecutor``.
+- **CLI E2E** : YAML déclarant 3 sources pré-calculées différentes
+  → benchmark complet avec 3 pipelines comparés sur TextView,
+  sans aucun OCR réel.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import textwrap
+import zipfile
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from picarones.adapters.ocr import (
+    BaseOCRAdapter,
+    OCRAdapterError,
+    PrecomputedTextAdapter,
+)
+from picarones.app.cli import cli
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.pipeline.types import RunContext
+
+
+# ──────────────────────────────────────────────────────────────────
+# Fixtures
+# ──────────────────────────────────────────────────────────────────
+
+
+def _png_bytes() -> bytes:
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        b"\x00\x00\x00\rIHDR"
+        b"\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00"
+        b"\x1f\x15\xc4\x89"
+    )
+
+
+def _ctx(doc_id: str = "doc01") -> RunContext:
+    return RunContext(
+        document_id=doc_id,
+        code_version="1.0.0-s26-test",
+        pipeline_name="test_pipeline",
+    )
+
+
+def _image_artifact(doc_id: str, path: Path) -> Artifact:
+    return Artifact(
+        id=f"{doc_id}:image",
+        document_id=doc_id,
+        type=ArtifactType.IMAGE,
+        uri=str(path),
+    )
+
+
+# ──────────────────────────────────────────────────────────────────
+# Contrat BaseOCRAdapter
+# ──────────────────────────────────────────────────────────────────
+
+
+class TestBaseOCRAdapterContract:
+    def test_cannot_instantiate_abstract_directly(self) -> None:
+        with pytest.raises(TypeError):
+            BaseOCRAdapter()  # type: ignore[abstract]
+
+    def test_minimal_subclass_with_name_and_execute_works(self) -> None:
+        class _Minimal(BaseOCRAdapter):
+            @property
+            def name(self) -> str:
+                return "minimal"
+
+            def execute(self, inputs, params, context):
+                return {}
+
+        adapter = _Minimal()
+        assert adapter.name == "minimal"
+        assert ArtifactType.IMAGE in adapter.input_types
+        assert ArtifactType.RAW_TEXT in adapter.output_types
+        assert adapter.execution_mode == "io"
+
+    def test_subclass_can_override_io_modes(self) -> None:
+        class _CPUBound(BaseOCRAdapter):
+            execution_mode = "cpu"
+            input_types = frozenset({ArtifactType.IMAGE})
+            output_types = frozenset({
+                ArtifactType.RAW_TEXT, ArtifactType.ALTO_XML,
+            })
+
+            @property
+            def name(self) -> str:
+                return "cpu_bound"
+
+            def execute(self, inputs, params, context):
+                return {}
+
+        adapter = _CPUBound()
+        assert adapter.execution_mode == "cpu"
+        assert ArtifactType.ALTO_XML in adapter.output_types
+
+
+# ──────────────────────────────────────────────────────────────────
+# PrecomputedTextAdapter — validation à l'init
+# ──────────────────────────────────────────────────────────────────
+
+
+class TestPrecomputedInitValidation:
+    def test_empty_source_label_rejected(self) -> None:
+        with pytest.raises(OCRAdapterError, match="vide"):
+            PrecomputedTextAdapter(source_label="")
+
+    def test_whitespace_source_label_rejected(self) -> None:
+        with pytest.raises(OCRAdapterError, match="vide"):
+            PrecomputedTextAdapter(source_label="   ")
+
+    def test_invalid_chars_in_source_label_rejected(self) -> None:
+        for bad in ("foo/bar", "foo bar", "foo.bar", "foo:bar"):
+            with pytest.raises(OCRAdapterError, match="invalide"):
+                PrecomputedTextAdapter(source_label=bad)
+
+    def test_valid_source_labels_accepted(self) -> None:
+        for good in ("tesseract", "gpt-4v", "pero_ocr", "ABC123"):
+            adapter = PrecomputedTextAdapter(source_label=good)
+            assert adapter.source_label == good
+            assert adapter.name == f"precomputed_{good}"
+
+    def test_invalid_missing_text_policy_rejected(self) -> None:
+        with pytest.raises(OCRAdapterError, match="missing_text_policy"):
+            PrecomputedTextAdapter(
+                source_label="tess",
+                missing_text_policy="silent",  # type: ignore[arg-type]
+            )
+
+    def test_default_missing_text_policy_is_raise(self) -> None:
+        adapter = PrecomputedTextAdapter(source_label="tess")
+        assert adapter._missing_policy == "raise"
+
+
+# ──────────────────────────────────────────────────────────────────
+# PrecomputedTextAdapter — exécution
+# ──────────────────────────────────────────────────────────────────
+
+
+class TestPrecomputedExecute:
+    def test_reads_text_file_by_convention(self, tmp_path: Path) -> None:
+        # Préparer image + texte pré-calculé.
+        image_path = tmp_path / "doc01.png"
+        image_path.write_bytes(_png_bytes())
+        text_path = tmp_path / "doc01.tesseract.txt"
+        text_path.write_text("Bonjour le monde", encoding="utf-8")
+
+        adapter = PrecomputedTextAdapter(source_label="tesseract")
+        outputs = adapter.execute(
+            inputs={ArtifactType.IMAGE: _image_artifact("doc01", image_path)},
+            params={},
+            context=_ctx("doc01"),
+        )
+        art = outputs[ArtifactType.RAW_TEXT]
+        assert art.type == ArtifactType.RAW_TEXT
+        assert art.document_id == "doc01"
+        assert Path(art.uri).read_text(encoding="utf-8") == "Bonjour le monde"
+        # Convention <doc_id>:<owner>:<role>.
+        assert art.id == "doc01:precomputed_tesseract:raw_text"
+
+    def test_missing_text_raises_by_default(self, tmp_path: Path) -> None:
+        image_path = tmp_path / "doc01.png"
+        image_path.write_bytes(_png_bytes())
+        # Pas de doc01.tesseract.txt.
+
+        adapter = PrecomputedTextAdapter(source_label="tesseract")
+        with pytest.raises(OCRAdapterError, match="introuvable"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: _image_artifact("doc01", image_path)},
+                params={},
+                context=_ctx("doc01"),
+            )
+
+    def test_missing_text_empty_policy_creates_empty_file(
+        self, tmp_path: Path,
+    ) -> None:
+        image_path = tmp_path / "doc01.png"
+        image_path.write_bytes(_png_bytes())
+
+        adapter = PrecomputedTextAdapter(
+            source_label="tess",
+            missing_text_policy="empty",
+        )
+        outputs = adapter.execute(
+            inputs={ArtifactType.IMAGE: _image_artifact("doc01", image_path)},
+            params={},
+            context=_ctx("doc01"),
+        )
+        art = outputs[ArtifactType.RAW_TEXT]
+        assert Path(art.uri).read_text(encoding="utf-8") == ""
+
+    def test_non_utf8_file_rejected(self, tmp_path: Path) -> None:
+        image_path = tmp_path / "doc01.png"
+        image_path.write_bytes(_png_bytes())
+        text_path = tmp_path / "doc01.tess.txt"
+        # Bytes invalides en UTF-8 (latin-1 avec accent).
+        text_path.write_bytes(b"\xe9\xe8")
+
+        adapter = PrecomputedTextAdapter(source_label="tess")
+        with pytest.raises(OCRAdapterError, match="UTF-8"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: _image_artifact("doc01", image_path)},
+                params={},
+                context=_ctx("doc01"),
+            )
+
+    def test_missing_image_input_rejected(self, tmp_path: Path) -> None:
+        adapter = PrecomputedTextAdapter(source_label="tess")
+        with pytest.raises(OCRAdapterError, match="IMAGE manquant"):
+            adapter.execute(inputs={}, params={}, context=_ctx())
+
+    def test_image_artifact_without_uri_rejected(self) -> None:
+        adapter = PrecomputedTextAdapter(source_label="tess")
+        with pytest.raises(OCRAdapterError, match="sans URI"):
+            adapter.execute(
+                inputs={
+                    ArtifactType.IMAGE: Artifact(
+                        id="d:image", document_id="d",
+                        type=ArtifactType.IMAGE,
+                    ),
+                },
+                params={},
+                context=_ctx(),
+            )
+
+    def test_two_sources_isolated_in_same_dir(self, tmp_path: Path) -> None:
+        """Cas BnF central : deux sources pré-calculées dans le même
+        répertoire ne se piétinent pas — chaque adapter lit son
+        propre fichier."""
+        image_path = tmp_path / "doc01.png"
+        image_path.write_bytes(_png_bytes())
+        (tmp_path / "doc01.tess.txt").write_text(
+            "tesseract output", encoding="utf-8",
+        )
+        (tmp_path / "doc01.gpt4v.txt").write_text(
+            "gpt-4 vision output", encoding="utf-8",
+        )
+
+        a_tess = PrecomputedTextAdapter(source_label="tess")
+        a_gpt = PrecomputedTextAdapter(source_label="gpt4v")
+
+        out_tess = a_tess.execute(
+            inputs={ArtifactType.IMAGE: _image_artifact("doc01", image_path)},
+            params={},
+            context=_ctx("doc01"),
+        )
+        out_gpt = a_gpt.execute(
+            inputs={ArtifactType.IMAGE: _image_artifact("doc01", image_path)},
+            params={},
+            context=_ctx("doc01"),
+        )
+        assert Path(out_tess[ArtifactType.RAW_TEXT].uri).read_text() \
+            == "tesseract output"
+        assert Path(out_gpt[ArtifactType.RAW_TEXT].uri).read_text() \
+            == "gpt-4 vision output"
+
+    def test_image_extension_variations_handled(
+        self, tmp_path: Path,
+    ) -> None:
+        """``stem`` strip toutes les extensions image courantes."""
+        for ext in (".png", ".jpg", ".jpeg", ".tif", ".tiff"):
+            image_path = tmp_path / f"folio_001{ext}"
+            image_path.write_bytes(_png_bytes())
+            text_path = tmp_path / "folio_001.src.txt"
+            text_path.write_text("ok", encoding="utf-8")
+
+            adapter = PrecomputedTextAdapter(source_label="src")
+            out = adapter.execute(
+                inputs={
+                    ArtifactType.IMAGE: _image_artifact("folio_001", image_path),
+                },
+                params={},
+                context=_ctx("folio_001"),
+            )
+            assert Path(out[ArtifactType.RAW_TEXT].uri).read_text() == "ok"
+
+
+# ──────────────────────────────────────────────────────────────────
+# Smoke pipeline executor
+# ──────────────────────────────────────────────────────────────────
+
+
+class TestPipelineExecutorIntegration:
+    def test_adapter_consumed_by_pipeline_executor(
+        self, tmp_path: Path,
+    ) -> None:
+        """Démontre que ``BaseOCRAdapter`` satisfait le contrat
+        ``StepExecutor`` du nouveau pipeline executor — preuve que
+        le contrat propre du nouveau monde est suffisant."""
+        from picarones.domain.documents import DocumentRef
+        from picarones.pipeline import (
+            PipelineExecutor, PipelineSpec, PipelineStep,
+        )
+
+        image_path = tmp_path / "doc01.png"
+        image_path.write_bytes(_png_bytes())
+        (tmp_path / "doc01.tess.txt").write_text(
+            "Bonjour", encoding="utf-8",
+        )
+
+        adapter = PrecomputedTextAdapter(source_label="tess")
+        spec = PipelineSpec(
+            name="precomputed_smoke",
+            initial_inputs=(ArtifactType.IMAGE,),
+            steps=(PipelineStep(
+                id="ocr", kind="ocr",
+                adapter_name="precomputed",
+                input_types=(ArtifactType.IMAGE,),
+                output_types=(ArtifactType.RAW_TEXT,),
+            ),),
+        )
+        executor = PipelineExecutor(adapter_resolver=lambda n: adapter)
+        result = executor.run(
+            spec=spec,
+            document=DocumentRef(id="doc01", image_uri=str(image_path)),
+            initial_inputs={
+                ArtifactType.IMAGE: _image_artifact("doc01", image_path),
+            },
+            context=_ctx("doc01"),
+        )
+        assert result.succeeded
+        text_arts = result.artifacts_of_type(ArtifactType.RAW_TEXT)
+        assert len(text_arts) == 1
+        assert Path(text_arts[0].uri).read_text() == "Bonjour"
+
+
+# ──────────────────────────────────────────────────────────────────
+# CLI E2E : 3 sources pré-calculées comparées via picarones-rewrite run
+# ──────────────────────────────────────────────────────────────────
+
+
+def _make_corpus_zip_with_sources() -> bytes:
+    """Corpus avec image + GT + 3 sources pré-calculées."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, mode="w") as zf:
+        for doc_id in ("doc01", "doc02"):
+            zf.writestr(f"{doc_id}.png", _png_bytes())
+            zf.writestr(f"{doc_id}.gt.txt", "Bonjour le monde")
+            # Tesseract : copie exacte de la GT (CER 0).
+            zf.writestr(
+                f"{doc_id}.tesseract.txt",
+                "Bonjour le monde",
+            )
+            # GPT-4v : 1 erreur (CER > 0).
+            zf.writestr(
+                f"{doc_id}.gpt4v.txt",
+                "Bonjur le monde",
+            )
+            # Pero : très dégradé.
+            zf.writestr(
+                f"{doc_id}.pero.txt",
+                "Bonjour 1e mond",
+            )
+    return buf.getvalue()
+
+
+class TestCLIComparingPrecomputedSources:
+    """Cas BnF concret : « j'ai 3 transcriptions déjà produites,
+    je veux les comparer ».
+
+    YAML déclare 3 pipelines, chacun pointant sur
+    ``PrecomputedTextAdapter`` avec un ``source_label`` distinct.
+    Le ``BenchmarkService`` les exécute en parallèle, le
+    ``ReportService`` les compare dans TextView.  Aucun OCR réel
+    n'est lancé."""
+
+    def test_three_precomputed_sources_compared_via_cli(
+        self, tmp_path: Path,
+    ) -> None:
+        runner = CliRunner()
+        corpus_zip = tmp_path / "corpus.zip"
+        corpus_zip.write_bytes(_make_corpus_zip_with_sources())
+
+        spec_path = tmp_path / "run.yaml"
+        out_dir = tmp_path / "out"
+        report_path = out_dir / "rapport.html"
+        spec_path.write_text(textwrap.dedent(f"""
+            corpus_zip: {corpus_zip}
+            corpus_name: bnf_3sources
+            pipelines:
+              - name: tesseract_baseline
+                initial_inputs: [image]
+                steps:
+                  - id: ocr
+                    adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+                    adapter_kwargs:
+                      source_label: tesseract
+                    input_types: [image]
+                    output_types: [raw_text]
+              - name: gpt4v_alternative
+                initial_inputs: [image]
+                steps:
+                  - id: ocr
+                    adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+                    adapter_kwargs:
+                      source_label: gpt4v
+                    input_types: [image]
+                    output_types: [raw_text]
+              - name: pero_alternative
+                initial_inputs: [image]
+                steps:
+                  - id: ocr
+                    adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+                    adapter_kwargs:
+                      source_label: pero
+                    input_types: [image]
+                    output_types: [raw_text]
+            views: [text_final]
+            output_dir: {out_dir}
+            report_html: {report_path}
+            code_version: "1.0.0-s26-bnf"
+        """))
+
+        result = runner.invoke(cli, ["run", "--spec", str(spec_path)])
+        assert result.exit_code == 0, result.output
+
+        # Validation : 2 docs × 3 pipelines × 1 vue = 6 ViewResults.
+        results_dir = out_dir / "results"
+        view_lines = [
+            json.loads(line)
+            for line in (results_dir / "view_results.jsonl").read_text().strip().split("\n")
+            if line.strip()
+        ]
+        assert len(view_lines) == 6
+
+        # Tesseract → CER 0 (copie exacte).
+        # GPT-4v / Pero → CER > 0.
+        cer_by_pipeline: dict[str, list[float]] = {}
+        for vr in view_lines:
+            cand_id = vr["candidate_artifact_id"]
+            if "precomputed_tesseract" in cand_id:
+                pipeline = "tesseract"
+            elif "precomputed_gpt4v" in cand_id:
+                pipeline = "gpt4v"
+            elif "precomputed_pero" in cand_id:
+                pipeline = "pero"
+            else:
+                pytest.fail(f"candidate id inattendu : {cand_id}")
+            cer_by_pipeline.setdefault(pipeline, []).append(
+                vr["metric_values"]["cer"],
+            )
+
+        # Tesseract = 0 sur les 2 docs.
+        assert cer_by_pipeline["tesseract"] == [0.0, 0.0]
+        # GPT-4v > 0 (1 erreur).
+        for cer in cer_by_pipeline["gpt4v"]:
+            assert cer > 0.0
+        # Pero strictement plus mauvais que GPT-4v.
+        for tess, gpt, pero in zip(
+            cer_by_pipeline["tesseract"],
+            cer_by_pipeline["gpt4v"],
+            cer_by_pipeline["pero"],
+        ):
+            assert pero > gpt > tess
+
+        # Le rapport HTML mentionne les 3 pipelines.
+        html = report_path.read_text(encoding="utf-8")
+        for name in ("tesseract_baseline", "gpt4v_alternative", "pero_alternative"):
+            assert name in html
+
+    def test_missing_source_file_produces_failed_step(
+        self, tmp_path: Path,
+    ) -> None:
+        """Si un fichier pré-calculé manque, le pipeline du document
+        concerné échoue (StepResult.error renseigné), mais les autres
+        pipelines/documents continuent — le benchmark ne crash pas
+        globalement."""
+        runner = CliRunner()
+        # Corpus avec 1 doc, mais le fichier .tesseract.txt manque.
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, mode="w") as zf:
+            zf.writestr("doc01.png", _png_bytes())
+            zf.writestr("doc01.gt.txt", "Bonjour")
+            # PAS de doc01.tesseract.txt
+        corpus_zip = tmp_path / "corpus.zip"
+        corpus_zip.write_bytes(buf.getvalue())
+
+        spec_path = tmp_path / "run.yaml"
+        out_dir = tmp_path / "out"
+        spec_path.write_text(textwrap.dedent(f"""
+            corpus_zip: {corpus_zip}
+            corpus_name: bnf_missing
+            pipelines:
+              - name: tesseract_baseline
+                initial_inputs: [image]
+                steps:
+                  - id: ocr
+                    adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+                    adapter_kwargs:
+                      source_label: tesseract
+                    input_types: [image]
+                    output_types: [raw_text]
+            views: [text_final]
+            output_dir: {out_dir}
+        """))
+
+        result = runner.invoke(cli, ["run", "--spec", str(spec_path)])
+        # Le run termine — l'erreur est isolée au step.
+        assert result.exit_code == 0, result.output
+
+        # Le PipelineResult reflète l'échec.
+        results_dir = out_dir / "results"
+        pipeline_lines = [
+            json.loads(line)
+            for line in (results_dir / "pipeline_results.jsonl").read_text().strip().split("\n")
+            if line.strip()
+        ]
+        assert len(pipeline_lines) == 1
+        pr = pipeline_lines[0]
+        assert pr["succeeded"] is False
+        assert any(
+            sr.get("error") and "introuvable" in sr["error"]
+            for sr in pr["step_results"]
+        )