perf: Sprint 2a — caching, parallel pipeline, async I/O, tests

Performance:
- Cache AI providers singleton (model_registry.py)
- LRU cache for prompt templates (prompt_loader.py)
- Cache profiles at startup (profiles.py)
- Parallelize corpus_runner with asyncio.Semaphore(3) + gather
- Wrap all blocking I/O in job_runner with asyncio.to_thread
- Defer base64 encoding in Mistral provider (skip for text-only models)

Code quality:
- Add pagination to list_manuscripts endpoint
- Add 31 new tests for response_parser and prompt_loader

https://claude.ai/code/session_012NCh8yLxMXkRmBYQgHCTik

backend/app/api/v1/corpora.py

@@ -127,13 +127,19 @@ async def delete_corpus(corpus_id: str, db: AsyncSession = Depends(get_db)) -> N
 
 @router.get("/{corpus_id}/manuscripts", response_model=list[ManuscriptResponse])
 async def list_manuscripts(
-    corpus_id: str, db: AsyncSession = Depends(get_db)
+    corpus_id: str,
+    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[ManuscriptModel]:
-    """Retourne tous les manuscrits d'un corpus."""
+    """Retourne les manuscrits d'un corpus (paginé)."""
     corpus = await db.get(CorpusModel, corpus_id)
     if corpus is None:
         raise HTTPException(status_code=404, detail="Corpus introuvable")
     result = await db.execute(
-        select(ManuscriptModel).where(ManuscriptModel.corpus_id == corpus_id)
+        select(ManuscriptModel)
+        .where(ManuscriptModel.corpus_id == corpus_id)
+        .offset(skip)
+        .limit(limit)
     )
     return list(result.scalars().all())

backend/app/api/v1/profiles.py

@@ -26,6 +26,27 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/profiles", tags=["profiles"])
 
+_profiles_cache: dict[str, CorpusProfile] | None = None
+
+
+def _load_all_profiles() -> dict[str, CorpusProfile]:
+    """Charge tous les profils depuis le disque (cache singleton)."""
+    global _profiles_cache
+    if _profiles_cache is not None:
+        return _profiles_cache
+
+    result: dict[str, CorpusProfile] = {}
+    if settings.profiles_dir.is_dir():
+        for path in sorted(settings.profiles_dir.glob("*.json")):
+            profile = _load_profile(path)
+            if profile is not None:
+                result[profile.profile_id] = profile
+    else:
+        logger.warning("profiles_dir introuvable : %s", settings.profiles_dir)
+
+    _profiles_cache = result
+    return _profiles_cache
+
 
 def _load_profile(path: Path) -> CorpusProfile | None:
     """Charge et valide un fichier de profil JSON. Retourne None si invalide."""
@@ -40,27 +61,8 @@ def _load_profile(path: Path) -> CorpusProfile | None:
 @router.get("", response_model=list[dict])
 async def list_profiles() -> list[dict]:
     """Retourne tous les profils valides du dossier profiles/."""
-    logger.info(
-        "Résolution profiles_dir",
-        extra={
-            "profiles_dir": str(settings.profiles_dir),
-            "resolved": str(settings.profiles_dir.resolve()),
-            "is_dir": settings.profiles_dir.is_dir(),
-        },
-    )
-    if not settings.profiles_dir.is_dir():
-        logger.warning("profiles_dir introuvable : %s", settings.profiles_dir)
-        return []
-
-    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)
+    profiles = _load_all_profiles()
+    return [p.model_dump() for p in profiles.values()]
 
 
 _SAFE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
@@ -71,16 +73,9 @@ async def get_profile(profile_id: str) -> dict:
     """Retourne un profil par son id (nom du fichier sans extension)."""
     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"
-
-    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")
+    profiles = _load_all_profiles()
+    profile = profiles.get(profile_id)
     if profile is None:
-        raise HTTPException(status_code=422, detail="Profil invalide")
+        raise HTTPException(status_code=404, detail="Profil introuvable")
     return profile.model_dump()

backend/app/services/ai/model_registry.py

@@ -23,24 +23,27 @@ _PROVIDER_DISPLAY_NAMES: dict[ProviderType, str] = {
 }
 
 
+_providers_cache: 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, cache singleton."""
+    global _providers_cache
+    if _providers_cache is not None:
+        return _providers_cache
 
-    Pas de cache global : la construction est triviale (4 objets légers)
-    et l'absence de cache permet de détecter immédiatement les changements
-    de variables d'environnement sans redémarrage.
-    """
     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 [
+    _providers_cache = [
         GoogleAIProvider(),
         VertexAPIKeyProvider(),
         VertexServiceAccountProvider(),
         MistralProvider(),
     ]
+    return _providers_cache
 
 
 def get_available_providers() -> list[dict]:

backend/app/services/ai/prompt_loader.py

@@ -7,11 +7,21 @@ Le code charge le fichier, substitue les variables {{nom}}, envoie à l'API.
 # 1. stdlib
 import logging
 import re
+from functools import lru_cache
 from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
 
+@lru_cache(maxsize=32)
+def _read_template(path_str: str) -> str:
+    """Lit un template depuis le disque avec cache LRU."""
+    path = Path(path_str)
+    if not path.exists():
+        raise FileNotFoundError(f"Template introuvable : {path_str}")
+    return path.read_text(encoding="utf-8")
+
+
 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.
 
@@ -30,10 +40,8 @@ def load_and_render_prompt(template_path: str | Path, context: dict[str, str]) -
         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")
+    template = _read_template(str(path))
 
     rendered = template
     for key, value in context.items():

backend/app/services/ai/provider_mistral.py

@@ -213,8 +213,10 @@ class MistralProvider(AIProvider):
         from mistralai import Mistral
 
         client = Mistral(api_key=os.environ[_ENV_KEY])
-        image_b64 = base64.b64encode(image_bytes).decode("utf-8")
-        data_url = f"data:image/jpeg;base64,{image_b64}"
+
+        # Encodage base64 différé — calculé uniquement si le modèle a besoin de l'image
+        def _image_data_url() -> str:
+            return f"data:image/jpeg;base64,{base64.b64encode(image_bytes).decode('utf-8')}"
 
         # ── Chemin 1 : OCR dédié ─────────────────────────────────────────────
         if _is_ocr_model(model_id):
@@ -222,7 +224,7 @@ class MistralProvider(AIProvider):
             try:
                 response = client.ocr.process(
                     model=model_id,
-                    document={"type": "image_url", "image_url": {"url": data_url}},
+                    document={"type": "image_url", "image_url": {"url": _image_data_url()}},
                 )
             except Exception as exc:
                 logger.error("Appel Mistral OCR échoué", extra={"model": model_id, "error": str(exc)})
@@ -236,7 +238,7 @@ class MistralProvider(AIProvider):
         # ── Chemin 2 : Vision multimodale ────────────────────────────────────
         if supports_vision:
             content: object = [
-                {"type": "image_url", "image_url": {"url": data_url}},
+                {"type": "image_url", "image_url": {"url": _image_data_url()}},
                 {"type": "text", "text": prompt},
             ]
         # ── Chemin 3 : Texte seul ─────────────────────────────────────────────

backend/app/services/corpus_runner.py

@@ -9,6 +9,7 @@ Point d'entrée : execute_corpus_job(corpus_id)
 Chaque page reçoit sa propre session pour isoler les échecs.
 """
 # 1. stdlib
+import asyncio
 import logging
 
 # 2. third-party
@@ -58,11 +59,18 @@ async def execute_corpus_job(corpus_id: str) -> dict:
         extra={"corpus_id": corpus_id, "jobs": len(job_ids)},
     )
 
-    # Exécution séquentielle — chaque job gère sa propre session
+    # Exécution concurrente avec semaphore — 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)
+    _MAX_CONCURRENT = 3  # limiter la pression sur les APIs IA
+
+    sem = asyncio.Semaphore(_MAX_CONCURRENT)
+
+    async def _run_one(jid: str) -> None:
+        async with sem:
+            await execute_page_job(jid)
+
+    await asyncio.gather(*[_run_one(jid) for jid in job_ids])
 
     # Bilan final
     async with async_session_factory() as db:

backend/app/services/job_runner.py

@@ -17,6 +17,7 @@ Sur toute exception : job → FAILED + error_message, page → ERROR.
 Aucun échec silencieux (CLAUDE.md §7).
 """
 # 1. stdlib
+import asyncio
 import json
 import logging
 from datetime import datetime, timezone
@@ -139,7 +140,8 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
 
         if page.iiif_service_url:
             # ── Mode IIIF natif : fetch en mémoire, zéro stockage ────────────
-            deriv_bytes, deriv_w, deriv_h = fetch_ai_derivative_bytes(
+            deriv_bytes, deriv_w, deriv_h = await asyncio.to_thread(
+                fetch_ai_derivative_bytes,
                 iiif_service_url=page.iiif_service_url,
                 fallback_url=None,
             )
@@ -153,7 +155,8 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
             )
 
             # ── 6. Analyse primaire IA (R05 : double stockage) ───────────────
-            page_master = run_primary_analysis(
+            page_master = await asyncio.to_thread(
+                run_primary_analysis,
                 derivative_image_bytes=deriv_bytes,
                 derivative_width=deriv_w,
                 derivative_height=deriv_h,
@@ -171,10 +174,12 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
 
         elif image_source.startswith(("http://", "https://")):
             # ── Mode fallback URL : télécharge + stocke sur disque (legacy) ──
-            image_info = fetch_and_normalize(
+            image_info = await asyncio.to_thread(
+                fetch_and_normalize,
                 image_source, corpus.slug, page.folio_label, data_dir
             )
-            page_master = run_primary_analysis(
+            page_master = await asyncio.to_thread(
+                run_primary_analysis,
                 derivative_image_path=Path(image_info.derivative_path),
                 corpus_profile=corpus_profile,
                 model_config=model_config,
@@ -198,10 +203,12 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
                     f"{image_source!r} (résolu : {source_path})"
                 )
             source_bytes = source_path.read_bytes()
-            image_info = create_derivatives(
+            image_info = await asyncio.to_thread(
+                create_derivatives,
                 source_bytes, image_source, corpus.slug, page.folio_label, data_dir
             )
-            page_master = run_primary_analysis(
+            page_master = await asyncio.to_thread(
+                run_primary_analysis,
                 derivative_image_path=Path(image_info.derivative_path),
                 corpus_profile=corpus_profile,
                 model_config=model_config,

backend/tests/test_prompt_loader.py

@@ -0,0 +1,60 @@
+"""
+Tests pour prompt_loader.py — chargement, rendu, et détection de variables non résolues.
+"""
+import pytest
+
+from app.services.ai.prompt_loader import load_and_render_prompt
+
+
+@pytest.fixture()
+def template_file(tmp_path):
+    """Crée un fichier template temporaire."""
+    def _create(content: str, name: str = "test_prompt.txt"):
+        path = tmp_path / name
+        path.write_text(content, encoding="utf-8")
+        return path
+    return _create
+
+
+class TestLoadAndRenderPrompt:
+    def test_simple_substitution(self, template_file):
+        path = template_file("Analysez ce {{profile_label}} en {{script_type}}.")
+        result = load_and_render_prompt(path, {
+            "profile_label": "manuscrit enluminé",
+            "script_type": "caroline",
+        })
+        assert result == "Analysez ce manuscrit enluminé en caroline."
+
+    def test_multiple_occurrences(self, template_file):
+        path = template_file("{{lang}} et encore {{lang}}")
+        result = load_and_render_prompt(path, {"lang": "latin"})
+        assert result == "latin et encore latin"
+
+    def test_unused_context_keys_ignored(self, template_file):
+        path = template_file("Hello {{name}}")
+        result = load_and_render_prompt(path, {"name": "World", "extra": "unused"})
+        assert result == "Hello World"
+
+    def test_unresolved_variable_raises(self, template_file):
+        path = template_file("{{resolved}} but {{unresolved}} remains")
+        with pytest.raises(ValueError, match="Variables non résolues"):
+            load_and_render_prompt(path, {"resolved": "ok"})
+
+    def test_file_not_found_raises(self, tmp_path):
+        with pytest.raises(FileNotFoundError, match="Template introuvable"):
+            load_and_render_prompt(tmp_path / "nonexistent.txt", {})
+
+    def test_empty_template(self, template_file):
+        path = template_file("")
+        result = load_and_render_prompt(path, {"key": "value"})
+        assert result == ""
+
+    def test_no_variables_in_template(self, template_file):
+        path = template_file("Just plain text, no variables.")
+        result = load_and_render_prompt(path, {})
+        assert result == "Just plain text, no variables."
+
+    def test_path_as_string(self, template_file):
+        path = template_file("{{x}}")
+        result = load_and_render_prompt(str(path), {"x": "replaced"})
+        assert result == "replaced"

backend/tests/test_response_parser.py

@@ -0,0 +1,125 @@
+"""
+Tests pour response_parser.py — extraction JSON, correction VLM, parsing tolérant.
+"""
+import pytest
+
+from app.services.ai.response_parser import (
+    ParseError,
+    _extract_json_object,
+    _fix_common_json_issues,
+    _try_parse_json,
+    parse_ai_response,
+)
+
+
+# ── _extract_json_object ─────────────────────────────────────────────────────
+
+class TestExtractJsonObject:
+    def test_simple_object(self):
+        assert _extract_json_object('{"a": 1}') == '{"a": 1}'
+
+    def test_text_before_json(self):
+        result = _extract_json_object('Here is the JSON: {"a": 1}')
+        assert result == '{"a": 1}'
+
+    def test_text_after_json(self):
+        result = _extract_json_object('{"a": 1} and more text')
+        assert result == '{"a": 1}'
+
+    def test_nested_braces(self):
+        result = _extract_json_object('{"a": {"b": {"c": 1}}}')
+        assert result == '{"a": {"b": {"c": 1}}}'
+
+    def test_braces_inside_strings(self):
+        result = _extract_json_object('{"text": "value with { and } inside"}')
+        assert result == '{"text": "value with { and } inside"}'
+
+    def test_escaped_quotes(self):
+        result = _extract_json_object('{"text": "he said \\"hello\\""}')
+        assert result == '{"text": "he said \\"hello\\""}'
+
+    def test_no_json(self):
+        result = _extract_json_object("no json here")
+        assert result == "no json here"
+
+    def test_unclosed_json(self):
+        result = _extract_json_object('some text {"a": 1')
+        assert result.startswith('{"a": 1')
+
+
+# ── _fix_common_json_issues ──────────────────────────────────────────────────
+
+class TestFixCommonJsonIssues:
+    def test_trailing_comma_before_brace(self):
+        assert _fix_common_json_issues('{"a": 1,}') == '{"a": 1}'
+
+    def test_trailing_comma_before_bracket(self):
+        assert _fix_common_json_issues('[1, 2,]') == '[1, 2]'
+
+    def test_trailing_comma_with_whitespace(self):
+        assert _fix_common_json_issues('{"a": 1 , }') == '{"a": 1 }'
+
+    def test_no_issues(self):
+        text = '{"a": 1, "b": 2}'
+        assert _fix_common_json_issues(text) == text
+
+
+# ── _try_parse_json ──────────────────────────────────────────────────────────
+
+class TestTryParseJson:
+    def test_valid_json(self):
+        assert _try_parse_json('{"a": 1}') == {"a": 1}
+
+    def test_json_with_trailing_comma(self):
+        result = _try_parse_json('{"a": 1,}')
+        assert result == {"a": 1}
+
+    def test_invalid_json(self):
+        assert _try_parse_json("not json at all") is None
+
+
+# ── parse_ai_response ────────────────────────────────────────────────────────
+
+class TestParseAiResponse:
+    def test_clean_json(self):
+        raw = '{"layout": {"regions": [{"id": "r1", "type": "text_block", "bbox": [10, 20, 100, 200], "confidence": 0.9}]}, "ocr": {"diplomatic_text": "hello", "confidence": 0.8}}'
+        layout, ocr = parse_ai_response(raw)
+        assert len(layout["regions"]) == 1
+        assert layout["regions"][0]["id"] == "r1"
+        assert ocr.diplomatic_text == "hello"
+
+    def test_markdown_fenced_json(self):
+        raw = '```json\n{"layout": {"regions": []}, "ocr": {"diplomatic_text": "test"}}\n```'
+        layout, ocr = parse_ai_response(raw)
+        assert layout["regions"] == []
+        assert ocr.diplomatic_text == "test"
+
+    def test_text_around_json(self):
+        raw = 'Here is my analysis:\n{"layout": {"regions": []}, "ocr": {"diplomatic_text": "ok"}}\nHope this helps!'
+        layout, ocr = parse_ai_response(raw)
+        assert ocr.diplomatic_text == "ok"
+
+    def test_invalid_region_skipped(self):
+        raw = '{"layout": {"regions": [{"id": "r1", "type": "text_block", "bbox": [-1, 0, 100, 200], "confidence": 0.5}, {"id": "r2", "type": "miniature", "bbox": [10, 20, 100, 200], "confidence": 0.8}]}}'
+        layout, ocr = parse_ai_response(raw)
+        assert len(layout["regions"]) == 1
+        assert layout["regions"][0]["id"] == "r2"
+
+    def test_missing_ocr_returns_default(self):
+        raw = '{"layout": {"regions": []}}'
+        layout, ocr = parse_ai_response(raw)
+        assert ocr.diplomatic_text == ""
+        assert ocr.confidence == 0.0
+
+    def test_not_json_raises_parse_error(self):
+        with pytest.raises(ParseError):
+            parse_ai_response("This is not JSON at all, no braces anywhere")
+
+    def test_json_array_raises_parse_error(self):
+        with pytest.raises(ParseError):
+            parse_ai_response("[1, 2, 3]")
+
+    def test_trailing_comma_tolerance(self):
+        raw = '{"layout": {"regions": [],}, "ocr": {"diplomatic_text": "tolerant",}}'
+        layout, ocr = parse_ai_response(raw)
+        assert ocr.diplomatic_text == "tolerant"