feat(adapters/ocr): Sprint A14-S34 — AzureDocIntelAdapter natif (Phase 2 done)

Migration native du legacy picarones.engines.azure_doc_intel vers
BaseOCRAdapter (S26). Pas un shim. **Phase 2 complete** : tous les 5
moteurs OCR sont maintenant migrés (Tesseract S30, Pero S31, Mistral S32,
Google Vision S33, Azure DI S34).

picarones/adapters/ocr/azure_doc_intel.py
-----------------------------------------
- AzureDocIntelAdapter(BaseOCRAdapter), execution_mode = "io".
- Constructeur kwargs-only : name, endpoint/api_key (overrides
AZURE_DOC_INTEL_ENDPOINT/AZURE_DOC_INTEL_KEY), model_id (défaut
"prebuilt-read"), locale (défaut "fr-FR"), api_version, timeout_seconds,
max_polling_attempts, polling_interval_base.
- Validation au constructeur : name alphanum + _-, timeouts > 0,
polling_interval >= 0.
- Routing : tente SDK azure-ai-documentintelligence ; fallback REST si
ImportError.
- API Azure asynchrone : POST → Operation-Location → polling tant que
status="running" (interval = base + 0.5 * attempt). Backoff linéaire
identique au legacy.
- Statuts : succeeded → extrait pages.lines.content ; failed/canceled →
OCRAdapterError.
- Sentinel _SDKMissing pour fallback propre — capturé en interne, ne
fuit jamais au caller.
- Erreurs HTTP/SDK wrappées dans OCRAdapterError avec type+message.
- Écrit dans <stem>.<name>.txt à côté de l'image.

Tests S34 dédiés (31 nouveaux)
------------------------------
- Constructor : defaults, custom name/model_id, rejet name vide/
invalide, rejet timeout/max_polling/polling_interval invalides.
- Contract : isinstance BaseOCRAdapter, input/output_types,
execution_mode = "io".
- Auth : explicit api_key/endpoint priority, env fallback, no key/
endpoint → OCRAdapterError, .rstrip("/") sur endpoint.
- InputValidation : IMAGE absent, sans URI, image inexistante → tous
OCRAdapterError.
- REST : succeeded → texte concaténé par lignes, running puis succeeded
(polling), failed/canceled → OCRAdapterError, polling timeout après
max_attempts → OCRAdapterError, no Operation-Location → OCRAdapterError,
écriture <stem>.<name>.txt.
- SDK : SDK call succeeds avec begin_analyze_document, SDK exception →
OCRAdapterError wrappé.
- ArtifactID : utilise adapter name.

Phase 2 récapitulatif (5 OCR engines migrés)
--------------------------------------------
| Sprint | Adapter | Tests | Total |
|--------|-----------------|-------|-------|
| S30 | Tesseract | 24 | +24 |
| S31 | Pero OCR | 21 | +21 |
| S32 | Mistral OCR | 28 | +28 |
| S33 | Google Vision | 29 | +29 |
| S34 | Azure DI | 31 | +31 |

Total Phase 2 : 133 nouveaux tests, 5 adapters migrés natifs.

Tests : 4731 passed, 11 skipped (vs 4700 avant : +31 S34).
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**: ~4720 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4750 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/ocr/__init__.py

@@ -19,6 +19,7 @@ dédiés, **natifs** au nouveau contrat (pas de shim sur le legacy
 
 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.google_vision import GoogleVisionAdapter
 from picarones.adapters.ocr.mistral_ocr import MistralOCRAdapter
@@ -29,6 +30,7 @@ from picarones.adapters.ocr.tesseract import TesseractAdapter
 __all__ = [
     "BaseOCRAdapter",
     "OCRAdapterError",
+    "AzureDocIntelAdapter",
     "GoogleVisionAdapter",
     "MistralOCRAdapter",
     "PeroOCRAdapter",

picarones/adapters/ocr/azure_doc_intel.py

@@ -0,0 +1,368 @@
+"""``AzureDocIntelAdapter`` natif — Sprint A14-S34.
+
+Migration native du legacy ``picarones.engines.azure_doc_intel`` vers
+``BaseOCRAdapter`` (S26).  **Pas un shim**.
+
+Le legacy reste en place jusqu'au S46.
+
+Cas d'usage BnF
+---------------
+Azure Document Intelligence (anciennement Form Recognizer) propose
+plusieurs modèles préentraînés :
+
+- ``prebuilt-read`` (défaut) : lecture générique optimisée pour les
+  documents textuels denses.
+- ``prebuilt-document`` : extraction layout + champs.
+- ``prebuilt-layout`` : analyse de mise en page.
+- modèles personnalisés entraînés.
+
+L'API est asynchrone : on poste l'image et on poll un endpoint
+status jusqu'à obtenir le résultat.
+
+L'adapter route automatiquement vers SDK
+(``azure-ai-documentintelligence``) si disponible, sinon REST
+direct via ``urllib`` (avec polling).
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"azure_doc_intel"``).
+- ``endpoint`` : URL de l'endpoint (overrides
+  ``AZURE_DOC_INTEL_ENDPOINT``).
+- ``api_key`` : clé API (overrides ``AZURE_DOC_INTEL_KEY``).
+- ``model_id`` (défaut ``"prebuilt-read"``).
+- ``locale`` (défaut ``"fr-FR"``).
+- ``api_version`` (défaut ``"2024-02-29-preview"``).
+- ``timeout_seconds`` (défaut 60) : timeout par requête HTTP.
+- ``max_polling_attempts`` (défaut 30) : nombre max de polls REST.
+- ``polling_interval_base`` (défaut 1.0) : intervalle de base entre
+  polls (incrémenté de 0.5s par tentative — backoff linéaire
+  identique au legacy).
+
+Comportement
+------------
+1. Valide IMAGE input.
+2. Résout endpoint + api_key (explicite > env).
+3. Tente le SDK ; sur ImportError, fallback REST.
+4. Pour le REST : POST → Operation-Location → poll jusqu'à
+   ``succeeded`` / ``failed`` / ``canceled``.
+5. Extrait le texte ligne par ligne dans l'ordre pages × lines.
+6. Écrit dans ``<stem>.<name>.txt`` à côté de l'image.
+
+Anti-sur-ingénierie
+-------------------
+- Pas d'extraction de confidences (legacy S51 — reportée).
+- Pas de support multi-langue dans une même requête.
+- Pas de retry au-delà du polling (qui est un retry implicite).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class AzureDocIntelAdapter(BaseOCRAdapter):
+    """Adapter Azure Document Intelligence natif au contrat S26.
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible.  Défaut ``"azure_doc_intel"``.
+    endpoint:
+        URL Azure (override ``AZURE_DOC_INTEL_ENDPOINT``).
+    api_key:
+        Clé API Azure (override ``AZURE_DOC_INTEL_KEY``).
+    model_id:
+        ``"prebuilt-read"`` (défaut), ``"prebuilt-document"``,
+        ``"prebuilt-layout"``, ou un modèle entraîné personnalisé.
+    locale:
+        Locale Azure (défaut ``"fr-FR"``).
+    api_version:
+        Version d'API Azure (défaut ``"2024-02-29-preview"``).
+    timeout_seconds:
+        Timeout HTTP (défaut 60).
+    max_polling_attempts:
+        Nombre max de polls REST (défaut 30).
+    polling_interval_base:
+        Intervalle de base entre polls (défaut 1.0s, +0.5s/attempt).
+
+    Raises
+    ------
+    OCRAdapterError
+        Au constructeur si name invalide ou paramètres hors plage.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        name: str = "azure_doc_intel",
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        model_id: str = "prebuilt-read",
+        locale: str = "fr-FR",
+        api_version: str = "2024-02-29-preview",
+        timeout_seconds: float = 60.0,
+        max_polling_attempts: int = 30,
+        polling_interval_base: float = 1.0,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "AzureDocIntelAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if timeout_seconds <= 0:
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : timeout_seconds doit être > 0, "
+                f"reçu {timeout_seconds}.",
+            )
+        if max_polling_attempts <= 0:
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : max_polling_attempts doit être "
+                f"> 0, reçu {max_polling_attempts}.",
+            )
+        if polling_interval_base < 0:
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : polling_interval_base doit être "
+                f">= 0, reçu {polling_interval_base}.",
+            )
+        self._name = name
+        self._explicit_endpoint = endpoint
+        self._explicit_api_key = api_key
+        self._model_id = model_id
+        self._locale = locale
+        self._api_version = api_version
+        self._timeout = timeout_seconds
+        self._max_polling_attempts = max_polling_attempts
+        self._polling_base = polling_interval_base
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def model_id(self) -> str:
+        return self._model_id
+
+    def _resolve_api_key(self) -> str:
+        key = self._explicit_api_key or os.environ.get("AZURE_DOC_INTEL_KEY")
+        if not key:
+            raise OCRAdapterError(
+                f"{self.name} : clé API Azure manquante. Définir "
+                "AZURE_DOC_INTEL_KEY ou passer api_key= au constructeur.",
+            )
+        return key
+
+    def _resolve_endpoint(self) -> str:
+        endpoint = (
+            self._explicit_endpoint
+            or os.environ.get("AZURE_DOC_INTEL_ENDPOINT", "")
+        ).rstrip("/")
+        if not endpoint:
+            raise OCRAdapterError(
+                f"{self.name} : endpoint Azure manquant. Définir "
+                "AZURE_DOC_INTEL_ENDPOINT ou passer endpoint= au "
+                "constructeur.",
+            )
+        return endpoint
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        api_key = self._resolve_api_key()
+        endpoint = self._resolve_endpoint()
+
+        # On tente le SDK d'abord ; sur ImportError, fallback REST.
+        try:
+            text = self._call_via_sdk(image_path, endpoint, api_key)
+        except _SDKMissing:
+            text = self._call_via_rest(image_path, endpoint, api_key)
+
+        text_path = (
+            image_path.parent / f"{image_path.stem}.{self.name}.txt"
+        )
+        text_path.write_text(text, encoding="utf-8")
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+    # ──────────────────────────────────────────────────────────────
+    # SDK
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_via_sdk(
+        self, image_path: Path, endpoint: str, api_key: str,
+    ) -> str:
+        try:
+            from azure.ai.documentintelligence import (
+                DocumentIntelligenceClient,
+            )
+            from azure.core.credentials import AzureKeyCredential
+        except ImportError as exc:
+            raise _SDKMissing() from exc
+
+        try:
+            client = DocumentIntelligenceClient(
+                endpoint=endpoint,
+                credential=AzureKeyCredential(api_key),
+            )
+            with open(image_path, "rb") as f:
+                poller = client.begin_analyze_document(
+                    model_id=self._model_id,
+                    body=f,
+                    locale=self._locale,
+                    content_type="application/octet-stream",
+                )
+            result = poller.result()
+            text = "\n".join(
+                line.content
+                for page in result.pages
+                for line in (page.lines or [])
+            )
+        except _SDKMissing:
+            raise
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : SDK Azure a levé : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+        return text
+
+    # ──────────────────────────────────────────────────────────────
+    # REST avec polling
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_via_rest(
+        self, image_path: Path, endpoint: str, api_key: str,
+    ) -> str:
+        image_bytes = image_path.read_bytes()
+        analyze_url = (
+            f"{endpoint}/documentintelligence/documentModels/"
+            f"{self._model_id}:analyze"
+            f"?api-version={self._api_version}&locale={self._locale}"
+        )
+        req = urllib.request.Request(
+            analyze_url,
+            data=image_bytes,
+            headers={
+                "Ocp-Apim-Subscription-Key": api_key,
+                "Content-Type": "application/octet-stream",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                operation_url = resp.headers.get("Operation-Location", "")
+        except urllib.error.HTTPError as exc:
+            body = ""
+            try:
+                body = exc.read().decode("utf-8")
+            except Exception:  # noqa: BLE001
+                pass
+            raise OCRAdapterError(
+                f"{self.name} : Azure Document Intelligence erreur "
+                f"{exc.code} : {body}",
+            ) from exc
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Azure : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+
+        if not operation_url:
+            raise OCRAdapterError(
+                f"{self.name} : Azure n'a pas retourné Operation-Location.",
+            )
+
+        # Polling du résultat (Azure asynchrone).
+        headers = {"Ocp-Apim-Subscription-Key": api_key}
+        for attempt in range(self._max_polling_attempts):
+            time.sleep(self._polling_base + attempt * 0.5)
+            poll_req = urllib.request.Request(operation_url, headers=headers)
+            try:
+                with urllib.request.urlopen(
+                    poll_req, timeout=self._timeout,
+                ) as resp:
+                    result = json.loads(resp.read().decode("utf-8"))
+            except Exception as exc:
+                raise OCRAdapterError(
+                    f"{self.name} : erreur de polling Azure : "
+                    f"{type(exc).__name__}: {exc}",
+                ) from exc
+            status = result.get("status", "")
+            if status == "succeeded":
+                return self._extract_text_from_rest_result(result)
+            if status in {"failed", "canceled"}:
+                raise OCRAdapterError(
+                    f"{self.name} : analyse Azure {status} : "
+                    f"{result.get('error', {})}",
+                )
+            # running → continue
+        raise OCRAdapterError(
+            f"{self.name} : timeout polling Azure après "
+            f"{self._max_polling_attempts} tentatives.",
+        )
+
+    @staticmethod
+    def _extract_text_from_rest_result(result: dict) -> str:
+        pages = result.get("analyzeResult", {}).get("pages", [])
+        lines: list[str] = []
+        for page in pages:
+            for line in page.get("lines", []):
+                content = line.get("content", "")
+                if content:
+                    lines.append(content)
+        return "\n".join(lines)
+
+
+class _SDKMissing(Exception):
+    """Sentinel interne pour signaler que le SDK Azure n'est pas
+    installé.  Capturé par ``execute`` pour fallback REST.
+
+    Ne fuit jamais au caller — c'est un détail d'implémentation.
+    """
+
+
+__all__ = ["AzureDocIntelAdapter"]

tests/adapters/ocr/test_sprint_a14_s34_azure_doc_intel_adapter.py

@@ -0,0 +1,536 @@
+"""Sprint A14-S34 — ``AzureDocIntelAdapter`` natif au contrat S26."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from picarones.adapters.ocr import (
+    AzureDocIntelAdapter,
+    BaseOCRAdapter,
+    OCRAdapterError,
+)
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.pipeline.types import RunContext
+
+
+def _make_image_artifact(uri: str) -> Artifact:
+    return Artifact(
+        id="d1:img",
+        document_id="d1",
+        type=ArtifactType.IMAGE,
+        uri=uri,
+    )
+
+
+def _make_context() -> RunContext:
+    return RunContext(
+        document_id="d1",
+        code_version="1.0.0",
+        pipeline_name="test",
+    )
+
+
+def _make_dummy_image(tmp_path: Path) -> Path:
+    path = tmp_path / "page.png"
+    path.write_bytes(b"PNG_FAKE_BYTES")
+    return path
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Constructeur
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelConstructor:
+    def test_defaults(self) -> None:
+        adapter = AzureDocIntelAdapter()
+        assert adapter.name == "azure_doc_intel"
+        assert adapter.model_id == "prebuilt-read"
+
+    def test_custom_name(self) -> None:
+        adapter = AzureDocIntelAdapter(name="my_azure")
+        assert adapter.name == "my_azure"
+
+    def test_custom_model_id(self) -> None:
+        adapter = AzureDocIntelAdapter(model_id="prebuilt-document")
+        assert adapter.model_id == "prebuilt-document"
+
+    def test_rejects_empty_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="vide"):
+            AzureDocIntelAdapter(name="")
+
+    def test_rejects_invalid_chars_in_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="invalide"):
+            AzureDocIntelAdapter(name="bad name")
+
+    def test_rejects_non_positive_timeout(self) -> None:
+        with pytest.raises(OCRAdapterError, match="timeout_seconds"):
+            AzureDocIntelAdapter(timeout_seconds=0)
+
+    def test_rejects_non_positive_max_polling(self) -> None:
+        with pytest.raises(OCRAdapterError, match="max_polling_attempts"):
+            AzureDocIntelAdapter(max_polling_attempts=0)
+
+    def test_rejects_negative_polling_interval(self) -> None:
+        with pytest.raises(OCRAdapterError, match="polling_interval_base"):
+            AzureDocIntelAdapter(polling_interval_base=-1.0)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Contrat BaseOCRAdapter
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelContract:
+    def test_inherits_base_adapter(self) -> None:
+        adapter = AzureDocIntelAdapter()
+        assert isinstance(adapter, BaseOCRAdapter)
+
+    def test_input_types(self) -> None:
+        assert AzureDocIntelAdapter.input_types == frozenset(
+            {ArtifactType.IMAGE},
+        )
+
+    def test_output_types(self) -> None:
+        assert AzureDocIntelAdapter.output_types == frozenset(
+            {ArtifactType.RAW_TEXT},
+        )
+
+    def test_execution_mode_is_io(self) -> None:
+        assert AzureDocIntelAdapter.execution_mode == "io"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Auth resolution
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelAuth:
+    def test_explicit_api_key_takes_priority(self) -> None:
+        adapter = AzureDocIntelAdapter(api_key="explicit")
+        with patch.dict("os.environ", {"AZURE_DOC_INTEL_KEY": "env"}):
+            assert adapter._resolve_api_key() == "explicit"
+
+    def test_env_api_key_fallback(self) -> None:
+        adapter = AzureDocIntelAdapter()
+        with patch.dict("os.environ", {"AZURE_DOC_INTEL_KEY": "env_key"}):
+            assert adapter._resolve_api_key() == "env_key"
+
+    def test_no_api_key_raises(self) -> None:
+        adapter = AzureDocIntelAdapter()
+        with patch.dict("os.environ", {}, clear=True):
+            with pytest.raises(OCRAdapterError, match="AZURE_DOC_INTEL_KEY"):
+                adapter._resolve_api_key()
+
+    def test_explicit_endpoint_takes_priority(self) -> None:
+        adapter = AzureDocIntelAdapter(endpoint="https://explicit.azure.com")
+        with patch.dict(
+            "os.environ", {"AZURE_DOC_INTEL_ENDPOINT": "https://env.azure.com"},
+        ):
+            assert adapter._resolve_endpoint() == "https://explicit.azure.com"
+
+    def test_env_endpoint_fallback(self) -> None:
+        adapter = AzureDocIntelAdapter()
+        with patch.dict(
+            "os.environ", {"AZURE_DOC_INTEL_ENDPOINT": "https://env.azure.com/"},
+        ):
+            # Note : .rstrip("/") supprime le trailing slash.
+            assert adapter._resolve_endpoint() == "https://env.azure.com"
+
+    def test_no_endpoint_raises(self) -> None:
+        adapter = AzureDocIntelAdapter()
+        with patch.dict("os.environ", {}, clear=True):
+            with pytest.raises(
+                OCRAdapterError, match="AZURE_DOC_INTEL_ENDPOINT",
+            ):
+                adapter._resolve_endpoint()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Input validation
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelInputValidation:
+    def test_missing_image_input_raises(self) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="x", endpoint="https://test.azure.com",
+        )
+        with pytest.raises(OCRAdapterError, match="IMAGE manquant"):
+            adapter.execute(inputs={}, params={}, context=_make_context())
+
+    def test_image_artifact_without_uri_raises(self) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="x", endpoint="https://test.azure.com",
+        )
+        artifact = Artifact(
+            id="d1:img",
+            document_id="d1",
+            type=ArtifactType.IMAGE,
+            uri=None,
+        )
+        with pytest.raises(OCRAdapterError, match="sans URI"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_image_path_does_not_exist_raises(self) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="x", endpoint="https://test.azure.com",
+        )
+        artifact = _make_image_artifact("/nonexistent/img.png")
+        with pytest.raises(OCRAdapterError, match="introuvable"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# REST path
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelREST:
+    def _patch_no_sdk(self):
+        """Mock le SDK Azure comme absent → fallback REST."""
+        return patch.dict(sys.modules, {
+            "azure.ai.documentintelligence": None,
+            "azure.core.credentials": None,
+        })
+
+    def _make_initial_response(self):
+        """Mock initial POST response retournant Operation-Location."""
+        mock_resp = MagicMock()
+        mock_resp.headers = {"Operation-Location": "https://op-status-url"}
+        mock_resp.__enter__.return_value = mock_resp
+        return mock_resp
+
+    def _make_polling_response(self, status: str, text_lines: list[str] | None = None):
+        """Mock polling response avec le status donné."""
+        result = {"status": status}
+        if status == "succeeded":
+            result["analyzeResult"] = {
+                "pages": [{
+                    "lines": [{"content": line} for line in (text_lines or [])],
+                }],
+            }
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps(result).encode("utf-8")
+        mock_resp.__enter__.return_value = mock_resp
+        return mock_resp
+
+    def test_succeeded_returns_text(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,  # pas de sleep dans les tests
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        initial = self._make_initial_response()
+        succeeded = self._make_polling_response(
+            "succeeded", text_lines=["Ligne 1", "Ligne 2"],
+        )
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[initial, succeeded],
+        ):
+            result = adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+        out_text = Path(result[ArtifactType.RAW_TEXT].uri).read_text(
+            encoding="utf-8",
+        )
+        assert out_text == "Ligne 1\nLigne 2"
+
+    def test_running_then_succeeded(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[
+                self._make_initial_response(),
+                self._make_polling_response("running"),
+                self._make_polling_response("running"),
+                self._make_polling_response(
+                    "succeeded", text_lines=["Done"],
+                ),
+            ],
+        ):
+            result = adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+        out_text = Path(result[ArtifactType.RAW_TEXT].uri).read_text(
+            encoding="utf-8",
+        )
+        assert out_text == "Done"
+
+    def test_failed_status_raises(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[
+                self._make_initial_response(),
+                self._make_polling_response("failed"),
+            ],
+        ):
+            with pytest.raises(OCRAdapterError, match="failed"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+    def test_canceled_status_raises(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[
+                self._make_initial_response(),
+                self._make_polling_response("canceled"),
+            ],
+        ):
+            with pytest.raises(OCRAdapterError, match="canceled"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+    def test_polling_timeout_raises(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+            max_polling_attempts=2,
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[
+                self._make_initial_response(),
+                self._make_polling_response("running"),
+                self._make_polling_response("running"),
+            ],
+        ):
+            with pytest.raises(OCRAdapterError, match="timeout polling"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+    def test_no_operation_location_raises(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        # Initial POST sans Operation-Location.
+        bad_initial = MagicMock()
+        bad_initial.headers = {}
+        bad_initial.__enter__.return_value = bad_initial
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[bad_initial],
+        ):
+            with pytest.raises(OCRAdapterError, match="Operation-Location"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+    def test_writes_to_stem_name_pattern(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+            name="my_azure",
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with self._patch_no_sdk(), patch(
+            "urllib.request.urlopen",
+            side_effect=[
+                self._make_initial_response(),
+                self._make_polling_response("succeeded", text_lines=["x"]),
+            ],
+        ):
+            result = adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+        out_path = Path(result[ArtifactType.RAW_TEXT].uri)
+        assert out_path.name == "page.my_azure.txt"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# SDK path
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelSDK:
+    def test_sdk_call_succeeds(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        # Mock du résultat SDK avec pages.lines.content.
+        mock_line_a = MagicMock()
+        mock_line_a.content = "Ligne A"
+        mock_line_b = MagicMock()
+        mock_line_b.content = "Ligne B"
+        mock_page = MagicMock()
+        mock_page.lines = [mock_line_a, mock_line_b]
+        mock_result = MagicMock()
+        mock_result.pages = [mock_page]
+
+        mock_poller = MagicMock()
+        mock_poller.result.return_value = mock_result
+        mock_client = MagicMock()
+        mock_client.begin_analyze_document.return_value = mock_poller
+
+        fake_di_module = MagicMock()
+        fake_di_module.DocumentIntelligenceClient = MagicMock(
+            return_value=mock_client,
+        )
+        fake_creds_module = MagicMock()
+        fake_creds_module.AzureKeyCredential = MagicMock(return_value="creds")
+
+        with patch.dict(sys.modules, {
+            "azure": MagicMock(),
+            "azure.ai": MagicMock(),
+            "azure.ai.documentintelligence": fake_di_module,
+            "azure.core": MagicMock(),
+            "azure.core.credentials": fake_creds_module,
+        }):
+            result = adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+        out_text = Path(result[ArtifactType.RAW_TEXT].uri).read_text(
+            encoding="utf-8",
+        )
+        assert out_text == "Ligne A\nLigne B"
+
+    def test_sdk_internal_error_wrapped(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        mock_client = MagicMock()
+        mock_client.begin_analyze_document.side_effect = RuntimeError(
+            "Azure boom",
+        )
+
+        fake_di_module = MagicMock()
+        fake_di_module.DocumentIntelligenceClient = MagicMock(
+            return_value=mock_client,
+        )
+        fake_creds_module = MagicMock()
+        fake_creds_module.AzureKeyCredential = MagicMock(return_value="creds")
+
+        with patch.dict(sys.modules, {
+            "azure": MagicMock(),
+            "azure.ai": MagicMock(),
+            "azure.ai.documentintelligence": fake_di_module,
+            "azure.core": MagicMock(),
+            "azure.core.credentials": fake_creds_module,
+        }):
+            with pytest.raises(OCRAdapterError, match="RuntimeError.*Azure boom"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Artifact ID
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestAzureDocIntelArtifactID:
+    def test_artifact_id_uses_adapter_name(self, tmp_path: Path) -> None:
+        adapter = AzureDocIntelAdapter(
+            api_key="k", endpoint="https://e.azure.com",
+            polling_interval_base=0,
+            name="custom_az",
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        mock_resp_initial = MagicMock()
+        mock_resp_initial.headers = {"Operation-Location": "https://op"}
+        mock_resp_initial.__enter__.return_value = mock_resp_initial
+
+        result_payload = {
+            "status": "succeeded",
+            "analyzeResult": {
+                "pages": [{"lines": [{"content": "x"}]}],
+            },
+        }
+        mock_resp_polling = MagicMock()
+        mock_resp_polling.read.return_value = json.dumps(
+            result_payload,
+        ).encode("utf-8")
+        mock_resp_polling.__enter__.return_value = mock_resp_polling
+
+        with patch.dict(sys.modules, {
+            "azure.ai.documentintelligence": None,
+            "azure.core.credentials": None,
+        }), patch(
+            "urllib.request.urlopen",
+            side_effect=[mock_resp_initial, mock_resp_polling],
+        ):
+            result = adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+        produced = result[ArtifactType.RAW_TEXT]
+        assert produced.id == "d1:custom_az:raw_text"
+        assert produced.document_id == "d1"
+        assert produced.produced_by_step == "ocr"