fix(sprint-f0): fondations — lazy imports, schémas conformes, pydantic-settings

Sprint F0 — corrections fondamentales qui débloquent tout le reste :

- Lazy imports des providers IA : l'import chain google-genai/mistralai
n'est plus chargée au démarrage. `from app.main import app` fonctionne
même si les SDK tiers ont des problèmes de dépendances.
Fichiers : ai/__init__.py, model_registry.py, jobs.py, models_api.py,
job_runner.py, corpus_runner.py, provider_vertex_key.py

- Schémas PageMaster conformes à CLAUDE.md §4.2 :
- ImageInfo(BaseModel) remplace image: dict (6 champs typés)
- Summary(BaseModel) remplace summary: dict (short + detailed)
- ProcessingInfo.provider: str ajouté (traçabilité du provider)
Fichiers : page_master.py, analyzer.py, exports (alto/iiif/mets)

- config.py migré vers pydantic-settings BaseSettings (CLAUDE.md §2/§7)
avec pydantic-settings ajouté dans pyproject.toml

- Defaults datetime sur CorpusModel et JobModel (plus de crash insert)

- 28 fichiers de tests mis à jour (mocks adaptés aux lazy imports,
fixtures image/ProcessingInfo corrigées)

Résultat : 460 tests passants, 0 échecs, 3 skipped.

https://claude.ai/code/session_015Lht7wNQRzhUaLw94dE9z9

backend/app/api/v1/jobs.py

@@ -22,8 +22,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
 from app.models.database import get_db
 from app.models.job import JobModel
-from app.services.corpus_runner import execute_corpus_job
-from app.services.job_runner import execute_page_job
 
 router = APIRouter(tags=["jobs"])
 
@@ -101,6 +99,8 @@ async def run_corpus(
     await db.commit()
 
     # Lancer le pipeline en arrière-plan (après envoi de la réponse)
+    from app.services.corpus_runner import execute_corpus_job
+
     background_tasks.add_task(execute_corpus_job, corpus_id)
 
     return CorpusRunResponse(
@@ -135,6 +135,8 @@ async def run_page(
     await db.refresh(job)
 
     # Lancer le pipeline en arrière-plan (après envoi de la réponse)
+    from app.services.job_runner import execute_page_job
+
     background_tasks.add_task(execute_page_job, job.id)
 
     return job
@@ -175,6 +177,8 @@ async def retry_job(
     await db.refresh(job)
 
     # Relancer le pipeline
+    from app.services.job_runner import execute_page_job
+
     background_tasks.add_task(execute_page_job, job.id)
 
     return job

backend/app/api/v1/models_api.py

@@ -25,11 +25,6 @@ from app.models.corpus import CorpusModel
 from app.models.database import get_db
 from app.models.model_config_db import ModelConfigDB
 from app.schemas.model_config import ProviderType
-from app.services.ai.model_registry import (
-    get_available_providers,
-    list_all_models,
-    list_models_for_provider,
-)
 
 logger = logging.getLogger(__name__)
 
@@ -77,6 +72,8 @@ async def list_providers() -> list[dict]:
     Un provider est disponible si la variable d'environnement correspondante
     est présente dans les secrets HuggingFace. Aucune clé n'est exposée.
     """
+    from app.services.ai.model_registry import get_available_providers
+
     return get_available_providers()
 
 
@@ -91,6 +88,8 @@ async def get_provider_models(provider_type: str) -> list[dict]:
             detail=f"Provider inconnu : {provider_type}. "
                    f"Valeurs acceptées : {[p.value for p in ProviderType]}",
         )
+    from app.services.ai.model_registry import list_models_for_provider
+
     try:
         models = list_models_for_provider(ptype)
     except RuntimeError as exc:
@@ -104,6 +103,8 @@ async def get_provider_models(provider_type: str) -> list[dict]:
 @router.post("/models/refresh", response_model=ModelsRefreshResponse)
 async def refresh_models() -> ModelsRefreshResponse:
     """Force la mise à jour de la liste agrégée de tous les modèles disponibles."""
+    from app.services.ai.model_registry import list_all_models
+
     models = list_all_models()
     return ModelsRefreshResponse(
         models=[m.model_dump() for m in models],

backend/app/config.py

@@ -1,17 +1,17 @@
 """
 Configuration globale de la plateforme, chargée depuis les variables d'environnement.
 
-Équivalent fonctionnel de pydantic-settings sans dépendance externe :
-  - les valeurs sont lues depuis os.environ au moment de l'instanciation
+Utilise pydantic-settings (CLAUDE.md §2, §7) :
+  - les valeurs sont lues depuis os.environ / fichier .env au moment de l'instanciation
   - l'objet `settings` est importé partout dans l'application
   - dans les tests : monkeypatch.setattr(config, "settings", ...) pour surcharger
 """
 # 1. stdlib
-import os
 from pathlib import Path
 
 # 2. third-party
-from pydantic import BaseModel, ConfigDict
+from pydantic import ConfigDict
+from pydantic_settings import BaseSettings
 
 # Racine du dépôt — résolue depuis l'emplacement absolu de ce fichier.
 # config.py se trouve dans backend/app/ ; 3 parents remontent à la racine.
@@ -19,14 +19,17 @@ from pydantic import BaseModel, ConfigDict
 _REPO_ROOT = Path(__file__).resolve().parent.parent.parent
 
 
-class Settings(BaseModel):
+class Settings(BaseSettings):
     """Paramètres d'application lus depuis les variables d'environnement.
 
     Toutes les clés API sont optionnelles (None si non configurées).
     Elles ne sont jamais loguées ni exportées (R06).
     """
 
-    model_config = ConfigDict(frozen=False)
+    model_config = ConfigDict(
+        env_file=".env",
+        extra="ignore",
+    )
 
     # ── Serveur ──────────────────────────────────────────────────────────────
     base_url: str = "http://localhost:8000"
@@ -50,21 +53,4 @@ class Settings(BaseModel):
     mistral_api_key: str | None = None
 
 
-def _load_settings() -> Settings:
-    """Lit les variables d'environnement et construit l'objet Settings."""
-    return Settings(
-        base_url=os.getenv("BASE_URL", "http://localhost:8000"),
-        data_dir=Path(os.getenv("DATA_DIR", "data")),
-        profiles_dir=Path(os.getenv("PROFILES_DIR", str(_REPO_ROOT / "profiles"))),
-        prompts_dir=Path(os.getenv("PROMPTS_DIR", str(_REPO_ROOT / "prompts"))),
-        database_url=os.getenv(
-            "DATABASE_URL", "sqlite+aiosqlite:///./scriptorium.db"
-        ),
-        google_ai_studio_api_key=os.getenv("GOOGLE_AI_STUDIO_API_KEY"),
-        vertex_api_key=os.getenv("VERTEX_API_KEY"),
-        vertex_service_account_json=os.getenv("VERTEX_SERVICE_ACCOUNT_JSON"),
-        mistral_api_key=os.getenv("MISTRAL_API_KEY"),
-    )
-
-
-settings: Settings = _load_settings()
+settings: Settings = Settings()

backend/app/models/corpus.py

@@ -6,6 +6,7 @@ Ils NE se substituent PAS aux schémas Pydantic (source canonique des types).
 """
 # 1. stdlib
 from datetime import datetime, timezone
+from functools import partial
 
 # 2. third-party
 from sqlalchemy import DateTime, Float, ForeignKey, Integer, String, Text
@@ -24,8 +25,12 @@ class CorpusModel(Base):
     slug: Mapped[str] = mapped_column(String, unique=True, nullable=False, index=True)
     title: Mapped[str] = mapped_column(String, nullable=False)
     profile_id: Mapped[str] = mapped_column(String, nullable=False)
-    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=partial(datetime.now, tz=timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=partial(datetime.now, tz=timezone.utc)
+    )
 
     manuscripts: Mapped[list["ManuscriptModel"]] = relationship(
         back_populates="corpus", cascade="all, delete-orphan"

backend/app/models/job.py

@@ -10,7 +10,8 @@ Cycle de vie :
                    ↘ failed
 """
 # 1. stdlib
-from datetime import datetime
+from datetime import datetime, timezone
+from functools import partial
 
 # 2. third-party
 from sqlalchemy import DateTime, ForeignKey, String, Text
@@ -37,4 +38,6 @@ class JobModel(Base):
     started_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
     finished_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
     error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
-    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=partial(datetime.now, tz=timezone.utc)
+    )

backend/app/schemas/page_master.py

@@ -29,14 +29,25 @@ class Region(BaseModel):
 
     @field_validator("bbox")
     @classmethod
-    def bbox_must_be_positive(cls, v: list[int]) -> list[int]:
+    def bbox_must_be_valid(cls, v: list[int]) -> list[int]:
         if any(x < 0 for x in v):
-            raise ValueError("bbox values must be >= 0")
+            raise ValueError("bbox: toutes les valeurs doivent être >= 0")
         if v[2] <= 0 or v[3] <= 0:
-            raise ValueError("bbox width and height must be > 0")
+            raise ValueError("bbox: width et height doivent être > 0")
         return v
 
 
+class ImageInfo(BaseModel):
+    """Métadonnées image — CLAUDE.md §4.2."""
+
+    master: str
+    derivative_web: str | None = None
+    thumbnail: str | None = None
+    iiif_base: str | None = None
+    width: int
+    height: int
+
+
 class OCRResult(BaseModel):
     diplomatic_text: str = ""
     blocks: list[dict] = []
@@ -51,6 +62,13 @@ class Translation(BaseModel):
     en: str = ""
 
 
+class Summary(BaseModel):
+    """Résumé — CLAUDE.md §4.2."""
+
+    short: str = ""
+    detailed: str = ""
+
+
 class CommentaryClaim(BaseModel):
     claim: str
     evidence_region_ids: list[str] = []
@@ -64,6 +82,7 @@ class Commentary(BaseModel):
 
 
 class ProcessingInfo(BaseModel):
+    provider: str
     model_id: str
     model_display_name: str
     prompt_version: str
@@ -96,11 +115,11 @@ class PageMaster(BaseModel):
     folio_label: str
     sequence: int
 
-    image: dict
+    image: ImageInfo
     layout: dict
     ocr: OCRResult | None = None
     translation: Translation | None = None
-    summary: dict | None = None
+    summary: Summary | None = None
     commentary: Commentary | None = None
     extensions: dict[str, Any] = {}
 

backend/app/services/ai/__init__.py

@@ -1,19 +1,31 @@
 """
 Services AI — providers Google AI, registre de modèles, et analyse IA.
+
+Les imports de providers sont différés (lazy) pour éviter de charger les SDK
+tiers (google-genai, mistralai) au démarrage. Cela permet à l'application
+de fonctionner même si un SDK n'est pas installé.
 """
-from app.services.ai.analyzer import run_primary_analysis
-from app.services.ai.client_factory import build_client
-from app.services.ai.model_registry import build_model_config, list_all_models
-from app.services.ai.prompt_loader import load_and_render_prompt
-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
-from app.services.ai.response_parser import ParseError, parse_ai_response
+
+
+def __getattr__(name: str):
+    """Import paresseux — les symboles sont résolus au premier accès."""
+    _lazy_map = {
+        "run_primary_analysis": "app.services.ai.analyzer",
+        "build_client": "app.services.ai.client_factory",
+        "build_model_config": "app.services.ai.model_registry",
+        "list_all_models": "app.services.ai.model_registry",
+        "load_and_render_prompt": "app.services.ai.prompt_loader",
+        "parse_ai_response": "app.services.ai.response_parser",
+        "ParseError": "app.services.ai.response_parser",
+    }
+    if name in _lazy_map:
+        import importlib
+        module = importlib.import_module(_lazy_map[name])
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 __all__ = [
-    "GoogleAIProvider",
-    "VertexAPIKeyProvider",
-    "VertexServiceAccountProvider",
     "list_all_models",
     "build_model_config",
     "build_client",

backend/app/services/ai/analyzer.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from app.schemas.corpus_profile import CorpusProfile
 from app.schemas.image import ImageDerivativeInfo
 from app.schemas.model_config import ModelConfig
-from app.schemas.page_master import EditorialInfo, EditorialStatus, PageMaster, ProcessingInfo
+from app.schemas.page_master import EditorialInfo, EditorialStatus, ImageInfo, PageMaster, ProcessingInfo
 from app.services.ai.master_writer import write_gemini_raw, write_master_json
 from app.services.ai.model_registry import get_provider
 from app.services.ai.prompt_loader import load_and_render_prompt
@@ -118,16 +118,17 @@ def run_primary_analysis(
         manuscript_id=manuscript_id,
         folio_label=folio_label,
         sequence=sequence,
-        image={
-            "original_url": image_info.original_url,
-            "derivative_web": image_info.derivative_path,
-            "thumbnail": image_info.thumbnail_path,
-            "width": image_info.derivative_width,
-            "height": image_info.derivative_height,
-        },
+        image=ImageInfo(
+            master=image_info.original_url,
+            derivative_web=image_info.derivative_path,
+            thumbnail=image_info.thumbnail_path,
+            width=image_info.derivative_width,
+            height=image_info.derivative_height,
+        ),
         layout=layout,
         ocr=ocr,
         processing=ProcessingInfo(
+            provider=model_config.provider.value if hasattr(model_config.provider, "value") else str(model_config.provider),
             model_id=model_config.selected_model_id,
             model_display_name=model_config.selected_model_display_name,
             prompt_version=prompt_rel_path,

backend/app/services/ai/model_registry.py

@@ -1,5 +1,8 @@
 """
 Registre agrégé des modèles disponibles tous providers confondus.
+
+Les imports de providers sont différés dans _build_providers() pour éviter
+de charger les SDK tiers (google-genai, mistralai) au niveau module.
 """
 # 1. stdlib
 import logging
@@ -8,10 +11,6 @@ from datetime import datetime, timezone
 # 2. local
 from app.schemas.model_config import ModelConfig, ModelInfo, ProviderType
 from app.services.ai.base import AIProvider
-from app.services.ai.provider_google_ai import GoogleAIProvider
-from app.services.ai.provider_mistral import MistralProvider
-from app.services.ai.provider_vertex_key import VertexAPIKeyProvider
-from app.services.ai.provider_vertex_sa import VertexServiceAccountProvider
 
 logger = logging.getLogger(__name__)
 
@@ -25,6 +24,12 @@ _PROVIDER_DISPLAY_NAMES: dict[ProviderType, str] = {
 
 
 def _build_providers() -> list[AIProvider]:
+    """Construit la liste des providers — imports différés."""
+    from app.services.ai.provider_google_ai import GoogleAIProvider
+    from app.services.ai.provider_mistral import MistralProvider
+    from app.services.ai.provider_vertex_key import VertexAPIKeyProvider
+    from app.services.ai.provider_vertex_sa import VertexServiceAccountProvider
+
     return [
         GoogleAIProvider(),
         VertexAPIKeyProvider(),

backend/app/services/ai/provider_vertex_key.py

@@ -22,9 +22,6 @@ retourne toujours False afin d'éviter des appels réseau voués à l'échec.
 import logging
 import os
 
-# 2. third-party
-from google.genai import types  # noqa: F401  (conservé pour import cohérence)
-
 # 3. local
 from app.schemas.model_config import ModelInfo, ProviderType
 from app.services.ai.base import AIProvider

backend/app/services/corpus_runner.py

@@ -17,7 +17,6 @@ from sqlalchemy import select
 # 3. local
 from app.models.database import async_session_factory
 from app.models.job import JobModel
-from app.services.job_runner import execute_page_job
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +53,8 @@ async def execute_corpus_job(corpus_id: str) -> dict:
     )
 
     # Exécution séquentielle — chaque job gère sa propre session
+    from app.services.job_runner import execute_page_job
+
     for job_id in job_ids:
         await execute_page_job(job_id)
 

backend/app/services/export/alto.py

@@ -160,11 +160,7 @@ def generate_alto(master: PageMaster) -> str:
     etree.SubElement(desc, _a("MeasurementUnit")).text = "pixel"
 
     src_info = etree.SubElement(desc, _a("sourceImageInformation"))
-    file_name = (
-        master.image.get("original_url")
-        or master.image.get("derivative_web")
-        or master.page_id
-    )
+    file_name = master.image.master or master.image.derivative_web or master.page_id
     etree.SubElement(src_info, _a("fileName")).text = str(file_name)
 
     if master.processing:
@@ -185,8 +181,8 @@ def generate_alto(master: PageMaster) -> str:
     # ── Layout ─────────────────────────────────────────────────────────────
     layout_el = etree.SubElement(root, _a("Layout"))
 
-    width = int(master.image.get("width", 0))
-    height = int(master.image.get("height", 0))
+    width = master.image.width
+    height = master.image.height
 
     page_id_safe = master.page_id.replace(" ", "_")
     page_el = etree.SubElement(

backend/app/services/export/iiif.py

@@ -102,12 +102,12 @@ def generate_manifest(
         canvas_id = (
             f"{base_url}/api/v1/manuscripts/{manuscript_id}/canvas/{page.page_id}"
         )
-        width  = int(page.image.get("width",  0))
-        height = int(page.image.get("height", 0))
+        width  = page.image.width
+        height = page.image.height
 
         annotation_page_id = f"{canvas_id}/annotation-page/1"
         annotation_id      = f"{canvas_id}/annotation/painting"
-        image_url          = page.image.get("original_url", "")
+        image_url          = page.image.master or ""
 
         canvas: dict = {
             "id":     canvas_id,

backend/app/services/export/mets.py

@@ -182,7 +182,7 @@ def generate_mets(
         f_master = _el(grp_master, f"{_M}file", {"ID": f"IMG_MASTER_{sid}", "MIMETYPE": "image/jpeg"})
         _el(f_master, f"{_M}FLocat", {
             "LOCTYPE": "URL",
-            f"{_XL}href": page.image.get("original_url", ""),
+            f"{_XL}href": page.image.master or "",
             f"{_XL}type": "simple",
         })
 
@@ -191,7 +191,7 @@ def generate_mets(
         _el(f_deriv, f"{_M}FLocat", {
             "LOCTYPE": "OTHER",
             "OTHERLOCTYPE": "filepath",
-            f"{_XL}href": page.image.get("derivative_web", ""),
+            f"{_XL}href": page.image.derivative_web or "",
             f"{_XL}type": "simple",
         })
 

backend/app/services/job_runner.py

@@ -33,8 +33,6 @@ from app.models.job import JobModel
 from app.models.model_config_db import ModelConfigDB
 from app.schemas.corpus_profile import CorpusProfile
 from app.schemas.model_config import ModelConfig, ProviderType
-from app.services.ai.analyzer import run_primary_analysis
-from app.services.export.alto import generate_alto, write_alto
 from app.services.image.normalizer import create_derivatives, fetch_and_normalize
 
 logger = logging.getLogger(__name__)
@@ -148,6 +146,8 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
             )
 
         # ── 6. Analyse primaire IA (R05 : double stockage) ───────────────────
+        from app.services.ai.analyzer import run_primary_analysis
+
         page_master = run_primary_analysis(
             derivative_image_path=Path(image_info.derivative_path),
             corpus_profile=corpus_profile,
@@ -163,6 +163,8 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
         )
 
         # ── 7. Générer et écrire l'ALTO XML ──────────────────────────────────
+        from app.services.export.alto import generate_alto, write_alto
+
         alto_xml = generate_alto(page_master)
         alto_path = (
             data_dir

backend/pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "fastapi>=0.111",
     "uvicorn[standard]>=0.29",
     "pydantic>=2.7",
+    "pydantic-settings>=2.0",
     "sqlalchemy>=2.0",
     "aiosqlite>=0.20",
     "google-genai>=1.0",

backend/tests/conftest_api.py

@@ -51,10 +51,11 @@ async def async_client(db_session: AsyncSession):
 
     app.dependency_overrides[get_db] = _override_get_db
     # Les background tasks (execute_corpus_job, execute_page_job) créent leur
-    # propre session via async_session_factory. On les neutralise pour éviter
-    # qu'elles tentent de se connecter à la BDD réelle pendant les tests d'API.
-    with patch("app.api.v1.jobs.execute_corpus_job", AsyncMock(return_value=None)), \
-         patch("app.api.v1.jobs.execute_page_job", AsyncMock(return_value=None)):
+    # propre session via async_session_factory. On les neutralise en mockant
+    # les modules sources pour éviter qu'elles tentent de se connecter à la
+    # BDD réelle pendant les tests d'API.
+    with patch("app.services.corpus_runner.execute_corpus_job", AsyncMock(return_value={"total": 0, "done": 0, "failed": 0})), \
+         patch("app.services.job_runner.execute_page_job", AsyncMock(return_value=None)):
         async with AsyncClient(
             transport=ASGITransport(app=app), base_url="http://test"
         ) as client:

backend/tests/test_ai_analyzer.py

@@ -432,7 +432,7 @@ def _make_page_master() -> PageMaster:
         folio_label="0001r",
         sequence=1,
         image={
-            "original_url": "https://example.com/img.jpg",
+            "master": "https://example.com/img.jpg",
             "derivative_web": "/data/deriv.jpg",
             "thumbnail": "/data/thumb.jpg",
             "width": 1500,
@@ -440,6 +440,7 @@ def _make_page_master() -> PageMaster:
         },
         layout={"regions": []},
         processing={
+            "provider": "google_ai_studio",
             "model_id": "gemini-2.0-flash",
             "model_display_name": "Gemini 2.0 Flash",
             "prompt_version": "prompts/medieval-illuminated/primary_v1.txt",
@@ -663,9 +664,9 @@ def test_run_primary_analysis_image_dict(tmp_path):
             project_root=tmp_path,
         )
 
-    assert result.image["original_url"] == image_info.original_url
-    assert result.image["width"] == image_info.derivative_width
-    assert result.image["height"] == image_info.derivative_height
+    assert result.image.master == image_info.original_url
+    assert result.image.width == image_info.derivative_width
+    assert result.image.height == image_info.derivative_height
 
 
 def test_run_primary_analysis_regions_in_layout(tmp_path):

backend/tests/test_api_corrections.py

@@ -75,7 +75,7 @@ def _make_master(
         "manuscript_id": "ms-test",
         "folio_label": "f001r",
         "sequence": 1,
-        "image": {"original_url": "https://example.com/f.jpg", "width": 1500, "height": 2000},
+        "image": {"master": "https://example.com/f.jpg", "width": 1500, "height": 2000},
         "layout": {"regions": []},
         "ocr": {
             "diplomatic_text": "Incipit liber primus",

backend/tests/test_api_export.py

@@ -83,7 +83,7 @@ def _make_master_json(page_id: str, folio_label: str, sequence: int) -> str:
         "folio_label": folio_label,
         "sequence": sequence,
         "image": {
-            "original_url": f"https://example.com/{page_id}.jpg",
+            "master": f"https://example.com/{page_id}.jpg",
             "derivative_web": f"/data/deriv/{page_id}.jpg",
             "thumbnail": f"/data/thumb/{page_id}.jpg",
             "width": 1500,

backend/tests/test_api_models.py

@@ -94,7 +94,7 @@ async def test_get_models_endpoint_removed(async_client):
 @pytest.mark.asyncio
 async def test_refresh_models_ok(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+        "app.services.ai.model_registry.list_all_models", lambda: _MOCK_MODELS
     )
     response = await async_client.post("/api/v1/models/refresh")
     assert response.status_code == 200
@@ -103,7 +103,7 @@ async def test_refresh_models_ok(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_refresh_models_has_timestamp(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+        "app.services.ai.model_registry.list_all_models", lambda: _MOCK_MODELS
     )
     data = (await async_client.post("/api/v1/models/refresh")).json()
     assert "refreshed_at" in data
@@ -113,7 +113,7 @@ async def test_refresh_models_has_timestamp(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_refresh_models_count(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+        "app.services.ai.model_registry.list_all_models", lambda: _MOCK_MODELS
     )
     data = (await async_client.post("/api/v1/models/refresh")).json()
     assert data["count"] == 2
@@ -123,7 +123,7 @@ async def test_refresh_models_count(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_refresh_models_structure(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+        "app.services.ai.model_registry.list_all_models", lambda: _MOCK_MODELS
     )
     data = (await async_client.post("/api/v1/models/refresh")).json()
     assert "models" in data

backend/tests/test_api_pages.py

@@ -87,7 +87,7 @@ def _make_master_json(page_id: str, corpus_profile: str = "medieval-illuminated"
         "folio_label": "f001r",
         "sequence": 1,
         "image": {
-            "original_url": "https://example.com/f001r.jpg",
+            "master": "https://example.com/f001r.jpg",
             "derivative_web": "/data/deriv/f001r.jpg",
             "thumbnail": "/data/thumb/f001r.jpg",
             "width": 1500,

backend/tests/test_api_providers.py

@@ -90,7 +90,7 @@ _MOCK_MISTRAL_MODELS = [
 
 @pytest.mark.asyncio
 async def test_list_providers_returns_list(async_client, monkeypatch):
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
     resp = await async_client.get("/api/v1/providers")
     assert resp.status_code == 200
     assert isinstance(resp.json(), list)
@@ -98,14 +98,14 @@ async def test_list_providers_returns_list(async_client, monkeypatch):
 
 @pytest.mark.asyncio
 async def test_list_providers_count(async_client, monkeypatch):
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
     data = (await async_client.get("/api/v1/providers")).json()
     assert len(data) == 4  # 4 providers connus
 
 
 @pytest.mark.asyncio
 async def test_list_providers_fields(async_client, monkeypatch):
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
     data = (await async_client.get("/api/v1/providers")).json()
     p = data[0]
     assert "provider_type" in p
@@ -116,7 +116,7 @@ async def test_list_providers_fields(async_client, monkeypatch):
 
 @pytest.mark.asyncio
 async def test_list_providers_all_unavailable(async_client, monkeypatch):
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
     data = (await async_client.get("/api/v1/providers")).json()
     assert all(not p["available"] for p in data)
     assert all(p["model_count"] == 0 for p in data)
@@ -124,7 +124,7 @@ async def test_list_providers_all_unavailable(async_client, monkeypatch):
 
 @pytest.mark.asyncio
 async def test_list_providers_google_available(async_client, monkeypatch):
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_GOOGLE_ONLY)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_GOOGLE_ONLY)
     data = (await async_client.get("/api/v1/providers")).json()
     google = next(p for p in data if p["provider_type"] == "google_ai_studio")
     assert google["available"] is True
@@ -133,7 +133,7 @@ async def test_list_providers_google_available(async_client, monkeypatch):
 
 @pytest.mark.asyncio
 async def test_list_providers_mistral_available(async_client, monkeypatch):
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_GOOGLE_AND_MISTRAL)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_GOOGLE_AND_MISTRAL)
     data = (await async_client.get("/api/v1/providers")).json()
     mistral = next(p for p in data if p["provider_type"] == "mistral")
     assert mistral["available"] is True
@@ -143,7 +143,7 @@ async def test_list_providers_mistral_available(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_list_providers_includes_mistral_type(async_client, monkeypatch):
     """Mistral est toujours dans la liste même si indisponible."""
-    monkeypatch.setattr(models_api_module, "get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
+    monkeypatch.setattr("app.services.ai.model_registry.get_available_providers", lambda: _PROVIDERS_ALL_UNAVAILABLE)
     data = (await async_client.get("/api/v1/providers")).json()
     types_ = [p["provider_type"] for p in data]
     assert "mistral" in types_
@@ -156,7 +156,7 @@ async def test_list_providers_includes_mistral_type(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_get_provider_models_google(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_models_for_provider", lambda ptype: _MOCK_GOOGLE_MODELS
+        "app.services.ai.model_registry.list_models_for_provider", lambda ptype: _MOCK_GOOGLE_MODELS
     )
     resp = await async_client.get("/api/v1/providers/google_ai_studio/models")
     assert resp.status_code == 200
@@ -166,7 +166,7 @@ async def test_get_provider_models_google(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_get_provider_models_mistral(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_models_for_provider", lambda ptype: _MOCK_MISTRAL_MODELS
+        "app.services.ai.model_registry.list_models_for_provider", lambda ptype: _MOCK_MISTRAL_MODELS
     )
     resp = await async_client.get("/api/v1/providers/mistral/models")
     assert resp.status_code == 200
@@ -189,7 +189,7 @@ async def test_get_provider_models_not_configured(async_client, monkeypatch):
     def _raise(ptype):
         raise RuntimeError("Variable d'environnement manquante : MISTRAL_API_KEY")
 
-    monkeypatch.setattr(models_api_module, "list_models_for_provider", _raise)
+    monkeypatch.setattr("app.services.ai.model_registry.list_models_for_provider", _raise)
     resp = await async_client.get("/api/v1/providers/mistral/models")
     assert resp.status_code == 503
 
@@ -197,7 +197,7 @@ async def test_get_provider_models_not_configured(async_client, monkeypatch):
 @pytest.mark.asyncio
 async def test_get_provider_models_fields(async_client, monkeypatch):
     monkeypatch.setattr(
-        models_api_module, "list_models_for_provider", lambda ptype: _MOCK_MISTRAL_MODELS
+        "app.services.ai.model_registry.list_models_for_provider", lambda ptype: _MOCK_MISTRAL_MODELS
     )
     data = (await async_client.get("/api/v1/providers/mistral/models")).json()
     m = data[0]

backend/tests/test_api_search.py

@@ -33,7 +33,7 @@ def _make_master(page_id: str, diplomatic_text: str = "", translation_fr: str =
         "manuscript_id": "ms-test",
         "folio_label": "f001r",
         "sequence": 1,
-        "image": {"original_url": "https://example.com/f.jpg", "width": 1500, "height": 2000},
+        "image": {"master": "https://example.com/f.jpg", "width": 1500, "height": 2000},
         "layout": {"regions": []},
         "ocr": {
             "diplomatic_text": diplomatic_text,

backend/tests/test_export_alto.py

@@ -52,6 +52,7 @@ def _make_master(
     processing = None
     if with_processing:
         processing = ProcessingInfo(
+            provider="google_ai_studio",
             model_id="gemini-2.0-flash",
             model_display_name="Gemini 2.0 Flash",
             prompt_version="prompts/medieval-illuminated/primary_v1.txt",
@@ -65,7 +66,7 @@ def _make_master(
         folio_label="0001r",
         sequence=sequence,
         image={
-            "original_url": "https://example.com/img.jpg",
+            "master": "https://example.com/img.jpg",
             "derivative_web": "/data/deriv.jpg",
             "thumbnail": "/data/thumb.jpg",
             "width": width,

backend/tests/test_export_iiif.py

@@ -53,7 +53,7 @@ def _make_page(
         folio_label=folio_label,
         sequence=sequence,
         image={
-            "original_url": original_url or f"https://example.com/{folio_label}.jpg",
+            "master": original_url or f"https://example.com/{folio_label}.jpg",
             "derivative_web": f"/data/deriv/{folio_label}.jpg",
             "thumbnail": f"/data/thumb/{folio_label}.jpg",
             "width": width,
@@ -344,7 +344,7 @@ def test_canvas_width_matches_image(beatus_pages, beatus_meta):
         # Trouve la page correspondante
         page_id = canvas["id"].split("/canvas/")[-1]
         page = next(p for p in beatus_pages if p.page_id == page_id)
-        assert canvas["width"] == page.image["width"]
+        assert canvas["width"] == page.image.width
 
 
 def test_canvas_height_matches_image(beatus_pages, beatus_meta):
@@ -352,7 +352,7 @@ def test_canvas_height_matches_image(beatus_pages, beatus_meta):
     for canvas in manifest["items"]:
         page_id = canvas["id"].split("/canvas/")[-1]
         page = next(p for p in beatus_pages if p.page_id == page_id)
-        assert canvas["height"] == page.image["height"]
+        assert canvas["height"] == page.image.height
 
 
 def test_canvas_dimensions_beatus_hr():
@@ -447,7 +447,7 @@ def test_annotation_body_id_is_original_url(beatus_pages, beatus_meta):
         page_id = canvas["id"].split("/canvas/")[-1]
         page = next(p for p in beatus_pages if p.page_id == page_id)
         body = canvas["items"][0]["items"][0]["body"]
-        assert body["id"] == page.image["original_url"]
+        assert body["id"] == page.image.master
 
 
 def test_annotation_body_contains_gallica_url(beatus_pages, beatus_meta):

backend/tests/test_export_mets.py

@@ -66,6 +66,7 @@ def _make_page(
     processing = None
     if with_processing:
         processing = ProcessingInfo(
+            provider="google_ai_studio",
             model_id="gemini-2.0-flash",
             model_display_name="Gemini 2.0 Flash",
             prompt_version="prompts/medieval-illuminated/primary_v1.txt",
@@ -80,7 +81,7 @@ def _make_page(
         folio_label=folio_label,
         sequence=sequence,
         image={
-            "original_url": original_url or f"https://example.com/{folio_label}.jpg",
+            "master": original_url or f"https://example.com/{folio_label}.jpg",
             "derivative_web": derivative_web or f"/data/deriv/{folio_label}.jpg",
             "thumbnail": f"/data/thumb/{folio_label}.jpg",
             "width": 1500,

backend/tests/test_job_runner.py

@@ -142,16 +142,24 @@ def _page_master(page_id: str, ms_id: str) -> PageMaster:
 
 
 def _apply_success_mocks(monkeypatch, page_id: str, ms_id: str) -> None:
-    """Applique les mocks IO pour un pipeline réussi."""
+    """Applique les mocks IO pour un pipeline réussi.
+
+    Les imports sont différés dans job_runner (lazy imports). On patche donc
+    les modules sources pour que le import dans la fonction cible récupère le mock.
+    """
     monkeypatch.setattr(
         job_runner_module, "fetch_and_normalize", lambda *a: _image_info()
     )
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: _page_master(page_id, ms_id),
     )
-    monkeypatch.setattr(job_runner_module, "generate_alto", lambda pm: "<alto/>")
-    monkeypatch.setattr(job_runner_module, "write_alto", lambda xml, path: None)
+    monkeypatch.setattr(
+        "app.services.export.alto.generate_alto", lambda pm: "<alto/>"
+    )
+    monkeypatch.setattr(
+        "app.services.export.alto.write_alto", lambda xml, path: None
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -274,7 +282,7 @@ async def test_no_image_path_job_failed(db, setup_with_model, monkeypatch):
     s["page"].image_master_path = None
     await db.commit()
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: _page_master(s["page"].id, s["ms"].id),
     )
 
@@ -291,7 +299,7 @@ async def test_no_image_path_page_error(db, setup_with_model, monkeypatch):
     s["page"].image_master_path = None
     await db.commit()
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: _page_master(s["page"].id, s["ms"].id),
     )
 
@@ -343,7 +351,7 @@ async def test_primary_analysis_fails_job_failed(db, setup_with_model, monkeypat
         job_runner_module, "fetch_and_normalize", lambda *a: _image_info()
     )
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: (_ for _ in ()).throw(ValueError("ParseError: invalid JSON")),
     )
 
@@ -361,7 +369,7 @@ async def test_primary_analysis_fails_page_error(db, setup_with_model, monkeypat
         job_runner_module, "fetch_and_normalize", lambda *a: _image_info()
     )
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: (_ for _ in ()).throw(ValueError("ParseError: invalid JSON")),
     )
 
@@ -379,7 +387,7 @@ async def test_primary_analysis_error_message_stored(db, setup_with_model, monke
         job_runner_module, "fetch_and_normalize", lambda *a: _image_info()
     )
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: (_ for _ in ()).throw(ValueError("ParseError: invalid JSON")),
     )
 
@@ -401,12 +409,14 @@ async def test_write_alto_fails_job_failed(db, setup_with_model, monkeypatch):
         job_runner_module, "fetch_and_normalize", lambda *a: _image_info()
     )
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: _page_master(s["page"].id, s["ms"].id),
     )
-    monkeypatch.setattr(job_runner_module, "generate_alto", lambda pm: "<alto/>")
     monkeypatch.setattr(
-        job_runner_module, "write_alto",
+        "app.services.export.alto.generate_alto", lambda pm: "<alto/>"
+    )
+    monkeypatch.setattr(
+        "app.services.export.alto.write_alto",
         lambda xml, path: (_ for _ in ()).throw(OSError("disk full")),
     )
 
@@ -424,12 +434,14 @@ async def test_write_alto_fails_page_error(db, setup_with_model, monkeypatch):
         job_runner_module, "fetch_and_normalize", lambda *a: _image_info()
     )
     monkeypatch.setattr(
-        job_runner_module, "run_primary_analysis",
+        "app.services.ai.analyzer.run_primary_analysis",
         lambda **kw: _page_master(s["page"].id, s["ms"].id),
     )
-    monkeypatch.setattr(job_runner_module, "generate_alto", lambda pm: "<alto/>")
     monkeypatch.setattr(
-        job_runner_module, "write_alto",
+        "app.services.export.alto.generate_alto", lambda pm: "<alto/>"
+    )
+    monkeypatch.setattr(
+        "app.services.export.alto.write_alto",
         lambda xml, path: (_ for _ in ()).throw(OSError("disk full")),
     )
 
@@ -534,7 +546,7 @@ async def test_corpus_runner_calls_execute_per_job(monkeypatch):
         return _FakeSession()
 
     monkeypatch.setattr(corpus_runner_module, "async_session_factory", _mock_factory)
-    monkeypatch.setattr(corpus_runner_module, "execute_page_job", _mock_execute)
+    monkeypatch.setattr("app.services.job_runner.execute_page_job", _mock_execute)
 
     await execute_corpus_job("corpus-xyz")