fix(sprint-f2): fiabilité — error handling, async I/O, pagination, cache, prompts

Sprint F2 — corrections de fiabilité et d'architecture :

- Error handling providers IA : try/catch autour de generate_content()
dans Google AI, Vertex SA et Mistral (log structuré + RuntimeError)
- Error handling analyzer.py : vérification existence image avant lecture,
catch OSError sur read_bytes()
- Error handling master_writer.py : try/catch sur mkdir + write_text
avec log d'erreur avant re-raise
- Async I/O : search.py, profiles.py, export.py — toutes les lectures
fichiers bloquantes wrappées dans asyncio.to_thread()
- Transactions ingest : cleanup des fichiers orphelins si commit BDD
échoue (written_files track + unlink on exception)
- Pagination : skip/limit sur list_corpora (défaut 100, max 1000),
limit sur search_pages (défaut 200, max 2000)
- Cache providers : singleton _cached_providers dans model_registry.py
(évite de recréer 4 instances à chaque requête)
- Prompt loader : validation des variables non résolues {{...}}
conformément à CLAUDE.md §8

477 tests passants, 0 échecs.

https://claude.ai/code/session_015Lht7wNQRzhUaLw94dE9z9

backend/app/api/v1/corpora.py

@@ -14,7 +14,7 @@ import uuid
 from datetime import datetime, timezone
 
 # 2. third-party
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -59,9 +59,13 @@ class ManuscriptResponse(BaseModel):
 # ── Endpoints ────────────────────────────────────────────────────────────────
 
 @router.get("", response_model=list[CorpusResponse])
-async def list_corpora(db: AsyncSession = Depends(get_db)) -> list[CorpusModel]:
-    """Retourne tous les corpus enregistrés."""
-    result = await db.execute(select(CorpusModel))
+async def list_corpora(
+    db: AsyncSession = Depends(get_db),
+    skip: int = Query(0, ge=0, description="Nombre d'éléments à sauter"),
+    limit: int = Query(100, ge=1, le=1000, description="Nombre maximum d'éléments"),
+) -> list[CorpusModel]:
+    """Retourne les corpus enregistrés (paginé)."""
+    result = await db.execute(select(CorpusModel).offset(skip).limit(limit))
     return list(result.scalars().all())
 
 

backend/app/api/v1/export.py

@@ -10,6 +10,7 @@ Règle (R02) : toutes les sorties sont générées depuis les PageMasters
 (master.json), jamais depuis les réponses brutes de l'IA.
 """
 # 1. stdlib
+import asyncio
 import io
 import json
 import logging
@@ -66,7 +67,7 @@ async def _load_manuscript_with_masters(
 
     masters: list[PageMaster] = []
     for page in pages:
-        master = _read_master_json(corpus.slug, page.id)
+        master = await _read_master_json(corpus.slug, page.id)
         if master is not None:
             masters.append(master)
 
@@ -79,8 +80,8 @@ async def _load_manuscript_with_masters(
     return manuscript, corpus, masters
 
 
-def _read_master_json(corpus_slug: str, page_id: str) -> PageMaster | None:
-    """Lit le master.json d'une page depuis data/. Retourne None si absent."""
+def _read_master_json_sync(corpus_slug: str, page_id: str) -> PageMaster | None:
+    """Lit le master.json d'une page depuis data/. Retourne None si absent (bloquant)."""
     path = (
         _config_module.settings.data_dir
         / "corpora"
@@ -95,6 +96,11 @@ def _read_master_json(corpus_slug: str, page_id: str) -> PageMaster | None:
     return PageMaster.model_validate(raw)
 
 
+async def _read_master_json(corpus_slug: str, page_id: str) -> PageMaster | None:
+    """Version async — délègue la lecture au threadpool."""
+    return await asyncio.to_thread(_read_master_json_sync, corpus_slug, page_id)
+
+
 def _build_manuscript_meta(
     manuscript: ManuscriptModel, corpus: CorpusModel
 ) -> dict:
@@ -154,7 +160,7 @@ async def get_alto(page_id: str, db: AsyncSession = Depends(get_db)) -> Response
     manuscript = await db.get(ManuscriptModel, page.manuscript_id)
     corpus = await db.get(CorpusModel, manuscript.corpus_id)
 
-    master = _read_master_json(corpus.slug, page_id)
+    master = await _read_master_json(corpus.slug, page_id)
     if master is None:
         raise HTTPException(
             status_code=404,

backend/app/api/v1/ingest.py

@@ -249,6 +249,7 @@ async def ingest_files(
     dupes = _find_duplicate_labels(labels)
 
     created: list[PageModel] = []
+    written_files: list[Path] = []
     skipped = 0
     for i, upload in enumerate(files):
         # Validation MIME type
@@ -281,6 +282,7 @@ async def ingest_files(
         master_dir.mkdir(parents=True, exist_ok=True)
         master_path = master_dir / filename
         master_path.write_bytes(content)
+        written_files.append(master_path)
 
         page = await _create_page(
             db, ms.id, page_id, folio_label, seq + i,
@@ -292,7 +294,13 @@ async def ingest_files(
             created.append(page)
 
     ms.total_pages = (ms.total_pages or 0) + len(created)
-    await db.commit()
+    try:
+        await db.commit()
+    except Exception:
+        # Nettoyage des fichiers orphelins si le commit BDD échoue
+        for f in written_files:
+            f.unlink(missing_ok=True)
+        raise
 
     logger.info(
         "Fichiers ingérés",

backend/app/api/v1/profiles.py

@@ -8,6 +8,7 @@ Les profils sont des fichiers JSON dans profiles/ (racine du dépôt).
 Ils sont validés par CorpusProfile avant d'être retournés.
 """
 # 1. stdlib
+import asyncio
 import json
 import logging
 import re
@@ -50,12 +51,16 @@ async def list_profiles() -> list[dict]:
     if not settings.profiles_dir.is_dir():
         logger.warning("profiles_dir introuvable : %s", settings.profiles_dir)
         return []
-    profiles = []
-    for path in sorted(settings.profiles_dir.glob("*.json")):
-        profile = _load_profile(path)
-        if profile is not None:
-            profiles.append(profile.model_dump())
-    return profiles
+
+    def _scan_profiles() -> list[dict]:
+        result = []
+        for path in sorted(settings.profiles_dir.glob("*.json")):
+            profile = _load_profile(path)
+            if profile is not None:
+                result.append(profile.model_dump())
+        return result
+
+    return await asyncio.to_thread(_scan_profiles)
 
 
 _SAFE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
@@ -67,9 +72,15 @@ async def get_profile(profile_id: str) -> dict:
     if not _SAFE_ID_RE.match(profile_id):
         raise HTTPException(status_code=400, detail="profile_id invalide")
     path = settings.profiles_dir / f"{profile_id}.json"
-    if not path.exists():
+
+    def _read() -> CorpusProfile | None:
+        if not path.exists():
+            return None
+        return _load_profile(path)
+
+    profile = await asyncio.to_thread(_read)
+    if profile is None and not path.exists():
         raise HTTPException(status_code=404, detail="Profil introuvable")
-    profile = _load_profile(path)
     if profile is None:
         raise HTTPException(status_code=422, detail="Profil invalide")
     return profile.model_dump()

backend/app/api/v1/search.py

@@ -7,6 +7,7 @@ Implémentation MVP : scan des fichiers master.json (pas d'index externe).
 Insensible à la casse et aux accents (unicodedata NFD + ASCII).
 """
 # 1. stdlib
+import asyncio
 import json
 import logging
 import unicodedata
@@ -96,6 +97,7 @@ def _score_master(data: dict, query_normalized: str) -> tuple[int, str]:
 @router.get("/search", response_model=list[SearchResult])
 async def search_pages(
     q: str = Query(..., min_length=2, max_length=500, description="Requête de recherche (2–500 caractères)"),
+    limit: int = Query(200, ge=1, le=2000, description="Nombre maximum de résultats"),
 ) -> list[SearchResult]:
     """Recherche plein texte dans les master.json de tous les corpus.
 
@@ -106,29 +108,32 @@ async def search_pages(
     query_normalized = _normalize(q.strip())
     data_dir = _config_module.settings.data_dir
 
-    results: list[SearchResult] = []
-
-    for master_path in data_dir.glob("corpora/*/pages/*/master.json"):
-        try:
-            raw: dict = json.loads(master_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
-            continue
-
-        score, excerpt = _score_master(raw, query_normalized)
-        if score == 0:
-            continue
-
-        results.append(
-            SearchResult(
-                page_id=raw.get("page_id", ""),
-                folio_label=raw.get("folio_label", ""),
-                manuscript_id=raw.get("manuscript_id", ""),
-                excerpt=excerpt,
-                score=score,
-                corpus_profile=raw.get("corpus_profile", ""),
+    def _scan() -> list[SearchResult]:
+        """Scan bloquant exécuté dans un thread dédié."""
+        hits: list[SearchResult] = []
+        for master_path in data_dir.glob("corpora/*/pages/*/master.json"):
+            try:
+                raw: dict = json.loads(master_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+
+            score, excerpt = _score_master(raw, query_normalized)
+            if score == 0:
+                continue
+
+            hits.append(
+                SearchResult(
+                    page_id=raw.get("page_id", ""),
+                    folio_label=raw.get("folio_label", ""),
+                    manuscript_id=raw.get("manuscript_id", ""),
+                    excerpt=excerpt,
+                    score=score,
+                    corpus_profile=raw.get("corpus_profile", ""),
+                )
             )
-        )
+        hits.sort(key=lambda r: r.score, reverse=True)
+        return hits
 
-    results.sort(key=lambda r: r.score, reverse=True)
+    results = await asyncio.to_thread(_scan)
     logger.info("Recherche exécutée", extra={"q": q, "results": len(results)})
-    return results
+    return results[:limit]

backend/app/services/ai/analyzer.py

@@ -85,7 +85,12 @@ def run_primary_analysis(
     )
 
     # ── 2. Chargement de l'image dérivée ────────────────────────────────────
-    jpeg_bytes = derivative_image_path.read_bytes()
+    if not derivative_image_path.exists():
+        raise FileNotFoundError(f"Image dérivée introuvable : {derivative_image_path}")
+    try:
+        jpeg_bytes = derivative_image_path.read_bytes()
+    except OSError as exc:
+        raise RuntimeError(f"Erreur lecture image {derivative_image_path} : {exc}") from exc
 
     # ── 3. Appel IA via le provider sélectionné ─────────────────────────────
     provider = get_provider(model_config.provider)

backend/app/services/ai/master_writer.py

@@ -22,17 +22,17 @@ def write_gemini_raw(raw_text: str, output_path: Path) -> None:
     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",
-    )
+    try:
+        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",
+        )
+    except OSError as exc:
+        logger.error("Écriture gemini_raw.json échouée", extra={"path": str(output_path), "error": str(exc)})
+        raise
     logger.info("gemini_raw.json écrit", extra={"path": str(output_path)})
 
 
@@ -41,14 +41,14 @@ def write_master_json(page_master: PageMaster, output_path: Path) -> None:
 
     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",
-    )
+    try:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(
+            page_master.model_dump_json(indent=2),
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        logger.error("Écriture master.json échouée", extra={"path": str(output_path), "error": str(exc)})
+        raise
     logger.info("master.json écrit", extra={"path": str(output_path)})

backend/app/services/ai/model_registry.py

@@ -23,19 +23,27 @@ _PROVIDER_DISPLAY_NAMES: dict[ProviderType, str] = {
 }
 
 
+_cached_providers: list[AIProvider] | None = None
+
+
 def _build_providers() -> list[AIProvider]:
-    """Construit la liste des providers — imports différés."""
+    """Construit la liste des providers — imports différés, résultat mis en cache."""
+    global _cached_providers
+    if _cached_providers is not None:
+        return _cached_providers
+
     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 [
+    _cached_providers = [
         GoogleAIProvider(),
         VertexAPIKeyProvider(),
         VertexServiceAccountProvider(),
         MistralProvider(),
     ]
+    return _cached_providers
 
 
 def get_available_providers() -> list[dict]:

backend/app/services/ai/prompt_loader.py

@@ -6,6 +6,7 @@ Le code charge le fichier, substitue les variables {{nom}}, envoie à l'API.
 """
 # 1. stdlib
 import logging
+import re
 from pathlib import Path
 
 logger = logging.getLogger(__name__)
@@ -38,6 +39,11 @@ def load_and_render_prompt(template_path: str | Path, context: dict[str, str]) -
     for key, value in context.items():
         rendered = rendered.replace("{{" + key + "}}", value)
 
+    # Vérifier qu'il ne reste pas de variables non résolues (CLAUDE.md §8)
+    unresolved = re.findall(r"\{\{\w+\}\}", rendered)
+    if unresolved:
+        raise ValueError(f"Variables non résolues dans le prompt : {unresolved}")
+
     logger.debug(
         "Prompt chargé et rendu",
         extra={"template": str(path), "variables": list(context.keys())},

backend/app/services/ai/provider_google_ai.py

@@ -60,8 +60,15 @@ class GoogleAIProvider(AIProvider):
             raise RuntimeError(f"Variable d'environnement manquante : {_ENV_KEY}")
         client = genai.Client(api_key=os.environ[_ENV_KEY])
         image_part = types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg")
-        response = client.models.generate_content(
-            model=model_id,
-            contents=[image_part, prompt],
-        )
+        try:
+            response = client.models.generate_content(
+                model=model_id,
+                contents=[image_part, prompt],
+            )
+        except Exception as exc:
+            logger.error(
+                "Appel API Google AI Studio échoué",
+                extra={"model": model_id, "error": str(exc)},
+            )
+            raise RuntimeError(f"Erreur API Google AI Studio ({model_id}) : {exc}") from exc
         return response.text or ""

backend/app/services/ai/provider_mistral.py

@@ -208,10 +208,14 @@ class MistralProvider(AIProvider):
         # ── Chemin 1 : OCR dédié ─────────────────────────────────────────────
         if _is_ocr_model(model_id):
             logger.info("Mistral OCR : endpoint dédié client.ocr.process()", extra={"model": model_id})
-            response = client.ocr.process(
-                model=model_id,
-                document={"type": "image_url", "image_url": {"url": data_url}},
-            )
+            try:
+                response = client.ocr.process(
+                    model=model_id,
+                    document={"type": "image_url", "image_url": {"url": data_url}},
+                )
+            except Exception as exc:
+                logger.error("Appel Mistral OCR échoué", extra={"model": model_id, "error": str(exc)})
+                raise RuntimeError(f"Erreur API Mistral OCR ({model_id}) : {exc}") from exc
             # OCRResponse.pages : list[OCRPageObject], chacun avec .markdown
             pages = getattr(response, "pages", []) or []
             return "\n\n".join(
@@ -233,10 +237,14 @@ class MistralProvider(AIProvider):
             )
             content = prompt
 
-        response = client.chat.complete(
-            model=model_id,
-            messages=[{"role": "user", "content": content}],
-        )
+        try:
+            response = client.chat.complete(
+                model=model_id,
+                messages=[{"role": "user", "content": content}],
+            )
+        except Exception as exc:
+            logger.error("Appel Mistral chat échoué", extra={"model": model_id, "error": str(exc)})
+            raise RuntimeError(f"Erreur API Mistral ({model_id}) : {exc}") from exc
         choices = response.choices or []
         if not choices:
             return ""

backend/app/services/ai/provider_vertex_sa.py

@@ -90,8 +90,15 @@ class VertexServiceAccountProvider(AIProvider):
             raise RuntimeError(f"Variable d'environnement manquante : {_ENV_KEY}")
         client = self._build_client()
         image_part = types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg")
-        response = client.models.generate_content(
-            model=model_id,
-            contents=[image_part, prompt],
-        )
+        try:
+            response = client.models.generate_content(
+                model=model_id,
+                contents=[image_part, prompt],
+            )
+        except Exception as exc:
+            logger.error(
+                "Appel API Vertex AI échoué",
+                extra={"model": model_id, "error": str(exc)},
+            )
+            raise RuntimeError(f"Erreur API Vertex AI ({model_id}) : {exc}") from exc
         return response.text or ""