Merge pull request #2 from maribakulj/claude/review-and-plan-r20qn

backend/app/schemas/image.py

@@ -0,0 +1,19 @@
+"""
+Schéma Pydantic pour les métadonnées du dérivé image produit par le pipeline.
+"""
+# 2. third-party
+from pydantic import BaseModel
+
+
+class ImageDerivativeInfo(BaseModel):
+    """Résultat de la normalisation d'une image : dimensions originales et chemins des dérivés."""
+
+    original_url: str
+    original_width: int
+    original_height: int
+    derivative_path: str
+    derivative_width: int
+    derivative_height: int
+    thumbnail_path: str
+    thumbnail_width: int
+    thumbnail_height: int

backend/app/schemas/model_config.py

@@ -0,0 +1,41 @@
+"""
+Schémas Pydantic pour la configuration et la découverte des modèles IA.
+"""
+# 1. stdlib
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+# 2. third-party
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProviderType(str, Enum):
+    GOOGLE_AI_STUDIO = "google_ai_studio"
+    VERTEX_API_KEY = "vertex_api_key"
+    VERTEX_SERVICE_ACCOUNT = "vertex_service_account"
+
+
+class ModelInfo(BaseModel):
+    """Décrit un modèle IA disponible chez un provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    model_id: str
+    display_name: str
+    provider: ProviderType
+    supports_vision: bool
+    input_token_limit: int | None = None
+    output_token_limit: int | None = None
+
+
+class ModelConfig(BaseModel):
+    """Configuration du modèle sélectionné pour un corpus (CLAUDE.md §9)."""
+
+    corpus_id: str
+    selected_model_id: str
+    selected_model_display_name: str
+    provider: ProviderType
+    supports_vision: bool
+    last_fetched_at: datetime
+    available_models: list[dict[str, Any]]  # cache sérialisé des ModelInfo

backend/app/services/ai/__init__.py

@@ -0,0 +1,15 @@
+"""
+Services AI — providers Google AI et registre de modèles.
+"""
+from app.services.ai.model_registry import build_model_config, list_all_models
+from app.services.ai.provider_google_ai import GoogleAIProvider
+from app.services.ai.provider_vertex_key import VertexAPIKeyProvider
+from app.services.ai.provider_vertex_sa import VertexServiceAccountProvider
+
+__all__ = [
+    "GoogleAIProvider",
+    "VertexAPIKeyProvider",
+    "VertexServiceAccountProvider",
+    "list_all_models",
+    "build_model_config",
+]

backend/app/services/ai/base.py

@@ -0,0 +1,42 @@
+"""
+Interface abstraite commune à tous les providers Google AI.
+"""
+# 1. stdlib
+from abc import ABC, abstractmethod
+from typing import Any
+
+# 2. local
+from app.schemas.model_config import ModelInfo, ProviderType
+
+
+def is_vision_model(model: Any) -> bool:
+    """Détermine si un modèle supporte les entrées image.
+
+    Les modèles Gemini sont tous multimodaux ; les modèles texte-only (ex :
+    embedding, AQA) ne contiennent pas 'gemini' dans leur identifiant.
+    """
+    name = (getattr(model, "name", "") or "").lower()
+    display = (getattr(model, "display_name", "") or "").lower()
+    return "gemini" in name or "vision" in name or "vision" in display
+
+
+class AIProvider(ABC):
+    """Interface commune à tous les providers Google AI."""
+
+    @property
+    @abstractmethod
+    def provider_type(self) -> ProviderType: ...
+
+    @abstractmethod
+    def is_configured(self) -> bool:
+        """Retourne True si les credentials nécessaires sont présents en environnement."""
+        ...
+
+    @abstractmethod
+    def list_models(self) -> list[ModelInfo]:
+        """Liste les modèles filtrés (generateContent présent dans les méthodes supportées).
+
+        Lève RuntimeError si le provider n'est pas configuré.
+        Propage les exceptions réseau/API sans les masquer.
+        """
+        ...

backend/app/services/ai/model_registry.py

@@ -0,0 +1,82 @@
+"""
+Registre agrégé des modèles disponibles tous providers confondus.
+"""
+# 1. stdlib
+import logging
+from datetime import datetime, timezone
+
+# 2. local
+from app.schemas.model_config import ModelConfig, ModelInfo
+from app.services.ai.base import AIProvider
+from app.services.ai.provider_google_ai import GoogleAIProvider
+from app.services.ai.provider_vertex_key import VertexAPIKeyProvider
+from app.services.ai.provider_vertex_sa import VertexServiceAccountProvider
+
+logger = logging.getLogger(__name__)
+
+
+def _build_providers() -> list[AIProvider]:
+    return [
+        GoogleAIProvider(),
+        VertexAPIKeyProvider(),
+        VertexServiceAccountProvider(),
+    ]
+
+
+def list_all_models() -> list[ModelInfo]:
+    """Interroge tous les providers configurés et retourne la liste agrégée.
+
+    - Un provider non configuré (credentials absentes) est silencieusement ignoré.
+    - Un provider défaillant (clé invalide, erreur réseau) logue un warning et est ignoré.
+    """
+    result: list[ModelInfo] = []
+
+    for provider in _build_providers():
+        if not provider.is_configured():
+            logger.debug(
+                "Provider non configuré, ignoré",
+                extra={"provider": provider.provider_type},
+            )
+            continue
+
+        try:
+            models = provider.list_models()
+            result.extend(models)
+            logger.info(
+                "Provider interrogé avec succès",
+                extra={"provider": provider.provider_type, "count": len(models)},
+            )
+        except Exception as exc:
+            logger.warning(
+                "Provider inaccessible",
+                extra={"provider": provider.provider_type, "error": str(exc)},
+            )
+
+    return result
+
+
+def build_model_config(corpus_id: str, selected_model_id: str) -> ModelConfig:
+    """Construit un ModelConfig à partir d'un model_id sélectionné.
+
+    Lève ValueError si le modèle n'est pas dans la liste des disponibles.
+    """
+    models = list_all_models()
+    model_map = {m.model_id: m for m in models}
+
+    if selected_model_id not in model_map:
+        available = sorted(model_map.keys())
+        raise ValueError(
+            f"Modèle '{selected_model_id}' non disponible. "
+            f"Modèles disponibles : {available}"
+        )
+
+    selected = model_map[selected_model_id]
+    return ModelConfig(
+        corpus_id=corpus_id,
+        selected_model_id=selected.model_id,
+        selected_model_display_name=selected.display_name,
+        provider=selected.provider,
+        supports_vision=selected.supports_vision,
+        last_fetched_at=datetime.now(tz=timezone.utc),
+        available_models=[m.model_dump() for m in models],
+    )

backend/app/services/ai/provider_google_ai.py

@@ -0,0 +1,55 @@
+"""
+Provider Google AI Studio — authentification via GOOGLE_AI_STUDIO_API_KEY.
+"""
+# 1. stdlib
+import logging
+import os
+
+# 2. third-party
+from google import genai
+
+# 3. local
+from app.schemas.model_config import ModelInfo, ProviderType
+from app.services.ai.base import AIProvider, is_vision_model
+
+logger = logging.getLogger(__name__)
+
+_ENV_KEY = "GOOGLE_AI_STUDIO_API_KEY"
+
+
+class GoogleAIProvider(AIProvider):
+    """Provider Google AI Studio (clé API GOOGLE_AI_STUDIO_API_KEY)."""
+
+    @property
+    def provider_type(self) -> ProviderType:
+        return ProviderType.GOOGLE_AI_STUDIO
+
+    def is_configured(self) -> bool:
+        return bool(os.environ.get(_ENV_KEY))
+
+    def list_models(self) -> list[ModelInfo]:
+        if not self.is_configured():
+            raise RuntimeError(f"Variable d'environnement manquante : {_ENV_KEY}")
+
+        client = genai.Client(api_key=os.environ[_ENV_KEY])
+        result: list[ModelInfo] = []
+
+        for model in client.models.list():
+            methods = getattr(model, "supported_generation_methods", []) or []
+            if "generateContent" not in methods:
+                continue
+
+            result.append(ModelInfo(
+                model_id=model.name,
+                display_name=getattr(model, "display_name", model.name),
+                provider=self.provider_type,
+                supports_vision=is_vision_model(model),
+                input_token_limit=getattr(model, "input_token_limit", None),
+                output_token_limit=getattr(model, "output_token_limit", None),
+            ))
+
+        logger.info(
+            "Google AI Studio models fetched",
+            extra={"provider": self.provider_type, "count": len(result)},
+        )
+        return result

backend/app/services/ai/provider_vertex_key.py

@@ -0,0 +1,59 @@
+"""
+Provider Vertex AI — authentification via clé API GCP (VERTEX_API_KEY).
+"""
+# 1. stdlib
+import logging
+import os
+
+# 2. third-party
+from google import genai
+
+# 3. local
+from app.schemas.model_config import ModelInfo, ProviderType
+from app.services.ai.base import AIProvider, is_vision_model
+
+logger = logging.getLogger(__name__)
+
+_ENV_KEY = "VERTEX_API_KEY"
+
+
+class VertexAPIKeyProvider(AIProvider):
+    """Provider Vertex AI via clé API GCP (VERTEX_API_KEY).
+
+    Utilise le SDK google-genai avec la clé GCP. La clé doit être autorisée
+    sur l'API Generative Language dans la console GCP.
+    """
+
+    @property
+    def provider_type(self) -> ProviderType:
+        return ProviderType.VERTEX_API_KEY
+
+    def is_configured(self) -> bool:
+        return bool(os.environ.get(_ENV_KEY))
+
+    def list_models(self) -> list[ModelInfo]:
+        if not self.is_configured():
+            raise RuntimeError(f"Variable d'environnement manquante : {_ENV_KEY}")
+
+        client = genai.Client(api_key=os.environ[_ENV_KEY])
+        result: list[ModelInfo] = []
+
+        for model in client.models.list():
+            methods = getattr(model, "supported_generation_methods", []) or []
+            if "generateContent" not in methods:
+                continue
+
+            result.append(ModelInfo(
+                model_id=model.name,
+                display_name=getattr(model, "display_name", model.name),
+                provider=self.provider_type,
+                supports_vision=is_vision_model(model),
+                input_token_limit=getattr(model, "input_token_limit", None),
+                output_token_limit=getattr(model, "output_token_limit", None),
+            ))
+
+        logger.info(
+            "Vertex API key models fetched",
+            extra={"provider": self.provider_type, "count": len(result)},
+        )
+        return result

backend/app/services/ai/provider_vertex_sa.py

@@ -0,0 +1,90 @@
+"""
+Provider Vertex AI — authentification via compte de service JSON (VERTEX_SERVICE_ACCOUNT_JSON).
+"""
+# 1. stdlib
+import json
+import logging
+import os
+
+# 2. third-party
+from google import genai
+from google.oauth2 import service_account
+
+# 3. local
+from app.schemas.model_config import ModelInfo, ProviderType
+from app.services.ai.base import AIProvider, is_vision_model
+
+logger = logging.getLogger(__name__)
+
+_ENV_KEY = "VERTEX_SERVICE_ACCOUNT_JSON"
+_VERTEX_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
+_DEFAULT_LOCATION = "us-central1"
+
+
+class VertexServiceAccountProvider(AIProvider):
+    """Provider Vertex AI via compte de service JSON (VERTEX_SERVICE_ACCOUNT_JSON).
+
+    Le JSON complet du compte de service est lu depuis la variable d'environnement.
+    Le project_id est extrait du JSON ; la localisation par défaut est us-central1.
+    """
+
+    @property
+    def provider_type(self) -> ProviderType:
+        return ProviderType.VERTEX_SERVICE_ACCOUNT
+
+    def is_configured(self) -> bool:
+        return bool(os.environ.get(_ENV_KEY))
+
+    def list_models(self) -> list[ModelInfo]:
+        if not self.is_configured():
+            raise RuntimeError(f"Variable d'environnement manquante : {_ENV_KEY}")
+
+        sa_json_str = os.environ[_ENV_KEY]
+        try:
+            sa_info = json.loads(sa_json_str)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"{_ENV_KEY} : JSON invalide — {exc}"
+            ) from exc
+
+        project_id: str | None = sa_info.get("project_id")
+        if not project_id:
+            raise ValueError(
+                f"{_ENV_KEY} : champ 'project_id' manquant dans le JSON"
+            )
+
+        credentials = service_account.Credentials.from_service_account_info(
+            sa_info,
+            scopes=_VERTEX_SCOPES,
+        )
+        client = genai.Client(
+            vertexai=True,
+            project=project_id,
+            location=_DEFAULT_LOCATION,
+            credentials=credentials,
+        )
+        result: list[ModelInfo] = []
+
+        for model in client.models.list():
+            methods = getattr(model, "supported_generation_methods", []) or []
+            if "generateContent" not in methods:
+                continue
+
+            result.append(ModelInfo(
+                model_id=model.name,
+                display_name=getattr(model, "display_name", model.name),
+                provider=self.provider_type,
+                supports_vision=is_vision_model(model),
+                input_token_limit=getattr(model, "input_token_limit", None),
+                output_token_limit=getattr(model, "output_token_limit", None),
+            ))
+
+        logger.info(
+            "Vertex service account models fetched",
+            extra={
+                "provider": self.provider_type,
+                "project": project_id,
+                "count": len(result),
+            },
+        )
+        return result

backend/app/services/image/__init__.py

@@ -0,0 +1,6 @@
+"""
+Services image — normalisation et production des dérivés JPEG pour le pipeline IA.
+"""
+from app.services.image.normalizer import create_derivatives, fetch_and_normalize
+
+__all__ = ["create_derivatives", "fetch_and_normalize"]

backend/app/services/image/normalizer.py

@@ -0,0 +1,145 @@
+"""
+Normalisation d'images : dérivé JPEG 1500px max + thumbnail pour le pipeline IA.
+"""
+# 1. stdlib
+import io
+import logging
+from pathlib import Path
+
+# 2. third-party
+from PIL import Image
+
+# 3. local
+from app.schemas.image import ImageDerivativeInfo
+from app.services.ingest.iiif_fetcher import fetch_iiif_image
+
+logger = logging.getLogger(__name__)
+
+# Constantes de normalisation
+_MAX_DERIVATIVE_PX = 1500   # grand côté max du dérivé envoyé à l'IA
+_MAX_THUMBNAIL_PX = 256     # grand côté max du thumbnail
+_DERIVATIVE_QUALITY = 90    # qualité JPEG dérivé
+_THUMBNAIL_QUALITY = 75     # qualité JPEG thumbnail
+
+
+def _resize_to_max(image: Image.Image, max_size: int) -> Image.Image:
+    """Redimensionne l'image pour que son grand côté vaille max_size.
+
+    Si l'image est déjà plus petite ou égale, retourne une copie sans upscaling.
+    Le ratio d'aspect est préservé. Utilise LANCZOS pour la qualité.
+    """
+    w, h = image.size
+    if max(w, h) <= max_size:
+        return image.copy()
+    if w >= h:
+        new_w = max_size
+        new_h = max(1, round(h * max_size / w))
+    else:
+        new_h = max_size
+        new_w = max(1, round(w * max_size / h))
+    return image.resize((new_w, new_h), Image.Resampling.LANCZOS)
+
+
+def create_derivatives(
+    source_bytes: bytes,
+    original_url: str,
+    corpus_slug: str,
+    folio_label: str,
+    base_data_dir: Path = Path("data"),
+) -> ImageDerivativeInfo:
+    """Produit un dérivé JPEG (1500px max) et un thumbnail depuis des bytes image.
+
+    Structure de sortie (CLAUDE.md §3) :
+      {base_data_dir}/corpora/{corpus_slug}/derivatives/{folio_label}.jpg
+      {base_data_dir}/corpora/{corpus_slug}/derivatives/{folio_label}_thumb.jpg
+
+    Args:
+        source_bytes: contenu brut de l'image source (JPEG, PNG, TIFF, etc.).
+        original_url: URL d'origine (conservée dans le schéma de sortie).
+        corpus_slug: identifiant du corpus (ex. "beatus-lat8878").
+        folio_label: identifiant du folio (ex. "0013r").
+        base_data_dir: racine du dossier data (défaut : Path("data")).
+
+    Returns:
+        ImageDerivativeInfo avec dimensions et chemins des fichiers produits.
+
+    Raises:
+        PIL.UnidentifiedImageError: si les bytes ne sont pas une image valide.
+        OSError: si l'écriture sur disque échoue.
+    """
+    image = Image.open(io.BytesIO(source_bytes))
+
+    # Convertir en RGB pour garantir un JPEG valide (PNG RGBA, palette, etc.)
+    if image.mode != "RGB":
+        image = image.convert("RGB")
+
+    original_width, original_height = image.size
+    logger.info(
+        "Image ouverte",
+        extra={
+            "corpus": corpus_slug,
+            "folio": folio_label,
+            "original_size": f"{original_width}x{original_height}",
+        },
+    )
+
+    # Dossier de sortie
+    derivatives_dir = base_data_dir / "corpora" / corpus_slug / "derivatives"
+    derivatives_dir.mkdir(parents=True, exist_ok=True)
+
+    # Dérivé IA : grand côté <= 1500px
+    deriv_image = _resize_to_max(image, _MAX_DERIVATIVE_PX)
+    derivative_width, derivative_height = deriv_image.size
+    derivative_path = derivatives_dir / f"{folio_label}.jpg"
+    deriv_image.save(derivative_path, format="JPEG", quality=_DERIVATIVE_QUALITY)
+
+    # Thumbnail : grand côté <= 256px
+    thumb_image = _resize_to_max(image, _MAX_THUMBNAIL_PX)
+    thumbnail_width, thumbnail_height = thumb_image.size
+    thumbnail_path = derivatives_dir / f"{folio_label}_thumb.jpg"
+    thumb_image.save(thumbnail_path, format="JPEG", quality=_THUMBNAIL_QUALITY)
+
+    logger.info(
+        "Dérivés produits",
+        extra={
+            "corpus": corpus_slug,
+            "folio": folio_label,
+            "derivative": f"{derivative_width}x{derivative_height}",
+            "thumbnail": f"{thumbnail_width}x{thumbnail_height}",
+        },
+    )
+
+    return ImageDerivativeInfo(
+        original_url=original_url,
+        original_width=original_width,
+        original_height=original_height,
+        derivative_path=str(derivative_path),
+        derivative_width=derivative_width,
+        derivative_height=derivative_height,
+        thumbnail_path=str(thumbnail_path),
+        thumbnail_width=thumbnail_width,
+        thumbnail_height=thumbnail_height,
+    )
+
+
+def fetch_and_normalize(
+    url: str,
+    corpus_slug: str,
+    folio_label: str,
+    base_data_dir: Path = Path("data"),
+) -> ImageDerivativeInfo:
+    """Point d'entrée principal : télécharge depuis une URL IIIF et produit les dérivés.
+
+    Chaîne fetch_iiif_image() → create_derivatives().
+
+    Args:
+        url: URL complète de l'image IIIF.
+        corpus_slug: identifiant du corpus.
+        folio_label: identifiant du folio.
+        base_data_dir: racine du dossier data.
+
+    Returns:
+        ImageDerivativeInfo rempli.
+    """
+    source_bytes = fetch_iiif_image(url)
+    return create_derivatives(source_bytes, url, corpus_slug, folio_label, base_data_dir)

backend/app/services/ingest/__init__.py

@@ -0,0 +1,6 @@
+"""
+Services d'ingestion — téléchargement de sources (IIIF, fichiers locaux).
+"""
+from app.services.ingest.iiif_fetcher import fetch_iiif_image
+
+__all__ = ["fetch_iiif_image"]

backend/app/services/ingest/iiif_fetcher.py

@@ -0,0 +1,37 @@
+"""
+Téléchargement d'images depuis des URLs IIIF via httpx.
+"""
+# 1. stdlib
+import logging
+
+# 2. third-party
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT = 60.0  # secondes — les images IIIF haute résolution peuvent être lourdes
+
+
+def fetch_iiif_image(url: str, timeout: float = _DEFAULT_TIMEOUT) -> bytes:
+    """Télécharge une image depuis une URL IIIF complète.
+
+    Args:
+        url: URL complète de l'image (ex. https://.../full/max/0/default.jpg).
+        timeout: délai maximal en secondes (défaut : 60 s).
+
+    Returns:
+        Contenu brut de l'image en bytes.
+
+    Raises:
+        httpx.HTTPStatusError: si le serveur retourne un code 4xx ou 5xx.
+        httpx.TimeoutException: si la requête dépasse le délai.
+        httpx.RequestError: pour toute autre erreur réseau.
+    """
+    logger.info("Fetching IIIF image", extra={"url": url})
+    response = httpx.get(url, follow_redirects=True, timeout=timeout)
+    response.raise_for_status()
+    logger.info(
+        "IIIF image fetched",
+        extra={"url": url, "size_bytes": len(response.content)},
+    )
+    return response.content

backend/pyproject.toml

@@ -13,7 +13,9 @@ dependencies = [
     "pydantic>=2.7",
     "sqlalchemy>=2.0",
     "aiosqlite>=0.20",
-    "google-generativeai>=0.3",
+    "google-genai>=1.0",
+    "google-auth>=2.0",
+    "httpx>=0.27",
     "lxml>=5.2",
     "Pillow>=10.3",
 ]

backend/tests/test_ai_providers.py

@@ -0,0 +1,471 @@
+"""
+Tests des providers Google AI et du registre de modèles.
+Aucun appel réseau réel — tous les clients SDK sont mockés.
+"""
+# 1. stdlib
+import json
+from datetime import datetime, timezone
+from unittest.mock import MagicMock, patch
+
+# 2. third-party
+import pytest
+from pydantic import ValidationError
+
+# 3. local
+from app.schemas.model_config import ModelConfig, ModelInfo, ProviderType
+from app.services.ai.base import is_vision_model
+from app.services.ai.model_registry import build_model_config, list_all_models
+from app.services.ai.provider_google_ai import GoogleAIProvider
+from app.services.ai.provider_vertex_key import VertexAPIKeyProvider
+from app.services.ai.provider_vertex_sa import VertexServiceAccountProvider
+
+# ---------------------------------------------------------------------------
+# Données de test partagées
+# ---------------------------------------------------------------------------
+
+FAKE_SA_JSON = {
+    "type": "service_account",
+    "project_id": "test-project-123",
+    "private_key_id": "key-abc",
+    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA\n-----END RSA PRIVATE KEY-----\n",
+    "client_email": "test-sa@test-project-123.iam.gserviceaccount.com",
+    "client_id": "123456789",
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://oauth2.googleapis.com/token",
+}
+
+
+def _make_mock_model(
+    name: str = "models/gemini-1.5-pro",
+    display_name: str = "Gemini 1.5 Pro",
+    methods: list[str] | None = None,
+    input_token_limit: int = 1_000_000,
+    output_token_limit: int = 8192,
+) -> MagicMock:
+    """Construit un objet modèle factice imitant google.genai.types.Model."""
+    m = MagicMock()
+    m.name = name
+    m.display_name = display_name
+    m.supported_generation_methods = methods if methods is not None else ["generateContent"]
+    m.input_token_limit = input_token_limit
+    m.output_token_limit = output_token_limit
+    return m
+
+
+# ---------------------------------------------------------------------------
+# Tests — ModelInfo (schéma)
+# ---------------------------------------------------------------------------
+
+def test_model_info_valid():
+    info = ModelInfo(
+        model_id="models/gemini-1.5-pro",
+        display_name="Gemini 1.5 Pro",
+        provider=ProviderType.GOOGLE_AI_STUDIO,
+        supports_vision=True,
+        input_token_limit=1_000_000,
+        output_token_limit=8192,
+    )
+    assert info.model_id == "models/gemini-1.5-pro"
+    assert info.supports_vision is True
+
+
+def test_model_info_is_frozen():
+    info = ModelInfo(
+        model_id="models/gemini-1.5-pro",
+        display_name="Gemini 1.5 Pro",
+        provider=ProviderType.GOOGLE_AI_STUDIO,
+        supports_vision=True,
+    )
+    with pytest.raises((TypeError, ValidationError)):
+        info.model_id = "changed"  # type: ignore[misc]
+
+
+def test_model_info_optional_token_limits():
+    info = ModelInfo(
+        model_id="models/gemini-2.0-flash",
+        display_name="Gemini 2.0 Flash",
+        provider=ProviderType.VERTEX_SERVICE_ACCOUNT,
+        supports_vision=True,
+    )
+    assert info.input_token_limit is None
+    assert info.output_token_limit is None
+
+
+def test_model_info_all_provider_types():
+    for ptype in ProviderType:
+        info = ModelInfo(
+            model_id=f"models/test-{ptype.value}",
+            display_name="Test",
+            provider=ptype,
+            supports_vision=False,
+        )
+        assert info.provider == ptype
+
+
+# ---------------------------------------------------------------------------
+# Tests — ModelConfig (schéma)
+# ---------------------------------------------------------------------------
+
+def test_model_config_valid():
+    cfg = ModelConfig(
+        corpus_id="corpus-001",
+        selected_model_id="models/gemini-1.5-pro",
+        selected_model_display_name="Gemini 1.5 Pro",
+        provider=ProviderType.GOOGLE_AI_STUDIO,
+        supports_vision=True,
+        last_fetched_at=datetime(2026, 3, 17, tzinfo=timezone.utc),
+        available_models=[],
+    )
+    assert cfg.corpus_id == "corpus-001"
+    assert cfg.supports_vision is True
+
+
+def test_model_config_missing_required_field():
+    with pytest.raises(ValidationError):
+        ModelConfig.model_validate({"corpus_id": "x"})
+
+
+# ---------------------------------------------------------------------------
+# Tests — is_vision_model helper
+# ---------------------------------------------------------------------------
+
+def test_is_vision_model_gemini():
+    m = MagicMock()
+    m.name = "models/gemini-1.5-pro"
+    m.display_name = "Gemini 1.5 Pro"
+    assert is_vision_model(m) is True
+
+
+def test_is_vision_model_vision_in_name():
+    m = MagicMock()
+    m.name = "models/some-vision-model"
+    m.display_name = "Some Model"
+    assert is_vision_model(m) is True
+
+
+def test_is_vision_model_vision_in_display():
+    m = MagicMock()
+    m.name = "models/some-model"
+    m.display_name = "Some Vision Model"
+    assert is_vision_model(m) is True
+
+
+def test_is_vision_model_text_only():
+    m = MagicMock()
+    m.name = "models/text-embedding-004"
+    m.display_name = "Text Embedding"
+    assert is_vision_model(m) is False
+
+
+# ---------------------------------------------------------------------------
+# Tests — GoogleAIProvider
+# ---------------------------------------------------------------------------
+
+def test_google_ai_provider_not_configured(monkeypatch):
+    monkeypatch.delenv("GOOGLE_AI_STUDIO_API_KEY", raising=False)
+    provider = GoogleAIProvider()
+    assert provider.is_configured() is False
+
+
+def test_google_ai_provider_configured(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    provider = GoogleAIProvider()
+    assert provider.is_configured() is True
+
+
+def test_google_ai_provider_type():
+    assert GoogleAIProvider().provider_type == ProviderType.GOOGLE_AI_STUDIO
+
+
+def test_google_ai_provider_list_models_not_configured(monkeypatch):
+    monkeypatch.delenv("GOOGLE_AI_STUDIO_API_KEY", raising=False)
+    with pytest.raises(RuntimeError, match="GOOGLE_AI_STUDIO_API_KEY"):
+        GoogleAIProvider().list_models()
+
+
+def test_google_ai_provider_list_models_success(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    mock_model = _make_mock_model()
+
+    with patch("app.services.ai.provider_google_ai.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = [mock_model]
+        models = GoogleAIProvider().list_models()
+
+    assert len(models) == 1
+    assert models[0].model_id == "models/gemini-1.5-pro"
+    assert models[0].provider == ProviderType.GOOGLE_AI_STUDIO
+    assert models[0].supports_vision is True
+    MockClient.assert_called_once_with(api_key="fake-key")
+
+
+def test_google_ai_provider_filters_non_generate_content(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    embedding = _make_mock_model(
+        name="models/text-embedding-004",
+        display_name="Text Embedding",
+        methods=["embedContent"],
+    )
+    gemini = _make_mock_model()
+
+    with patch("app.services.ai.provider_google_ai.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = [embedding, gemini]
+        models = GoogleAIProvider().list_models()
+
+    assert len(models) == 1
+    assert models[0].model_id == "models/gemini-1.5-pro"
+
+
+def test_google_ai_provider_empty_list(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    with patch("app.services.ai.provider_google_ai.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = []
+        models = GoogleAIProvider().list_models()
+    assert models == []
+
+
+# ---------------------------------------------------------------------------
+# Tests — VertexAPIKeyProvider
+# ---------------------------------------------------------------------------
+
+def test_vertex_key_provider_not_configured(monkeypatch):
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    assert VertexAPIKeyProvider().is_configured() is False
+
+
+def test_vertex_key_provider_configured(monkeypatch):
+    monkeypatch.setenv("VERTEX_API_KEY", "fake-vertex-key")
+    assert VertexAPIKeyProvider().is_configured() is True
+
+
+def test_vertex_key_provider_type():
+    assert VertexAPIKeyProvider().provider_type == ProviderType.VERTEX_API_KEY
+
+
+def test_vertex_key_provider_list_models_not_configured(monkeypatch):
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    with pytest.raises(RuntimeError, match="VERTEX_API_KEY"):
+        VertexAPIKeyProvider().list_models()
+
+
+def test_vertex_key_provider_list_models_success(monkeypatch):
+    monkeypatch.setenv("VERTEX_API_KEY", "fake-vertex-key")
+    mock_model = _make_mock_model(
+        name="models/gemini-2.0-flash",
+        display_name="Gemini 2.0 Flash",
+    )
+
+    with patch("app.services.ai.provider_vertex_key.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = [mock_model]
+        models = VertexAPIKeyProvider().list_models()
+
+    assert len(models) == 1
+    assert models[0].model_id == "models/gemini-2.0-flash"
+    assert models[0].provider == ProviderType.VERTEX_API_KEY
+    MockClient.assert_called_once_with(api_key="fake-vertex-key")
+
+
+# ---------------------------------------------------------------------------
+# Tests — VertexServiceAccountProvider
+# ---------------------------------------------------------------------------
+
+def test_vertex_sa_provider_not_configured(monkeypatch):
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    assert VertexServiceAccountProvider().is_configured() is False
+
+
+def test_vertex_sa_provider_configured(monkeypatch):
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", json.dumps(FAKE_SA_JSON))
+    assert VertexServiceAccountProvider().is_configured() is True
+
+
+def test_vertex_sa_provider_type():
+    assert VertexServiceAccountProvider().provider_type == ProviderType.VERTEX_SERVICE_ACCOUNT
+
+
+def test_vertex_sa_provider_list_models_not_configured(monkeypatch):
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    with pytest.raises(RuntimeError, match="VERTEX_SERVICE_ACCOUNT_JSON"):
+        VertexServiceAccountProvider().list_models()
+
+
+def test_vertex_sa_provider_invalid_json(monkeypatch):
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", "not-valid-json{{{")
+    with pytest.raises(ValueError, match="JSON invalide"):
+        VertexServiceAccountProvider().list_models()
+
+
+def test_vertex_sa_provider_missing_project_id(monkeypatch):
+    sa_no_project = {k: v for k, v in FAKE_SA_JSON.items() if k != "project_id"}
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", json.dumps(sa_no_project))
+    with pytest.raises(ValueError, match="project_id"):
+        VertexServiceAccountProvider().list_models()
+
+
+def test_vertex_sa_provider_list_models_success(monkeypatch):
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", json.dumps(FAKE_SA_JSON))
+    mock_model = _make_mock_model(
+        name="models/gemini-1.5-pro-002",
+        display_name="Gemini 1.5 Pro 002",
+    )
+    mock_credentials = MagicMock()
+
+    with patch(
+        "app.services.ai.provider_vertex_sa.service_account.Credentials.from_service_account_info",
+        return_value=mock_credentials,
+    ) as mock_creds_factory:
+        with patch("app.services.ai.provider_vertex_sa.genai.Client") as MockClient:
+            MockClient.return_value.models.list.return_value = [mock_model]
+            models = VertexServiceAccountProvider().list_models()
+
+    assert len(models) == 1
+    assert models[0].model_id == "models/gemini-1.5-pro-002"
+    assert models[0].provider == ProviderType.VERTEX_SERVICE_ACCOUNT
+    mock_creds_factory.assert_called_once_with(
+        FAKE_SA_JSON,
+        scopes=["https://www.googleapis.com/auth/cloud-platform"],
+    )
+    MockClient.assert_called_once_with(
+        vertexai=True,
+        project="test-project-123",
+        location="us-central1",
+        credentials=mock_credentials,
+    )
+
+
+def test_vertex_sa_provider_filters_non_generate_content(monkeypatch):
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", json.dumps(FAKE_SA_JSON))
+    embedding = _make_mock_model(
+        name="models/textembedding-gecko",
+        display_name="Text Embedding Gecko",
+        methods=["embedContent"],
+    )
+
+    with patch(
+        "app.services.ai.provider_vertex_sa.service_account.Credentials.from_service_account_info",
+        return_value=MagicMock(),
+    ):
+        with patch("app.services.ai.provider_vertex_sa.genai.Client") as MockClient:
+            MockClient.return_value.models.list.return_value = [embedding]
+            models = VertexServiceAccountProvider().list_models()
+
+    assert models == []
+
+
+# ---------------------------------------------------------------------------
+# Tests — model_registry.list_all_models
+# ---------------------------------------------------------------------------
+
+def test_list_all_models_no_providers_configured(monkeypatch):
+    monkeypatch.delenv("GOOGLE_AI_STUDIO_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    result = list_all_models()
+    assert result == []
+
+
+def test_list_all_models_one_provider(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    mock_model = _make_mock_model()
+
+    with patch("app.services.ai.provider_google_ai.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = [mock_model]
+        result = list_all_models()
+
+    assert len(result) == 1
+    assert result[0].provider == ProviderType.GOOGLE_AI_STUDIO
+
+
+def test_list_all_models_aggregates_multiple_providers(monkeypatch):
+    # Note : provider_google_ai et provider_vertex_key partagent le même objet
+    # google.genai (import module). On patch au niveau des méthodes pour éviter
+    # que le second patch.object("...genai.Client") écrase le premier.
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key-ai")
+    monkeypatch.setenv("VERTEX_API_KEY", "fake-key-vertex")
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+
+    models_ai = [ModelInfo(
+        model_id="models/gemini-1.5-pro",
+        display_name="Gemini 1.5 Pro",
+        provider=ProviderType.GOOGLE_AI_STUDIO,
+        supports_vision=True,
+    )]
+    models_vertex = [ModelInfo(
+        model_id="models/gemini-2.0-flash",
+        display_name="Gemini 2.0 Flash",
+        provider=ProviderType.VERTEX_API_KEY,
+        supports_vision=True,
+    )]
+
+    with patch.object(GoogleAIProvider, "list_models", return_value=models_ai):
+        with patch.object(VertexAPIKeyProvider, "list_models", return_value=models_vertex):
+            result = list_all_models()
+
+    assert len(result) == 2
+    providers = {m.provider for m in result}
+    assert ProviderType.GOOGLE_AI_STUDIO in providers
+    assert ProviderType.VERTEX_API_KEY in providers
+
+
+def test_list_all_models_failing_provider_is_skipped(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "bad-key")
+    monkeypatch.setenv("VERTEX_API_KEY", "good-key")
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+
+    models_vertex = [ModelInfo(
+        model_id="models/gemini-2.0-flash",
+        display_name="Gemini 2.0 Flash",
+        provider=ProviderType.VERTEX_API_KEY,
+        supports_vision=True,
+    )]
+
+    with patch.object(GoogleAIProvider, "list_models", side_effect=Exception("API key invalid")):
+        with patch.object(VertexAPIKeyProvider, "list_models", return_value=models_vertex):
+            result = list_all_models()
+
+    assert len(result) == 1
+    assert result[0].provider == ProviderType.VERTEX_API_KEY
+
+
+# ---------------------------------------------------------------------------
+# Tests — model_registry.build_model_config
+# ---------------------------------------------------------------------------
+
+def test_build_model_config_valid(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    mock_model = _make_mock_model()
+
+    with patch("app.services.ai.provider_google_ai.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = [mock_model]
+        cfg = build_model_config("corpus-001", "models/gemini-1.5-pro")
+
+    assert cfg.corpus_id == "corpus-001"
+    assert cfg.selected_model_id == "models/gemini-1.5-pro"
+    assert cfg.selected_model_display_name == "Gemini 1.5 Pro"
+    assert cfg.provider == ProviderType.GOOGLE_AI_STUDIO
+    assert cfg.supports_vision is True
+    assert len(cfg.available_models) == 1
+    assert isinstance(cfg.available_models[0], dict)
+
+
+def test_build_model_config_unknown_model(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key")
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    mock_model = _make_mock_model()
+
+    with patch("app.services.ai.provider_google_ai.genai.Client") as MockClient:
+        MockClient.return_value.models.list.return_value = [mock_model]
+        with pytest.raises(ValueError, match="non disponible"):
+            build_model_config("corpus-001", "models/nonexistent-model")
+
+
+def test_build_model_config_no_providers(monkeypatch):
+    monkeypatch.delenv("GOOGLE_AI_STUDIO_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+    with pytest.raises(ValueError, match="non disponible"):
+        build_model_config("corpus-001", "models/gemini-1.5-pro")

backend/tests/test_image_pipeline.py

@@ -0,0 +1,393 @@
+"""
+Tests du pipeline image : fetch IIIF + normalisation (dérivé + thumbnail).
+Tests unitaires : httpx mocké, images créées en mémoire (Pillow).
+Tests d'intégration : requêtes réseau réelles, activés via RUN_INTEGRATION_TESTS=1.
+"""
+# 1. stdlib
+import io
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+# 2. third-party
+import httpx
+import pytest
+from PIL import Image
+from pydantic import ValidationError
+
+# 3. local
+from app.schemas.image import ImageDerivativeInfo
+from app.services.image.normalizer import (
+    _MAX_DERIVATIVE_PX,
+    _MAX_THUMBNAIL_PX,
+    _resize_to_max,
+    create_derivatives,
+    fetch_and_normalize,
+)
+from app.services.ingest.iiif_fetcher import fetch_iiif_image
+
+# ---------------------------------------------------------------------------
+# Marqueur d'intégration — activé seulement si RUN_INTEGRATION_TESTS=1
+# ---------------------------------------------------------------------------
+
+integration = pytest.mark.skipif(
+    not os.environ.get("RUN_INTEGRATION_TESTS"),
+    reason="Tests réseau réels : définir RUN_INTEGRATION_TESTS=1 pour les activer",
+)
+
+# URLs IIIF des 3 manuscrits de test (BnF Gallica)
+_URL_BEATUS_HI = (
+    "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432836p/f13/full/max/0/default.jpg"
+)
+_URL_BEATUS_LO = (
+    "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432836p/f13/full/600,/0/default.jpg"
+)
+_URL_GRANDES_CHRONIQUES = (
+    "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8427295k/f3/full/max/0/default.jpg"
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers de test
+# ---------------------------------------------------------------------------
+
+def _make_jpeg_bytes(width: int, height: int, color: tuple[int, int, int] = (200, 150, 100)) -> bytes:
+    """Crée un JPEG minimal en mémoire pour les tests unitaires."""
+    img = Image.new("RGB", (width, height), color=color)
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG", quality=85)
+    return buf.getvalue()
+
+
+def _make_png_rgba_bytes(width: int, height: int) -> bytes:
+    """Crée un PNG RGBA en mémoire (pour tester la conversion RGB)."""
+    img = Image.new("RGBA", (width, height), color=(100, 150, 200, 128))
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# Tests — ImageDerivativeInfo (schéma)
+# ---------------------------------------------------------------------------
+
+def test_schema_valid():
+    info = ImageDerivativeInfo(
+        original_url="https://example.com/image.jpg",
+        original_width=3000,
+        original_height=4000,
+        derivative_path="/data/corpora/test/derivatives/0001r.jpg",
+        derivative_width=1125,
+        derivative_height=1500,
+        thumbnail_path="/data/corpora/test/derivatives/0001r_thumb.jpg",
+        thumbnail_width=192,
+        thumbnail_height=256,
+    )
+    assert info.original_width == 3000
+    assert info.derivative_width == 1125
+
+
+def test_schema_missing_required_field():
+    with pytest.raises(ValidationError):
+        ImageDerivativeInfo.model_validate({"original_url": "https://x.com/img.jpg"})
+
+
+def test_schema_all_fields_present():
+    fields = ImageDerivativeInfo.model_fields.keys()
+    expected = {
+        "original_url", "original_width", "original_height",
+        "derivative_path", "derivative_width", "derivative_height",
+        "thumbnail_path", "thumbnail_width", "thumbnail_height",
+    }
+    assert set(fields) == expected
+
+
+# ---------------------------------------------------------------------------
+# Tests — _resize_to_max
+# ---------------------------------------------------------------------------
+
+def test_resize_small_image_not_upscaled():
+    """Une image déjà petite ne doit pas être agrandie."""
+    img = Image.new("RGB", (800, 600))
+    result = _resize_to_max(img, _MAX_DERIVATIVE_PX)
+    assert result.size == (800, 600)
+
+
+def test_resize_exact_max_not_changed():
+    """Une image dont le grand côté est exactement max_size n'est pas redimensionnée."""
+    img = Image.new("RGB", (1500, 1000))
+    result = _resize_to_max(img, _MAX_DERIVATIVE_PX)
+    assert result.size == (1500, 1000)
+
+
+def test_resize_landscape_large():
+    """Paysage 3000x2000 → 1500x1000."""
+    img = Image.new("RGB", (3000, 2000))
+    result = _resize_to_max(img, 1500)
+    assert result.size == (1500, 1000)
+
+
+def test_resize_portrait_large():
+    """Portrait 2000x3000 → 1000x1500."""
+    img = Image.new("RGB", (2000, 3000))
+    result = _resize_to_max(img, 1500)
+    assert result.size == (1000, 1500)
+
+
+def test_resize_square_large():
+    """Carré 2000x2000 → 1500x1500."""
+    img = Image.new("RGB", (2000, 2000))
+    result = _resize_to_max(img, 1500)
+    assert result.size == (1500, 1500)
+
+
+def test_resize_preserves_aspect_ratio():
+    """Le ratio d'aspect est préservé après resize."""
+    img = Image.new("RGB", (4000, 3000))
+    result = _resize_to_max(img, 1500)
+    w, h = result.size
+    assert w == 1500
+    assert abs(w / h - 4 / 3) < 0.01
+
+
+def test_resize_returns_copy_when_no_resize_needed():
+    """Retourne une copie (pas la même instance) même sans resize."""
+    img = Image.new("RGB", (100, 100))
+    result = _resize_to_max(img, 1500)
+    assert result is not img
+
+
+def test_resize_thumbnail_size():
+    """Vérification pour la taille thumbnail (256px)."""
+    img = Image.new("RGB", (1200, 800))
+    result = _resize_to_max(img, _MAX_THUMBNAIL_PX)
+    assert result.size[0] == 256
+    assert result.size[1] == 171  # round(800 * 256 / 1200) = round(170.67) = 171
+
+
+# ---------------------------------------------------------------------------
+# Tests — create_derivatives
+# ---------------------------------------------------------------------------
+
+def test_create_derivatives_large_landscape(tmp_path):
+    """Image 3000x2000 → dérivé 1500x1000, thumbnail 256x171."""
+    source = _make_jpeg_bytes(3000, 2000)
+    info = create_derivatives(source, "https://x.com/img.jpg", "test-corpus", "0001r", tmp_path)
+
+    assert info.original_width == 3000
+    assert info.original_height == 2000
+    assert info.derivative_width == 1500
+    assert info.derivative_height == 1000
+    assert info.thumbnail_width == 256
+    assert info.thumbnail_height == 171
+    assert info.original_url == "https://x.com/img.jpg"
+
+
+def test_create_derivatives_small_image_not_upscaled(tmp_path):
+    """Image 600x900 (< 1500px) : dérivé conserve les dimensions originales."""
+    source = _make_jpeg_bytes(600, 900)
+    info = create_derivatives(source, "https://x.com/img.jpg", "test-corpus", "0001r", tmp_path)
+
+    assert info.derivative_width == 600
+    assert info.derivative_height == 900
+    assert info.original_width == 600
+    assert info.original_height == 900
+
+
+def test_create_derivatives_files_exist(tmp_path):
+    """Les deux fichiers JPEG sont bien créés sur disque."""
+    source = _make_jpeg_bytes(2000, 3000)
+    info = create_derivatives(source, "https://x.com/img.jpg", "corpus-a", "f001r", tmp_path)
+
+    assert Path(info.derivative_path).exists()
+    assert Path(info.thumbnail_path).exists()
+
+
+def test_create_derivatives_path_structure(tmp_path):
+    """Les chemins respectent la convention CLAUDE.md §3."""
+    source = _make_jpeg_bytes(1000, 1000)
+    info = create_derivatives(source, "https://x.com/img.jpg", "beatus-lat8878", "0013r", tmp_path)
+
+    expected_deriv = tmp_path / "corpora" / "beatus-lat8878" / "derivatives" / "0013r.jpg"
+    expected_thumb = tmp_path / "corpora" / "beatus-lat8878" / "derivatives" / "0013r_thumb.jpg"
+    assert info.derivative_path == str(expected_deriv)
+    assert info.thumbnail_path == str(expected_thumb)
+
+
+def test_create_derivatives_output_is_jpeg(tmp_path):
+    """Les fichiers produits sont bien des JPEG valides."""
+    source = _make_jpeg_bytes(1000, 800)
+    info = create_derivatives(source, "https://x.com/img.jpg", "corpus-b", "f002r", tmp_path)
+
+    with Image.open(info.derivative_path) as img:
+        assert img.format == "JPEG"
+    with Image.open(info.thumbnail_path) as img:
+        assert img.format == "JPEG"
+
+
+def test_create_derivatives_rgba_converted_to_rgb(tmp_path):
+    """Un PNG RGBA est converti en RGB sans erreur."""
+    source = _make_png_rgba_bytes(800, 1000)
+    info = create_derivatives(source, "https://x.com/img.png", "corpus-c", "f003r", tmp_path)
+
+    with Image.open(info.derivative_path) as img:
+        assert img.mode == "RGB"
+    assert info.original_width == 800
+    assert info.original_height == 1000
+
+
+def test_create_derivatives_thumbnail_dimensions(tmp_path):
+    """Le thumbnail a bien son grand côté <= 256px."""
+    source = _make_jpeg_bytes(3000, 4000)
+    info = create_derivatives(source, "https://x.com/img.jpg", "corpus-d", "f004r", tmp_path)
+
+    assert max(info.thumbnail_width, info.thumbnail_height) == _MAX_THUMBNAIL_PX
+
+
+def test_create_derivatives_creates_parent_dirs(tmp_path):
+    """Les dossiers intermédiaires sont créés automatiquement."""
+    source = _make_jpeg_bytes(500, 500)
+    new_slug = "nouveau-corpus-jamais-vu"
+    info = create_derivatives(source, "https://x.com/img.jpg", new_slug, "f001r", tmp_path)
+
+    assert Path(info.derivative_path).parent.exists()
+
+
+# ---------------------------------------------------------------------------
+# Tests — fetch_iiif_image
+# ---------------------------------------------------------------------------
+
+def test_fetch_iiif_image_success():
+    """Retourne les bytes de l'image si la requête réussit."""
+    fake_bytes = _make_jpeg_bytes(100, 100)
+
+    with patch("app.services.ingest.iiif_fetcher.httpx.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.content = fake_bytes
+        mock_response.raise_for_status.return_value = None
+        mock_get.return_value = mock_response
+
+        result = fetch_iiif_image("https://example.com/image.jpg")
+
+    assert result == fake_bytes
+    mock_get.assert_called_once_with(
+        "https://example.com/image.jpg",
+        follow_redirects=True,
+        timeout=60.0,
+    )
+
+
+def test_fetch_iiif_image_http_error():
+    """Propage HTTPStatusError si le serveur répond 404."""
+    with patch("app.services.ingest.iiif_fetcher.httpx.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "404 Not Found",
+            request=MagicMock(),
+            response=MagicMock(status_code=404),
+        )
+        mock_get.return_value = mock_response
+
+        with pytest.raises(httpx.HTTPStatusError):
+            fetch_iiif_image("https://example.com/missing.jpg")
+
+
+def test_fetch_iiif_image_timeout():
+    """Propage TimeoutException si la requête dépasse le délai."""
+    with patch("app.services.ingest.iiif_fetcher.httpx.get") as mock_get:
+        mock_get.side_effect = httpx.TimeoutException("timed out")
+
+        with pytest.raises(httpx.TimeoutException):
+            fetch_iiif_image("https://example.com/slow.jpg", timeout=1.0)
+
+
+def test_fetch_iiif_image_custom_timeout():
+    """Le timeout personnalisé est bien transmis à httpx.get."""
+    fake_bytes = _make_jpeg_bytes(50, 50)
+
+    with patch("app.services.ingest.iiif_fetcher.httpx.get") as mock_get:
+        mock_response = MagicMock()
+        mock_response.content = fake_bytes
+        mock_response.raise_for_status.return_value = None
+        mock_get.return_value = mock_response
+
+        fetch_iiif_image("https://example.com/img.jpg", timeout=120.0)
+
+    _, kwargs = mock_get.call_args
+    assert kwargs["timeout"] == 120.0
+
+
+# ---------------------------------------------------------------------------
+# Tests — fetch_and_normalize (end-to-end mocké)
+# ---------------------------------------------------------------------------
+
+def test_fetch_and_normalize_chains_correctly(tmp_path):
+    """fetch_and_normalize appelle fetch_iiif_image puis create_derivatives."""
+    fake_bytes = _make_jpeg_bytes(2000, 1500)
+
+    with patch("app.services.image.normalizer.fetch_iiif_image", return_value=fake_bytes) as mock_fetch:
+        info = fetch_and_normalize(
+            "https://example.com/ms/f001.jpg",
+            "corpus-test",
+            "0001r",
+            tmp_path,
+        )
+
+    mock_fetch.assert_called_once_with("https://example.com/ms/f001.jpg")
+    assert info.original_url == "https://example.com/ms/f001.jpg"
+    assert info.original_width == 2000
+    assert info.original_height == 1500
+    assert info.derivative_width == 1500
+    assert info.derivative_height == 1125
+    assert Path(info.derivative_path).exists()
+    assert Path(info.thumbnail_path).exists()
+
+
+def test_fetch_and_normalize_propagates_http_error(tmp_path):
+    """Les erreurs HTTP de fetch_iiif_image sont propagées sans être masquées."""
+    with patch(
+        "app.services.image.normalizer.fetch_iiif_image",
+        side_effect=httpx.HTTPStatusError("403", request=MagicMock(), response=MagicMock()),
+    ):
+        with pytest.raises(httpx.HTTPStatusError):
+            fetch_and_normalize("https://example.com/img.jpg", "corpus", "f001", tmp_path)
+
+
+# ---------------------------------------------------------------------------
+# Tests d'intégration — URLs IIIF BnF réelles (skippés par défaut)
+# ---------------------------------------------------------------------------
+
+@integration
+def test_integration_beatus_high_res(tmp_path):
+    """Beatus de Saint-Sever, BnF Latin 8878, f.13 — haute résolution."""
+    info = fetch_and_normalize(_URL_BEATUS_HI, "beatus-lat8878", "0013r", tmp_path)
+
+    assert info.original_width > 1500 or info.original_height > 1500
+    assert info.derivative_width <= _MAX_DERIVATIVE_PX
+    assert info.derivative_height <= _MAX_DERIVATIVE_PX
+    assert max(info.derivative_width, info.derivative_height) == _MAX_DERIVATIVE_PX
+    assert Path(info.derivative_path).exists()
+    assert Path(info.thumbnail_path).exists()
+
+
+@integration
+def test_integration_beatus_low_res(tmp_path):
+    """Beatus de Saint-Sever, BnF Latin 8878, f.13 — 600px (image déjà petite)."""
+    info = fetch_and_normalize(_URL_BEATUS_LO, "beatus-lat8878", "0013r-600", tmp_path)
+
+    # Image à 600px de large : pas d'upscaling, dérivé == original
+    assert info.derivative_width <= _MAX_DERIVATIVE_PX
+    assert info.derivative_height <= _MAX_DERIVATIVE_PX
+    assert max(info.derivative_width, info.derivative_height) <= 600
+    assert Path(info.derivative_path).exists()
+
+
+@integration
+def test_integration_grandes_chroniques(tmp_path):
+    """Grandes Chroniques de France, BnF Français 2813."""
+    info = fetch_and_normalize(_URL_GRANDES_CHRONIQUES, "grandes-chroniques", "f003", tmp_path)
+
+    assert info.derivative_width <= _MAX_DERIVATIVE_PX
+    assert info.derivative_height <= _MAX_DERIVATIVE_PX
+    assert Path(info.derivative_path).exists()
+    assert Path(info.thumbnail_path).exists()