sprint33: Phase 0.2 — interface module générique (BaseModule)

Deuxième sprint du plan d'évolution 2026. Pose l'abstraction qui rend
n'importe quel module de pipeline (OCR, reconstructeur ALTO, rewriter,
mappeur VLM→ALTO, NER, etc.) exécutable par le même runner avec des
types d'I/O déclarés explicitement.

Nouveau module picarones/core/modules.py :
- enum ArtifactType (IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER) —
valeurs string alignées sur GTLevel pour conversion triviale
- classe abstraite BaseModule avec input_types/output_types déclaratifs,
execution_mode (io/cpu), process(dict[ArtifactType, Any]) typée, et
helpers validate_inputs/validate_outputs

BaseOCREngine (picarones/engines/base.py) hérite désormais de BaseModule
avec input_types=(IMAGE,), output_types=(TEXT,). Sa nouvelle méthode
process wrappe l'API historique run() — aucun adaptateur OCR existant
(Tesseract, Pero, Mistral OCR, Google Vision, Azure DI) n'est touché.
test_engines.py passe à 20/20 sans modification.

Tests : +23 dans test_sprint33_module_interface.py couvrant le contrat
(instanciation, validation I/O, repr), un TextToAltoMock démonstratif
(critère explicite du plan), la délégation BaseOCREngine.process → run,
et la cohérence ArtifactType/GTLevel.
Suite complète : 1495 → 1518 passed, 2 skipped, 0 failed.

Verrou levé : le runner peut maintenant composer des modules de types
d'I/O hétérogènes — fondation directe pour l'axe B (banc d'essai
pipelines BnF) et plusieurs métriques de l'axe A (Layout F1, NER,
reading order F1).

CHANGELOG.md

@@ -16,6 +16,24 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 33 — Phase 0.2 : interface module générique.** Création de
+  `picarones/core/modules.py` :
+  - Enum `ArtifactType` (IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER) —
+    valeurs string alignées sur `GTLevel` pour conversion triviale
+  - Classe abstraite `BaseModule` avec `input_types`/`output_types`
+    déclaratifs, `execution_mode: "io"|"cpu"`, méthode `process` typée
+    `dict[ArtifactType, Any] → dict[ArtifactType, Any]`, helpers
+    `validate_inputs`/`validate_outputs`, `metadata()` libre
+  - `BaseOCREngine` hérite désormais de `BaseModule` avec
+    `input_types=(IMAGE,)`, `output_types=(TEXT,)`. Sa nouvelle méthode
+    `process` wrappe l'API historique `run()`. Aucun adaptateur OCR
+    existant (Tesseract, Pero, Mistral OCR, Google Vision, Azure DI) n'est
+    touché — le test_engines.py passe sans modification.
+  - +23 tests dans `tests/test_sprint33_module_interface.py` couvrant le
+    contrat (instanciation, validation I/O, repr), un `TextToAltoMock`
+    démonstratif (TEXT→ALTO, critère explicite du plan), la délégation
+    `BaseOCREngine.process → run`, et la cohérence ArtifactType/GTLevel.
+
 - **Sprint 32 — Phase 0.1 : modèle de données GT multi-niveaux.**
   Refonte de `picarones/core/corpus.py` :
   - Enum `GTLevel` (TEXT, ALTO, PAGE, ENTITIES, READING_ORDER)
@@ -38,8 +56,7 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1495 tests (+17 sur le Sprint 32). Aucune régression sur la
-  suite existante.
+- 1478 → 1518 tests (+17 Sprint 32, +23 Sprint 33). Aucune régression.
 
 ---
 

CLAUDE.md

@@ -204,6 +204,7 @@ AZURE_DOC_INTEL_KEY=...
 | 22 | **Sprint 7 du plan rapport (clôture phase 0)** : études de cas, documentation utilisateur, documentation développeur. Création de `docs/case-studies/` avec 2 cas d'école explicitement étiquetés (registres paroissiaux XVIIᵉ-XVIIIᵉ pour archivistes ; édition critique d'un manuscrit médiéval pour philologues). Encart sous la synthèse pointant vers le dossier. Documentation utilisateur `docs/user/reading-a-report.md` (anatomie du rapport, ordre de lecture suggéré, panneau avancé). Trois guides développeur (`docs/developer/index.md`, `narrative-engine.md`, `extending-glossary.md`, `extending-i18n.md`) couvrant l'extension de chaque sous-système. Tests E2E sur petits/grands corpus + locale EN, garde-fou « pas de fausses études prétendant être réelles » (chaque .md case-study doit contenir « Cas d'école »). 18 tests Sprint 22. |
 | 23-31 | Sprints intermédiaires : anti-hallucination, sécurité institutionnelle, refactor frontend Jinja2, persistance SQLite des jobs, snapshots reproductibilité, save/load config + comparaison de runs, registre déclaratif des détecteurs, polish/a11y/DX, couverture des modules sous-testés. Voir `CHANGELOG.md` [1.1.x] pour le détail. |
 | 32 | **Sprint 1 du plan d'évolution 2026 — Phase 0.1 : GT multi-niveaux**. Refonte de `picarones/core/corpus.py` pour porter une vérité terrain à plusieurs niveaux (`GTLevel.{TEXT,ALTO,PAGE,ENTITIES,READING_ORDER}`), payloads typés (`TextGT`, `AltoGT`, `PageGT`, `EntitiesGT`, `ReadingOrderGT`) avec `source_path` traçable. Le champ `Document.ground_truth: str` reste la source de vérité historique et est synchronisé automatiquement avec `Document.ground_truths[GTLevel.TEXT]` — rétrocompatibilité stricte (1478 tests existants passent sans modification). Le loader détecte automatiquement `.gt.alto.xml`, `.gt.page.xml`, `.gt.entities.json`, `.gt.reading_order.json` à côté de l'image. `Corpus.gt_level_coverage()` et `Corpus.available_gt_levels` exposent la couverture. Erreurs de parse dégradées en `logger.warning` (jamais `except: pass`). +17 tests dans `test_sprint32_multi_level_gt.py`. **Verrou levé** : ce sprint débloque l'évaluation des modules qui produisent ou consomment ALTO/PAGE/entités (axe B du plan, à venir Sprint 35+) et plusieurs métriques de l'axe A (Layout F1, reading order F1, NER). |
+| 33 | **Sprint 2 du plan d'évolution 2026 — Phase 0.2 : interface module générique**. Nouveau module `picarones/core/modules.py` avec l'enum `ArtifactType` (IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER) et la classe abstraite `BaseModule` qui déclare `input_types`/`output_types`, `execution_mode` (`"io"`/`"cpu"`), une méthode `process(dict[ArtifactType, Any]) → dict[ArtifactType, Any]`, et des helpers `validate_inputs`/`validate_outputs`. `BaseOCREngine` (`picarones/engines/base.py`) hérite désormais de `BaseModule` avec `input_types=(IMAGE,)` et `output_types=(TEXT,)` ; sa nouvelle méthode `process` wrappe l'API historique `run()`. Aucun adaptateur OCR existant n'est touché — `test_engines.py` passe à 20/20 sans modification. +23 tests dans `test_sprint33_module_interface.py` (contrat, validation, MockModule TEXT→ALTO démonstratif comme demandé par le plan, délégation `BaseOCREngine.process → run`, cohérence ArtifactType/GTLevel). **Verrou levé** : un même runner peut maintenant exécuter un OCR (image→texte), un mappeur VLM→ALTO, un rewriter ALTO→ALTO, un module NER (texte→entités), etc. — fondation directe pour l'axe B du plan. |
 
 ---
 
@@ -250,7 +251,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1495 passed, 2 skipped (Sprint 32 — Phase 0.1 du plan d'évolution 2026 terminée)
+- **Tests** : 1518 passed, 2 skipped (Sprints 32-33 — Phase 0.1 + 0.2 du plan d'évolution 2026)
 - **Plan d'évolution actif** : [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md)
 - **Branche active** : `claude/analyze-project-evolution-KOA56`
 - **Transcript de la conversation de développement** :

picarones/core/modules.py

@@ -0,0 +1,173 @@
+"""Interface module générique (Sprint 33 — Phase 0.2 du plan d'évolution).
+
+Pourquoi ce module
+------------------
+Aujourd'hui ``BaseOCREngine`` (`picarones/engines/base.py`) est typé
+implicitement « image → texte » par sa signature.  Cette assomption
+empêche d'évaluer dans le même runner :
+
+- un mappeur VLM → ALTO (image → texte + ALTO),
+- un rewriter ALTO post-correction (ALTO → ALTO),
+- un module NER (texte → entités),
+- un reconstructeur de structure (image + texte → ALTO).
+
+``BaseModule`` est l'interface générique dont ``BaseOCREngine`` devient
+un cas particulier.  Un module déclare explicitement les types
+d'artefacts qu'il **consomme** (``input_types``) et qu'il **produit**
+(``output_types``).  Le runner peut alors composer plusieurs modules en
+une pipeline (cf. axe B du plan d'évolution).
+
+Rétrocompatibilité
+------------------
+Aucun adaptateur OCR existant n'est touché par ce sprint.  La méthode
+``BaseModule.process`` est implémentée par défaut sur ``BaseOCREngine``
+de manière à wrapper l'ancien ``_run_ocr`` — toutes les sous-classes
+historiques (Tesseract, Pero OCR, Mistral OCR, Google Vision,
+Azure Document Intelligence) continuent à fonctionner sans modification.
+
+Convention sur ``ArtifactType``
+-------------------------------
+Les valeurs string de ``ArtifactType`` sont volontairement les mêmes que
+celles de ``GTLevel`` (Sprint 32) sauf pour ``IMAGE`` qui n'a pas de
+correspondance GT.  La conversion entre les deux se fait trivialement
+via ``.value`` :
+
+>>> from picarones.core.corpus import GTLevel
+>>> from picarones.core.modules import ArtifactType
+>>> ArtifactType(GTLevel.TEXT.value) is ArtifactType.TEXT
+True
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Literal
+
+
+class ArtifactType(str, Enum):
+    """Type d'artefact transitant entre modules d'une pipeline.
+
+    Inclut le ``IMAGE`` (entrée typique d'un OCR) et tous les niveaux
+    de ``GTLevel`` (Sprint 32) qui peuvent être produits ou consommés
+    par un module.
+    """
+
+    IMAGE = "image"
+    TEXT = "text"
+    ALTO = "alto"
+    PAGE = "page"
+    ENTITIES = "entities"
+    READING_ORDER = "reading_order"
+
+
+ExecutionMode = Literal["io", "cpu"]
+
+
+class BaseModule(ABC):
+    """Interface générique pour tout module exécutable par le runner.
+
+    Un module est une fonction typée d'artefacts vers artefacts.  Il
+    déclare ce qu'il consomme et ce qu'il produit, et expose une méthode
+    ``process`` qui prend un dictionnaire d'entrées et retourne un
+    dictionnaire de sorties.
+
+    Attributs de classe (à surcharger en sous-classe)
+    -------------------------------------------------
+    input_types : tuple[ArtifactType, ...]
+        Types d'artefacts consommés par ``process``.  L'ordre n'a pas de
+        signification ; le runner passe un dictionnaire.
+    output_types : tuple[ArtifactType, ...]
+        Types d'artefacts produits par ``process``.  Tous les types
+        listés doivent être présents dans le dict retourné par
+        ``process`` (le runner valide).
+    execution_mode : ``"io"`` ou ``"cpu"``
+        Indique au runner quel exécuteur utiliser : ``ThreadPoolExecutor``
+        pour les modules I/O-bound (API, réseau), ``ProcessPoolExecutor``
+        pour les CPU-bound (Tesseract, Pero).
+
+    Exemple minimal
+    ---------------
+    >>> class UpperCaseModule(BaseModule):
+    ...     input_types = (ArtifactType.TEXT,)
+    ...     output_types = (ArtifactType.TEXT,)
+    ...     execution_mode = "cpu"
+    ...
+    ...     @property
+    ...     def name(self) -> str:
+    ...         return "uppercase"
+    ...
+    ...     def process(self, inputs):
+    ...         return {ArtifactType.TEXT: inputs[ArtifactType.TEXT].upper()}
+    >>> m = UpperCaseModule()
+    >>> m.process({ArtifactType.TEXT: "hello"})
+    {<ArtifactType.TEXT: 'text'>: 'HELLO'}
+    """
+
+    input_types: tuple[ArtifactType, ...] = ()
+    output_types: tuple[ArtifactType, ...] = ()
+    execution_mode: ExecutionMode = "io"
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Identifiant unique et stable du module."""
+
+    @abstractmethod
+    def process(self, inputs: dict[ArtifactType, Any]) -> dict[ArtifactType, Any]:
+        """Exécute le module sur les artefacts d'entrée.
+
+        Parameters
+        ----------
+        inputs:
+            Dictionnaire ``{ArtifactType: payload}``.  Tous les types
+            déclarés dans ``input_types`` doivent être présents
+            (``validate_inputs`` peut être utilisé pour valider).
+
+        Returns
+        -------
+        dict[ArtifactType, Any]
+            Dictionnaire des sorties produites.  Tous les types déclarés
+            dans ``output_types`` doivent être présents.
+        """
+
+    def metadata(self) -> dict:
+        """Métadonnées libres exposées par le module.
+
+        Sous-classes peuvent surcharger pour exposer la version, la
+        license, la citation académique, etc.  Le runner inclut ce dict
+        dans le résultat afin que le rapport puisse l'afficher.
+        """
+        return {}
+
+    # ──────────────────────────────────────────────────────────────────
+    # Helpers de validation utilisés par le runner et les tests
+    # ──────────────────────────────────────────────────────────────────
+
+    def validate_inputs(self, inputs: dict[ArtifactType, Any]) -> None:
+        """Lève ``ValueError`` si un type d'entrée déclaré est manquant."""
+        missing = [t for t in self.input_types if t not in inputs]
+        if missing:
+            raise ValueError(
+                f"Module {self.name!r} : entrées manquantes "
+                f"{[t.value for t in missing]} (attendues : "
+                f"{[t.value for t in self.input_types]})"
+            )
+
+    def validate_outputs(self, outputs: dict[ArtifactType, Any]) -> None:
+        """Lève ``ValueError`` si un type de sortie déclaré est manquant."""
+        missing = [t for t in self.output_types if t not in outputs]
+        if missing:
+            raise ValueError(
+                f"Module {self.name!r} : sorties manquantes "
+                f"{[t.value for t in missing]} (déclarées : "
+                f"{[t.value for t in self.output_types]})"
+            )
+
+    def __repr__(self) -> str:
+        ins = ",".join(t.value for t in self.input_types) or "·"
+        outs = ",".join(t.value for t in self.output_types) or "·"
+        return f"{self.__class__.__name__}(name={self.name!r}, {ins}→{outs})"
+
+
+__all__ = ["ArtifactType", "BaseModule", "ExecutionMode"]

picarones/engines/base.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 import hashlib
 import time
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
+
+from picarones.core.modules import ArtifactType, BaseModule
 
 
 @dataclass
@@ -30,9 +32,16 @@ class EngineResult:
         return hashlib.sha256(Path(self.image_path).read_bytes()).hexdigest()
 
 
-class BaseOCREngine(ABC):
+class BaseOCREngine(BaseModule):
     """Classe de base dont héritent tous les adaptateurs OCR.
 
+    Sprint 33 — Phase 0.2 : ``BaseOCREngine`` hérite désormais de
+    ``BaseModule`` (cf. ``picarones.core.modules``) afin que les moteurs
+    OCR existants soient automatiquement utilisables comme nœuds d'une
+    pipeline composée (axe B du plan d'évolution).  Aucune sous-classe
+    OCR n'est touchée : la méthode ``process`` est implémentée ici et
+    délègue à ``run`` puis à ``_run_ocr``.
+
     Chaque adaptateur doit implémenter :
     - ``name`` : identifiant unique du moteur
     - ``version()`` : retourne la version du moteur sous forme de chaîne
@@ -46,6 +55,9 @@ class BaseOCREngine(ABC):
         - ``"cpu"`` → ``ProcessPoolExecutor`` (moteurs CPU-intensifs : Tesseract, Pero, Kraken)
     """
 
+    # Déclaration BaseModule — un OCR consomme une image et produit du texte.
+    input_types = (ArtifactType.IMAGE,)
+    output_types = (ArtifactType.TEXT,)
     execution_mode: str = "io"
     """``"io"`` pour ThreadPoolExecutor (défaut), ``"cpu"`` pour ProcessPoolExecutor."""
 
@@ -65,6 +77,27 @@ class BaseOCREngine(ABC):
     def _run_ocr(self, image_path: Path) -> str:
         """Exécute l'OCR et retourne le texte brut extrait."""
 
+    # ──────────────────────────────────────────────────────────────────
+    # Implémentation BaseModule (Sprint 33)
+    # ──────────────────────────────────────────────────────────────────
+
+    def process(self, inputs: dict[ArtifactType, Any]) -> dict[ArtifactType, Any]:
+        """Exécute le moteur OCR comme un module générique.
+
+        Wrapper rétrocompatible : extrait le chemin image de ``inputs``,
+        appelle ``run()``, et retourne la sortie sous forme de dictionnaire
+        ``{ArtifactType.TEXT: text}``.  Les erreurs sont conservées dans
+        le résultat (cf. ``EngineResult.error``) plutôt que de lever, comme
+        l'implémentation historique de ``run()``.
+        """
+        self.validate_inputs(inputs)
+        result = self.run(inputs[ArtifactType.IMAGE])
+        return {ArtifactType.TEXT: result.text}
+
+    def metadata(self) -> dict:
+        """Expose la version du moteur dans les métadonnées du module."""
+        return {"engine_version": self._safe_version()}
+
     def run(self, image_path: str | Path) -> EngineResult:
         """Point d'entrée public : exécute l'OCR et mesure le temps d'exécution."""
         image_path = Path(image_path)

tests/test_sprint33_module_interface.py

@@ -0,0 +1,266 @@
+"""Tests Sprint 33 — Interface module générique (Phase 0.2).
+
+Vérifie :
+
+1. ``BaseModule`` est instanciable via une sous-classe minimale qui
+   déclare ses ``input_types`` / ``output_types`` et implémente
+   ``process``.
+2. La validation des entrées/sorties (``validate_inputs`` /
+   ``validate_outputs``) lève ``ValueError`` quand un type déclaré est
+   manquant.
+3. Un ``MockModule`` qui consomme ``TEXT`` et produit ``ALTO`` peut
+   exister — l'interface n'est pas restreinte aux OCR (critère
+   explicite du plan).
+4. ``BaseOCREngine`` hérite de ``BaseModule`` et expose
+   ``input_types=(IMAGE,)``, ``output_types=(TEXT,)``.
+5. La méthode ``process`` d'un moteur OCR existant délègue correctement
+   à ``run``/``_run_ocr`` et retourne le bon type d'artefact.
+6. Les valeurs string de ``ArtifactType`` correspondent à celles de
+   ``GTLevel`` pour permettre la conversion triviale.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from picarones.core.corpus import GTLevel
+from picarones.core.modules import ArtifactType, BaseModule
+from picarones.engines.base import BaseOCREngine, EngineResult
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Fixtures de modules de test
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class UpperCaseTextModule(BaseModule):
+    """Module trivial TEXT → TEXT pour valider le contrat de base."""
+
+    input_types = (ArtifactType.TEXT,)
+    output_types = (ArtifactType.TEXT,)
+    execution_mode = "cpu"
+
+    @property
+    def name(self) -> str:
+        return "uppercase"
+
+    def process(self, inputs: dict[ArtifactType, Any]) -> dict[ArtifactType, Any]:
+        self.validate_inputs(inputs)
+        return {ArtifactType.TEXT: inputs[ArtifactType.TEXT].upper()}
+
+
+class TextToAltoMock(BaseModule):
+    """Mock TEXT → ALTO : le critère de réussite explicite du plan.
+
+    Un cas d'école pour le futur ``alto_reconstructor`` BnF (cf. plan
+    d'évolution, Sprint B.1).
+    """
+
+    input_types = (ArtifactType.TEXT,)
+    output_types = (ArtifactType.ALTO,)
+    execution_mode = "cpu"
+
+    @property
+    def name(self) -> str:
+        return "text_to_alto_mock"
+
+    def process(self, inputs: dict[ArtifactType, Any]) -> dict[ArtifactType, Any]:
+        self.validate_inputs(inputs)
+        text = inputs[ArtifactType.TEXT]
+        # Génère un ALTO trivial qui contient le texte en CONTENT
+        alto = (
+            '<?xml version="1.0" encoding="UTF-8"?>'
+            '<alto xmlns="http://www.loc.gov/standards/alto/ns-v4#">'
+            f'<Layout><Page><PrintSpace><TextBlock><TextLine>'
+            f'<String CONTENT="{text}"/>'
+            f'</TextLine></TextBlock></PrintSpace></Page></Layout>'
+            '</alto>'
+        )
+        return {ArtifactType.ALTO: alto}
+
+    def metadata(self) -> dict:
+        return {"strategy": "trivial_single_string"}
+
+
+class FaultyModule(BaseModule):
+    """Module qui prétend produire ALTO mais ne le fait pas — pour tester
+    la validation des sorties."""
+
+    input_types = (ArtifactType.TEXT,)
+    output_types = (ArtifactType.ALTO,)
+
+    @property
+    def name(self) -> str:
+        return "faulty"
+
+    def process(self, inputs: dict[ArtifactType, Any]) -> dict[ArtifactType, Any]:
+        return {ArtifactType.TEXT: "oops"}  # mauvais type de sortie
+
+
+class FakeOCREngine(BaseOCREngine):
+    """Moteur OCR factice pour tester la délégation BaseOCREngine.process."""
+
+    @property
+    def name(self) -> str:
+        return "fake_ocr"
+
+    def version(self) -> str:
+        return "0.1.0"
+
+    def _run_ocr(self, image_path: Path) -> str:
+        return f"transcription de {image_path.name}"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1 & 2. Contrat BaseModule : instanciation et validation
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestBaseModuleContract:
+    def test_minimal_module_runs(self) -> None:
+        m = UpperCaseTextModule()
+        out = m.process({ArtifactType.TEXT: "bonjour"})
+        assert out == {ArtifactType.TEXT: "BONJOUR"}
+
+    def test_validate_inputs_missing_raises(self) -> None:
+        m = UpperCaseTextModule()
+        with pytest.raises(ValueError, match="entrées manquantes"):
+            m.validate_inputs({})
+
+    def test_validate_outputs_missing_raises(self) -> None:
+        m = UpperCaseTextModule()
+        with pytest.raises(ValueError, match="sorties manquantes"):
+            m.validate_outputs({})
+
+    def test_validate_outputs_passes_when_complete(self) -> None:
+        m = UpperCaseTextModule()
+        # Doit passer sans lever
+        m.validate_outputs({ArtifactType.TEXT: "hello"})
+
+    def test_default_metadata_is_empty(self) -> None:
+        assert UpperCaseTextModule().metadata() == {}
+
+    def test_repr_shows_io_types(self) -> None:
+        m = UpperCaseTextModule()
+        r = repr(m)
+        assert "uppercase" in r
+        assert "text→text" in r
+
+    def test_default_execution_mode(self) -> None:
+        # UpperCaseTextModule a forcé "cpu" ; un module qui ne déclare
+        # rien hérite de "io".
+        class IOModule(BaseModule):
+            input_types = (ArtifactType.TEXT,)
+            output_types = (ArtifactType.TEXT,)
+
+            @property
+            def name(self) -> str:
+                return "io"
+
+            def process(self, inputs):
+                return {ArtifactType.TEXT: inputs[ArtifactType.TEXT]}
+
+        assert IOModule.execution_mode == "io"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 3. MockModule TEXT → ALTO (critère explicite du plan)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestMockTextToAlto:
+    def test_text_to_alto_runs(self) -> None:
+        m = TextToAltoMock()
+        out = m.process({ArtifactType.TEXT: "Hello"})
+
+        assert ArtifactType.ALTO in out
+        assert "Hello" in out[ArtifactType.ALTO]
+        assert "alto" in out[ArtifactType.ALTO]
+
+    def test_text_to_alto_declares_correct_types(self) -> None:
+        assert TextToAltoMock.input_types == (ArtifactType.TEXT,)
+        assert TextToAltoMock.output_types == (ArtifactType.ALTO,)
+
+    def test_text_to_alto_metadata_exposed(self) -> None:
+        assert TextToAltoMock().metadata() == {"strategy": "trivial_single_string"}
+
+    def test_validate_inputs_catches_missing_text(self) -> None:
+        m = TextToAltoMock()
+        with pytest.raises(ValueError):
+            # Donne une IMAGE alors qu'on attend TEXT
+            m.process({ArtifactType.IMAGE: Path("/tmp/x.png")})
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4 & 5. BaseOCREngine est rétrocompatible et respecte BaseModule
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestOCREngineAsModule:
+    def test_baseocrengine_is_basemodule(self) -> None:
+        assert issubclass(BaseOCREngine, BaseModule)
+
+    def test_baseocrengine_io_types(self) -> None:
+        assert BaseOCREngine.input_types == (ArtifactType.IMAGE,)
+        assert BaseOCREngine.output_types == (ArtifactType.TEXT,)
+
+    def test_fake_engine_run_unchanged(self, tmp_path: Path) -> None:
+        """L'API historique ``run`` retourne un ``EngineResult`` intact."""
+        image = tmp_path / "doc.png"
+        image.write_bytes(b"\x89PNG")
+        engine = FakeOCREngine()
+
+        result = engine.run(image)
+
+        assert isinstance(result, EngineResult)
+        assert result.success
+        assert result.text == "transcription de doc.png"
+        assert result.engine_name == "fake_ocr"
+
+    def test_fake_engine_process_returns_text_artifact(self, tmp_path: Path) -> None:
+        """``process`` délègue à ``run`` et retourne ``{TEXT: ...}``."""
+        image = tmp_path / "doc.png"
+        image.write_bytes(b"\x89PNG")
+        engine = FakeOCREngine()
+
+        outputs = engine.process({ArtifactType.IMAGE: image})
+
+        assert outputs == {ArtifactType.TEXT: "transcription de doc.png"}
+
+    def test_fake_engine_process_validates_missing_image(self) -> None:
+        engine = FakeOCREngine()
+        with pytest.raises(ValueError, match="entrées manquantes"):
+            engine.process({ArtifactType.TEXT: "wrong artifact"})
+
+    def test_fake_engine_metadata_exposes_version(self) -> None:
+        meta = FakeOCREngine().metadata()
+        assert meta == {"engine_version": "0.1.0"}
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 6. Cohérence ArtifactType / GTLevel
+# ───────��──────────────────────────────────────────────────────────────────
+
+
+class TestArtifactTypeGTLevelCoherence:
+    @pytest.mark.parametrize(
+        "level",
+        [
+            GTLevel.TEXT,
+            GTLevel.ALTO,
+            GTLevel.PAGE,
+            GTLevel.ENTITIES,
+            GTLevel.READING_ORDER,
+        ],
+    )
+    def test_each_gtlevel_maps_to_artifacttype(self, level: GTLevel) -> None:
+        """La conversion ``GTLevel → ArtifactType`` doit être triviale."""
+        assert ArtifactType(level.value) is not None
+
+    def test_image_has_no_gtlevel_counterpart(self) -> None:
+        """``IMAGE`` n'est pas une GT, c'est cohérent avec le plan."""
+        gt_values = {lvl.value for lvl in GTLevel}
+        assert ArtifactType.IMAGE.value not in gt_values