feat(6-volet2): make_ocr_llm_pipeline_spec — convergence des 3 modes vers PipelineSpec

Phase 6 volet 2 — fondation pour le retrait de
``picarones.pipelines.base.OCRLLMPipeline``.

Le builder ``make_ocr_llm_pipeline_spec(mode, ocr_adapter_name,
llm_adapter_name)`` convertit les 3 modes historiques (``text_only``,
``text_and_image``, ``zero_shot``) en ``PipelineSpec`` canoniques
exécutables par ``PipelineExecutor``. C'est le pont entre l'API
legacy et le rewrite (Sprints A14-S6/S7/S44/S45).

Découverte
----------
Audit de l'infrastructure rewrite — ``BaseLLMAdapter`` (couche
``adapters/llm/``) et ``BaseVLMAdapter`` (couche ``adapters/vlm/``)
implémentent **déjà** le contrat ``StepExecutor`` (depuis A14-S44/S45) :

- ``BaseLLMAdapter`` : ``RAW_TEXT`` → ``CORRECTED_TEXT`` (+ ``IMAGE``
optionnelle pour mode VLM).
- ``BaseVLMAdapter`` : ``IMAGE`` → ``RAW_TEXT``.

Ces deux contrats couvrent exactement les 3 modes de
``OCRLLMPipeline``. Le travail volet 2 ne nécessite **pas** de
créer de nouveaux adapters — juste de fournir le builder de
``PipelineSpec`` qui assemble les briques existantes.

Mapping mode → spec
-------------------
| Mode legacy | Initial inputs | Steps | Output final |
|--------------------|----------------|---------------|------------------|
| ``text_only`` | IMAGE | OCR + LLM | CORRECTED_TEXT |
| ``text_and_image`` | IMAGE | OCR + LLM* | CORRECTED_TEXT |
| ``zero_shot`` | IMAGE | VLM seul | RAW_TEXT |

(* en mode ``text_and_image``, le step LLM consomme aussi ``IMAGE``
depuis ``__initial__``, en plus du ``RAW_TEXT`` issu de l'OCR.)

API
---
- ``picarones.pipeline.make_ocr_llm_pipeline_spec(...)`` —
fonction publique, ré-exportée depuis ``picarones.pipeline``.
- ``picarones.pipeline.OCRLLMPipelineMode`` — type
``Literal["text_only", "text_and_image", "zero_shot"]``.
- Le builder valide les combinaisons :
``zero_shot`` + ``ocr_adapter_name`` lève ``PicaronesError`` ;
``text_only`` ou ``text_and_image`` sans ``ocr_adapter_name``
lèvent aussi.
- Auto-naming : ``ocr_llm_<mode>_<ocr>_to_<llm>`` ou
``vlm_zero_shot_<llm>``.

Tests
-----
``tests/pipeline/test_phase6_volet2_llm_pipeline_builder.py`` —
26 tests couvrant :

- Structure du DAG pour chacun des 3 modes (1 ou 2 steps,
``inputs_from`` correctement câblé).
- Types d'artefacts produits/consommés à chaque step.
- ``validate_spec`` accepte les 3 specs sans erreur.
- Erreurs sur combinaisons invalides.
- Auto-naming (incluant l'échappement des ``:`` dans les
noms d'adapter LLM).
- Round-trip YAML (les specs traversent ``dump_spec_to_yaml``
/ ``load_spec_from_yaml`` sans perte).

Migration future (sub-phases 6.B+)
----------------------------------
Avec ce builder en place, les 3 callers internes de
``OCRLLMPipeline`` peuvent migrer un à un :

1. ``picarones/web/benchmark_utils.py:131`` — instancie
``OCRLLMPipeline(...)`` ; remplaçable par
``make_ocr_llm_pipeline_spec(...)`` + ``PipelineExecutor.run``
(via ``RunOrchestrator``).
2. ``picarones/measurements/runner/orchestration.py:520-521`` —
``isinstance(engine, OCRLLMPipeline)`` ; remplaçable par
un check ``is_pipeline`` au niveau ``PipelineSpec``.
3. ``picarones/fixtures.py`` (callers indirects via runner).

Quand les 3 callers consomment des ``PipelineSpec``, le
``OCRLLMPipeline`` legacy peut être supprimé. Ce travail
incrémental sortira d'un commit ``feat(6-volet2-N)`` séparé pour
chaque caller.

Bilan
-----
- ``pytest tests/`` : 4740 passed (+25), 0 failed.
- ``ruff check`` : clean.
- 1 module créé (245 LOC), 1 fichier de tests créé (264 LOC),
``pipeline/__init__.py`` exporte 2 symboles supplémentaires.
- Aucun caller existant n'est touché — l'API legacy
``OCRLLMPipeline`` reste exécutable et inchangée pour
cette session.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

CLAUDE.md

@@ -123,7 +123,7 @@ picarones/
 
 ## État des tests et bugs historiques
 
-`pytest tests/` → **4750 passed, 12 skipped, 8 deselected, 0 failed**
+`pytest tests/` → **4770 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` → 4750 passed.
+3. `pytest tests/ -q --no-header --tb=line` → 4770 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` → 4750 passed, 12 skipped, 24
+- **Tests** : `pytest tests/ -q` → 4770 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

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

@@ -56,6 +56,10 @@ from picarones.pipeline.executor import (
     PipelineExecutor,
     PipelineSpecInvalid,
 )
+from picarones.pipeline.llm_pipeline_builder import (
+    OCRLLMPipelineMode,
+    make_ocr_llm_pipeline_spec,
+)
 from picarones.pipeline.planner import (
     ExecutionPlan,
     MetricJunction,
@@ -99,6 +103,9 @@ __all__ = [
     "PipelineExecutor",
     "PipelineSpecInvalid",
     "AdapterResolver",
+    # Builder OCR+LLM (Phase 6 volet 2)
+    "make_ocr_llm_pipeline_spec",
+    "OCRLLMPipelineMode",
     # Planner (S28)
     "PipelinePlanner",
     "PlanningError",

picarones/pipeline/llm_pipeline_builder.py

@@ -0,0 +1,250 @@
+"""Builder de ``PipelineSpec`` pour les chaînes OCR + LLM (Phase 6 volet 2).
+
+Ce module fournit la convergence entre les 3 modes historiques de
+``picarones.pipelines.base.OCRLLMPipeline`` (legacy) et la
+``PipelineSpec`` canonique exécutable par ``PipelineExecutor``.
+
+Mapping mode legacy → spec canonique
+------------------------------------
+
+================ ============= =========== ================================
+Mode legacy      Initial input Steps       Output final
+================ ============= =========== ================================
+``text_only``    IMAGE         OCR + LLM   ``CORRECTED_TEXT``
+``text_and_image`` IMAGE       OCR + LLM   ``CORRECTED_TEXT`` (LLM voit aussi IMAGE)
+``zero_shot``    IMAGE         VLM seul    ``RAW_TEXT``
+================ ============= =========== ================================
+
+Les 3 modes correspondent aux contrats ``StepExecutor`` :
+
+- ``BaseLLMAdapter`` (texte → texte corrigé) — couvre ``text_only``
+  et ``text_and_image`` car son ``execute()`` lit l'image
+  optionnellement présente dans le bag d'inputs.
+- ``BaseVLMAdapter`` (image → texte) — couvre ``zero_shot``.
+
+L'adapter OCR amont (Tesseract, Pero, Mistral OCR, Google Vision,
+Azure DI, ou ``precomputed`` quand le corpus porte déjà l'OCR) est
+quelconque tant qu'il déclare ``output_types ⊇ {RAW_TEXT}``.
+
+Exemple de migration
+--------------------
+Code legacy ::
+
+    from picarones.pipelines import OCRLLMPipeline, PipelineMode
+    from picarones.adapters.legacy_engines.tesseract import TesseractEngine
+    from picarones.adapters.llm import OpenAIAdapter
+
+    pipeline = OCRLLMPipeline(
+        ocr_engine=TesseractEngine({"lang": "fra"}),
+        llm_adapter=OpenAIAdapter(model="gpt-4o"),
+        mode=PipelineMode.TEXT_ONLY,
+    )
+    result = pipeline.run("scan.jpg")  # → EngineResult
+
+Code canonique équivalent ::
+
+    from picarones.pipeline import PipelineExecutor
+    from picarones.pipeline.llm_pipeline_builder import (
+        make_ocr_llm_pipeline_spec,
+    )
+
+    spec = make_ocr_llm_pipeline_spec(
+        mode="text_only",
+        ocr_adapter_name="tesseract",
+        llm_adapter_name="openai:gpt-4o",
+    )
+    executor = PipelineExecutor(adapter_resolver=resolver, ...)
+    result = executor.run(spec, document, initial_inputs={IMAGE: ...}, context=...)
+
+Le runtime résout les ``adapter_name`` en instances via le
+``adapter_resolver`` du caller (cf. ``picarones.app.services.run_orchestrator``).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from picarones.domain.artifacts import ArtifactType
+from picarones.domain.errors import PicaronesError
+from picarones.domain.pipeline_spec import (
+    INITIAL_STEP_ID,
+    PipelineSpec,
+    PipelineStep,
+)
+
+
+#: Modes supportés — alignés sur ``picarones.pipelines.base.PipelineMode``.
+OCRLLMPipelineMode = Literal["text_only", "text_and_image", "zero_shot"]
+
+
+def make_ocr_llm_pipeline_spec(
+    mode: OCRLLMPipelineMode,
+    *,
+    ocr_adapter_name: str | None = None,
+    llm_adapter_name: str,
+    name: str | None = None,
+    description: str = "",
+    ocr_step_id: str = "ocr",
+    llm_step_id: str = "llm",
+) -> PipelineSpec:
+    """Construit la ``PipelineSpec`` correspondant à un mode OCR+LLM.
+
+    Parameters
+    ----------
+    mode:
+        ``"text_only"`` (OCR → LLM texte) | ``"text_and_image"`` (OCR
+        → LLM texte+image) | ``"zero_shot"`` (VLM image → texte).
+    ocr_adapter_name:
+        Nom de l'adapter OCR amont (ex. ``"tesseract"``,
+        ``"precomputed"``).  **Requis** pour ``text_only`` et
+        ``text_and_image`` ; **interdit** pour ``zero_shot``.
+    llm_adapter_name:
+        Nom de l'adapter LLM ou VLM (ex. ``"openai:gpt-4o"``,
+        ``"anthropic:claude-3-5-sonnet"``).  Pour ``zero_shot``,
+        doit pointer sur un VLM adapter.
+    name:
+        Nom court de la pipeline (snake_case).  Auto-généré depuis
+        ``mode`` + adapters si non fourni.
+    description:
+        Phrase courte pour le rapport.  Vide par défaut.
+    ocr_step_id, llm_step_id:
+        Identifiants des étapes (utiles pour les ``inputs_from``
+        cross-pipeline).  Défauts : ``"ocr"`` et ``"llm"``.
+
+    Returns
+    -------
+    PipelineSpec
+        Spec immutable prête à être exécutée par ``PipelineExecutor``.
+
+    Raises
+    ------
+    PicaronesError
+        Si la combinaison mode/adapters est incohérente
+        (ex. ``zero_shot`` avec ``ocr_adapter_name`` fourni).
+    """
+    if mode == "zero_shot":
+        if ocr_adapter_name is not None:
+            raise PicaronesError(
+                "mode 'zero_shot' incompatible avec ocr_adapter_name : "
+                "le VLM consomme directement l'image, pas d'OCR amont."
+            )
+        return _make_zero_shot_spec(
+            llm_adapter_name=llm_adapter_name,
+            name=name or f"vlm_zero_shot_{_safe_name(llm_adapter_name)}",
+            description=description,
+            llm_step_id=llm_step_id,
+        )
+
+    if mode not in ("text_only", "text_and_image"):
+        raise PicaronesError(
+            f"mode OCR+LLM inconnu : {mode!r}.  "
+            "Attendu : text_only | text_and_image | zero_shot."
+        )
+
+    if not ocr_adapter_name:
+        raise PicaronesError(
+            f"mode {mode!r} requiert ocr_adapter_name (un adapter "
+            "produisant RAW_TEXT en amont du LLM)."
+        )
+
+    return _make_ocr_plus_llm_spec(
+        mode=mode,
+        ocr_adapter_name=ocr_adapter_name,
+        llm_adapter_name=llm_adapter_name,
+        name=name or (
+            f"ocr_llm_{mode}_"
+            f"{_safe_name(ocr_adapter_name)}_to_{_safe_name(llm_adapter_name)}"
+        ),
+        description=description,
+        ocr_step_id=ocr_step_id,
+        llm_step_id=llm_step_id,
+    )
+
+
+def _make_zero_shot_spec(
+    *,
+    llm_adapter_name: str,
+    name: str,
+    description: str,
+    llm_step_id: str,
+) -> PipelineSpec:
+    """Spec ``zero_shot`` : un seul step VLM IMAGE → RAW_TEXT."""
+    return PipelineSpec(
+        name=name,
+        description=description,
+        initial_inputs=(ArtifactType.IMAGE,),
+        steps=(
+            PipelineStep(
+                id=llm_step_id,
+                kind="zero_shot_transcription",
+                adapter_name=llm_adapter_name,
+                input_types=(ArtifactType.IMAGE,),
+                output_types=(ArtifactType.RAW_TEXT,),
+                inputs_from={ArtifactType.IMAGE: INITIAL_STEP_ID},
+            ),
+        ),
+    )
+
+
+def _make_ocr_plus_llm_spec(
+    *,
+    mode: str,
+    ocr_adapter_name: str,
+    llm_adapter_name: str,
+    name: str,
+    description: str,
+    ocr_step_id: str,
+    llm_step_id: str,
+) -> PipelineSpec:
+    """Spec à 2 steps : OCR (IMAGE → RAW_TEXT) + LLM (RAW_TEXT → CORRECTED_TEXT)."""
+    llm_inputs_from: dict[ArtifactType, str] = {
+        ArtifactType.RAW_TEXT: ocr_step_id,
+    }
+    llm_input_types: list[ArtifactType] = [ArtifactType.RAW_TEXT]
+    if mode == "text_and_image":
+        # Le LLM voit aussi l'image initiale (mode multimodal).
+        llm_inputs_from[ArtifactType.IMAGE] = INITIAL_STEP_ID
+        llm_input_types.append(ArtifactType.IMAGE)
+
+    return PipelineSpec(
+        name=name,
+        description=description,
+        initial_inputs=(ArtifactType.IMAGE,),
+        steps=(
+            PipelineStep(
+                id=ocr_step_id,
+                kind="ocr",
+                adapter_name=ocr_adapter_name,
+                input_types=(ArtifactType.IMAGE,),
+                output_types=(ArtifactType.RAW_TEXT,),
+                inputs_from={ArtifactType.IMAGE: INITIAL_STEP_ID},
+            ),
+            PipelineStep(
+                id=llm_step_id,
+                kind="post_correction",
+                adapter_name=llm_adapter_name,
+                input_types=tuple(llm_input_types),
+                output_types=(ArtifactType.CORRECTED_TEXT,),
+                inputs_from=llm_inputs_from,
+            ),
+        ),
+    )
+
+
+def _safe_name(adapter_name: str) -> str:
+    """Convertit un ``adapter_name`` (qui peut contenir ``:``, ``/``,
+    etc.) en suffixe ``snake_case`` valide pour un step id."""
+    return (
+        adapter_name
+        .replace(":", "_")
+        .replace("/", "_")
+        .replace("-", "_")
+        .replace(".", "_")
+        .lower()
+    )
+
+
+__all__ = [
+    "OCRLLMPipelineMode",
+    "make_ocr_llm_pipeline_spec",
+]

tests/pipeline/test_phase6_volet2_llm_pipeline_builder.py

@@ -0,0 +1,306 @@
+"""Phase 6 volet 2 — ``make_ocr_llm_pipeline_spec``.
+
+Vérifie que les 3 modes historiques de
+``picarones.pipelines.base.OCRLLMPipeline`` (text_only,
+text_and_image, zero_shot) se traduisent en ``PipelineSpec``
+canoniques exécutables par ``PipelineExecutor``.
+
+Ces tests valident la **structure** de la spec produite ; ils ne
+lancent pas de vraie exécution OCR/LLM (les adapters concrets sont
+testés ailleurs).  Le smoke test d'exécution end-to-end passe par
+le runner de fixtures et vit dans
+``tests/integration/test_pipeline_executor_smoke.py`` (S8 / S9).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.domain import ArtifactType, PicaronesError
+from picarones.domain.pipeline_spec import INITIAL_STEP_ID
+from picarones.pipeline.llm_pipeline_builder import make_ocr_llm_pipeline_spec
+from picarones.pipeline.validation import validate_spec
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Mode text_only — OCR + LLM (texte seul)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestTextOnlyMode:
+    def test_two_steps_ocr_then_llm(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="openai:gpt-4o",
+        )
+        assert len(spec.steps) == 2
+        assert spec.steps[0].kind == "ocr"
+        assert spec.steps[0].adapter_name == "tesseract"
+        assert spec.steps[1].kind == "post_correction"
+        assert spec.steps[1].adapter_name == "openai:gpt-4o"
+
+    def test_initial_input_is_image(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="openai:gpt-4o",
+        )
+        assert spec.initial_inputs == (ArtifactType.IMAGE,)
+
+    def test_ocr_consumes_image_produces_raw_text(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="mistral:large",
+        )
+        ocr = spec.steps[0]
+        assert ArtifactType.IMAGE in ocr.input_types
+        assert ArtifactType.RAW_TEXT in ocr.output_types
+        assert ocr.inputs_from[ArtifactType.IMAGE] == INITIAL_STEP_ID
+
+    def test_llm_reads_text_from_ocr_step(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="mistral:large",
+        )
+        llm = spec.steps[1]
+        assert ArtifactType.RAW_TEXT in llm.input_types
+        # Crucial : le LLM tire son RAW_TEXT du step OCR (et non des
+        # initial inputs) — c'est la chaîne de production.
+        assert llm.inputs_from[ArtifactType.RAW_TEXT] == "ocr"
+
+    def test_llm_produces_corrected_text(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="anthropic:claude-3-5-sonnet",
+        )
+        llm = spec.steps[1]
+        assert ArtifactType.CORRECTED_TEXT in llm.output_types
+
+    def test_llm_does_not_see_image_in_text_only(self) -> None:
+        """En mode text_only, le LLM ne consomme pas d'IMAGE."""
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="ollama:llama3",
+        )
+        llm = spec.steps[1]
+        assert ArtifactType.IMAGE not in llm.input_types
+        assert ArtifactType.IMAGE not in llm.inputs_from
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Mode text_and_image — OCR + LLM multimodal
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestTextAndImageMode:
+    def test_two_steps_like_text_only(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_and_image",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="openai:gpt-4o",
+        )
+        assert len(spec.steps) == 2
+
+    def test_llm_consumes_both_text_and_image(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_and_image",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="openai:gpt-4o",
+        )
+        llm = spec.steps[1]
+        assert ArtifactType.RAW_TEXT in llm.input_types
+        assert ArtifactType.IMAGE in llm.input_types
+        # Le RAW_TEXT vient de l'OCR, l'IMAGE vient des inputs initiaux.
+        assert llm.inputs_from[ArtifactType.RAW_TEXT] == "ocr"
+        assert llm.inputs_from[ArtifactType.IMAGE] == INITIAL_STEP_ID
+
+    def test_llm_still_produces_corrected_text(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_and_image",
+            ocr_adapter_name="precomputed",
+            llm_adapter_name="mistral:large",
+        )
+        assert ArtifactType.CORRECTED_TEXT in spec.steps[1].output_types
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Mode zero_shot — VLM seul (pas d'OCR amont)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestZeroShotMode:
+    def test_single_step(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="zero_shot",
+            llm_adapter_name="anthropic:claude-3-5-sonnet",
+        )
+        assert len(spec.steps) == 1
+
+    def test_vlm_consumes_image_directly(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="zero_shot",
+            llm_adapter_name="openai:gpt-4o",
+        )
+        vlm = spec.steps[0]
+        assert ArtifactType.IMAGE in vlm.input_types
+        assert vlm.inputs_from[ArtifactType.IMAGE] == INITIAL_STEP_ID
+
+    def test_vlm_produces_raw_text_not_corrected(self) -> None:
+        """En zero_shot, le VLM transcrit — il produit RAW_TEXT
+        (transcription primaire) et non CORRECTED_TEXT (qui implique
+        la correction d'un texte préexistant)."""
+        spec = make_ocr_llm_pipeline_spec(
+            mode="zero_shot",
+            llm_adapter_name="anthropic:claude-3-5-sonnet",
+        )
+        vlm = spec.steps[0]
+        assert ArtifactType.RAW_TEXT in vlm.output_types
+        assert ArtifactType.CORRECTED_TEXT not in vlm.output_types
+
+    def test_kind_is_zero_shot_transcription(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="zero_shot",
+            llm_adapter_name="mistral:pixtral",
+        )
+        assert spec.steps[0].kind == "zero_shot_transcription"
+
+    def test_zero_shot_rejects_ocr_adapter(self) -> None:
+        """Combinaison incohérente : on ne fournit pas d'OCR amont
+        en zero-shot — le VLM consomme directement l'image."""
+        with pytest.raises(PicaronesError, match="zero_shot.*incompatible"):
+            make_ocr_llm_pipeline_spec(
+                mode="zero_shot",
+                ocr_adapter_name="tesseract",
+                llm_adapter_name="anthropic:claude-3-5-sonnet",
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Validation — les specs produites passent ``validate_spec``
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestSpecsArevalid:
+    @pytest.mark.parametrize(
+        "mode,ocr_name",
+        [
+            ("text_only", "tesseract"),
+            ("text_and_image", "tesseract"),
+            ("zero_shot", None),
+        ],
+    )
+    def test_spec_passes_validation(self, mode: str, ocr_name: str | None) -> None:
+        """Les 3 modes produisent une spec valide ``validate_spec``."""
+        spec = make_ocr_llm_pipeline_spec(
+            mode=mode,
+            ocr_adapter_name=ocr_name,
+            llm_adapter_name="openai:gpt-4o",
+        )
+        # Passer des adapters fictifs disponibles — on teste juste
+        # la structure du DAG, pas la résolution runtime.
+        validate_spec(
+            spec,
+            available_adapters={"tesseract", "openai:gpt-4o"},
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Erreurs — combinaisons invalides
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestErrorPaths:
+    def test_unknown_mode_raises(self) -> None:
+        with pytest.raises(PicaronesError, match="mode OCR.LLM inconnu"):
+            make_ocr_llm_pipeline_spec(
+                mode="invalid_mode",  # type: ignore[arg-type]
+                ocr_adapter_name="tesseract",
+                llm_adapter_name="openai:gpt-4o",
+            )
+
+    def test_text_only_requires_ocr(self) -> None:
+        with pytest.raises(PicaronesError, match="requiert ocr_adapter_name"):
+            make_ocr_llm_pipeline_spec(
+                mode="text_only",
+                llm_adapter_name="openai:gpt-4o",
+            )
+
+    def test_text_and_image_requires_ocr(self) -> None:
+        with pytest.raises(PicaronesError, match="requiert ocr_adapter_name"):
+            make_ocr_llm_pipeline_spec(
+                mode="text_and_image",
+                llm_adapter_name="openai:gpt-4o",
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Auto-naming
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAutoNaming:
+    def test_auto_name_text_only(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="openai:gpt-4o",
+        )
+        assert "text_only" in spec.name
+        assert "tesseract" in spec.name
+        # Les ``:`` du nom d'adapter LLM sont remplacés par ``_``.
+        assert ":" not in spec.name
+        assert "openai_gpt_4o" in spec.name
+
+    def test_explicit_name_overrides_auto(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="text_only",
+            ocr_adapter_name="tesseract",
+            llm_adapter_name="openai:gpt-4o",
+            name="my_custom_pipeline",
+        )
+        assert spec.name == "my_custom_pipeline"
+
+    def test_auto_name_zero_shot(self) -> None:
+        spec = make_ocr_llm_pipeline_spec(
+            mode="zero_shot",
+            llm_adapter_name="anthropic:claude-3-5-sonnet",
+        )
+        assert spec.name.startswith("vlm_zero_shot_")
+        assert "claude_3_5_sonnet" in spec.name
+
+
+# ──────────────────────────────────────────────────────────────────────
+# YAML round-trip (réutilise l'infra Sprint S6)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestYamlRoundtrip:
+    @pytest.mark.parametrize(
+        "mode,ocr_name",
+        [
+            ("text_only", "tesseract"),
+            ("text_and_image", "tesseract"),
+            ("zero_shot", None),
+        ],
+    )
+    def test_round_trip_through_yaml(self, mode: str, ocr_name: str | None) -> None:
+        """Une spec produite par le builder doit faire l'aller-retour
+        complet vers YAML sans perte d'information."""
+        from picarones.pipeline.yaml_io import (
+            dump_spec_to_yaml,
+            load_spec_from_yaml,
+        )
+
+        original = make_ocr_llm_pipeline_spec(
+            mode=mode,
+            ocr_adapter_name=ocr_name,
+            llm_adapter_name="openai:gpt-4o",
+        )
+        yaml_text = dump_spec_to_yaml(original)
+        reloaded = load_spec_from_yaml(yaml_text)
+        assert reloaded == original