feat(sprint-H.2.b): factory canonique ocr_adapter_from_name

Sprint H.2.b du plan v2.0 — première brique de la migration des
callers legacy_engines vers les adapters canoniques.

Pourquoi
--------
``picarones.adapters.legacy_engines.factory.engine_from_name``
retourne des ``BaseOCREngine`` (legacy, ``run(image_path)``)
qu'il faut wrapper via ``LegacyOCREngineExecutor`` avant de les
brancher au ``PipelineExecutor``. La factory canonique
retourne directement des ``BaseOCRAdapter`` qui implémentent le
protocole ``StepExecutor`` natif — pas de wrapping nécessaire.

Cette factory est le building block qui permettra la migration
progressive des callers (CLI/web ``_legacy/``,
``_legacy_runner_adapter``) sans toucher la classe ``BaseOCREngine``
elle-même (qui sera supprimée en H.2.d).

Modifications
-------------
- ``picarones/adapters/ocr/factory.py`` (nouveau, ~175 LOC) :
``ocr_adapter_from_name(name, **kwargs) → BaseOCRAdapter``.
Supporte les 6 adapters canoniques (tesseract, pero_ocr,
mistral_ocr, google_vision, azure_doc_intel, precomputed)
avec alias courts (``tess``, ``pero``, ``mistral``,
``google``/``gv``, ``azure``/``adi``). Insensible à la casse.
- ``picarones/adapters/ocr/__init__.py`` : exporte
``ocr_adapter_from_name``.
- ``picarones/adapters/legacy_engines/factory.py`` : docstring
mise à jour pour pointer vers la canonique et préciser le
calendrier de retrait (H.2.d avec ``BaseOCREngine``).

Tests
-----
- ``tests/adapters/ocr/test_factory.py`` (nouveau, 13 tests) :
- ``TestTesseract`` (6) : nom canonique, alias ``tess``,
casse normalisée, kwargs propagés, faute de frappe lève
``TypeError`` (pas masqué), psm invalide lève
``OCRAdapterError``.
- ``TestPrecomputed`` (1) : sans dep optionnelle.
- ``TestCloudAdapters`` (3) : mistral/google/azure
instanciables sans credentials (résolution paresseuse à
``execute()``).
- ``TestPeroOCR`` (1) : tolérant à l'absence de ``pero-ocr``
avec message d'erreur explicite.
- ``TestUnknownName`` (2) : nom inconnu liste les supportés
+ alias ; nom vide lève.

Comparaison avec la factory legacy
----------------------------------
| Aspect | legacy_engines.engine_from_name | ocr.ocr_adapter_from_name |
|--------|--------------------------------|---------------------------|
| Retour | ``BaseOCREngine`` (legacy) | ``BaseOCRAdapter`` (canonique) |
| Protocole | ``run(image_path) → EngineResult`` | ``execute(inputs, params, ctx)`` |
| Wrapping | ``LegacyOCREngineExecutor`` requis | ✅ direct |
| Adapters | tesseract, pero_ocr | tesseract, pero_ocr, mistral_ocr, google_vision, azure_doc_intel, precomputed |
| Alias | aucun | tess, pero, mistral, google/gv, azure/adi |
| kwargs | ``lang``, ``psm`` (positionnels) | tous les kwargs du constructeur |

Tests : 4663 passed, 9 skipped, 24 deselected.

Reste pour v2.0
---------------
- H.2.b suite : migrer les callers de ``engine_from_name`` (CLI
``_workflows.py``, ``_robustness.py`` ; web
``benchmark_utils.py``) à utiliser ``ocr_adapter_from_name``.
- H.2.c : suppression ``OCRLLMPipeline`` (callers basculent à
``make_ocr_llm_pipeline_spec`` directement).
- H.2.d : suppression ``BaseOCREngine`` + ``adapters/legacy_engines/``.
- H.4 : refonte interfaces/{cli,web}/_legacy/.
- H.6 : bump version + tag v2.0.0.

https://claude.ai/code/session_01NxyVKqg2SowXLZdM4H1ZDE

CLAUDE.md

@@ -123,7 +123,7 @@ picarones/
 
 ## État des tests et bugs historiques
 
-`pytest tests/` → **4680 passed, 12 skipped, 8 deselected, 0 failed**
+`pytest tests/` → **4690 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
@@ -252,7 +252,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` → 4680 passed.
+3. `pytest tests/ -q --no-header --tb=line` → 4690 passed.
 4. `git log -1 --format=%B` → décrit la prochaine sub-phase.
 
 **Règles d'architecture critiques** (apprises à la dure) :
@@ -340,7 +340,7 @@ détecte, arbitre, rend.
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces, Python 3.11+
-- **Tests** : `pytest tests/ -q` → 4680 passed, 12 skipped, 24
+- **Tests** : `pytest tests/ -q` → 4690 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

@@ -395,7 +395,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~4680 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4690 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/factory.py

@@ -1,23 +1,18 @@
-"""Factory : instancier un moteur OCR à partir de son nom court.
+"""Factory legacy : instancier un ``BaseOCREngine`` à partir de son nom court.
 
 Phase 7.A — module relocalisé depuis ``picarones.engines.factory``
-vers ``picarones.adapters.legacy_engines.factory``.  Le chemin legacy
-reste disponible via un shim avec ``DeprecationWarning`` ;
-suppression prévue en 2.0.
+vers ``picarones.adapters.legacy_engines.factory``.
 
-Vit en cercle 2 (``picarones.adapters.legacy_engines``) parce que c'est de la logique de
-catalogue OCR — le CLI (cercle 3) et l'API web (cercle 3) la consomment
-tous les deux. Auparavant ce helper était défini dans
-``picarones.cli`` puis importé par ``picarones.web.benchmark_utils`` —
-violation de la règle d'imports inward-only.
-
-Cette factory ne dépend d'aucune brique cercle 3 (pas de ``click``,
-pas de FastAPI). Les erreurs sont signalées via ``ValueError``, le CLI
-les retraduit en ``click.BadParameter`` et l'API web les convertit en
-warning utilisateur.
+Sprint H.2.b du plan v2.0 — équivalent canonique disponible :
+``picarones.adapters.ocr.factory.ocr_adapter_from_name`` retourne
+des ``BaseOCRAdapter`` (StepExecutor Protocol) directement
+consommables par ``PipelineExecutor`` sans ``LegacyOCREngineExecutor``.
+Les nouveaux callers doivent utiliser la factory canonique.  Cette
+factory ne sera supprimée qu'avec ``BaseOCREngine`` lui-même
+(H.2.d).
 
 Discipline : ne pas importer ``click`` ici, sous peine de remonter une
-dépendance cercle 3 dans cercle 2.
+dépendance interfaces dans la couche adapters.
 """
 
 from __future__ import annotations

picarones/adapters/ocr/__init__.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 
 from picarones.adapters.ocr.azure_doc_intel import AzureDocIntelAdapter
 from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.ocr.factory import ocr_adapter_from_name
 from picarones.adapters.ocr.google_vision import GoogleVisionAdapter
 from picarones.adapters.ocr.mistral_ocr import MistralOCRAdapter
 from picarones.adapters.ocr.pero_ocr import PeroOCRAdapter
@@ -36,4 +37,5 @@ __all__ = [
     "PeroOCRAdapter",
     "PrecomputedTextAdapter",
     "TesseractAdapter",
+    "ocr_adapter_from_name",
 ]

picarones/adapters/ocr/factory.py

@@ -0,0 +1,184 @@
+"""Factory canonique : instancier un ``BaseOCRAdapter`` par nom court.
+
+Sprint H.2.b du plan v2.0 — équivalent canonique de
+``picarones.adapters.legacy_engines.factory.engine_from_name`` qui
+retournait des ``BaseOCREngine`` (legacy, ``run(image_path) →
+EngineResult``).  Cette factory retourne des ``BaseOCRAdapter``
+(rewrite, ``StepExecutor`` Protocol, ``execute(inputs, params,
+context) → dict[ArtifactType, Artifact]``).
+
+Pourquoi ici
+------------
+Vit en couche 5 (``picarones.adapters.ocr``) plutôt qu'en
+``app/`` parce que c'est de la logique de catalogue OCR — la CLI
+(couche 8) et la web API (couche 8) la consomment toutes les deux.
+Cette factory ne dépend d'aucune brique de couche supérieure
+(pas de ``click``, pas de FastAPI).
+
+Migration depuis le legacy
+--------------------------
+Code legacy ::
+
+    from picarones.adapters.legacy_engines.factory import engine_from_name
+    engine = engine_from_name("tesseract", lang="fra", psm=6)
+    # engine est un BaseOCREngine, à wrapper via LegacyOCREngineExecutor
+    # avant de pouvoir être consommé par PipelineExecutor.
+
+Code canonique équivalent ::
+
+    from picarones.adapters.ocr.factory import ocr_adapter_from_name
+    adapter = ocr_adapter_from_name("tesseract", lang="fra", psm=6)
+    # adapter est un BaseOCRAdapter — déjà un StepExecutor, peut
+    # être directement enregistré dans un adapter_resolver et
+    # consommé par PipelineExecutor sans wrapping.
+
+Alias supportés
+---------------
+- ``tesseract`` / ``tess``
+- ``pero_ocr`` / ``pero``
+- ``mistral_ocr`` / ``mistral``
+- ``google_vision`` / ``google`` / ``gv``
+- ``azure_doc_intel`` / ``azure`` / ``adi``
+- ``precomputed``
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from picarones.adapters.ocr.base import BaseOCRAdapter
+
+#: Mapping ``alias → nom canonique`` pour les noms abrégés.
+_ALIASES: dict[str, str] = {
+    "tess": "tesseract",
+    "pero": "pero_ocr",
+    "mistral": "mistral_ocr",
+    "google": "google_vision",
+    "gv": "google_vision",
+    "azure": "azure_doc_intel",
+    "adi": "azure_doc_intel",
+}
+
+#: Liste des noms canoniques supportés pour les messages d'erreur.
+_SUPPORTED: tuple[str, ...] = (
+    "tesseract",
+    "pero_ocr",
+    "mistral_ocr",
+    "google_vision",
+    "azure_doc_intel",
+    "precomputed",
+)
+
+
+def ocr_adapter_from_name(
+    name: str, **kwargs: Any,
+) -> BaseOCRAdapter:
+    """Instancie un ``BaseOCRAdapter`` canonique par son nom court.
+
+    Parameters
+    ----------
+    name:
+        Identifiant court du moteur (cf. liste des alias dans le
+        docstring du module).  Insensible à la casse.
+    **kwargs:
+        Arguments propagés au constructeur de l'adapter cible.
+        Les kwargs non reconnus par le constructeur lèveront un
+        ``TypeError`` — c'est intentionnel, on ne masque pas les
+        fautes de frappe.
+
+    Returns
+    -------
+    BaseOCRAdapter
+        Instance prête à être enregistrée dans un
+        ``adapter_resolver`` et consommée par ``PipelineExecutor``.
+
+    Raises
+    ------
+    ValueError
+        Si ``name`` est inconnu, ou si l'adapter cible nécessite
+        une dépendance optionnelle non installée (ex : Pero OCR
+        sans ``pero-ocr``).  Le message d'erreur inclut la liste
+        des moteurs effectivement supportés.
+
+    Examples
+    --------
+    >>> adapter = ocr_adapter_from_name("tesseract", lang="fra")
+    >>> adapter.name
+    'tesseract'
+
+    >>> adapter = ocr_adapter_from_name("tess")  # alias
+    >>> adapter.name
+    'tesseract'
+
+    >>> adapter = ocr_adapter_from_name(
+    ...     "precomputed", source_label="bnf_jean_zay",
+    ... )
+    >>> adapter.name
+    'precomputed:bnf_jean_zay'
+    """
+    canonical = _ALIASES.get(name.lower(), name.lower())
+
+    if canonical == "tesseract":
+        from picarones.adapters.ocr.tesseract import TesseractAdapter
+        return TesseractAdapter(**kwargs)
+
+    if canonical == "pero_ocr":
+        try:
+            from picarones.adapters.ocr.pero_ocr import PeroOCRAdapter
+        except ImportError as exc:
+            raise ValueError(
+                f"Adapter 'pero_ocr' indisponible : {exc}.  "
+                "Installer la dépendance optionnelle ``pero-ocr``."
+            ) from exc
+        return PeroOCRAdapter(**kwargs)
+
+    if canonical == "mistral_ocr":
+        try:
+            from picarones.adapters.ocr.mistral_ocr import MistralOCRAdapter
+        except ImportError as exc:
+            raise ValueError(
+                f"Adapter 'mistral_ocr' indisponible : {exc}.  "
+                "Installer la dépendance optionnelle ``mistralai``."
+            ) from exc
+        return MistralOCRAdapter(**kwargs)
+
+    if canonical == "google_vision":
+        try:
+            from picarones.adapters.ocr.google_vision import (
+                GoogleVisionAdapter,
+            )
+        except ImportError as exc:
+            raise ValueError(
+                f"Adapter 'google_vision' indisponible : {exc}.  "
+                "Installer la dépendance optionnelle "
+                "``google-cloud-vision``."
+            ) from exc
+        return GoogleVisionAdapter(**kwargs)
+
+    if canonical == "azure_doc_intel":
+        try:
+            from picarones.adapters.ocr.azure_doc_intel import (
+                AzureDocIntelAdapter,
+            )
+        except ImportError as exc:
+            raise ValueError(
+                f"Adapter 'azure_doc_intel' indisponible : {exc}.  "
+                "Installer la dépendance optionnelle "
+                "``azure-ai-formrecognizer``."
+            ) from exc
+        return AzureDocIntelAdapter(**kwargs)
+
+    if canonical == "precomputed":
+        from picarones.adapters.ocr.precomputed import (
+            PrecomputedTextAdapter,
+        )
+        return PrecomputedTextAdapter(**kwargs)
+
+    raise ValueError(
+        f"Moteur OCR inconnu : {name!r}.  Valeurs supportées : "
+        f"{', '.join(_SUPPORTED)} (alias : "
+        f"{', '.join(sorted(_ALIASES))}).",
+    )
+
+
+__all__ = ["ocr_adapter_from_name"]

tests/adapters/ocr/test_factory.py

@@ -0,0 +1,125 @@
+"""Sprint H.2.b — factory canonique ``ocr_adapter_from_name``.
+
+Vérifie l'équivalent canonique de
+``picarones.adapters.legacy_engines.factory.engine_from_name`` :
+
+- Résolution des alias (``tess`` → ``tesseract``, etc.) ;
+- Construction effective des 6 adapters supportés (1 sans deps,
+  4 cloud avec deps optionnelles, 1 precomputed) ;
+- ``ValueError`` propre sur nom inconnu / dépendance absente,
+  avec message d'erreur listant les moteurs supportés ;
+- Insensibilité à la casse du nom.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.adapters.ocr import ocr_adapter_from_name
+from picarones.adapters.ocr.base import BaseOCRAdapter
+from picarones.adapters.ocr.tesseract import TesseractAdapter
+
+
+class TestTesseract:
+    def test_canonical_name(self) -> None:
+        adapter = ocr_adapter_from_name("tesseract")
+        assert isinstance(adapter, TesseractAdapter)
+        assert adapter.name == "tesseract"
+
+    def test_alias_tess(self) -> None:
+        adapter = ocr_adapter_from_name("tess")
+        assert isinstance(adapter, TesseractAdapter)
+        # L'alias normalise vers le nom canonique "tesseract".
+        assert adapter.name == "tesseract"
+
+    def test_uppercase_name_normalized(self) -> None:
+        adapter = ocr_adapter_from_name("Tesseract")
+        assert isinstance(adapter, TesseractAdapter)
+
+    def test_kwargs_propagate(self) -> None:
+        adapter = ocr_adapter_from_name(
+            "tesseract", lang="eng", psm=3,
+        )
+        assert adapter.lang == "eng"
+
+    def test_invalid_kwarg_raises_typeerror(self) -> None:
+        # Pas de masquage des fautes de frappe.
+        with pytest.raises(TypeError):
+            ocr_adapter_from_name("tesseract", langg="fra")
+
+    def test_invalid_psm_raises_ocr_adapter_error(self) -> None:
+        from picarones.adapters.ocr.base import OCRAdapterError
+        with pytest.raises(OCRAdapterError, match="psm"):
+            ocr_adapter_from_name("tesseract", psm=99)
+
+
+class TestPrecomputed:
+    """``precomputed`` n'a pas de dépendance optionnelle — doit
+    toujours être instanciable."""
+
+    def test_canonical_name(self) -> None:
+        adapter = ocr_adapter_from_name(
+            "precomputed", source_label="bnf",
+        )
+        assert isinstance(adapter, BaseOCRAdapter)
+        assert "bnf" in adapter.name
+
+
+class TestCloudAdapters:
+    """Les adapters cloud sont importables sans la dépendance
+    système (pas de credentials nécessaires à l'instanciation —
+    la lib client est résolue paresseusement à execute())."""
+
+    def test_mistral_ocr_via_alias(self) -> None:
+        adapter = ocr_adapter_from_name(
+            "mistral", model="mistral-ocr-latest", api_key="fake",
+        )
+        assert isinstance(adapter, BaseOCRAdapter)
+        assert adapter.name == "mistral_ocr"
+
+    def test_google_vision_via_alias(self) -> None:
+        adapter = ocr_adapter_from_name(
+            "google", api_key="fake",
+        )
+        assert isinstance(adapter, BaseOCRAdapter)
+        assert adapter.name == "google_vision"
+
+    def test_azure_doc_intel_via_alias(self) -> None:
+        adapter = ocr_adapter_from_name(
+            "azure", endpoint="https://x.com", api_key="fake",
+        )
+        assert isinstance(adapter, BaseOCRAdapter)
+        assert adapter.name == "azure_doc_intel"
+
+
+class TestPeroOCR:
+    """Pero OCR a une dépendance optionnelle ``pero-ocr`` — peut
+    être absent dans l'environnement de test."""
+
+    def test_canonical_or_helpful_error(self, tmp_path) -> None:
+        cfg = tmp_path / "fake_pero.ini"
+        cfg.write_text("# fake config", encoding="utf-8")
+        try:
+            adapter = ocr_adapter_from_name(
+                "pero_ocr", config_path=str(cfg),
+            )
+            assert isinstance(adapter, BaseOCRAdapter)
+        except ValueError as exc:
+            # Si ``pero-ocr`` n'est pas installé, on attend un
+            # message d'erreur qui explique comment l'installer.
+            assert "pero-ocr" in str(exc).lower()
+
+
+class TestUnknownName:
+    def test_unknown_raises_with_supported_list(self) -> None:
+        with pytest.raises(ValueError) as ctx:
+            ocr_adapter_from_name("not_a_real_engine")
+        msg = str(ctx.value)
+        # Le message liste les moteurs supportés et les alias —
+        # utile pour le diagnostic.
+        assert "tesseract" in msg
+        assert "alias" in msg.lower()
+
+    def test_empty_name_raises(self) -> None:
+        with pytest.raises(ValueError):
+            ocr_adapter_from_name("")