feat(domain): Sprint A14-S52 — hiérarchie d'erreurs unifiée (fix audit #7 + #11)

Avant S52 :
- BaseLLMAdapter.execute levait OCRAdapterError (sémantiquement faux).
- BaseVLMAdapter.execute levait OCRAdapterError (sémantiquement faux).
- JobStoreError héritait de Exception (un caller `except
PicaronesError` ratait silencieusement les erreurs JobStore).
- Pas de racine commune pour catcher 'toute erreur d'adapter'.

Après S52 :

picarones/domain/errors.py
--------------------------
Nouvelle classe AdapterStepError(PicaronesError) — racine commune
des 3 sous-classes d'adapter (OCR/LLM/VLM).

picarones/adapters/ocr/base.py
------------------------------
OCRAdapterError hérite désormais de AdapterStepError au lieu de
PicaronesError directement (pas de breaking change pour les callers
qui catchaient PicaronesError).

picarones/adapters/llm/base.py
------------------------------
- Nouvelle classe LLMAdapterError(AdapterStepError) exportée.
- BaseLLMAdapter.execute lève LLMAdapterError (au lieu de
OCRAdapterError importé depuis ocr.base).
- Suppression de l'import croisé ocr.base → llm.

picarones/adapters/vlm/base.py
------------------------------
- Nouvelle classe VLMAdapterError(AdapterStepError) exportée.
- BaseVLMAdapter.execute lève VLMAdapterError.

picarones/adapters/storage/job_store.py
---------------------------------------
JobStoreError hérite désormais de PicaronesError (au lieu de
Exception). Un caller `except PicaronesError` attrape désormais
les erreurs de persistance jobs.

Tests S52 (9 nouveaux)
----------------------
- TestErrorInheritance : OCR/LLM/VLM AdapterErrors héritent de
AdapterStepError ET de PicaronesError ; JobStoreError de
PicaronesError.
- TestPolymorphicCatch : except AdapterStepError attrape les 3
sous-classes ; except PicaronesError attrape tout (y compris
JobStoreError).

Migration tests existants
-------------------------
- tests/adapters/llm/test_sprint_a14_s44 : OCRAdapterError →
LLMAdapterError (4 substitutions).
- tests/adapters/vlm/test_sprint_a14_s45 : OCRAdapterError →
VLMAdapterError (4 substitutions).

Tests : 268 passed dans tests/adapters/ + tests/domain/, 0
régression.
Lint : All checks passed.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

picarones/adapters/llm/base.py

@@ -138,6 +138,22 @@ def log_http_error(
         )
 
 
+from picarones.domain.errors import AdapterStepError
+
+
+class LLMAdapterError(AdapterStepError):
+    """Erreur typée pour un échec d'adapter LLM (Sprint S52).
+
+    Hérite de ``AdapterStepError`` (commune avec OCR et VLM) → un
+    caller peut catcher ``AdapterStepError`` pour toute erreur
+    d'adapter sans connaître la sous-classe.
+
+    Avant S52, ``BaseLLMAdapter.execute`` levait ``OCRAdapterError``
+    par confusion sémantique — c'était noté dans l'audit comme issue
+    #11 (hiérarchie incohérente).
+    """
+
+
 @dataclass
 class LLMResult:
     """Résultat produit par un appel LLM."""
@@ -341,22 +357,21 @@ class BaseLLMAdapter(ABC):
         from pathlib import Path
         import base64
 
-        from picarones.adapters.ocr.base import OCRAdapterError
         from picarones.domain.artifacts import Artifact, ArtifactType
 
         if ArtifactType.RAW_TEXT not in inputs:
-            raise OCRAdapterError(
+            raise LLMAdapterError(
                 f"{self.name} : input RAW_TEXT manquant.",
             )
         text_artifact = inputs[ArtifactType.RAW_TEXT]
         if text_artifact.uri is None:
-            raise OCRAdapterError(
+            raise LLMAdapterError(
                 f"{self.name} : artefact RAW_TEXT "
                 f"{text_artifact.id!r} sans URI.",
             )
         text_path = Path(text_artifact.uri)
         if not text_path.exists():
-            raise OCRAdapterError(
+            raise LLMAdapterError(
                 f"{self.name} : fichier texte introuvable {text_path!r}.",
             )
 
@@ -379,7 +394,7 @@ class BaseLLMAdapter(ABC):
 
         result = self.complete(prompt, image_b64=image_b64)
         if not result.success:
-            raise OCRAdapterError(
+            raise LLMAdapterError(
                 f"{self.name} : LLM a échoué ({result.error}).",
             )
 
@@ -411,6 +426,7 @@ class BaseLLMAdapter(ABC):
 
 __all__ = [
     "BaseLLMAdapter",
+    "LLMAdapterError",
     "LLMResult",
     "log_http_error",
     "normalize_llm_content",

picarones/adapters/ocr/base.py

@@ -57,12 +57,17 @@ from abc import ABC, abstractmethod
 from typing import Any
 
 from picarones.domain.artifacts import Artifact, ArtifactType
-from picarones.domain.errors import PicaronesError
+from picarones.domain.errors import AdapterStepError
 
 
-class OCRAdapterError(PicaronesError):
+class OCRAdapterError(AdapterStepError):
     """Erreur typée pour un échec d'adapter OCR du nouveau monde.
 
+    Hérite de ``AdapterStepError`` (Sprint S52) qui hérite de
+    ``PicaronesError``.  Un caller peut catcher
+    ``AdapterStepError`` pour toute erreur d'adapter (OCR/LLM/VLM)
+    sans connaître la sous-classe.
+
     Le ``PipelineExecutor`` capture cette exception (et toute autre)
     et marque le step correspondant comme failed avec
     ``StepResult.error`` renseigné.  Les callers downstream

picarones/adapters/storage/job_store.py

@@ -126,8 +126,17 @@ class JobRecord:
         return self.status in _LIVE_STATUSES
 
 
-class JobStoreError(Exception):
-    """Erreur de persistance SQLite côté JobStore."""
+from picarones.domain.errors import PicaronesError
+
+
+class JobStoreError(PicaronesError):
+    """Erreur de persistance SQLite côté JobStore.
+
+    Sprint S52 : hérite désormais de ``PicaronesError`` (avant
+    héritait directement d'``Exception`` — un caller qui faisait
+    ``except PicaronesError`` ratait silencieusement les erreurs
+    JobStore).
+    """
 
 
 class JobStore:

picarones/adapters/vlm/base.py

@@ -33,12 +33,20 @@ from pathlib import Path
 from typing import Any
 
 from picarones.adapters.llm.base import BaseLLMAdapter
-from picarones.adapters.ocr.base import OCRAdapterError
 from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.domain.errors import AdapterStepError
 
 logger = logging.getLogger(__name__)
 
 
+class VLMAdapterError(AdapterStepError):
+    """Erreur typée pour un échec d'adapter VLM (Sprint S52).
+
+    Hérite de ``AdapterStepError`` (commune avec OCR et LLM).
+    Avant S52, les VLM levaient ``OCRAdapterError`` par confusion.
+    """
+
+
 class BaseVLMAdapter(BaseLLMAdapter):
     """Adapter VLM qui transcrit une IMAGE en RAW_TEXT.
 
@@ -84,18 +92,18 @@ class BaseVLMAdapter(BaseLLMAdapter):
         ``{RAW_TEXT: Artifact}``.
         """
         if ArtifactType.IMAGE not in inputs:
-            raise OCRAdapterError(
+            raise VLMAdapterError(
                 f"{self.name} : input IMAGE manquant.",
             )
         image_artifact = inputs[ArtifactType.IMAGE]
         if image_artifact.uri is None:
-            raise OCRAdapterError(
+            raise VLMAdapterError(
                 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(
+            raise VLMAdapterError(
                 f"{self.name} : image introuvable {image_path!r}.",
             )
 
@@ -109,7 +117,7 @@ class BaseVLMAdapter(BaseLLMAdapter):
 
         result = self.complete(prompt, image_b64=image_b64)
         if not result.success:
-            raise OCRAdapterError(
+            raise VLMAdapterError(
                 f"{self.name} : VLM a échoué ({result.error}).",
             )
 
@@ -134,4 +142,4 @@ class BaseVLMAdapter(BaseLLMAdapter):
         }
 
 
-__all__ = ["BaseVLMAdapter"]
+__all__ = ["BaseVLMAdapter", "VLMAdapterError"]

picarones/domain/errors.py

@@ -57,9 +57,21 @@ class CorpusSpecError(PicaronesError):
     """
 
 
+class AdapterStepError(PicaronesError):
+    """Racine commune des erreurs d'adapter (OCR / LLM / VLM) — Sprint S52.
+
+    Permet à un caller (typiquement le ``PipelineExecutor``) de
+    catcher *« toute erreur d'adapter »* sans avoir à connaître la
+    sous-classe spécifique.  Les sous-classes ``OCRAdapterError``,
+    ``LLMAdapterError``, ``VLMAdapterError`` héritent toutes de
+    ``AdapterStepError``.
+    """
+
+
 __all__ = [
     "PicaronesError",
     "ArtifactValidationError",
     "ProjectionError",
     "CorpusSpecError",
+    "AdapterStepError",
 ]

tests/adapters/llm/test_sprint_a14_s44_llm_step_executor.py

@@ -24,7 +24,7 @@ from pathlib import Path
 import pytest
 
 from picarones.adapters.llm.base import BaseLLMAdapter
-from picarones.adapters.ocr.base import OCRAdapterError
+from picarones.adapters.llm.base import LLMAdapterError
 from picarones.domain.artifacts import Artifact, ArtifactType
 from picarones.pipeline.types import RunContext
 
@@ -184,7 +184,7 @@ class TestLLMExecuteNominal:
 class TestLLMExecuteErrors:
     def test_missing_raw_text_raises(self) -> None:
         adapter = _StubLLMAdapter()
-        with pytest.raises(OCRAdapterError, match="RAW_TEXT manquant"):
+        with pytest.raises(LLMAdapterError, match="RAW_TEXT manquant"):
             adapter.execute(
                 inputs={},
                 params={},
@@ -199,7 +199,7 @@ class TestLLMExecuteErrors:
             type=ArtifactType.RAW_TEXT,
             uri=None,
         )
-        with pytest.raises(OCRAdapterError, match="sans URI"):
+        with pytest.raises(LLMAdapterError, match="sans URI"):
             adapter.execute(
                 inputs={ArtifactType.RAW_TEXT: artifact},
                 params={},
@@ -208,7 +208,7 @@ class TestLLMExecuteErrors:
 
     def test_text_path_not_existing_raises(self) -> None:
         adapter = _StubLLMAdapter()
-        with pytest.raises(OCRAdapterError, match="introuvable"):
+        with pytest.raises(LLMAdapterError, match="introuvable"):
             adapter.execute(
                 inputs={ArtifactType.RAW_TEXT: _make_text_artifact(
                     "/nonexistent/x.txt",
@@ -223,7 +223,7 @@ class TestLLMExecuteErrors:
         adapter = _StubLLMAdapter(raise_on_call=True, config={
             "max_retries": 0,  # pas de retry pour accélérer le test
         })
-        with pytest.raises(OCRAdapterError, match="LLM a échoué"):
+        with pytest.raises(LLMAdapterError, match="LLM a échoué"):
             adapter.execute(
                 inputs={ArtifactType.RAW_TEXT: _make_text_artifact(str(text_path))},
                 params={},

tests/adapters/vlm/test_sprint_a14_s45_vlm_adapters.py

@@ -11,7 +11,7 @@ from pathlib import Path
 
 import pytest
 
-from picarones.adapters.ocr.base import OCRAdapterError
+from picarones.adapters.vlm.base import VLMAdapterError
 from picarones.adapters.vlm import (
     AnthropicVLMAdapter,
     BaseVLMAdapter,
@@ -169,7 +169,7 @@ class TestVLMExecuteNominal:
 class TestVLMExecuteErrors:
     def test_missing_image_raises(self) -> None:
         adapter = _StubVLMAdapter()
-        with pytest.raises(OCRAdapterError, match="IMAGE manquant"):
+        with pytest.raises(VLMAdapterError, match="IMAGE manquant"):
             adapter.execute(inputs={}, params={}, context=_make_context())
 
     def test_image_without_uri_raises(self) -> None:
@@ -180,7 +180,7 @@ class TestVLMExecuteErrors:
             type=ArtifactType.IMAGE,
             uri=None,
         )
-        with pytest.raises(OCRAdapterError, match="sans URI"):
+        with pytest.raises(VLMAdapterError, match="sans URI"):
             adapter.execute(
                 inputs={ArtifactType.IMAGE: artifact},
                 params={},
@@ -189,7 +189,7 @@ class TestVLMExecuteErrors:
 
     def test_image_path_not_existing_raises(self) -> None:
         adapter = _StubVLMAdapter()
-        with pytest.raises(OCRAdapterError, match="introuvable"):
+        with pytest.raises(VLMAdapterError, match="introuvable"):
             adapter.execute(
                 inputs={ArtifactType.IMAGE: _make_image_artifact(
                     "/nonexistent/img.png",
@@ -202,7 +202,7 @@ class TestVLMExecuteErrors:
         image_path = tmp_path / "doc.png"
         image_path.write_bytes(b"x")
         adapter = _StubVLMAdapter(raise_on_call=True)
-        with pytest.raises(OCRAdapterError, match="VLM a échoué"):
+        with pytest.raises(VLMAdapterError, match="VLM a échoué"):
             adapter.execute(
                 inputs={ArtifactType.IMAGE: _make_image_artifact(str(image_path))},
                 params={},

tests/domain/test_sprint_a14_s52_error_hierarchy.py

@@ -0,0 +1,67 @@
+"""Sprint A14-S52 — hiérarchie d'erreurs unifiée (fix audit #7 + #11).
+
+Avant S52 :
+- LLM/VLM levaient OCRAdapterError (mauvaise classe).
+- JobStoreError héritait de Exception (pas de PicaronesError).
+- Pas de racine commune AdapterStepError pour catcher OCR+LLM+VLM.
+
+Après S52 :
+- AdapterStepError(PicaronesError) est la racine commune.
+- OCRAdapterError, LLMAdapterError, VLMAdapterError héritent.
+- JobStoreError hérite de PicaronesError.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.adapters.llm.base import LLMAdapterError
+from picarones.adapters.ocr.base import OCRAdapterError
+from picarones.adapters.storage import JobStoreError
+from picarones.adapters.vlm.base import VLMAdapterError
+from picarones.domain.errors import AdapterStepError, PicaronesError
+
+
+class TestErrorInheritance:
+    def test_ocr_inherits_adapter_step_error(self) -> None:
+        assert issubclass(OCRAdapterError, AdapterStepError)
+        assert issubclass(OCRAdapterError, PicaronesError)
+
+    def test_llm_inherits_adapter_step_error(self) -> None:
+        assert issubclass(LLMAdapterError, AdapterStepError)
+        assert issubclass(LLMAdapterError, PicaronesError)
+
+    def test_vlm_inherits_adapter_step_error(self) -> None:
+        assert issubclass(VLMAdapterError, AdapterStepError)
+        assert issubclass(VLMAdapterError, PicaronesError)
+
+    def test_jobstore_inherits_picarones_error(self) -> None:
+        # Avant S52, héritait de Exception → un caller `except
+        # PicaronesError` ratait JobStoreError.  Maintenant inclus.
+        assert issubclass(JobStoreError, PicaronesError)
+
+
+class TestPolymorphicCatch:
+    """Un caller peut catcher AdapterStepError pour gérer toute
+    erreur d'adapter sans connaître la sous-classe."""
+
+    def test_catches_ocr(self) -> None:
+        with pytest.raises(AdapterStepError):
+            raise OCRAdapterError("ocr boom")
+
+    def test_catches_llm(self) -> None:
+        with pytest.raises(AdapterStepError):
+            raise LLMAdapterError("llm boom")
+
+    def test_catches_vlm(self) -> None:
+        with pytest.raises(AdapterStepError):
+            raise VLMAdapterError("vlm boom")
+
+    def test_picarones_catches_all_adapter_errors(self) -> None:
+        for cls in (OCRAdapterError, LLMAdapterError, VLMAdapterError):
+            with pytest.raises(PicaronesError):
+                raise cls("boom")
+
+    def test_picarones_catches_jobstore(self) -> None:
+        with pytest.raises(PicaronesError):
+            raise JobStoreError("store boom")