feat(sprint2-session-c): premier appel Google AI → master.json valide

Pipeline d'analyse primaire complet :
- prompt_loader.py : charge et rend les templates {{var}} (R04)
- client_factory.py : construit genai.Client selon le provider (R06, R11)
- response_parser.py: parse JSON brut → layout + OCRResult ; bbox invalide
ignorée individuellement, JSON non parseable → ParseError
- master_writer.py : gemini_raw.json toujours écrit en premier (R05),
master.json seulement si parsing OK
- analyzer.py : run_primary_analysis() chaîne les 4 composants
- test_ai_analyzer.py : 46 tests unitaires (tous passent, aucun appel réseau)

Total : 162 tests passent, 3 skippés (intégration réseau).

https://claude.ai/code/session_018woyEHc8HG2th7V4ewJ4Kg

backend/app/services/ai/__init__.py

@@ -1,10 +1,14 @@
 """
-Services AI — providers Google AI et registre de modèles.
+Services AI — providers Google AI, registre de modèles, et analyse IA.
 """
+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
 
 __all__ = [
     "GoogleAIProvider",
@@ -12,4 +16,9 @@ __all__ = [
     "VertexServiceAccountProvider",
     "list_all_models",
     "build_model_config",
+    "build_client",
+    "load_and_render_prompt",
+    "parse_ai_response",
+    "ParseError",
+    "run_primary_analysis",
 ]

backend/app/services/ai/analyzer.py

@@ -0,0 +1,153 @@
+"""
+Analyse primaire IA d'un folio : appel Google AI + écriture master.json (R02, R04, R05).
+
+Point d'entrée : run_primary_analysis().
+Chaîne : prompt_loader → client_factory → Google AI → master_writer → response_parser.
+"""
+# 1. stdlib
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+
+# 2. third-party
+from google.genai import types
+
+# 3. local
+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.services.ai.client_factory import build_client
+from app.services.ai.master_writer import write_gemini_raw, write_master_json
+from app.services.ai.prompt_loader import load_and_render_prompt
+from app.services.ai.response_parser import ParseError, parse_ai_response  # noqa: F401
+
+logger = logging.getLogger(__name__)
+
+
+def run_primary_analysis(
+    derivative_image_path: Path,
+    corpus_profile: CorpusProfile,
+    model_config: ModelConfig,
+    page_id: str,
+    manuscript_id: str,
+    corpus_slug: str,
+    folio_label: str,
+    sequence: int,
+    image_info: ImageDerivativeInfo,
+    base_data_dir: Path = Path("data"),
+    project_root: Path = Path("."),
+) -> PageMaster:
+    """Analyse primaire d'un folio : charge le prompt, appelle l'IA, écrit les fichiers.
+
+    Respecte R05 : gemini_raw.json est toujours écrit en premier, même en cas
+    d'erreur de parsing. master.json n'est écrit QUE si le parsing a réussi.
+
+    Args:
+        derivative_image_path: chemin vers le JPEG dérivé (1500px max).
+        corpus_profile: profil du corpus (pilote le prompt et les layers).
+        model_config: configuration du modèle sélectionné (provider + model_id).
+        page_id: identifiant unique de la page (ex. "beatus-lat8878-0013r").
+        manuscript_id: identifiant du manuscrit.
+        corpus_slug: identifiant du corpus (ex. "beatus-lat8878").
+        folio_label: label du folio (ex. "0013r").
+        sequence: numéro de séquence dans le manuscrit.
+        image_info: métadonnées de l'image normalisée (dimensions, chemins).
+        base_data_dir: racine du dossier data.
+        project_root: racine du projet (pour résoudre les chemins des prompts).
+
+    Returns:
+        PageMaster validé (gemini_raw.json et master.json écrits sur disque).
+
+    Raises:
+        ParseError: si la réponse IA n'est pas un JSON valide.
+        FileNotFoundError: si le template de prompt est introuvable.
+        RuntimeError: si le provider n'est pas configuré (variable d'env absente).
+    """
+    # ── Chemins de sortie ───────────────────────────────────────────────────
+    page_dir = base_data_dir / "corpora" / corpus_slug / "pages" / folio_label
+    raw_path = page_dir / "gemini_raw.json"
+    master_path = page_dir / "master.json"
+
+    # ── 1. Chargement et rendu du prompt (R04) ──────────────────────────────
+    prompt_rel_path: str = corpus_profile.prompt_templates["primary"]
+    prompt_abs_path = project_root / prompt_rel_path
+
+    context = {
+        "profile_label": corpus_profile.label,
+        "language_hints": ", ".join(corpus_profile.language_hints),
+        "script_type": corpus_profile.script_type.value,
+    }
+    prompt_text = load_and_render_prompt(prompt_abs_path, context)
+    logger.info(
+        "Prompt rendu",
+        extra={"template": prompt_rel_path, "corpus": corpus_slug, "folio": folio_label},
+    )
+
+    # ── 2. Chargement de l'image dérivée ────────────────────────────────────
+    jpeg_bytes = derivative_image_path.read_bytes()
+
+    # ── 3. Appel Google AI ──────────────────────────────────────────────────
+    client = build_client(model_config.provider)
+    image_part = types.Part.from_bytes(data=jpeg_bytes, mime_type="image/jpeg")
+
+    logger.info(
+        "Appel Google AI",
+        extra={
+            "model": model_config.selected_model_id,
+            "corpus": corpus_slug,
+            "folio": folio_label,
+        },
+    )
+    response = client.models.generate_content(
+        model=model_config.selected_model_id,
+        contents=[image_part, prompt_text],
+    )
+    raw_text: str = response.text or ""
+
+    # ── 4. Écriture gemini_raw.json TOUJOURS EN PREMIER (R05) ───────────────
+    write_gemini_raw(raw_text, raw_path)
+
+    # ── 5. Parsing + validation (ParseError si JSON invalide) ───────────────
+    layout, ocr = parse_ai_response(raw_text)
+
+    # ── 6. Construction du PageMaster ───────────────────────────────────────
+    processed_at = datetime.now(tz=timezone.utc)
+    page_master = PageMaster(
+        page_id=page_id,
+        corpus_profile=corpus_profile.profile_id,
+        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,
+        },
+        layout=layout,
+        ocr=ocr,
+        processing=ProcessingInfo(
+            model_id=model_config.selected_model_id,
+            model_display_name=model_config.selected_model_display_name,
+            prompt_version=prompt_rel_path,
+            raw_response_path=str(raw_path),
+            processed_at=processed_at,
+        ),
+        editorial=EditorialInfo(status=EditorialStatus.MACHINE_DRAFT),
+    )
+
+    # ── 7. Écriture master.json (seulement si parsing OK) ───────────────────
+    write_master_json(page_master, master_path)
+
+    logger.info(
+        "Analyse primaire terminée",
+        extra={
+            "page_id": page_id,
+            "corpus": corpus_slug,
+            "folio": folio_label,
+            "regions": len(layout.get("regions", [])),
+        },
+    )
+    return page_master

backend/app/services/ai/client_factory.py

@@ -0,0 +1,97 @@
+"""
+Factory pour créer un genai.Client selon le type de provider (R06, R11).
+
+Standalone — ne modifie pas les fichiers providers de la Session A.
+La clé API n'est jamais dans le code : lue exclusivement depuis les variables
+d'environnement (R06).
+"""
+# 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 ProviderType
+
+logger = logging.getLogger(__name__)
+
+_VERTEX_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
+_DEFAULT_VERTEX_LOCATION = "us-central1"
+
+
+def build_client(provider_type: ProviderType) -> genai.Client:
+    """Crée un genai.Client configuré pour le provider indiqué.
+
+    Lit les variables d'environnement nécessaires selon le provider :
+    - GOOGLE_AI_STUDIO  → GOOGLE_AI_STUDIO_API_KEY
+    - VERTEX_API_KEY    → VERTEX_API_KEY
+    - VERTEX_SA         → VERTEX_SERVICE_ACCOUNT_JSON
+
+    Args:
+        provider_type: type de provider (GOOGLE_AI_STUDIO, VERTEX_API_KEY,
+                       VERTEX_SERVICE_ACCOUNT).
+
+    Returns:
+        Instance genai.Client prête à l'emploi.
+
+    Raises:
+        RuntimeError: si la variable d'environnement requise est absente.
+        ValueError: si le JSON du compte de service est invalide ou incomplet.
+    """
+    if provider_type == ProviderType.GOOGLE_AI_STUDIO:
+        api_key = os.environ.get("GOOGLE_AI_STUDIO_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "Variable d'environnement manquante : GOOGLE_AI_STUDIO_API_KEY"
+            )
+        logger.debug("Client Google AI Studio créé")
+        return genai.Client(api_key=api_key)
+
+    if provider_type == ProviderType.VERTEX_API_KEY:
+        api_key = os.environ.get("VERTEX_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "Variable d'environnement manquante : VERTEX_API_KEY"
+            )
+        logger.debug("Client Vertex AI (clé API) créé")
+        return genai.Client(api_key=api_key)
+
+    if provider_type == ProviderType.VERTEX_SERVICE_ACCOUNT:
+        sa_json_str = os.environ.get("VERTEX_SERVICE_ACCOUNT_JSON")
+        if not sa_json_str:
+            raise RuntimeError(
+                "Variable d'environnement manquante : VERTEX_SERVICE_ACCOUNT_JSON"
+            )
+        try:
+            sa_info = json.loads(sa_json_str)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"VERTEX_SERVICE_ACCOUNT_JSON : JSON invalide — {exc}"
+            ) from exc
+
+        project_id: str | None = sa_info.get("project_id")
+        if not project_id:
+            raise ValueError(
+                "VERTEX_SERVICE_ACCOUNT_JSON : champ 'project_id' manquant dans le JSON"
+            )
+
+        credentials = service_account.Credentials.from_service_account_info(
+            sa_info,
+            scopes=_VERTEX_SCOPES,
+        )
+        logger.debug(
+            "Client Vertex AI (compte de service) créé",
+            extra={"project": project_id},
+        )
+        return genai.Client(
+            vertexai=True,
+            project=project_id,
+            location=_DEFAULT_VERTEX_LOCATION,
+            credentials=credentials,
+        )
+
+    raise ValueError(f"Type de provider inconnu : {provider_type}")

backend/app/services/ai/master_writer.py

@@ -0,0 +1,54 @@
+"""
+Écriture des fichiers gemini_raw.json et master.json (R02, R05).
+
+Règle R05 non négociable :
+  1. gemini_raw.json est TOUJOURS écrit en premier.
+  2. master.json n'est écrit QUE si le parsing et la validation Pydantic ont réussi.
+"""
+# 1. stdlib
+import json
+import logging
+from pathlib import Path
+
+# 3. local
+from app.schemas.page_master import PageMaster
+
+logger = logging.getLogger(__name__)
+
+
+def write_gemini_raw(raw_text: str, output_path: Path) -> None:
+    """Écrit la réponse brute de l'IA dans gemini_raw.json (R05).
+
+    Toujours appelé AVANT toute tentative de parsing.
+    Le contenu est enveloppé dans un objet JSON pour garantir un fichier valide,
+    même si la réponse IA n'est pas du JSON.
+
+    Args:
+        raw_text: texte brut retourné par l'API Google AI.
+        output_path: chemin complet du fichier de sortie (gemini_raw.json).
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"response_text": raw_text}
+    output_path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    logger.info("gemini_raw.json écrit", extra={"path": str(output_path)})
+
+
+def write_master_json(page_master: PageMaster, output_path: Path) -> None:
+    """Écrit le PageMaster validé dans master.json (R02, R05).
+
+    N'est appelé QUE si le parsing et la validation Pydantic ont réussi.
+    Crée les dossiers parents si nécessaire.
+
+    Args:
+        page_master: instance PageMaster validée par Pydantic.
+        output_path: chemin complet du fichier de sortie (master.json).
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(
+        page_master.model_dump_json(indent=2),
+        encoding="utf-8",
+    )
+    logger.info("master.json écrit", extra={"path": str(output_path)})

backend/app/services/ai/prompt_loader.py

@@ -0,0 +1,45 @@
+"""
+Chargement et rendu des templates de prompts depuis le système de fichiers (R04).
+
+Les prompts vivent dans prompts/{profile_id}/{famille}_v{n}.txt.
+Le code charge le fichier, substitue les variables {{nom}}, envoie à l'API.
+"""
+# 1. stdlib
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def load_and_render_prompt(template_path: str | Path, context: dict[str, str]) -> str:
+    """Charge un template de prompt depuis un fichier et substitue les variables.
+
+    Les variables du template ont la forme {{nom_variable}}.
+    Toutes les clés de `context` sont substituées ; les clés absentes du template
+    sont ignorées silencieusement.
+
+    Args:
+        template_path: chemin vers le fichier template (.txt), absolu ou relatif au CWD.
+        context: dictionnaire {nom_variable: valeur} pour la substitution.
+
+    Returns:
+        Texte du prompt avec toutes les variables substituées.
+
+    Raises:
+        FileNotFoundError: si le fichier template n'existe pas.
+    """
+    path = Path(template_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Template de prompt introuvable : {path}")
+
+    template = path.read_text(encoding="utf-8")
+
+    rendered = template
+    for key, value in context.items():
+        rendered = rendered.replace("{{" + key + "}}", value)
+
+    logger.debug(
+        "Prompt chargé et rendu",
+        extra={"template": str(path), "variables": list(context.keys())},
+    )
+    return rendered

backend/app/services/ai/response_parser.py

@@ -0,0 +1,106 @@
+"""
+Parsing et validation de la réponse brute de l'IA → layout dict + OCRResult.
+
+Comportement :
+- JSON non parseable       → ParseError (toute la page échoue)
+- Région avec bbox invalide → région ignorée + log (la page continue)
+- OCR invalide             → OCRResult() par défaut + log (la page continue)
+"""
+# 1. stdlib
+import json
+import logging
+
+# 2. third-party
+from pydantic import ValidationError
+
+# 3. local
+from app.schemas.page_master import OCRResult, Region
+
+logger = logging.getLogger(__name__)
+
+
+class ParseError(Exception):
+    """Levée si la réponse de l'IA est un JSON invalide ou structurellement incorrecte."""
+
+
+def parse_ai_response(raw_text: str) -> tuple[dict, OCRResult]:
+    """Parse la réponse textuelle de l'IA en layout dict + OCRResult validés.
+
+    Les régions avec bbox invalide sont ignorées individuellement (loguées) sans
+    faire échouer toute la page. Un JSON non parseable lève ParseError.
+
+    Gère les balises Markdown (```json ... ```) que certains modèles ajoutent
+    malgré les instructions.
+
+    Args:
+        raw_text: texte brut retourné par l'IA (censé être du JSON strict).
+
+    Returns:
+        Tuple (layout_dict, ocr_result) où layout_dict = {"regions": [...]}.
+
+    Raises:
+        ParseError: si le texte n'est pas du JSON valide ou pas un objet JSON.
+    """
+    # Suppression des balises Markdown éventuelles
+    text = raw_text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        end = len(lines) - 1 if lines[-1].strip() == "```" else len(lines)
+        text = "\n".join(lines[1:end])
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ParseError(
+            f"Réponse IA non parseable en JSON : {exc}"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise ParseError(
+            f"Réponse IA invalide — objet JSON attendu, reçu : {type(data).__name__}"
+        )
+
+    # ── Layout / régions ────────────────────────────────────────────────────
+    raw_layout = data.get("layout")
+    raw_regions: list = []
+    if isinstance(raw_layout, dict):
+        raw_regions = raw_layout.get("regions") or []
+
+    valid_regions: list[dict] = []
+    for i, raw_region in enumerate(raw_regions):
+        try:
+            region = Region.model_validate(raw_region)
+            valid_regions.append(region.model_dump())
+        except (ValidationError, Exception) as exc:
+            logger.warning(
+                "Région ignorée — bbox ou champ invalide",
+                extra={"index": i, "region": raw_region, "error": str(exc)},
+            )
+
+    layout: dict = {"regions": valid_regions}
+
+    # ── OCR ─────────────────────────────────────────────────────────────────
+    raw_ocr = data.get("ocr")
+    ocr: OCRResult
+    if raw_ocr and isinstance(raw_ocr, dict):
+        try:
+            ocr = OCRResult.model_validate(raw_ocr)
+        except ValidationError as exc:
+            logger.warning(
+                "OCR invalide — utilisation des valeurs par défaut",
+                extra={"error": str(exc)},
+            )
+            ocr = OCRResult()
+    else:
+        ocr = OCRResult()
+
+    logger.info(
+        "Réponse IA parsée",
+        extra={
+            "regions_total": len(raw_regions),
+            "regions_valides": len(valid_regions),
+            "regions_ignorees": len(raw_regions) - len(valid_regions),
+            "ocr_confidence": ocr.confidence,
+        },
+    )
+    return layout, ocr

backend/tests/test_ai_analyzer.py

@@ -0,0 +1,871 @@
+"""
+Tests du pipeline d'analyse IA :
+  - prompt_loader  : chargement + rendu des templates
+  - client_factory : construction du genai.Client selon le provider
+  - response_parser: parsing JSON brut → layout + OCRResult
+  - master_writer  : écriture gemini_raw.json et master.json
+  - analyzer       : run_primary_analysis (end-to-end mocké)
+"""
+# 1. stdlib
+import io
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import MagicMock, call, patch
+
+# 2. third-party
+import pytest
+from PIL import Image
+from pydantic import ValidationError
+
+# 3. local
+from app.schemas.corpus_profile import (
+    CorpusProfile,
+    ExportConfig,
+    LayerType,
+    ScriptType,
+    UncertaintyConfig,
+)
+from app.schemas.image import ImageDerivativeInfo
+from app.schemas.model_config import ModelConfig, ProviderType
+from app.schemas.page_master import OCRResult, PageMaster
+from app.services.ai.analyzer import run_primary_analysis
+from app.services.ai.client_factory import build_client
+from app.services.ai.master_writer import write_gemini_raw, write_master_json
+from app.services.ai.prompt_loader import load_and_render_prompt
+from app.services.ai.response_parser import ParseError, parse_ai_response
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_jpeg_bytes(width: int = 100, height: int = 100) -> bytes:
+    img = Image.new("RGB", (width, height), color=(128, 64, 32))
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG", quality=85)
+    return buf.getvalue()
+
+
+def _make_corpus_profile(
+    profile_id: str = "medieval-illuminated",
+    prompt_rel_path: str = "prompts/medieval-illuminated/primary_v1.txt",
+) -> CorpusProfile:
+    return CorpusProfile(
+        profile_id=profile_id,
+        label="Manuscrit médiéval enluminé",
+        language_hints=["la"],
+        script_type=ScriptType.CAROLINE,
+        active_layers=[LayerType.IMAGE, LayerType.OCR_DIPLOMATIC],
+        prompt_templates={"primary": prompt_rel_path},
+        uncertainty_config=UncertaintyConfig(),
+        export_config=ExportConfig(),
+    )
+
+
+def _make_model_config(provider: ProviderType = ProviderType.GOOGLE_AI_STUDIO) -> ModelConfig:
+    return ModelConfig(
+        corpus_id="test-corpus",
+        selected_model_id="gemini-2.0-flash",
+        selected_model_display_name="Gemini 2.0 Flash",
+        provider=provider,
+        supports_vision=True,
+        last_fetched_at=datetime.now(tz=timezone.utc),
+        available_models=[],
+    )
+
+
+def _make_image_info() -> ImageDerivativeInfo:
+    return ImageDerivativeInfo(
+        original_url="https://example.com/iiif/f001.jpg",
+        original_width=3000,
+        original_height=4000,
+        derivative_path="/data/corpora/test-corpus/derivatives/0001r.jpg",
+        derivative_width=1125,
+        derivative_height=1500,
+        thumbnail_path="/data/corpora/test-corpus/derivatives/0001r_thumb.jpg",
+        thumbnail_width=192,
+        thumbnail_height=256,
+    )
+
+
+def _valid_ai_json(regions: list | None = None) -> str:
+    if regions is None:
+        regions = [
+            {"id": "r1", "type": "text_block", "bbox": [10, 20, 300, 400], "confidence": 0.95},
+            {"id": "r2", "type": "miniature", "bbox": [0, 0, 500, 600], "confidence": 0.88},
+        ]
+    return json.dumps({
+        "layout": {"regions": regions},
+        "ocr": {
+            "diplomatic_text": "Incipit liber beati Ieronimi",
+            "blocks": [],
+            "lines": [],
+            "language": "la",
+            "confidence": 0.87,
+            "uncertain_segments": [],
+        },
+    })
+
+
+# ---------------------------------------------------------------------------
+# Tests — load_and_render_prompt
+# ---------------------------------------------------------------------------
+
+def test_prompt_loader_renders_variables(tmp_path):
+    tpl = tmp_path / "prompt.txt"
+    tpl.write_text("Corpus : {{profile_label}}\nLangue : {{language_hints}}")
+
+    result = load_and_render_prompt(tpl, {
+        "profile_label": "Manuscrit test",
+        "language_hints": "la, fr",
+    })
+
+    assert "Manuscrit test" in result
+    assert "la, fr" in result
+    assert "{{profile_label}}" not in result
+    assert "{{language_hints}}" not in result
+
+
+def test_prompt_loader_unknown_variable_kept(tmp_path):
+    """Une variable absente du contexte reste telle quelle dans le texte."""
+    tpl = tmp_path / "prompt.txt"
+    tpl.write_text("Hello {{name}} — {{unknown}}")
+
+    result = load_and_render_prompt(tpl, {"name": "World"})
+
+    assert "World" in result
+    assert "{{unknown}}" in result
+
+
+def test_prompt_loader_empty_context(tmp_path):
+    tpl = tmp_path / "prompt.txt"
+    tpl.write_text("Texte sans variables.")
+
+    result = load_and_render_prompt(tpl, {})
+    assert result == "Texte sans variables."
+
+
+def test_prompt_loader_file_not_found():
+    with pytest.raises(FileNotFoundError):
+        load_and_render_prompt("/nonexistent/path/prompt.txt", {})
+
+
+def test_prompt_loader_accepts_path_object(tmp_path):
+    tpl = tmp_path / "sub" / "tpl.txt"
+    tpl.parent.mkdir()
+    tpl.write_text("OK {{var}}")
+
+    result = load_and_render_prompt(tpl, {"var": "value"})
+    assert result == "OK value"
+
+
+def test_prompt_loader_multiple_occurrences(tmp_path):
+    """Une même variable peut apparaître plusieurs fois."""
+    tpl = tmp_path / "prompt.txt"
+    tpl.write_text("{{x}} et {{x}} encore")
+
+    result = load_and_render_prompt(tpl, {"x": "Z"})
+    assert result == "Z et Z encore"
+
+
+# ---------------------------------------------------------------------------
+# Tests — build_client
+# ---------------------------------------------------------------------------
+
+def test_build_client_google_ai_studio(monkeypatch):
+    monkeypatch.setenv("GOOGLE_AI_STUDIO_API_KEY", "fake-key-studio")
+
+    with patch("app.services.ai.client_factory.genai.Client") as mock_cls:
+        mock_cls.return_value = MagicMock()
+        client = build_client(ProviderType.GOOGLE_AI_STUDIO)
+
+    mock_cls.assert_called_once_with(api_key="fake-key-studio")
+    assert client is mock_cls.return_value
+
+
+def test_build_client_google_ai_studio_missing_env(monkeypatch):
+    monkeypatch.delenv("GOOGLE_AI_STUDIO_API_KEY", raising=False)
+
+    with pytest.raises(RuntimeError, match="GOOGLE_AI_STUDIO_API_KEY"):
+        build_client(ProviderType.GOOGLE_AI_STUDIO)
+
+
+def test_build_client_vertex_api_key(monkeypatch):
+    monkeypatch.setenv("VERTEX_API_KEY", "fake-vertex-key")
+
+    with patch("app.services.ai.client_factory.genai.Client") as mock_cls:
+        mock_cls.return_value = MagicMock()
+        client = build_client(ProviderType.VERTEX_API_KEY)
+
+    mock_cls.assert_called_once_with(api_key="fake-vertex-key")
+    assert client is mock_cls.return_value
+
+
+def test_build_client_vertex_api_key_missing_env(monkeypatch):
+    monkeypatch.delenv("VERTEX_API_KEY", raising=False)
+
+    with pytest.raises(RuntimeError, match="VERTEX_API_KEY"):
+        build_client(ProviderType.VERTEX_API_KEY)
+
+
+def test_build_client_vertex_service_account(monkeypatch):
+    sa_json = json.dumps({
+        "type": "service_account",
+        "project_id": "my-project",
+        "private_key_id": "key-id",
+        "private_key": "-----BEGIN RSA PRIVATE KEY-----\nfake\n-----END RSA PRIVATE KEY-----\n",
+        "client_email": "sa@my-project.iam.gserviceaccount.com",
+        "client_id": "123",
+        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+        "token_uri": "https://oauth2.googleapis.com/token",
+    })
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", sa_json)
+
+    mock_creds = MagicMock()
+    with (
+        patch("app.services.ai.client_factory.service_account.Credentials.from_service_account_info",
+              return_value=mock_creds) as mock_sa,
+        patch("app.services.ai.client_factory.genai.Client") as mock_cls,
+    ):
+        mock_cls.return_value = MagicMock()
+        client = build_client(ProviderType.VERTEX_SERVICE_ACCOUNT)
+
+    mock_sa.assert_called_once()
+    mock_cls.assert_called_once_with(
+        vertexai=True,
+        project="my-project",
+        location="us-central1",
+        credentials=mock_creds,
+    )
+    assert client is mock_cls.return_value
+
+
+def test_build_client_vertex_sa_missing_env(monkeypatch):
+    monkeypatch.delenv("VERTEX_SERVICE_ACCOUNT_JSON", raising=False)
+
+    with pytest.raises(RuntimeError, match="VERTEX_SERVICE_ACCOUNT_JSON"):
+        build_client(ProviderType.VERTEX_SERVICE_ACCOUNT)
+
+
+def test_build_client_vertex_sa_invalid_json(monkeypatch):
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", "not-valid-json{{{")
+
+    with pytest.raises(ValueError, match="JSON invalide"):
+        build_client(ProviderType.VERTEX_SERVICE_ACCOUNT)
+
+
+def test_build_client_vertex_sa_missing_project_id(monkeypatch):
+    sa_json = json.dumps({"type": "service_account"})  # no project_id
+    monkeypatch.setenv("VERTEX_SERVICE_ACCOUNT_JSON", sa_json)
+
+    with pytest.raises(ValueError, match="project_id"):
+        build_client(ProviderType.VERTEX_SERVICE_ACCOUNT)
+
+
+# ---------------------------------------------------------------------------
+# Tests — parse_ai_response
+# ---------------------------------------------------------------------------
+
+def test_parse_valid_response():
+    layout, ocr = parse_ai_response(_valid_ai_json())
+
+    assert len(layout["regions"]) == 2
+    assert layout["regions"][0]["id"] == "r1"
+    assert layout["regions"][0]["type"] == "text_block"
+    assert layout["regions"][0]["bbox"] == [10, 20, 300, 400]
+    assert isinstance(ocr, OCRResult)
+    assert ocr.diplomatic_text == "Incipit liber beati Ieronimi"
+    assert ocr.confidence == pytest.approx(0.87)
+
+
+def test_parse_invalid_json_raises_parse_error():
+    with pytest.raises(ParseError, match="non parseable"):
+        parse_ai_response("this is not json at all {{}")
+
+
+def test_parse_non_object_raises_parse_error():
+    with pytest.raises(ParseError, match="objet JSON attendu"):
+        parse_ai_response("[1, 2, 3]")
+
+
+def test_parse_invalid_bbox_region_is_skipped():
+    """Une région avec bbox invalide est ignorée ; les autres sont conservées."""
+    raw = json.dumps({
+        "layout": {
+            "regions": [
+                {"id": "r1", "type": "text_block", "bbox": [0, 0, 100, 100], "confidence": 0.9},
+                {"id": "r_bad", "type": "text_block", "bbox": [0, 0, -10, 50], "confidence": 0.7},
+                {"id": "r3", "type": "miniature", "bbox": [5, 5, 200, 300], "confidence": 0.8},
+            ]
+        },
+        "ocr": {},
+    })
+
+    layout, ocr = parse_ai_response(raw)
+
+    assert len(layout["regions"]) == 2
+    ids = [r["id"] for r in layout["regions"]]
+    assert "r1" in ids
+    assert "r3" in ids
+    assert "r_bad" not in ids
+
+
+def test_parse_zero_width_bbox_is_skipped():
+    """Une bbox avec width=0 est rejetée par le validator Pydantic."""
+    raw = json.dumps({
+        "layout": {
+            "regions": [
+                {"id": "r1", "type": "text_block", "bbox": [0, 0, 0, 100], "confidence": 0.9},
+            ]
+        },
+        "ocr": {},
+    })
+
+    layout, _ = parse_ai_response(raw)
+    assert len(layout["regions"]) == 0
+
+
+def test_parse_all_bad_regions_returns_empty_layout():
+    raw = json.dumps({
+        "layout": {"regions": [
+            {"id": "r1", "type": "text_block", "bbox": [-5, 0, 100, 100], "confidence": 0.9},
+        ]},
+        "ocr": {},
+    })
+
+    layout, _ = parse_ai_response(raw)
+    assert layout == {"regions": []}
+
+
+def test_parse_missing_layout_returns_empty():
+    raw = json.dumps({"ocr": {"diplomatic_text": "hello", "confidence": 0.5}})
+
+    layout, ocr = parse_ai_response(raw)
+    assert layout == {"regions": []}
+    assert ocr.diplomatic_text == "hello"
+
+
+def test_parse_missing_ocr_returns_default():
+    raw = json.dumps({"layout": {"regions": []}})
+
+    layout, ocr = parse_ai_response(raw)
+    assert isinstance(ocr, OCRResult)
+    assert ocr.diplomatic_text == ""
+    assert ocr.confidence == 0.0
+
+
+def test_parse_markdown_code_fence_stripped():
+    """Les balises ```json ... ``` sont supprimées avant parsing."""
+    inner = json.dumps({"layout": {"regions": []}, "ocr": {}})
+    fenced = f"```json\n{inner}\n```"
+
+    layout, ocr = parse_ai_response(fenced)
+    assert layout == {"regions": []}
+
+
+def test_parse_markdown_code_fence_no_lang_stripped():
+    inner = json.dumps({"layout": {"regions": []}, "ocr": {}})
+    fenced = f"```\n{inner}\n```"
+
+    layout, ocr = parse_ai_response(fenced)
+    assert layout == {"regions": []}
+
+
+def test_parse_invalid_ocr_uses_defaults():
+    """Un champ OCR hors bornes (confidence > 1) → valeurs par défaut."""
+    raw = json.dumps({
+        "layout": {"regions": []},
+        "ocr": {"confidence": 9.9},  # confidence > 1.0 : Pydantic rejette
+    })
+
+    layout, ocr = parse_ai_response(raw)
+    assert ocr.confidence == 0.0  # valeur par défaut
+
+
+def test_parse_empty_regions_list():
+    raw = json.dumps({"layout": {"regions": []}, "ocr": {}})
+    layout, _ = parse_ai_response(raw)
+    assert layout == {"regions": []}
+
+
+# ---------------------------------------------------------------------------
+# Tests — write_gemini_raw / write_master_json
+# ---------------------------------------------------------------------------
+
+def test_write_gemini_raw_creates_file(tmp_path):
+    out = tmp_path / "page" / "gemini_raw.json"
+    write_gemini_raw("raw AI text here", out)
+
+    assert out.exists()
+
+
+def test_write_gemini_raw_valid_json(tmp_path):
+    out = tmp_path / "gemini_raw.json"
+    write_gemini_raw('{"not": "valid json from AI"}', out)
+
+    content = json.loads(out.read_text(encoding="utf-8"))
+    assert "response_text" in content
+    assert content["response_text"] == '{"not": "valid json from AI"}'
+
+
+def test_write_gemini_raw_creates_parent_dirs(tmp_path):
+    out = tmp_path / "deep" / "nested" / "dir" / "gemini_raw.json"
+    write_gemini_raw("text", out)
+    assert out.exists()
+
+
+def test_write_gemini_raw_with_non_json_text(tmp_path):
+    """Même si le texte brut est invalide, gemini_raw.json est créé."""
+    out = tmp_path / "gemini_raw.json"
+    write_gemini_raw("this is not json at all", out)
+
+    content = json.loads(out.read_text(encoding="utf-8"))
+    assert content["response_text"] == "this is not json at all"
+
+
+def _make_page_master() -> PageMaster:
+    return PageMaster(
+        page_id="test-ms-0001r",
+        corpus_profile="medieval-illuminated",
+        manuscript_id="ms-test",
+        folio_label="0001r",
+        sequence=1,
+        image={
+            "original_url": "https://example.com/img.jpg",
+            "derivative_web": "/data/deriv.jpg",
+            "thumbnail": "/data/thumb.jpg",
+            "width": 1500,
+            "height": 2000,
+        },
+        layout={"regions": []},
+        processing={
+            "model_id": "gemini-2.0-flash",
+            "model_display_name": "Gemini 2.0 Flash",
+            "prompt_version": "prompts/medieval-illuminated/primary_v1.txt",
+            "raw_response_path": "/data/gemini_raw.json",
+            "processed_at": datetime.now(tz=timezone.utc),
+        },
+    )
+
+
+def test_write_master_json_creates_file(tmp_path):
+    out = tmp_path / "master.json"
+    pm = _make_page_master()
+    write_master_json(pm, out)
+    assert out.exists()
+
+
+def test_write_master_json_valid_json(tmp_path):
+    out = tmp_path / "master.json"
+    pm = _make_page_master()
+    write_master_json(pm, out)
+
+    content = json.loads(out.read_text(encoding="utf-8"))
+    assert content["page_id"] == "test-ms-0001r"
+    assert content["schema_version"] == "1.0"
+
+
+def test_write_master_json_creates_parent_dirs(tmp_path):
+    out = tmp_path / "a" / "b" / "c" / "master.json"
+    write_master_json(_make_page_master(), out)
+    assert out.exists()
+
+
+def test_write_master_json_contains_processing_info(tmp_path):
+    out = tmp_path / "master.json"
+    write_master_json(_make_page_master(), out)
+
+    content = json.loads(out.read_text(encoding="utf-8"))
+    assert content["processing"]["model_id"] == "gemini-2.0-flash"
+    assert content["processing"]["prompt_version"] == "prompts/medieval-illuminated/primary_v1.txt"
+
+
+# ---------------------------------------------------------------------------
+# Tests — run_primary_analysis (end-to-end mocké)
+# ---------------------------------------------------------------------------
+
+def _setup_prompt_file(tmp_path: Path, rel_path: str) -> Path:
+    """Crée le fichier template dans tmp_path/rel_path."""
+    full = tmp_path / rel_path
+    full.parent.mkdir(parents=True, exist_ok=True)
+    full.write_text(
+        "Analyse {{profile_label}} en {{language_hints}} ({{script_type}}).",
+        encoding="utf-8",
+    )
+    return full
+
+
+def _setup_derivative(tmp_path: Path) -> Path:
+    """Crée un JPEG dérivé factice dans tmp_path."""
+    deriv = tmp_path / "derivative.jpg"
+    deriv.write_bytes(_make_jpeg_bytes(200, 300))
+    return deriv
+
+
+def _make_mock_client(ai_response_text: str) -> MagicMock:
+    mock_response = MagicMock()
+    mock_response.text = ai_response_text
+    mock_client = MagicMock()
+    mock_client.models.generate_content.return_value = mock_response
+    return mock_client
+
+
+def test_run_primary_analysis_success(tmp_path):
+    """Cas nominal : retourne un PageMaster, crée les deux fichiers."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    profile = _make_corpus_profile(prompt_rel_path=prompt_rel)
+    model_cfg = _make_model_config()
+    image_info = _make_image_info()
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=profile,
+            model_config=model_cfg,
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=image_info,
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert isinstance(result, PageMaster)
+    assert result.page_id == "test-corpus-0001r"
+    assert result.corpus_profile == "medieval-illuminated"
+    assert result.folio_label == "0001r"
+    assert result.sequence == 1
+
+
+def test_run_primary_analysis_files_created(tmp_path):
+    """Les deux fichiers obligatoires (R05) sont créés sur disque."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    page_dir = tmp_path / "data" / "corpora" / "test-corpus" / "pages" / "0001r"
+    assert (page_dir / "gemini_raw.json").exists()
+    assert (page_dir / "master.json").exists()
+
+
+def test_run_primary_analysis_raw_written_before_parse(tmp_path):
+    """gemini_raw.json est écrit AVANT que le parsing échoue (R05)."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client("this is definitely not json {{{{")
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        with pytest.raises(ParseError):
+            run_primary_analysis(
+                derivative_image_path=deriv_path,
+                corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+                model_config=_make_model_config(),
+                page_id="test-corpus-0001r",
+                manuscript_id="ms-test",
+                corpus_slug="test-corpus",
+                folio_label="0001r",
+                sequence=1,
+                image_info=_make_image_info(),
+                base_data_dir=tmp_path / "data",
+                project_root=tmp_path,
+            )
+
+    # gemini_raw.json existe malgré l'échec de parsing
+    raw_path = tmp_path / "data" / "corpora" / "test-corpus" / "pages" / "0001r" / "gemini_raw.json"
+    assert raw_path.exists()
+
+    # master.json N'existe PAS (parsing a échoué)
+    master_path = tmp_path / "data" / "corpora" / "test-corpus" / "pages" / "0001r" / "master.json"
+    assert not master_path.exists()
+
+
+def test_run_primary_analysis_processing_info(tmp_path):
+    """ProcessingInfo contient le bon model_id et prompt_version."""
+    prompt_rel = "prompts/test-profile/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    profile = _make_corpus_profile(
+        profile_id="test-profile",
+        prompt_rel_path=prompt_rel,
+    )
+    model_cfg = _make_model_config()
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=profile,
+            model_config=model_cfg,
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert result.processing is not None
+    assert result.processing.model_id == "gemini-2.0-flash"
+    assert result.processing.model_display_name == "Gemini 2.0 Flash"
+    assert result.processing.prompt_version == prompt_rel
+
+
+def test_run_primary_analysis_image_dict(tmp_path):
+    """Le dict image du PageMaster reprend les données de ImageDerivativeInfo."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    image_info = _make_image_info()
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=image_info,
+            base_data_dir=tmp_path / "data",
+            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
+
+
+def test_run_primary_analysis_regions_in_layout(tmp_path):
+    """Les régions valides de la réponse IA sont dans layout du PageMaster."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert len(result.layout["regions"]) == 2
+
+
+def test_run_primary_analysis_prompt_rendered_with_profile(tmp_path):
+    """Le prompt envoyé à l'IA contient les valeurs du profil substituées."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    tpl = tmp_path / prompt_rel
+    tpl.parent.mkdir(parents=True, exist_ok=True)
+    tpl.write_text("Profil: {{profile_label}} | Script: {{script_type}}")
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client(_valid_ai_json())
+    profile = _make_corpus_profile(prompt_rel_path=prompt_rel)
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=profile,
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    # Vérifier que generate_content a été appelé avec le prompt rendu
+    call_args = mock_client.models.generate_content.call_args
+    contents = call_args.kwargs.get("contents") or call_args.args[0] if call_args.args else call_args.kwargs["contents"]
+    prompt_sent = contents[-1]  # le prompt est le dernier élément
+    assert "Manuscrit médiéval enluminé" in prompt_sent
+    assert "caroline" in prompt_sent
+    assert "{{profile_label}}" not in prompt_sent
+
+
+def test_run_primary_analysis_prompt_not_found_raises(tmp_path):
+    """FileNotFoundError si le template de prompt n'existe pas."""
+    deriv_path = _setup_derivative(tmp_path)
+    profile = _make_corpus_profile(prompt_rel_path="prompts/nonexistent/prompt.txt")
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        with pytest.raises(FileNotFoundError):
+            run_primary_analysis(
+                derivative_image_path=deriv_path,
+                corpus_profile=profile,
+                model_config=_make_model_config(),
+                page_id="test-corpus-0001r",
+                manuscript_id="ms-test",
+                corpus_slug="test-corpus",
+                folio_label="0001r",
+                sequence=1,
+                image_info=_make_image_info(),
+                base_data_dir=tmp_path / "data",
+                project_root=tmp_path,
+            )
+
+
+def test_run_primary_analysis_ocr_in_result(tmp_path):
+    """Le résultat OCR est bien présent dans le PageMaster."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert result.ocr is not None
+    assert result.ocr.diplomatic_text == "Incipit liber beati Ieronimi"
+    assert result.ocr.language == "la"
+
+
+def test_run_primary_analysis_editorial_status_machine_draft(tmp_path):
+    """Le statut éditorial initial est machine_draft."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert result.editorial.status.value == "machine_draft"
+
+
+def test_run_primary_analysis_master_json_content(tmp_path):
+    """Le master.json écrit sur disque est un JSON valide avec schema_version."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    mock_client = _make_mock_client(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    master_path = tmp_path / "data" / "corpora" / "test-corpus" / "pages" / "0001r" / "master.json"
+    content = json.loads(master_path.read_text(encoding="utf-8"))
+    assert content["schema_version"] == "1.0"
+    assert content["page_id"] == "test-corpus-0001r"
+
+
+def test_run_primary_analysis_invalid_region_skipped(tmp_path):
+    """Une région invalide dans la réponse IA est ignorée sans lever d'exception."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+    deriv_path = _setup_derivative(tmp_path)
+
+    response_with_bad_region = json.dumps({
+        "layout": {"regions": [
+            {"id": "r_good", "type": "text_block", "bbox": [0, 0, 100, 100], "confidence": 0.9},
+            {"id": "r_bad", "type": "text_block", "bbox": [-1, 0, 100, 100], "confidence": 0.9},
+        ]},
+        "ocr": {},
+    })
+    mock_client = _make_mock_client(response_with_bad_region)
+
+    with patch("app.services.ai.analyzer.build_client", return_value=mock_client):
+        result = run_primary_analysis(
+            derivative_image_path=deriv_path,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-corpus-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert len(result.layout["regions"]) == 1
+    assert result.layout["regions"][0]["id"] == "r_good"