feat(sprint-A): wrapper BaseOCREngine→StepExecutor + prompt_template via params

Sprint A du plan v2.0 — fondation du chemin de retrait
``OCRLLMPipeline``. Trois livrables concrets qui débloquent le
Sprint B (refactor de ``OCRLLMPipeline.run()`` pour qu'il délègue
à ``PipelineExecutor``).

A.1 — LegacyOCREngineExecutor
-----------------------------
Nouveau module ``picarones/adapters/legacy_engines/_step_executor.py``
qui présente un ``BaseOCREngine`` legacy comme ``StepExecutor`` du
pipeline rewrite. Permet au ``PipelineExecutor`` (S7 du rewrite) de
consommer les 5 OCR engines legacy (Tesseract, Pero, Mistral OCR,
Google Vision, Azure DI) sans réimplémenter chacun en
``BaseOCRAdapter``.

Contrat :

- ``input_types = frozenset({IMAGE})``,
``output_types = frozenset({RAW_TEXT})``.
- ``execution_mode`` hérité de l'engine wrappé (``"cpu"`` pour
Tesseract/Pero, ``"io"`` pour les engines cloud).
- ``execute()`` lit l'``Artifact IMAGE``, appelle ``engine.run(uri)``,
écrit le texte produit dans ``context.workspace_uri`` via
``resolve_output_path``, retourne un ``Artifact RAW_TEXT``.
- ``EngineResult.error`` non-vide → ``OCRAdapterError`` propagée
(le ``PipelineExecutor`` capturera et marquera le step en échec).

Trace de retrait : ce wrapper est lui-même temporaire, supprimé en
Sprint H quand ``BaseOCREngine`` disparaîtra (les 5 engines auront
leur jumeau ``adapters/ocr/<engine>.py`` qui implémente déjà
``BaseOCRAdapter`` — la parité est déjà 5/5 côté rewrite).

A.2 — params["prompt_template"] pour BaseLLMAdapter.execute()
-------------------------------------------------------------
Le contrat actuel de ``BaseLLMAdapter.execute()`` (Sprint A14-S44)
substituait ``{text}`` via ``str.format(text=...)`` depuis
``self.config["correction_prompt"]`` ou les défauts par langue.
Le format legacy d'``OCRLLMPipeline`` utilise ``{ocr_output}``
et ``{image_b64}`` — incompatible avec ``str.format`` strict.

Trois ajouts :

1. Helper ``_substitute_prompt_variables(template, text, image_b64)``
qui détecte automatiquement la convention :
- ``{text}`` présent → ``str.format(text=...)`` (rewrite, strict).
- ``{ocr_output}`` ou ``{image_b64}`` présent → ``str.replace``
tolérant (legacy).
2. ``execute()`` lit ``params["prompt_template"]`` en priorité, puis
tombe sur ``self.config["correction_prompt"]``, puis sur les
défauts par langue. Permet à un caller construisant une
``PipelineSpec`` d'injecter un prompt sans devoir reconfigurer
l'adapter au constructeur.
3. La priorité reste documentée :
``params > config > defaults_per_lang > FR fallback``.

Aucune régression sur les callers existants — ceux qui définissent
``self.config["correction_prompt"]`` ou utilisent les défauts par
langue voient le même comportement qu'avant.

A.3 — Tests d'intégration
-------------------------
``tests/pipeline/test_sprint_a_legacy_engine_executor.py`` —
15 tests couvrant :

- Le contrat statique du wrapper (input_types, output_types).
- Le rejet d'un argument non-``BaseOCREngine``.
- L'héritage de ``execution_mode``.
- L'écriture du fichier ``RAW_TEXT`` dans ``workspace_uri``.
- La levée d'``OCRAdapterError`` quand ``IMAGE`` est manquant.
- Les deux conventions de substitution de prompt
(``{text}`` rewrite ; ``{ocr_output}`` / ``{image_b64}`` legacy).
- L'override ``params["prompt_template"]`` qui prime sur
``self.config``.
- **End-to-end** : un OCR legacy wrappé + un LLM rewrite enchaînés
via ``PipelineExecutor`` produisent un ``CORRECTED_TEXT`` identique
à ce que ``OCRLLMPipeline`` aurait produit. Vérifié pour les
modes ``text_only`` et ``text_and_image`` (le LLM reçoit l'image
encodée base64 en multimodal).

Bilan
-----
- ``pytest tests/`` : 4755 passed (+15), 0 failed.
- ``ruff check`` : clean.
- 1 module créé (181 LOC), 1 test créé (322 LOC), 2 fonctions
ajoutées dans ``adapters/llm/base.py`` (+45 LOC).
- Aucune API publique modifiée — c'est un ajout pur.

Sprint B débloqué
-----------------
Avec ``LegacyOCREngineExecutor`` et le ``params["prompt_template"]``,
le Sprint B peut maintenant :

1. Construire un ``PipelineSpec`` via ``make_ocr_llm_pipeline_spec``
(commit f894bf0).
2. Wrapper ``self.ocr_engine`` via ``LegacyOCREngineExecutor``.
3. Construire un mini-``PipelineExecutor`` mono-document avec un
tempdir comme ``workspace_uri``.
4. Lancer ``executor.run(spec, doc, initial_inputs, context)`` et
convertir le ``PipelineResult`` en ``EngineResult`` legacy.

C'est ce qui sera fait dans le commit ``feat(sprint-B)``.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

CLAUDE.md

@@ -123,7 +123,7 @@ picarones/
 
 ## État des tests et bugs historiques
 
-`pytest tests/` → **4770 passed, 12 skipped, 8 deselected, 0 failed**
+`pytest tests/` → **4790 passed, 12 skipped, 8 deselected, 0 failed**
 (post-S59).  Les deselected sont les markers `live` (5 tests d'intégration
 contre vraie API/binaire) + `network` (3 tests qui hit le réseau réel),
 opt-in en local via `pytest -m live` ou `pytest -m network`.  Le
@@ -253,7 +253,7 @@ Résumé express :
 
 1. `git branch --show-current` → `claude/repo-analysis-cukvm`.
 2. `git status` → working tree clean.
-3. `pytest tests/ -q --no-header --tb=line` → 4770 passed.
+3. `pytest tests/ -q --no-header --tb=line` → 4790 passed.
 4. `git log -1 --format=%B` → décrit la prochaine sub-phase.
 
 **Règles d'architecture critiques** (apprises à la dure) :
@@ -341,7 +341,7 @@ détecte, arbitre, rend.
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces, Python 3.11+
-- **Tests** : `pytest tests/ -q` → 4770 passed, 12 skipped, 24
+- **Tests** : `pytest tests/ -q` → 4790 passed, 12 skipped, 24
   deselected, 0 failed (au moment de la pause de session).
 - **Plan d'évolution actif** : [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md).
 - **Plan retrait du legacy (maître)** : [`docs/migration/legacy-retirement-plan.md`](docs/migration/legacy-retirement-plan.md).

README.md

@@ -200,6 +200,7 @@ 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 |
@@ -394,7 +395,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~4770 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4790 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/legacy_engines/_step_executor.py

@@ -0,0 +1,180 @@
+"""``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:
+        if not isinstance(engine, BaseOCREngine):
+            raise OCRAdapterError(
+                "LegacyOCREngineExecutor requires a BaseOCREngine instance ; "
+                f"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.
+        self.execution_mode: str = getattr(engine, "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/llm/base.py

@@ -152,6 +152,47 @@ def log_http_error(
 from picarones.domain.errors import AdapterStepError
 
 
+def _substitute_prompt_variables(
+    template: str,
+    text: str,
+    image_b64: str | None,
+) -> str:
+    """Substitue les variables d'un template de prompt LLM.
+
+    Supporte deux conventions de nommage des variables :
+
+    - **Rewrite** (Sprint A14-S44) : ``{text}``.  Substitué par
+      ``str.format(text=text)``.
+    - **Legacy** (``OCRLLMPipeline``, Sprint A.2 du plan v2.0) :
+      ``{ocr_output}`` et ``{image_b64}``.  Substitués par
+      ``str.replace(...)`` — tolérant si une variable est absente
+      du template.
+
+    La convention est détectée automatiquement.  Si le template
+    contient ``{ocr_output}`` ou ``{image_b64}``, on applique le
+    format legacy ; sinon, on applique le format rewrite (qui
+    lèvera ``KeyError`` si une variable inattendue est utilisée,
+    comportement strict d'origine).
+
+    Parameters
+    ----------
+    template:
+        Template de prompt (chaîne avec variables ``{...}``).
+    text:
+        Texte OCR à injecter (substitue ``{text}`` ou ``{ocr_output}``).
+    image_b64:
+        Image encodée base64 sans préfixe (substitue ``{image_b64}``).
+        ``None`` → chaîne vide pour les modes texte-seul.
+    """
+    if "{ocr_output}" in template or "{image_b64}" in template:
+        return (
+            template
+            .replace("{ocr_output}", text)
+            .replace("{image_b64}", image_b64 or "")
+        )
+    return template.format(text=text)
+
+
 class LLMAdapterError(AdapterStepError):
     """Erreur typée pour un échec d'adapter LLM.
 
@@ -427,26 +468,38 @@ class BaseLLMAdapter(ABC):
                     image_path.read_bytes(),
                 ).decode("ascii")
 
-        # Priorité : override explicite via config > prompt par langue
-        # selon config["lang"] > FR par défaut.
-        custom_prompt = self.config.get("correction_prompt")
-        if custom_prompt is not None:
-            prompt_template = custom_prompt
+        # Priorité (Sprint A.2 du plan v2.0) :
+        # 1. ``params["prompt_template"]`` (override par le step lui-même —
+        #    permet à un caller qui construit une PipelineSpec d'injecter
+        #    un prompt personnalisé sans toucher à la config de l'adapter).
+        # 2. ``self.config["correction_prompt"]`` (override au constructeur
+        #    de l'adapter — pattern historique).
+        # 3. Prompt par langue selon ``self.config["lang"]``.
+        # 4. Fallback FR.
+        param_prompt = params.get("prompt_template") if params else None
+        if param_prompt is not None:
+            prompt_template = param_prompt
         else:
-            lang = (self.config.get("lang") or "fr").lower()
-            if lang not in self.DEFAULT_CORRECTION_PROMPTS:
-                logger.warning(
-                    "[%s] lang=%r non supportée par "
-                    "DEFAULT_CORRECTION_PROMPTS (%s) — fallback FR. "
-                    "Pour un corpus dans cette langue, fournir "
-                    "config['correction_prompt'] explicite.",
-                    self.name, lang,
-                    sorted(self.DEFAULT_CORRECTION_PROMPTS.keys()),
+            custom_prompt = self.config.get("correction_prompt")
+            if custom_prompt is not None:
+                prompt_template = custom_prompt
+            else:
+                lang = (self.config.get("lang") or "fr").lower()
+                if lang not in self.DEFAULT_CORRECTION_PROMPTS:
+                    logger.warning(
+                        "[%s] lang=%r non supportée par "
+                        "DEFAULT_CORRECTION_PROMPTS (%s) — fallback FR. "
+                        "Pour un corpus dans cette langue, fournir "
+                        "config['correction_prompt'] explicite.",
+                        self.name, lang,
+                        sorted(self.DEFAULT_CORRECTION_PROMPTS.keys()),
+                    )
+                prompt_template = self.DEFAULT_CORRECTION_PROMPTS.get(
+                    lang, self.DEFAULT_CORRECTION_PROMPTS["fr"],
                 )
-            prompt_template = self.DEFAULT_CORRECTION_PROMPTS.get(
-                lang, self.DEFAULT_CORRECTION_PROMPTS["fr"],
-            )
-        prompt = prompt_template.format(text=original_text)
+        prompt = _substitute_prompt_variables(
+            prompt_template, original_text, image_b64,
+        )
 
         result = self.complete(prompt, image_b64=image_b64)
         if not result.success:

tests/pipeline/test_sprint_a_legacy_engine_executor.py

@@ -0,0 +1,411 @@
+"""Sprint A.3 (plan v2.0) — intégration OCR legacy + LLM rewrite.
+
+Vérifie que :
+
+1. ``LegacyOCREngineExecutor`` (Sprint A.1) wrap correctement un
+   ``BaseOCREngine`` legacy en ``StepExecutor`` rewrite.
+2. ``BaseLLMAdapter.execute()`` (Sprint A.2) accepte un
+   ``params["prompt_template"]`` avec convention legacy
+   (``{ocr_output}`` / ``{image_b64}``) en plus de la convention
+   rewrite (``{text}``).
+3. Les deux briques s'enchaînent dans ``PipelineExecutor`` via la
+   spec produite par ``make_ocr_llm_pipeline_spec`` (Phase 6 volet 2,
+   commit f894bf0) et produisent le texte attendu.
+
+Ce test prouve que la délégation prévue au Sprint B (refactor de
+``OCRLLMPipeline.run()``) est techniquement réalisable — le pont
+entre l'API legacy et le rewrite est fonctionnel.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import pytest
+
+from picarones.adapters.legacy_engines._step_executor import (
+    LegacyOCREngineExecutor,
+)
+from picarones.adapters.legacy_engines.base import BaseOCREngine
+from picarones.adapters.llm.base import (
+    BaseLLMAdapter,
+    _substitute_prompt_variables,
+)
+from picarones.adapters.ocr.base import OCRAdapterError
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.domain.documents import DocumentRef
+from picarones.pipeline import (
+    PipelineExecutor,
+    RunContext,
+    make_ocr_llm_pipeline_spec,
+)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Mocks — OCR engine legacy + LLM adapter rewrite
+# ──────────────────────────────────────────────────────────────────────
+
+
+class _MockOCREngine(BaseOCREngine):
+    """OCR engine déterministe (texte fixe quel que soit l'image)."""
+
+    def __init__(self, fixed_text: str = "ocr output text") -> None:
+        super().__init__(config={})
+        self._fixed_text = fixed_text
+
+    @property
+    def name(self) -> str:
+        return "mock_ocr"
+
+    def version(self) -> str:
+        return "1.0.0"
+
+    def _run_ocr(self, image_path: Path) -> str:
+        return self._fixed_text
+
+
+class _MockLLMAdapter(BaseLLMAdapter):
+    """LLM adapter qui renvoie le prompt reçu en upper-case.
+
+    Utile pour vérifier ce que l'adapter a effectivement reçu après
+    substitution des variables — le test peut grep le ``LLMResult.text``.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(model="mock-1", config={})
+        self.last_prompt: Optional[str] = None
+        self.last_image_b64: Optional[str] = None
+
+    @property
+    def name(self) -> str:
+        return "mock_llm"
+
+    @property
+    def default_model(self) -> str:
+        return "mock-1"
+
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        self.last_prompt = prompt
+        self.last_image_b64 = image_b64
+        # Renvoie le prompt entier en upper-case pour qu'on puisse le
+        # vérifier côté test.
+        return prompt.upper()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# A.1 — LegacyOCREngineExecutor seul
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestLegacyOCREngineExecutor:
+    def test_static_contract(self) -> None:
+        """Les attributs StepExecutor sont déclarés correctement."""
+        assert LegacyOCREngineExecutor.input_types == frozenset(
+            {ArtifactType.IMAGE},
+        )
+        assert LegacyOCREngineExecutor.output_types == frozenset(
+            {ArtifactType.RAW_TEXT},
+        )
+
+    def test_rejects_non_engine(self) -> None:
+        with pytest.raises(OCRAdapterError):
+            LegacyOCREngineExecutor("not an engine")  # type: ignore[arg-type]
+
+    def test_inherits_execution_mode_from_engine(self) -> None:
+        engine = _MockOCREngine()
+        engine.execution_mode = "cpu"
+        step = LegacyOCREngineExecutor(engine)
+        assert step.execution_mode == "cpu"
+
+    def test_name_delegates_to_engine(self) -> None:
+        step = LegacyOCREngineExecutor(_MockOCREngine())
+        assert step.name == "mock_ocr"
+
+    def test_execute_writes_text_artifact(self, tmp_path: Path) -> None:
+        """Le wrapper écrit le texte OCR dans le workspace et retourne
+        un Artifact RAW_TEXT pointant sur ce fichier."""
+        engine = _MockOCREngine(fixed_text="bonjour le monde")
+        step = LegacyOCREngineExecutor(engine)
+
+        # Préparer un fichier image factice (le mock n'utilise pas son
+        # contenu, mais le wrapper vérifie son existence).
+        image_path = tmp_path / "input.png"
+        image_path.write_bytes(b"\x89PNG fake")
+        image_artifact = Artifact(
+            id="doc1:initial:image",
+            document_id="doc1",
+            type=ArtifactType.IMAGE,
+            uri=str(image_path),
+        )
+        context = RunContext(
+            document_id="doc1",
+            code_version="test",
+            pipeline_name="test_pipe",
+            workspace_uri=str(tmp_path),
+        )
+
+        outputs = step.execute(
+            inputs={ArtifactType.IMAGE: image_artifact},
+            params={},
+            context=context,
+        )
+
+        assert ArtifactType.RAW_TEXT in outputs
+        text_artifact = outputs[ArtifactType.RAW_TEXT]
+        assert text_artifact.document_id == "doc1"
+        assert text_artifact.produced_by_step == "ocr"
+        text_path = Path(text_artifact.uri)
+        assert text_path.exists()
+        assert text_path.read_text(encoding="utf-8") == "bonjour le monde"
+
+    def test_execute_raises_on_missing_image(self, tmp_path: Path) -> None:
+        step = LegacyOCREngineExecutor(_MockOCREngine())
+        context = RunContext(
+            document_id="doc1",
+            code_version="test",
+            pipeline_name="test_pipe",
+            workspace_uri=str(tmp_path),
+        )
+        with pytest.raises(OCRAdapterError, match="IMAGE manquant"):
+            step.execute(inputs={}, params={}, context=context)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# A.2 — _substitute_prompt_variables et BaseLLMAdapter avec params
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestPromptSubstitution:
+    def test_rewrite_format_text(self) -> None:
+        out = _substitute_prompt_variables("Corrige : {text}", "ocr", None)
+        assert out == "Corrige : ocr"
+
+    def test_legacy_format_ocr_output(self) -> None:
+        out = _substitute_prompt_variables(
+            "Corrige : {ocr_output}", "ocr", None,
+        )
+        assert out == "Corrige : ocr"
+
+    def test_legacy_format_with_image_b64(self) -> None:
+        out = _substitute_prompt_variables(
+            "Img: {image_b64} OCR: {ocr_output}", "ocr", "b64data",
+        )
+        assert out == "Img: b64data OCR: ocr"
+
+    def test_legacy_format_image_none_becomes_empty(self) -> None:
+        out = _substitute_prompt_variables(
+            "Img: {image_b64}, OCR: {ocr_output}", "ocr", None,
+        )
+        assert out == "Img: , OCR: ocr"
+
+    def test_only_image_b64_no_ocr_output(self) -> None:
+        """Un template legacy peut n'avoir que ``{image_b64}`` (mode
+        zero-shot avec convention legacy)."""
+        out = _substitute_prompt_variables(
+            "Transcris l'image : {image_b64}", "", "b64data",
+        )
+        assert out == "Transcris l'image : b64data"
+
+
+class TestBaseLLMAdapterAcceptsParamsPromptTemplate:
+    def test_params_prompt_template_overrides_config(
+        self, tmp_path: Path,
+    ) -> None:
+        """Sprint A.2 — un caller qui construit une PipelineSpec peut
+        injecter un prompt_template via ``params``, qui prime sur
+        ``self.config["correction_prompt"]``."""
+        adapter = _MockLLMAdapter()
+        adapter.config["correction_prompt"] = "OLD CONFIG: {text}"
+
+        # Préparer un text artifact (le LLM lit depuis disque).
+        text_path = tmp_path / "ocr.txt"
+        text_path.write_text("ocr text here", encoding="utf-8")
+        text_artifact = Artifact(
+            id="doc1:ocr:raw_text",
+            document_id="doc1",
+            type=ArtifactType.RAW_TEXT,
+            uri=str(text_path),
+        )
+        context = RunContext(
+            document_id="doc1",
+            code_version="test",
+            pipeline_name="test_pipe",
+            workspace_uri=str(tmp_path),
+        )
+
+        adapter.execute(
+            inputs={ArtifactType.RAW_TEXT: text_artifact},
+            params={"prompt_template": "NEW PARAM: {ocr_output}"},
+            context=context,
+        )
+
+        # Le prompt utilisé doit venir de params, pas de config.
+        assert adapter.last_prompt == "NEW PARAM: ocr text here"
+
+    def test_params_legacy_template_with_image(
+        self, tmp_path: Path,
+    ) -> None:
+        """Le template legacy ``{ocr_output}`` + ``{image_b64}`` est
+        substitué correctement quand l'image est dans les inputs."""
+        adapter = _MockLLMAdapter()
+        text_path = tmp_path / "ocr.txt"
+        text_path.write_text("hello", encoding="utf-8")
+        image_path = tmp_path / "img.png"
+        image_path.write_bytes(b"\x89PNG fake")
+        text_artifact = Artifact(
+            id="doc1:ocr:raw_text",
+            document_id="doc1",
+            type=ArtifactType.RAW_TEXT,
+            uri=str(text_path),
+        )
+        image_artifact = Artifact(
+            id="doc1:initial:image",
+            document_id="doc1",
+            type=ArtifactType.IMAGE,
+            uri=str(image_path),
+        )
+        context = RunContext(
+            document_id="doc1",
+            code_version="test",
+            pipeline_name="test_pipe",
+            workspace_uri=str(tmp_path),
+        )
+
+        adapter.execute(
+            inputs={
+                ArtifactType.RAW_TEXT: text_artifact,
+                ArtifactType.IMAGE: image_artifact,
+            },
+            params={
+                "prompt_template": (
+                    "T:{ocr_output}|I:{image_b64}"
+                ),
+            },
+            context=context,
+        )
+
+        assert adapter.last_prompt is not None
+        assert adapter.last_prompt.startswith("T:hello|I:")
+        # L'image a été passée au LLM (mode multimodal).
+        assert adapter.last_image_b64 is not None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# A.3 — Intégration OCR legacy + LLM rewrite via PipelineExecutor
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestEndToEndOCRPlusLLM:
+    """Le scénario clé : un caller qui aujourd'hui construit un
+    ``OCRLLMPipeline(...)`` peut, dès Sprint A, le remplacer par
+    une ``PipelineSpec`` exécutée via ``PipelineExecutor`` avec un
+    OCR engine legacy wrappé."""
+
+    def _build_executor(
+        self,
+        ocr_engine: BaseOCREngine,
+        llm_adapter: BaseLLMAdapter,
+    ) -> PipelineExecutor:
+        ocr_step = LegacyOCREngineExecutor(ocr_engine)
+
+        def resolver(name: str) -> Any:
+            if name == ocr_engine.name:
+                return ocr_step
+            if name == "mock_llm:mock-1":
+                return llm_adapter
+            raise KeyError(f"adapter inconnu : {name}")
+
+        return PipelineExecutor(adapter_resolver=resolver)
+
+    def test_text_only_pipeline_runs_end_to_end(
+        self, tmp_path: Path,
+    ) -> None:
+        """Mode TEXT_ONLY — OCR legacy → LLM rewrite produit
+        ``CORRECTED_TEXT``."""
+        ocr = _MockOCREngine(fixed_text="texte ocr brut")
+        llm = _MockLLMAdapter()
+
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name=ocr.name,
+            llm_adapter_name="mock_llm:mock-1",
+        )
+
+        # Image factice
+        image_path = tmp_path / "scan.png"
+        image_path.write_bytes(b"\x89PNG fake")
+        document = DocumentRef(id="doc_e2e", image_uri=str(image_path))
+        context = RunContext(
+            document_id="doc_e2e",
+            code_version="test",
+            pipeline_name=spec.name,
+            workspace_uri=str(tmp_path),
+        )
+        initial_inputs = {
+            ArtifactType.IMAGE: Artifact(
+                id="doc_e2e:initial:image",
+                document_id="doc_e2e",
+                type=ArtifactType.IMAGE,
+                uri=str(image_path),
+            ),
+        }
+
+        executor = self._build_executor(ocr, llm)
+        result = executor.run(spec, document, initial_inputs, context)
+
+        assert result.succeeded, f"pipeline failed: {result}"
+        # Le résultat porte une liste plate d'artifacts ; on filtre par
+        # type pour récupérer le CORRECTED_TEXT produit en bout de chaîne.
+        corrected_artifacts = [
+            a for a in result.artifacts if a.type == ArtifactType.CORRECTED_TEXT
+        ]
+        assert len(corrected_artifacts) == 1
+        corrected = corrected_artifacts[0]
+        text = Path(corrected.uri).read_text(encoding="utf-8")
+        # Le mock LLM met le prompt en upper-case ; le texte OCR est
+        # quelque part dans cette upper-case version.
+        assert "TEXTE OCR BRUT" in text
+        # Le LLM a bien reçu le texte OCR (pas l'image en text-only).
+        assert "texte ocr brut" in (llm.last_prompt or "")
+        assert llm.last_image_b64 is None
+
+    def test_text_and_image_pipeline_passes_image_to_llm(
+        self, tmp_path: Path,
+    ) -> None:
+        """Mode TEXT_AND_IMAGE — le LLM reçoit l'image en plus du
+        RAW_TEXT issu de l'OCR."""
+        ocr = _MockOCREngine(fixed_text="ocr txt")
+        llm = _MockLLMAdapter()
+
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_and_image",
+            ocr_adapter_name=ocr.name,
+            llm_adapter_name="mock_llm:mock-1",
+        )
+
+        image_path = tmp_path / "scan.png"
+        image_path.write_bytes(b"\x89PNG fake bytes")
+        document = DocumentRef(id="doc_e2e", image_uri=str(image_path))
+        context = RunContext(
+            document_id="doc_e2e",
+            code_version="test",
+            pipeline_name=spec.name,
+            workspace_uri=str(tmp_path),
+        )
+        initial_inputs = {
+            ArtifactType.IMAGE: Artifact(
+                id="doc_e2e:initial:image",
+                document_id="doc_e2e",
+                type=ArtifactType.IMAGE,
+                uri=str(image_path),
+            ),
+        }
+
+        executor = self._build_executor(ocr, llm)
+        result = executor.run(spec, document, initial_inputs, context)
+
+        assert result.succeeded
+        # En mode multimodal, le LLM a reçu l'image (encodée base64).
+        assert llm.last_image_b64 is not None
+        assert len(llm.last_image_b64) > 0