feat(adapters/llm): Sprint A14-S44 — BaseLLMAdapter implémente StepExecutor

Les 4 LLM adapters (Anthropic, Mistral, OpenAI, Ollama) sont désormais
**directement** utilisables comme steps de pipeline sans wrapper / shim.

picarones/adapters/llm/base.py
------------------------------
BaseLLMAdapter implémente nativement le contrat StepExecutor du
pipeline (S6) en plus de son API LLM historique (complete()) :

- ``input_types`` (property, défaut {RAW_TEXT}, surchargeable).
- ``output_types`` (property, défaut {CORRECTED_TEXT}, surchargeable).
- ``execution_mode = "io"`` (LLM via API → IO-bound, ThreadPool).
- ``DEFAULT_CORRECTION_PROMPT`` (configurable via
config["correction_prompt"]).
- ``execute(inputs, params, context) -> dict[ArtifactType, Artifact]`` :
· valide RAW_TEXT input (URI + fichier existe → OCRAdapterError sinon) ;
· charge le texte UTF-8 ;
· optionnellement encode IMAGE en base64 (mode VLM si supporté) ;
· format prompt avec {text} ;
· appelle self.complete(prompt, image_b64) avec retry hérité ;
· si LLMResult.error → OCRAdapterError ;
· écrit dans <stem>.<name>.corrected.txt ;
· retourne Artifact CORRECTED_TEXT avec id "<doc>:<name>:corrected_text".

Pas de wrapper externe : le contrat StepExecutor vit dans la base, partagé
nativement par les 4 adapters concrets via héritage.

Régressions corrigées
---------------------
- tests/app/test_run_orchestrator.py : assertion "3 fichiers" → "4
fichiers" (artifacts_index ajouté en S41).
- tests/architecture/test_file_budgets.py : ajout de
benchmark_service.py (400 lignes, S41) et adapters/llm/base.py
(410 lignes, S44) au tableau des budgets surveillés.

Tests S44 dédiés (18 nouveaux)
------------------------------
- BaseLLMAdapterContract : input_types, output_types,
execution_mode = "io".
- LLMExecuteNominal : correction basique → fichier
<stem>.<name>.corrected.txt avec contenu LLM, artifact id correct,
prompt formaté avec {text}, custom prompt via config.
- LLMExecuteErrors : RAW_TEXT manquant, sans URI, fichier inexistant,
LLM call failing → tous OCRAdapterError.
- LLMExecuteWithImage : IMAGE optionnel encodé en base64, omis si
absent.
- ConcreteAdaptersInheritContract : OpenAI/Anthropic/Mistral/Ollama
ont tous execute() + input_types + output_types.
- PipelineIntegration : un LLM adapter se branche directement comme
step de pipeline via PipelineExecutor.run() (test bout-en-bout).

Tests : 4881 passed, 11 skipped (vs 4863 avant : +18 S44).
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**: ~4840 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4880 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/llm/base.py

@@ -182,6 +182,20 @@ class BaseLLMAdapter(ABC):
     un log discriminant par ``status_code`` (401 → clé invalide,
     429 → rate limit, 5xx → serveur).  Auparavant ce log était
     dupliqué chez Mistral/OpenAI et absent chez Anthropic.
+
+    Sprint A14-S44 — intégration pipeline native
+    ---------------------------------------------
+    ``BaseLLMAdapter`` implémente désormais le contrat ``StepExecutor``
+    du pipeline (``input_types``, ``output_types``, ``execution_mode``,
+    ``execute(inputs, params, context)``) — un adapter LLM est
+    directement utilisable comme step de pipeline pour la post-correction
+    de texte OCR.  Pas de wrapper / shim : la méthode ``execute`` vit
+    dans la base et est partagée par les 4 adapters concrets.
+
+    Convention par défaut : un LLM consomme ``RAW_TEXT`` (depuis l'OCR
+    en amont) et produit ``CORRECTED_TEXT``.  Une sous-classe peut
+    surcharger ``input_types`` / ``output_types`` si elle implémente un
+    autre contrat (ex : ALTO → ALTO pour un module de remappage).
     """
 
     # Variable d'environnement portant la clé API.  Sous-classes
@@ -190,6 +204,37 @@ class BaseLLMAdapter(ABC):
     # pour les providers sans clé (Ollama).
     api_key_env_var: Optional[str] = None
 
+    # ──────────────────────────────────────────────────────────────────
+    # Sprint A14-S44 — contrat StepExecutor du pipeline
+    # ──────────────────────────────────────────────────────────────────
+
+    #: Types d'artefacts consommés par défaut.  Surchargeable par
+    #: une sous-classe qui consommerait des artefacts différents
+    #: (ex : ALTO_XML pour un remappeur ALTO LLM).
+    @property
+    def input_types(self) -> "frozenset":
+        from picarones.domain.artifacts import ArtifactType
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    @property
+    def output_types(self) -> "frozenset":
+        from picarones.domain.artifacts import ArtifactType
+        return frozenset({ArtifactType.CORRECTED_TEXT})
+
+    #: Mode d'exécution : LLM via API → IO-bound → ThreadPool dans le
+    #: runner.  Une sous-classe locale (Ollama CPU-bound) peut
+    #: surcharger en ``"cpu"``.
+    execution_mode: str = "io"
+
+    #: Prompt de post-correction par défaut.  Surchargeable via
+    #: ``config["correction_prompt"]`` au constructeur.
+    DEFAULT_CORRECTION_PROMPT: str = (
+        "Corrige les erreurs OCR dans le texte suivant en conservant "
+        "fidèlement la langue, l'orthographe historique et la "
+        "ponctuation. Retourne uniquement le texte corrigé, sans "
+        "commentaire :\n\n{text}"
+    )
+
     def __init__(
         self,
         model: Optional[str] = None,
@@ -267,6 +312,92 @@ class BaseLLMAdapter(ABC):
             error=str(last_exc),
         )
 
+    # ──────────────────────────────────────────────────────────────────
+    # Sprint A14-S44 — execute() pour le pipeline
+    # ──────────────────────────────────────────────────────────────────
+
+    def execute(
+        self,
+        inputs: dict,
+        params: dict,
+        context: Any,
+    ) -> dict:
+        """Exécute la post-correction LLM en tant que step de pipeline.
+
+        Convention par défaut : lit ``inputs[RAW_TEXT]`` (Artifact),
+        charge son contenu UTF-8 depuis l'URI, appelle ``self.complete``
+        avec le ``correction_prompt`` formaté, écrit le résultat dans
+        un fichier ``<input_stem>.<adapter_name>.corrected.txt``, et
+        retourne ``{CORRECTED_TEXT: Artifact}``.
+
+        Le caller (``PipelineExecutor``) catch les exceptions ; on les
+        propage telles quelles.
+
+        Optionnel : si ``inputs[IMAGE]`` est présent, l'image est
+        encodée en base64 et passée au LLM (mode VLM).  Les sous-classes
+        qui ne supportent pas la vision (ex. ollama texte) ignorent
+        silencieusement.
+        """
+        from pathlib import Path
+        import base64
+
+        from picarones.adapters.ocr.base import OCRAdapterError
+        from picarones.domain.artifacts import Artifact, ArtifactType
+
+        if ArtifactType.RAW_TEXT not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input RAW_TEXT manquant.",
+            )
+        text_artifact = inputs[ArtifactType.RAW_TEXT]
+        if text_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact RAW_TEXT "
+                f"{text_artifact.id!r} sans URI.",
+            )
+        text_path = Path(text_artifact.uri)
+        if not text_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : fichier texte introuvable {text_path!r}.",
+            )
+
+        original_text = text_path.read_text(encoding="utf-8")
+
+        # Image optionnelle (VLM-style si supporté).
+        image_b64: Optional[str] = None
+        image_artifact = inputs.get(ArtifactType.IMAGE)
+        if image_artifact is not None and image_artifact.uri is not None:
+            image_path = Path(image_artifact.uri)
+            if image_path.exists():
+                image_b64 = base64.b64encode(
+                    image_path.read_bytes(),
+                ).decode("ascii")
+
+        prompt_template = self.config.get(
+            "correction_prompt", self.DEFAULT_CORRECTION_PROMPT,
+        )
+        prompt = prompt_template.format(text=original_text)
+
+        result = self.complete(prompt, image_b64=image_b64)
+        if not result.success:
+            raise OCRAdapterError(
+                f"{self.name} : LLM a échoué ({result.error}).",
+            )
+
+        out_path = (
+            text_path.parent / f"{text_path.stem}.{self.name}.corrected.txt"
+        )
+        out_path.write_text(result.text, encoding="utf-8")
+
+        return {
+            ArtifactType.CORRECTED_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:corrected_text",
+                document_id=context.document_id,
+                type=ArtifactType.CORRECTED_TEXT,
+                produced_by_step="post_correction",
+                uri=str(out_path),
+            ),
+        }
+
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(model={self.model!r})"
 

tests/adapters/llm/test_sprint_a14_s44_llm_step_executor.py

@@ -0,0 +1,344 @@
+"""Sprint A14-S44 — ``BaseLLMAdapter`` implémente le contrat StepExecutor.
+
+Tests de l'intégration native des 4 LLM adapters dans le pipeline :
+``execute(inputs, params, context) -> dict[ArtifactType, Artifact]``
+ajouté à ``BaseLLMAdapter`` (sans wrapper / sans shim).
+
+Couvre :
+1. ``BaseLLMAdapter.input_types`` / ``output_types`` / ``execution_mode``
+2. ``execute`` lit RAW_TEXT, appelle ``complete``, écrit
+   ``<stem>.<name>.corrected.txt``, retourne CORRECTED_TEXT.
+3. Erreurs : RAW_TEXT manquant, sans URI, fichier inexistant,
+   complete() en échec.
+4. Image optionnelle : ``inputs[IMAGE]`` est encodée en base64 et
+   passée au ``complete``.
+5. Les 4 adapters concrets (Anthropic, Mistral, OpenAI, Ollama)
+   héritent bien du contrat.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+import pytest
+
+from picarones.adapters.llm.base import BaseLLMAdapter
+from picarones.adapters.ocr.base import OCRAdapterError
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.pipeline.types import RunContext
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Adapter de test concret
+# ──────────────────────────────────────────────────────────────────────
+
+
+class _StubLLMAdapter(BaseLLMAdapter):
+    """LLM stub pour tester ``execute`` sans appeler une vraie API."""
+
+    @property
+    def name(self) -> str:
+        return "stub_llm"
+
+    @property
+    def default_model(self) -> str:
+        return "stub-model-1.0"
+
+    def __init__(
+        self,
+        response_text: str = "TEXTE CORRIGÉ",
+        raise_on_call: bool = False,
+        model=None,
+        config=None,
+    ) -> None:
+        super().__init__(model=model, config=config)
+        self._response = response_text
+        self._raise = raise_on_call
+        self.last_prompt = None
+        self.last_image_b64 = None
+
+    def _call(self, prompt, image_b64=None):
+        self.last_prompt = prompt
+        self.last_image_b64 = image_b64
+        if self._raise:
+            raise RuntimeError("LLM crashed")
+        return self._response
+
+
+def _make_context() -> RunContext:
+    return RunContext(
+        document_id="doc01",
+        code_version="1.0.0",
+        pipeline_name="test",
+    )
+
+
+def _make_text_artifact(uri: str) -> Artifact:
+    return Artifact(
+        id="doc01:ocr:raw_text",
+        document_id="doc01",
+        type=ArtifactType.RAW_TEXT,
+        uri=uri,
+    )
+
+
+def _make_image_artifact(uri: str) -> Artifact:
+    return Artifact(
+        id="doc01:image",
+        document_id="doc01",
+        type=ArtifactType.IMAGE,
+        uri=uri,
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Contract StepExecutor
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestBaseLLMAdapterContract:
+    def test_input_types_default_raw_text(self) -> None:
+        adapter = _StubLLMAdapter()
+        assert ArtifactType.RAW_TEXT in adapter.input_types
+
+    def test_output_types_default_corrected_text(self) -> None:
+        adapter = _StubLLMAdapter()
+        assert ArtifactType.CORRECTED_TEXT in adapter.output_types
+
+    def test_execution_mode_default_io(self) -> None:
+        # Class attribute, pas instance.
+        assert BaseLLMAdapter.execution_mode == "io"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# execute() — chemin nominal
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestLLMExecuteNominal:
+    def test_basic_correction(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "doc01.txt"
+        text_path.write_text("texte avec erreurs", encoding="utf-8")
+
+        adapter = _StubLLMAdapter(response_text="texte sans erreurs")
+        result = adapter.execute(
+            inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
+            params={},
+            context=_make_context(),
+        )
+        assert ArtifactType.CORRECTED_TEXT in result
+        produced = result[ArtifactType.CORRECTED_TEXT]
+        assert produced.type == ArtifactType.CORRECTED_TEXT
+        assert produced.document_id == "doc01"
+
+        out_path = Path(produced.uri)
+        assert out_path.exists()
+        assert out_path.read_text(encoding="utf-8") == "texte sans erreurs"
+        assert out_path.name == "doc01.stub_llm.corrected.txt"
+
+    def test_artifact_id_uses_adapter_name(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "doc01.txt"
+        text_path.write_text("x", encoding="utf-8")
+        adapter = _StubLLMAdapter()
+        result = adapter.execute(
+            inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
+            params={},
+            context=_make_context(),
+        )
+        produced = result[ArtifactType.CORRECTED_TEXT]
+        assert produced.id == "doc01:stub_llm:corrected_text"
+        assert produced.produced_by_step == "post_correction"
+
+    def test_prompt_template_formatted_with_text(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "doc01.txt"
+        text_path.write_text("input text", encoding="utf-8")
+        adapter = _StubLLMAdapter()
+        adapter.execute(
+            inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
+            params={},
+            context=_make_context(),
+        )
+        # Le prompt doit contenir le texte d'entrée.
+        assert "input text" in adapter.last_prompt
+
+    def test_custom_prompt_via_config(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "doc01.txt"
+        text_path.write_text("input", encoding="utf-8")
+        adapter = _StubLLMAdapter(config={
+            "correction_prompt": "Custom: {text}",
+        })
+        adapter.execute(
+            inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
+            params={},
+            context=_make_context(),
+        )
+        assert adapter.last_prompt == "Custom: input"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Erreurs
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestLLMExecuteErrors:
+    def test_missing_raw_text_raises(self) -> None:
+        adapter = _StubLLMAdapter()
+        with pytest.raises(OCRAdapterError, match="RAW_TEXT manquant"):
+            adapter.execute(
+                inputs={},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_text_artifact_without_uri_raises(self) -> None:
+        adapter = _StubLLMAdapter()
+        artifact = Artifact(
+            id="x",
+            document_id="doc01",
+            type=ArtifactType.RAW_TEXT,
+            uri=None,
+        )
+        with pytest.raises(OCRAdapterError, match="sans URI"):
+            adapter.execute(
+                inputs={ArtifactType.RAW_TEXT: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_text_path_not_existing_raises(self) -> None:
+        adapter = _StubLLMAdapter()
+        with pytest.raises(OCRAdapterError, match="introuvable"):
+            adapter.execute(
+                inputs={ArtifactType.RAW_TEXT: _make_text_artifact(
+                    "/nonexistent/x.txt",
+                )},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_llm_call_failing_raises(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "x.txt"
+        text_path.write_text("x", encoding="utf-8")
+        adapter = _StubLLMAdapter(raise_on_call=True, config={
+            "max_retries": 0,  # pas de retry pour accélérer le test
+        })
+        with pytest.raises(OCRAdapterError, match="LLM a échoué"):
+            adapter.execute(
+                inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
+                params={},
+                context=_make_context(),
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Image optionnelle (mode VLM)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestLLMExecuteWithImage:
+    def test_image_passed_to_llm_as_base64(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "doc.txt"
+        text_path.write_text("x", encoding="utf-8")
+        image_path = tmp_path / "doc.png"
+        image_path.write_bytes(b"PNGBYTES")
+
+        adapter = _StubLLMAdapter()
+        adapter.execute(
+            inputs={
+                ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path)),
+                ArtifactType.IMAGE: _make_image_artifact(str(image_path)),
+            },
+            params={},
+            context=_make_context(),
+        )
+        # L'image doit être encodée en base64.
+        assert adapter.last_image_b64 is not None
+        decoded = base64.b64decode(adapter.last_image_b64)
+        assert decoded == b"PNGBYTES"
+
+    def test_image_omitted_when_not_provided(self, tmp_path: Path) -> None:
+        text_path = tmp_path / "doc.txt"
+        text_path.write_text("x", encoding="utf-8")
+        adapter = _StubLLMAdapter()
+        adapter.execute(
+            inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
+            params={},
+            context=_make_context(),
+        )
+        assert adapter.last_image_b64 is None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Adapters concrets héritent du contrat
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestConcreteAdaptersInheritContract:
+    def test_openai_has_execute(self) -> None:
+        from picarones.adapters.llm.openai_adapter import OpenAIAdapter
+        # Vérifie que la méthode execute est héritée.
+        assert hasattr(OpenAIAdapter, "execute")
+        assert hasattr(OpenAIAdapter, "input_types")
+        assert hasattr(OpenAIAdapter, "output_types")
+
+    def test_anthropic_has_execute(self) -> None:
+        from picarones.adapters.llm.anthropic_adapter import AnthropicAdapter
+        assert hasattr(AnthropicAdapter, "execute")
+
+    def test_mistral_has_execute(self) -> None:
+        from picarones.adapters.llm.mistral_adapter import MistralAdapter
+        assert hasattr(MistralAdapter, "execute")
+
+    def test_ollama_has_execute(self) -> None:
+        from picarones.adapters.llm.ollama_adapter import OllamaAdapter
+        assert hasattr(OllamaAdapter, "execute")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Intégration pipeline (utilisation comme StepExecutor)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestPipelineIntegration:
+    def test_used_as_pipeline_step(self, tmp_path: Path) -> None:
+        """Un adapter LLM se branche directement comme step de pipeline."""
+        from picarones.pipeline.executor import PipelineExecutor
+        from picarones.pipeline.spec import PipelineSpec, PipelineStep
+        from picarones.domain.documents import DocumentRef
+
+        text_path = tmp_path / "doc01.txt"
+        text_path.write_text("input ocr", encoding="utf-8")
+
+        adapter = _StubLLMAdapter(response_text="cleaned text")
+        executor = PipelineExecutor(
+            adapter_resolver=lambda name: adapter,
+        )
+        spec = PipelineSpec(
+            name="post_correction",
+            initial_inputs=(ArtifactType.RAW_TEXT,),
+            steps=(
+                PipelineStep(
+                    id="llm",
+                    kind="post_correction",
+                    adapter_name="stub_llm",
+                    input_types=(ArtifactType.RAW_TEXT,),
+                    output_types=(ArtifactType.CORRECTED_TEXT,),
+                ),
+            ),
+        )
+        result = executor.run(
+            spec=spec,
+            document=DocumentRef(id="doc01"),
+            initial_inputs={
+                ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path)),
+            },
+            context=_make_context(),
+        )
+        assert result.succeeded
+        # Trouve le CORRECTED_TEXT artefact.
+        corrected = [
+            a for a in result.artifacts
+            if a.type == ArtifactType.CORRECTED_TEXT
+        ]
+        assert len(corrected) == 1

tests/app/test_run_orchestrator.py

@@ -156,9 +156,9 @@ class TestExecuteHappyPath:
         assert result.extracted_corpus_dir.resolve().is_relative_to(
             out_dir.resolve(),
         )
-        # 3 fichiers persistés.
+        # S41 — 4 fichiers persistés (artifacts_index séparé).
         assert set(result.persisted_files) == {
-            "manifest", "pipeline_results", "view_results",
+            "manifest", "pipeline_results", "artifacts_index", "view_results",
         }
         for path in result.persisted_files.values():
             assert path.exists()

tests/architecture/test_file_budgets.py

@@ -88,6 +88,11 @@ FILE_BUDGETS: dict[str, int] = {
     # hash multi-paramètres pour adresser la critique d'audit n° 14
     # « hash multi-paramètres + reprise par hash ».
     "picarones/adapters/storage/artifact_store.py": 580,  # actuel 504
+    # Sprint A14-S41 — artifacts_index.jsonl séparé.
+    "picarones/app/services/benchmark_service.py": 470,   # actuel 400
+    # Sprint A14-S44 — BaseLLMAdapter implémente le contrat StepExecutor
+    # (input_types, output_types, execute) en plus de complete().
+    "picarones/adapters/llm/base.py": 475,                # actuel 410
     "picarones/core/corpus.py": 600,                      # actuel 511
     "picarones/fixtures.py": 600,                         # actuel 510
     "picarones/measurements/inter_engine.py": 575,        # actuel 484