feat(adapters/ocr): Sprint A14-S32 — MistralOCRAdapter natif (no shim)

Migration native du legacy picarones.engines.mistral_ocr vers le contrat
BaseOCRAdapter (S26). Pas un shim : implémente directement le contrat du
nouveau monde.

picarones/adapters/ocr/mistral_ocr.py
-------------------------------------
- MistralOCRAdapter(BaseOCRAdapter) — direct hérite, pas de shim.
- input_types = {IMAGE}, output_types = {RAW_TEXT}, execution_mode = "io"
(appels HTTP, ThreadPool dans le runner).
- Constructeur kwargs-only : name, model (défaut mistral-ocr-latest),
prompt, max_tokens, api_key (override de MISTRAL_API_KEY env var),
timeout_seconds. Validation stricte au constructeur.
- Routing automatique selon model :
· mistral-ocr-* → POST /v1/ocr via urllib (endpoint dédié, retourne
pages structurées en markdown) ;
· pixtral-* → API chat/vision via SDK mistralai (texte transcrit
par message du LLM).
- _resolve_api_key() : explicite > env var > OCRAdapterError.
- _encode_image() : détection MIME selon extension (png/jpg/tif/webp,
fallback jpeg pour les inconnues), base64 + data URI.
- execute() : valide IMAGE input + URI + fichier ; route selon model ;
écrit dans <stem>.<name>.txt à côté de l'image ; retourne Artifact
RAW_TEXT.
- Erreurs HTTP/SDK wrappées dans OCRAdapterError avec type+message.
- SDK mistralai absent → OCRAdapterError clair avec pip install.

Tests S32 dédiés (28 nouveaux)
------------------------------
- Constructor : defaults, custom name/model, rejet name vide/invalide,
rejet max_tokens et timeout_seconds non-positifs.
- Contract : isinstance BaseOCRAdapter, input/output_types,
execution_mode = "io".
- ApiKey : explicite prend priorité, env utilisé sans explicite, pas de
clé → OCRAdapterError.
- Encoding : png → image/png, jpg → image/jpeg, extension inconnue →
défaut jpeg.
- InputValidation : IMAGE absent, sans URI, image inexistante, pas de
clé API → tous OCRAdapterError.
- NativeAPI : concatène pages markdown avec \n\n, écrit à
<stem>.<name>.txt, ConnectionError → OCRAdapterError wrappé.
- VisionAPI : pixtral-* route vers chat/vision SDK, SDK manquant →
OCRAdapterError, RuntimeError SDK → OCRAdapterError wrappé.
- ArtifactID : utilise adapter name dans id "<doc>:<name>:raw_text".

Pas de confidences pour S32
---------------------------
Confidences (legacy S49 cascade pages.{words,lines,blocks}.confidence)
reportées au sprint dédié ConfidenceArtifact.

Tests : 4671 passed, 11 skipped (vs 4643 avant : +28 S32).
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**: ~4660 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/ocr/__init__.py

@@ -20,6 +20,7 @@ dédiés, **natifs** au nouveau contrat (pas de shim sur le legacy
 from __future__ import annotations
 
 from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.ocr.mistral_ocr import MistralOCRAdapter
 from picarones.adapters.ocr.pero_ocr import PeroOCRAdapter
 from picarones.adapters.ocr.precomputed import PrecomputedTextAdapter
 from picarones.adapters.ocr.tesseract import TesseractAdapter
@@ -27,6 +28,7 @@ from picarones.adapters.ocr.tesseract import TesseractAdapter
 __all__ = [
     "BaseOCRAdapter",
     "OCRAdapterError",
+    "MistralOCRAdapter",
     "PeroOCRAdapter",
     "PrecomputedTextAdapter",
     "TesseractAdapter",

picarones/adapters/ocr/mistral_ocr.py

@@ -0,0 +1,312 @@
+"""``MistralOCRAdapter`` natif — Sprint A14-S32.
+
+Migration native du legacy ``picarones.engines.mistral_ocr.MistralOCREngine``
+vers le contrat ``BaseOCRAdapter`` (S26).  **Pas un shim** : la classe
+implémente directement le contrat du nouveau monde.
+
+Le legacy ``MistralOCREngine`` reste en place jusqu'au S46.
+
+Cas d'usage BnF
+---------------
+Mistral AI fournit deux familles d'OCR :
+
+- **API dédiée ``/v1/ocr``** pour les modèles ``mistral-ocr-*`` —
+  endpoint optimisé qui renvoie des pages structurées en markdown
+  (et parfois des confidences mot par mot).
+- **API vision/chat** pour les modèles ``pixtral-*`` —
+  reconnaissance via prompt textuel + image base64.
+
+L'adapter route automatiquement selon le nom du modèle.
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"mistral_ocr"``) : identifiant de l'instance.
+- ``model`` (défaut ``"mistral-ocr-latest"``) : modèle Mistral.
+  - ``mistral-ocr-*`` → endpoint dédié ;
+  - ``pixtral-*`` → API vision/chat.
+- ``prompt`` : texte du prompt pour les modèles vision.  Défaut :
+  instruction générique de transcription.
+- ``max_tokens`` (défaut 4096) : limite tokens en sortie pour les
+  modèles vision.
+- ``api_key`` : clé API Mistral.  Si ``None`` (défaut), lit la
+  variable d'environnement ``MISTRAL_API_KEY``.
+- ``timeout_seconds`` (défaut 60) : timeout HTTP pour ``urllib``.
+
+Comportement
+------------
+1. Vérifie présence d'un ``Artifact`` ``IMAGE`` avec URI valide.
+2. Encode l'image en base64 + détecte ``image/...`` MIME selon
+   l'extension.
+3. Route vers ``/v1/ocr`` ou chat/vision selon ``model``.
+4. Concatène le markdown / texte de toutes les pages.
+5. Écrit dans ``<stem>.<name>.txt`` à côté de l'image.
+6. Retourne un ``Artifact`` ``RAW_TEXT``.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de retry / backoff (le caller wrappe si besoin).
+- Pas d'extraction de confidences (legacy S49 — reportées au
+  sprint ``ConfidenceArtifact``).
+- Pas de support multi-page (l'image est traitée comme une seule
+  page d'entrée — Mistral OCR retourne une liste de pages dont on
+  concatène les markdowns).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+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
+
+
+_DEFAULT_PROMPT = (
+    "Transcris fidèlement le texte visible sur cette image de document "
+    "historique. Retourne uniquement le texte, sans commentaire."
+)
+
+
+_MEDIA_TYPES: dict[str, str] = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".webp": "image/webp",
+}
+
+
+class MistralOCRAdapter(BaseOCRAdapter):
+    """Adapter Mistral OCR natif au contrat S26.
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible.  Défaut ``"mistral_ocr"``.
+    model:
+        Modèle Mistral.  ``mistral-ocr-*`` → API dédiée ``/v1/ocr``,
+        ``pixtral-*`` → API vision/chat.  Défaut ``"mistral-ocr-latest"``.
+    prompt:
+        Prompt pour les modèles vision.
+    max_tokens:
+        Limite tokens en sortie pour les modèles vision.  Défaut 4096.
+    api_key:
+        Clé API Mistral.  Si ``None`` (défaut), lit
+        ``MISTRAL_API_KEY``.
+    timeout_seconds:
+        Timeout HTTP pour les appels ``urllib``.  Défaut 60.
+
+    Raises
+    ------
+    OCRAdapterError
+        Si ``name`` est invalide au constructeur.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        name: str = "mistral_ocr",
+        model: str = "mistral-ocr-latest",
+        prompt: str = _DEFAULT_PROMPT,
+        max_tokens: int = 4096,
+        api_key: str | None = None,
+        timeout_seconds: float = 60.0,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "MistralOCRAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"MistralOCRAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if max_tokens <= 0:
+            raise OCRAdapterError(
+                f"MistralOCRAdapter : max_tokens doit être > 0, "
+                f"reçu {max_tokens}.",
+            )
+        if timeout_seconds <= 0:
+            raise OCRAdapterError(
+                f"MistralOCRAdapter : timeout_seconds doit être > 0, "
+                f"reçu {timeout_seconds}.",
+            )
+        self._name = name
+        self._model = model
+        self._prompt = prompt
+        self._max_tokens = max_tokens
+        self._explicit_api_key = api_key
+        self._timeout = timeout_seconds
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    def _resolve_api_key(self) -> str:
+        """Résout la clé API : explicite > env var.
+
+        Lève ``OCRAdapterError`` si aucune clé n'est disponible.
+        """
+        key = self._explicit_api_key or os.environ.get("MISTRAL_API_KEY")
+        if not key:
+            raise OCRAdapterError(
+                f"{self.name} : clé API Mistral manquante. "
+                "Définir MISTRAL_API_KEY ou passer api_key= au "
+                "constructeur.",
+            )
+        return key
+
+    def _encode_image(self, image_path: Path) -> str:
+        """Retourne ``data:<mime>;base64,<...>`` pour l'image."""
+        suffix = image_path.suffix.lower()
+        media_type = _MEDIA_TYPES.get(suffix, "image/jpeg")
+        image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+        return f"data:{media_type};base64,{image_b64}"
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute Mistral OCR sur l'image fournie.
+
+        Route vers l'API appropriée selon ``self.model`` :
+        - ``mistral-ocr-*`` → ``/v1/ocr`` via ``urllib`` ;
+        - ``pixtral-*`` → API chat/vision via SDK ``mistralai``.
+
+        Raises
+        ------
+        OCRAdapterError
+            Erreur d'input, clé manquante, SDK absent (pour pixtral),
+            ou API Mistral en erreur.
+        """
+        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()
+        image_url = self._encode_image(image_path)
+
+        if "mistral-ocr" in self._model.lower():
+            text = self._call_native_ocr_api(image_url, api_key)
+        else:
+            text = self._call_chat_vision_api(image_url, 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),
+            ),
+        }
+
+    # ──────────────────────────────────────────────────────────────
+    # API natives
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_native_ocr_api(self, image_url: str, api_key: str) -> str:
+        """Appelle ``POST /v1/ocr`` via urllib et retourne le markdown
+        concaténé."""
+        payload = json.dumps({
+            "model": self._model,
+            "document": {"type": "image_url", "image_url": image_url},
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            "https://api.mistral.ai/v1/ocr",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                data = json.loads(resp.read().decode())
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Mistral /v1/ocr : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+        pages = data.get("pages", [])
+        text = "\n\n".join(p.get("markdown", "") for p in pages).strip()
+        return text
+
+    def _call_chat_vision_api(self, image_url: str, api_key: str) -> str:
+        """Appelle l'API chat/vision Mistral via le SDK ``mistralai``."""
+        try:
+            try:
+                from mistralai.client import Mistral
+            except ImportError:
+                from mistralai import Mistral  # type: ignore[no-redef]
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : SDK 'mistralai' non installé. "
+                "Installer avec : pip install mistralai",
+            ) from exc
+
+        client = Mistral(api_key=api_key)
+        try:
+            response = client.chat.complete(
+                model=self._model,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": [
+                            {"type": "text", "text": self._prompt},
+                            {"type": "image_url", "image_url": image_url},
+                        ],
+                    },
+                ],
+                max_tokens=self._max_tokens,
+            )
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Mistral chat : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+
+        try:
+            return response.choices[0].message.content or ""
+        except (AttributeError, IndexError) as exc:
+            raise OCRAdapterError(
+                f"{self.name} : réponse Mistral chat malformée : {exc}",
+            ) from exc
+
+
+__all__ = ["MistralOCRAdapter"]

tests/adapters/ocr/test_sprint_a14_s32_mistral_ocr_adapter.py

@@ -0,0 +1,390 @@
+"""Sprint A14-S32 — ``MistralOCRAdapter`` natif au contrat S26."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from picarones.adapters.ocr import (
+    BaseOCRAdapter,
+    MistralOCRAdapter,
+    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:initial:image",
+        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"\x89PNG\r\n\x1a\nfakeimagebytes")
+    return path
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Constructeur
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRAdapterConstructor:
+    def test_defaults(self) -> None:
+        adapter = MistralOCRAdapter()
+        assert adapter.name == "mistral_ocr"
+        assert adapter.model == "mistral-ocr-latest"
+
+    def test_custom_name(self) -> None:
+        adapter = MistralOCRAdapter(name="my_mistral")
+        assert adapter.name == "my_mistral"
+
+    def test_custom_model(self) -> None:
+        adapter = MistralOCRAdapter(model="pixtral-12b-2409")
+        assert adapter.model == "pixtral-12b-2409"
+
+    def test_rejects_empty_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="vide"):
+            MistralOCRAdapter(name="")
+
+    def test_rejects_invalid_chars_in_name(self) -> None:
+        with pytest.raises(OCRAdapterError, match="invalide"):
+            MistralOCRAdapter(name="bad name")
+
+    def test_rejects_non_positive_max_tokens(self) -> None:
+        with pytest.raises(OCRAdapterError, match="max_tokens"):
+            MistralOCRAdapter(max_tokens=0)
+        with pytest.raises(OCRAdapterError, match="max_tokens"):
+            MistralOCRAdapter(max_tokens=-1)
+
+    def test_rejects_non_positive_timeout(self) -> None:
+        with pytest.raises(OCRAdapterError, match="timeout_seconds"):
+            MistralOCRAdapter(timeout_seconds=0)
+        with pytest.raises(OCRAdapterError, match="timeout_seconds"):
+            MistralOCRAdapter(timeout_seconds=-1.0)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Contrat BaseOCRAdapter
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRAdapterContract:
+    def test_inherits_base_adapter(self) -> None:
+        adapter = MistralOCRAdapter()
+        assert isinstance(adapter, BaseOCRAdapter)
+
+    def test_input_types(self) -> None:
+        assert MistralOCRAdapter.input_types == frozenset({ArtifactType.IMAGE})
+
+    def test_output_types(self) -> None:
+        assert MistralOCRAdapter.output_types == frozenset({ArtifactType.RAW_TEXT})
+
+    def test_execution_mode_is_io(self) -> None:
+        """Mistral OCR fait des appels HTTP — IO-bound, ThreadPool."""
+        assert MistralOCRAdapter.execution_mode == "io"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# API key resolution
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRApiKey:
+    def test_explicit_key_takes_priority(self) -> None:
+        adapter = MistralOCRAdapter(api_key="explicit_key")
+        # Mock l'env pour s'assurer qu'on n'utilise pas la valeur env.
+        with patch.dict("os.environ", {"MISTRAL_API_KEY": "env_key"}):
+            assert adapter._resolve_api_key() == "explicit_key"
+
+    def test_env_key_used_when_no_explicit(self) -> None:
+        adapter = MistralOCRAdapter()
+        with patch.dict("os.environ", {"MISTRAL_API_KEY": "env_key"}):
+            assert adapter._resolve_api_key() == "env_key"
+
+    def test_no_key_raises(self) -> None:
+        adapter = MistralOCRAdapter()
+        # Vide l'env de MISTRAL_API_KEY.
+        with patch.dict("os.environ", {}, clear=True):
+            with pytest.raises(OCRAdapterError, match="MISTRAL_API_KEY"):
+                adapter._resolve_api_key()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Encoding
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCREncoding:
+    def test_png_extension_yields_png_mime(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter()
+        image_path = _make_dummy_image(tmp_path)
+        encoded = adapter._encode_image(image_path)
+        assert encoded.startswith("data:image/png;base64,")
+
+    def test_jpg_extension_yields_jpeg_mime(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter()
+        path = tmp_path / "img.jpg"
+        path.write_bytes(b"jpegbytes")
+        encoded = adapter._encode_image(path)
+        assert encoded.startswith("data:image/jpeg;base64,")
+
+    def test_unknown_extension_defaults_to_jpeg(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter()
+        path = tmp_path / "img.xyz"
+        path.write_bytes(b"random")
+        encoded = adapter._encode_image(path)
+        assert encoded.startswith("data:image/jpeg;base64,")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Input validation
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRInputValidation:
+    def test_missing_image_input_raises(self) -> None:
+        adapter = MistralOCRAdapter(api_key="x")
+        with pytest.raises(OCRAdapterError, match="IMAGE manquant"):
+            adapter.execute(inputs={}, params={}, context=_make_context())
+
+    def test_image_artifact_without_uri_raises(self) -> None:
+        adapter = MistralOCRAdapter(api_key="x")
+        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 = MistralOCRAdapter(api_key="x")
+        artifact = _make_image_artifact("/nonexistent/img.png")
+        with pytest.raises(OCRAdapterError, match="introuvable"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+
+    def test_no_api_key_raises(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter()  # pas d'api_key explicite
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+        with patch.dict("os.environ", {}, clear=True):
+            with pytest.raises(OCRAdapterError, match="MISTRAL_API_KEY"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# /v1/ocr API (mistral-ocr-* models)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRNativeAPI:
+    def _mock_urlopen_ok(self, response_json: dict):
+        """Helper : retourne un context manager qui mock urlopen."""
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = repr(response_json).encode()
+        # On ne peut pas json.dumps un dict avec json.dumps directement
+        # à cause du repr ; on encode proprement.
+        import json as _json
+        mock_resp.read.return_value = _json.dumps(response_json).encode()
+        mock_resp.__enter__.return_value = mock_resp
+        return patch("urllib.request.urlopen", return_value=mock_resp)
+
+    def test_native_api_concatenates_pages(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter(api_key="x")
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        response_json = {
+            "pages": [
+                {"markdown": "Page 1 contenu"},
+                {"markdown": "Page 2 contenu"},
+            ],
+        }
+
+        with self._mock_urlopen_ok(response_json):
+            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 == "Page 1 contenu\n\nPage 2 contenu"
+
+    def test_native_api_writes_to_stem_name_pattern(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter(api_key="x", name="my_mistral")
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with self._mock_urlopen_ok({"pages": [{"markdown": "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_mistral.txt"
+
+    def test_native_api_raises_on_http_error(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter(api_key="x")
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with patch(
+            "urllib.request.urlopen",
+            side_effect=ConnectionError("API down"),
+        ):
+            with pytest.raises(OCRAdapterError, match="ConnectionError"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Vision/chat API (pixtral-* models)
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRVisionAPI:
+    def test_pixtral_routes_to_vision_api(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter(
+            api_key="x",
+            model="pixtral-12b-2409",
+        )
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        # Mock le SDK mistralai.
+        mock_message = MagicMock()
+        mock_message.content = "Texte transcrit par pixtral."
+        mock_choice = MagicMock(message=mock_message)
+        mock_response = MagicMock()
+        mock_response.choices = [mock_choice]
+
+        mock_client = MagicMock()
+        mock_client.chat.complete.return_value = mock_response
+
+        fake_module = MagicMock()
+        fake_module.Mistral = MagicMock(return_value=mock_client)
+        fake_client_module = MagicMock()
+        fake_client_module.Mistral = fake_module.Mistral
+
+        with patch.dict(sys.modules, {
+            "mistralai": fake_module,
+            "mistralai.client": fake_client_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 == "Texte transcrit par pixtral."
+
+    def test_pixtral_sdk_missing_raises_clean_error(
+        self, tmp_path: Path,
+    ) -> None:
+        adapter = MistralOCRAdapter(api_key="x", model="pixtral-12b")
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        with patch.dict(sys.modules, {
+            "mistralai": None,
+            "mistralai.client": None,
+        }):
+            with pytest.raises(OCRAdapterError, match="mistralai"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+    def test_pixtral_api_error_wrapped(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter(api_key="x", model="pixtral-12b")
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        mock_client = MagicMock()
+        mock_client.chat.complete.side_effect = RuntimeError("API error")
+
+        fake_module = MagicMock()
+        fake_module.Mistral = MagicMock(return_value=mock_client)
+        fake_client_module = MagicMock()
+        fake_client_module.Mistral = fake_module.Mistral
+
+        with patch.dict(sys.modules, {
+            "mistralai": fake_module,
+            "mistralai.client": fake_client_module,
+        }):
+            with pytest.raises(OCRAdapterError, match="RuntimeError.*API error"):
+                adapter.execute(
+                    inputs={ArtifactType.IMAGE: artifact},
+                    params={},
+                    context=_make_context(),
+                )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Artifact ID
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestMistralOCRArtifactID:
+    def test_artifact_id_uses_adapter_name(self, tmp_path: Path) -> None:
+        adapter = MistralOCRAdapter(api_key="x", name="custom")
+        image_path = _make_dummy_image(tmp_path)
+        artifact = _make_image_artifact(str(image_path))
+
+        mock_resp = MagicMock()
+        import json as _json
+        mock_resp.read.return_value = _json.dumps(
+            {"pages": [{"markdown": "x"}]},
+        ).encode()
+        mock_resp.__enter__.return_value = mock_resp
+
+        with patch("urllib.request.urlopen", return_value=mock_resp):
+            result = adapter.execute(
+                inputs={ArtifactType.IMAGE: artifact},
+                params={},
+                context=_make_context(),
+            )
+        produced = result[ArtifactType.RAW_TEXT]
+        assert produced.id == "d1:custom:raw_text"
+        assert produced.document_id == "d1"
+        assert produced.produced_by_step == "ocr"