feat(adapters/ocr): Sprint A14-S30 — TesseractAdapter natif (no shim)

Migration native du legacy picarones.engines.tesseract.TesseractEngine
vers le contrat BaseOCRAdapter (S26). Pas un shim : la classe implémente
directement le contrat du nouveau monde, sans héritage du legacy.

Le legacy TesseractEngine reste en place pour les callers qui n'ont
pas encore migré ; sa suppression viendra au S46 quand la parité sera
atteinte sur tous les adapters (S30-S34).

picarones/adapters/ocr/tesseract.py
-----------------------------------
- TesseractAdapter(BaseOCRAdapter) — direct hérite, pas de shim.
- input_types = {IMAGE}, output_types = {RAW_TEXT}.
- execution_mode = "cpu" (Tesseract appelle une lib C en sous-process,
ProcessPool dans le runner pour vrai parallélisme).
- Constructeur kwargs-only : name (alphanum + _-), lang, psm (0-13),
oem (0-3), tesseract_cmd. Validation stricte au constructeur.
- execute(inputs, params, context) :
· valide IMAGE input + URI + fichier existe ;
· lazy-import pytesseract + PIL avec OCRAdapterError clair si absent ;
· applique tesseract_cmd custom si fourni ;
· pytesseract.image_to_string(image, lang, --oem N --psm M) ;
· text strippé (rétrocompat octet-pour-octet legacy S1) ;
· écrit dans <stem>.<name>.txt à côté de l'image (cohérent avec
PrecomputedTextAdapter — un caller peut relire la sortie via
cet adapter pour la comparer dans un second run) ;
· Artifact RAW_TEXT avec id "<doc>:<name>:raw_text".
- Erreurs Tesseract wrappées dans OCRAdapterError avec type+message.

Tests S30 dédiés (24 nouveaux)
------------------------------
- TesseractAdapterConstructor : defaults, custom name, rejet name vide/
whitespace/chars invalides, rejet psm hors [0,13], rejet oem hors
[0,3], boundary values acceptées.
- TesseractAdapterContract : isinstance BaseOCRAdapter, input_types,
output_types, execution_mode = "cpu".
- TesseractAdapterInputValidation : IMAGE absent → OCRAdapterError,
artefact sans URI → OCRAdapterError, image inexistante →
OCRAdapterError.
- TesseractAdapterExecute : nominal (mocked pytesseract) → Artifact +
fichier <stem>.tesseract.txt, custom name change le filename, lang/
psm/oem passés correctement à pytesseract, tesseract_cmd appliqué,
exception Tesseract wrappée, pytesseract absent → OCRAdapterError
avec pip install hint, artifact id utilise adapter name, text strippé.

Pas de confidences pour S30
---------------------------
Confidences (legacy S47 image_to_data) reportées à un sprint dédié qui
définira ConfidenceArtifact typé, conformément à la doc BaseOCRAdapter
(S26). La fonctionnalité reste disponible via legacy
picarones.engines.tesseract jusqu'au S46.

Tests : 4622 passed, 11 skipped (vs 4596 avant : +24 S30 + 2 README).
Lint : ruff check picarones/ tests/ → All checks passed.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

README.md

@@ -396,7 +396,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~4610 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4640 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP. A handful of tests depend on optional engines
 (`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when

picarones/adapters/ocr/__init__.py

@@ -21,9 +21,11 @@ from __future__ import annotations
 
 from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
 from picarones.adapters.ocr.precomputed import PrecomputedTextAdapter
+from picarones.adapters.ocr.tesseract import TesseractAdapter
 
 __all__ = [
     "BaseOCRAdapter",
     "OCRAdapterError",
     "PrecomputedTextAdapter",
+    "TesseractAdapter",
 ]

picarones/adapters/ocr/tesseract.py

@@ -0,0 +1,237 @@
+"""``TesseractAdapter`` natif — Sprint A14-S30.
+
+Migration native du legacy ``picarones.engines.tesseract.TesseractEngine``
+vers le contrat ``BaseOCRAdapter`` (S26).  **Pas un shim** : la classe
+implémente directement le contrat du nouveau monde, sans héritage du
+legacy.
+
+Le legacy ``TesseractEngine`` reste en place pour les callers qui
+n'ont pas encore migré ; sa suppression viendra au S46 quand la
+parité sera atteinte sur tous les adapters.
+
+Cas d'usage BnF
+---------------
+Tesseract 5 reste l'OCR open-source de référence pour les corpus
+imprimés et certains manuscrits réguliers.  L'adapter est CPU-bound
+(Tesseract appelle une lib C en sous-process) — déclaré
+``execution_mode="cpu"`` pour que le runner utilise un
+``ProcessPoolExecutor``.
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"tesseract"``) : identifiant de l'instance.
+  Sert de suffixe au fichier de sortie ``<stem>.<name>.txt`` —
+  permet de coexister avec plusieurs configurations Tesseract dans
+  un même benchmark.
+- ``lang`` (défaut ``"fra"``) : code langue Tesseract (``"fra"``,
+  ``"lat"``, ``"eng"``, ``"fra+lat"``).
+- ``psm`` (défaut ``6``) : Page Segmentation Mode (0-13).
+- ``oem`` (défaut ``3``) : OCR Engine Mode.
+- ``tesseract_cmd`` (défaut ``None``) : chemin vers l'exécutable
+  ``tesseract`` si non standard.
+
+Comportement
+------------
+1. Vérifie qu'un ``Artifact`` ``IMAGE`` est présent dans ``inputs``
+   et qu'il porte une ``uri`` filesystem.
+2. Lazy-import de ``pytesseract`` et ``PIL`` — si absent, lève
+   ``OCRAdapterError`` avec message explicite.
+3. Applique ``tesseract_cmd`` s'il est fourni.
+4. Appelle ``pytesseract.image_to_string`` avec ``lang`` et
+   ``--oem N --psm M``.
+5. Écrit le texte dans ``<stem>.<name>.txt`` à côté de l'image.
+   Cohérent avec le pattern ``PrecomputedTextAdapter`` (Sprint S26)
+   — un caller peut relire la sortie via cet adapter pour la
+   comparer dans un second run.
+6. Retourne un ``Artifact`` ``RAW_TEXT`` pointant vers le fichier
+   produit.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de retry — Tesseract échoue rarement sur une image valide,
+  et un appelant peut wrapper si besoin.
+- Pas d'extraction de confidences (legacy S47) — reporté à un
+  sprint dédié qui définira ``ConfidenceArtifact`` typé.  La
+  fonctionnalité reste disponible via le legacy
+  ``picarones.engines.tesseract.TesseractEngine`` jusqu'au S46.
+- Pas de validation de l'encodage de l'image — Tesseract gère.
+- Pas de support batch — un appel par image (le runner gère le
+  parallélisme inter-documents).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class TesseractAdapter(BaseOCRAdapter):
+    """Adapter Tesseract 5 natif au nouveau contrat (S26).
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible de l'instance.  Défaut ``"tesseract"``.
+        Doit être alphanumérique + ``_-`` (composant de nom de fichier).
+    lang:
+        Code langue Tesseract (``"fra"``, ``"lat"``, ``"eng"``, ...).
+        Défaut ``"fra"``.
+    psm:
+        Page Segmentation Mode entre 0 et 13.  Défaut 6
+        (single uniform block of text).
+    oem:
+        OCR Engine Mode (0-3).  Défaut 3 (LSTM, le plus précis).
+    tesseract_cmd:
+        Chemin custom vers l'exécutable ``tesseract``.  Défaut
+        ``None`` (laisse pytesseract trouver l'installation système).
+
+    Raises
+    ------
+    OCRAdapterError
+        Si le ``name`` ou les valeurs de ``psm`` / ``oem`` sont
+        invalides.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "cpu"
+
+    def __init__(
+        self,
+        *,
+        name: str = "tesseract",
+        lang: str = "fra",
+        psm: int = 6,
+        oem: int = 3,
+        tesseract_cmd: str | None = None,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "TesseractAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"TesseractAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if not 0 <= psm <= 13:
+            raise OCRAdapterError(
+                f"TesseractAdapter : psm doit être ∈ [0, 13], reçu {psm}.",
+            )
+        if not 0 <= oem <= 3:
+            raise OCRAdapterError(
+                f"TesseractAdapter : oem doit être ∈ [0, 3], reçu {oem}.",
+            )
+        self._name = name
+        self._lang = lang
+        self._psm = psm
+        self._oem = oem
+        self._tesseract_cmd = tesseract_cmd
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def lang(self) -> str:
+        return self._lang
+
+    @property
+    def psm(self) -> int:
+        return self._psm
+
+    @property
+    def oem(self) -> int:
+        return self._oem
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute Tesseract sur l'image fournie.
+
+        Raises
+        ------
+        OCRAdapterError
+            - input ``IMAGE`` absent ;
+            - artefact image sans URI ;
+            - fichier image introuvable ;
+            - ``pytesseract`` ou ``PIL`` non installé ;
+            - erreur Tesseract (lib system manquante, etc.).
+        """
+        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} : image introuvable {image_path!r}.",
+            )
+
+        # Lazy-import de pytesseract + PIL — si absents, message
+        # explicite plutôt qu'``ImportError`` au top-level.
+        try:
+            import pytesseract  # type: ignore[import-untyped]
+            from PIL import Image
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : pytesseract/Pillow non installés. "
+                "Installer avec : pip install pytesseract pillow",
+            ) from exc
+
+        # Application du tesseract_cmd custom si fourni.
+        if self._tesseract_cmd is not None:
+            pytesseract.pytesseract.tesseract_cmd = self._tesseract_cmd
+
+        # OCR.
+        custom_config = f"--oem {self._oem} --psm {self._psm}"
+        try:
+            with Image.open(image_path) as image:
+                text = pytesseract.image_to_string(
+                    image,
+                    lang=self._lang,
+                    config=custom_config,
+                )
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : Tesseract a levé sur "
+                f"{image_path!r} : {type(exc).__name__}: {exc}",
+            ) from exc
+
+        text = text.strip()
+
+        # Écriture du résultat à côté de l'image.  Cohérent avec le
+        # pattern ``PrecomputedTextAdapter`` — un caller peut relire
+        # la sortie via cet adapter pour la comparer dans un second run.
+        text_path = (
+            image_path.parent / f"{image_path.stem}.{self.name}.txt"
+        )
+        text_path.write_text(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(text_path),
+            ),
+        }
+
+
+__all__ = ["TesseractAdapter"]

tests/adapters/ocr/test_sprint_a14_s30_tesseract_adapter.py

@@ -0,0 +1,377 @@
+"""Sprint A14-S30 — ``TesseractAdapter`` natif au contrat S26.
+
+Tests de l'adapter Tesseract migré nativement (pas de shim sur le
+legacy ``picarones.engines.tesseract``).
+
+Couvre :
+
+1. Constructeur :
+   - rejet des paramètres invalides (name, psm, oem) ;
+   - valeurs par défaut ;
+   - propriétés en lecture.
+
+2. ``execute`` :
+   - cas nominal (mock pytesseract) → Artifact RAW_TEXT avec URI ;
+   - input IMAGE absent → OCRAdapterError ;
+   - artefact image sans URI → OCRAdapterError ;
+   - image inexistante → OCRAdapterError ;
+   - pytesseract non installé → OCRAdapterError ;
+   - Tesseract lève → OCRAdapterError ;
+   - écriture du fichier de sortie au bon emplacement ;
+   - tesseract_cmd appliqué.
+
+3. Contrat ``BaseOCRAdapter`` :
+   - input_types / output_types / execution_mode ;
+   - hérite bien de BaseOCRAdapter.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from picarones.adapters.ocr import (
+    BaseOCRAdapter,
+    OCRAdapterError,
+    TesseractAdapter,
+)
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.pipeline.types import RunContext
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────────────────────────────
+
+
+def _make_image_artifact(uri: str) -> Artifact:
+    return Artifact(
+        id="d1:initial:image",
+        document_id="d1",
+        type=ArtifactType.IMAGE,
+        uri=uri,
+    )
+
+
+def _make_context() -> RunContext:
+    return RunContext(
+        document_id="d1",
+        code_version="1.0.0",
+        pipeline_name="test",
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Constructeur
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestTesseractAdapterConstructor:
+    def test_defaults(self) -> None:
+        adapter = TesseractAdapter()
+        assert adapter.name == "tesseract"
+        assert adapter.lang == "fra"
+        assert adapter.psm == 6
+        assert adapter.oem == 3
+
+    def test_custom_name(self) -> None:
+        adapter = TesseractAdapter(name="my_tesseract_lat")
+        assert adapter.name == "my_tesseract_lat"
+
+    def test_rejects_empty_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="vide"):
+            TesseractAdapter(name="")
+
+    def test_rejects_whitespace_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="vide"):
+            TesseractAdapter(name="   ")
+
+    def test_rejects_invalid_chars_in_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="invalide"):
+            TesseractAdapter(name="bad name with space")
+
+    def test_rejects_psm_out_of_range(self) -> None:
+        with pytest.raises(OCRAdapterError, match=r"psm.*\[0, 13\]"):
+            TesseractAdapter(psm=14)
+        with pytest.raises(OCRAdapterError, match=r"psm.*\[0, 13\]"):
+            TesseractAdapter(psm=-1)
+
+    def test_rejects_oem_out_of_range(self) -> None:
+        with pytest.raises(OCRAdapterError, match=r"oem.*\[0, 3\]"):
+            TesseractAdapter(oem=4)
+        with pytest.raises(OCRAdapterError, match=r"oem.*\[0, 3\]"):
+            TesseractAdapter(oem=-1)
+
+    def test_accepts_psm_boundary_values(self) -> None:
+        TesseractAdapter(psm=0)
+        TesseractAdapter(psm=13)
+
+    def test_accepts_oem_boundary_values(self) -> None:
+        TesseractAdapter(oem=0)
+        TesseractAdapter(oem=3)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Contrat BaseOCRAdapter
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestTesseractAdapterContract:
+    def test_inherits_base_adapter(self) -> None:
+        adapter = TesseractAdapter()
+        assert isinstance(adapter, BaseOCRAdapter)
+
+    def test_input_types(self) -> None:
+        assert TesseractAdapter.input_types == frozenset({ArtifactType.IMAGE})
+
+    def test_output_types(self) -> None:
+        assert TesseractAdapter.output_types == frozenset({ArtifactType.RAW_TEXT})
+
+    def test_execution_mode_is_cpu(self) -> None:
+        """Tesseract est CPU-bound — utilise un ProcessPool dans le runner."""
+        assert TesseractAdapter.execution_mode == "cpu"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# execute() — validation des inputs
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestTesseractAdapterInputValidation:
+    def test_missing_image_input_raises(self, tmp_path: Path) -> None:
+        adapter = TesseractAdapter()
+        with pytest.raises(OCRAdapterError, match="IMAGE manquant"):
+            adapter.execute(inputs={}, params={}, context=_make_context())
+
+    def test_image_artifact_without_uri_raises(self) -> None:
+        adapter = TesseractAdapter()
+        artifact = Artifact(
+            id="d1:img",
+            document_id="d1",
+            type=ArtifactType.IMAGE,
+            uri=None,  # explicit no URI
+        )
+        with pytest.raises(OCRAdapterError, match="sans URI"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_image_path_does_not_exist_raises(self) -> None:
+        adapter = TesseractAdapter()
+        artifact = _make_image_artifact("/nonexistent/path/img.png")
+        with pytest.raises(OCRAdapterError, match="introuvable"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# execute() — chemin nominal et erreurs Tesseract
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestTesseractAdapterExecute:
+    def _create_dummy_image(self, tmp_path: Path) -> Path:
+        """Crée un fichier vide qui sert d'image (les tests mocquent
+        pytesseract donc le contenu n'est pas analysé)."""
+        path = tmp_path / "page.png"
+        path.write_bytes(b"\x89PNG\r\n\x1a\n")  # signature PNG basique
+        return path
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_nominal_execution(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Cas nominal : pytesseract retourne du texte → Artifact RAW_TEXT
+        avec URI vers un fichier produit."""
+        mock_image_to_string.return_value = "Bonjour le monde\n"
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter()
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        result = adapter.execute(
+            inputs={ArtifactType.IMAGE: artifact},
+            params={},
+            context=_make_context(),
+        )
+        assert ArtifactType.RAW_TEXT in result
+        produced = result[ArtifactType.RAW_TEXT]
+        assert produced.type == ArtifactType.RAW_TEXT
+        assert produced.uri is not None
+
+        # Le fichier de sortie existe et contient le texte stripé.
+        out_path = Path(produced.uri)
+        assert out_path.exists()
+        assert out_path.read_text(encoding="utf-8") == "Bonjour le monde"
+
+        # Convention : <stem>.<name>.txt à côté de l'image.
+        assert out_path.name == "page.tesseract.txt"
+        assert out_path.parent == tmp_path
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_custom_name_changes_output_filename(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        mock_image_to_string.return_value = "x"
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter(name="tess_lat_psm6")
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        result = adapter.execute(
+            inputs={ArtifactType.IMAGE: artifact},
+            params={},
+            context=_make_context(),
+        )
+        out_path = Path(result[ArtifactType.RAW_TEXT].uri)
+        assert out_path.name == "page.tess_lat_psm6.txt"
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_lang_psm_oem_passed_to_pytesseract(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        mock_image_to_string.return_value = "x"
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter(lang="lat", psm=4, oem=1)
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        adapter.execute(
+            inputs={ArtifactType.IMAGE: artifact},
+            params={},
+            context=_make_context(),
+        )
+
+        # On vérifie l'appel à pytesseract.image_to_string avec les bons args.
+        assert mock_image_to_string.called
+        kwargs = mock_image_to_string.call_args.kwargs
+        assert kwargs["lang"] == "lat"
+        assert "--psm 4" in kwargs["config"]
+        assert "--oem 1" in kwargs["config"]
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_tesseract_cmd_applied_when_set(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        mock_image_to_string.return_value = "x"
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        # Ré-import temporaire pour récupérer le module.
+        import pytesseract  # type: ignore[import-untyped]
+        adapter = TesseractAdapter(tesseract_cmd="/custom/bin/tesseract")
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        adapter.execute(
+            inputs={ArtifactType.IMAGE: artifact},
+            params={},
+            context=_make_context(),
+        )
+        assert pytesseract.pytesseract.tesseract_cmd == "/custom/bin/tesseract"
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_tesseract_exception_wrapped_in_ocr_error(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        mock_image_to_string.side_effect = RuntimeError("Tesseract crashed")
+        adapter = TesseractAdapter()
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with pytest.raises(OCRAdapterError, match="RuntimeError.*Tesseract crashed"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_pytesseract_not_installed_raises_clean_error(
+        self, tmp_path: Path,
+    ) -> None:
+        """Si pytesseract est introuvable, l'erreur est claire et
+        propose une commande pip."""
+        adapter = TesseractAdapter()
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        # Simule que pytesseract est absent.
+        with patch.dict(sys.modules, {"pytesseract": None}):
+            with pytest.raises(
+                OCRAdapterError, match="pytesseract.*pip install",
+            ):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_artifact_id_uses_adapter_name(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        mock_image_to_string.return_value = "x"
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter(name="custom_name")
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        result = adapter.execute(
+            inputs={ArtifactType.IMAGE: artifact},
+            params={},
+            context=_make_context(),
+        )
+        produced = result[ArtifactType.RAW_TEXT]
+        assert produced.id == "d1:custom_name:raw_text"
+        assert produced.document_id == "d1"
+        assert produced.produced_by_step == "ocr"
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_text_is_stripped(
+        self, mock_image_to_string: MagicMock,
+        mock_image_open: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Le texte est strippé des whitespaces extérieurs comme dans
+        le legacy."""
+        mock_image_to_string.return_value = "  \n\nHello world\n\n  "
+        mock_image_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter()
+        image_path = self._create_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        result = adapter.execute(
+            inputs={ArtifactType.IMAGE: artifact},
+            params={},
+            context=_make_context(),
+        )
+        out_text = Path(result[ArtifactType.RAW_TEXT].uri).read_text(
+            encoding="utf-8",
+        )
+        assert out_text == "Hello world"