fix(sprint-f3): conformité spec — IIIF langue, ai_raw.json, prompts génériques

Sprint F3 — alignement avec CLAUDE.md et correction des exports :

- IIIF : tag langue "none" → "en" (défaut conforme IIIF Presentation 3.0)
Canvas labels utilisent la langue du manuscrit au lieu de "none"
- ALTO : commentaire clarifié (TextBlock vide déjà correct — pas de data loss)
- METS : warning logger si fichier ALTO référencé n'existe pas encore
- Renommage gemini_raw.json → ai_raw.json (conforme CLAUDE.md §3)
Fonction write_gemini_raw() → write_ai_raw() dans master_writer.py
- Prompts : langue hardcodée ("la"/"fr") → {{primary_language}}
Nouvelle variable primary_language dans le contexte de rendu
- IIIF fetcher : Referer Gallica hardcodé retiré (code générique)

477 tests passants, 0 échecs.

https://claude.ai/code/session_015Lht7wNQRzhUaLw94dE9z9

backend/app/services/ai/analyzer.py

@@ -14,7 +14,7 @@ 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, ImageInfo, PageMaster, ProcessingInfo
-from app.services.ai.master_writer import write_gemini_raw, write_master_json
+from app.services.ai.master_writer import write_ai_raw, write_master_json
 from app.services.ai.model_registry import get_provider
 from app.services.ai.prompt_loader import load_and_render_prompt
 from app.services.ai.response_parser import ParseError, parse_ai_response  # noqa: F401
@@ -37,7 +37,7 @@ def run_primary_analysis(
 ) -> 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
+    Respecte R05 : ai_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.
 
     Le provider est sélectionné dynamiquement depuis model_config.provider ;
@@ -57,7 +57,7 @@ def run_primary_analysis(
         project_root: racine du projet (pour résoudre les chemins des prompts).
 
     Returns:
-        PageMaster validé (gemini_raw.json et master.json écrits sur disque).
+        PageMaster validé (ai_raw.json et master.json écrits sur disque).
 
     Raises:
         ParseError: si la réponse IA n'est pas un JSON valide.
@@ -66,7 +66,7 @@ def run_primary_analysis(
     """
     # ── Chemins de sortie ───────────────────────────────────────────────────
     page_dir = base_data_dir / "corpora" / corpus_slug / "pages" / folio_label
-    raw_path = page_dir / "gemini_raw.json"
+    raw_path = page_dir / "ai_raw.json"
     master_path = page_dir / "master.json"
 
     # ── 1. Chargement et rendu du prompt (R04) ──────────────────────────────
@@ -76,6 +76,7 @@ def run_primary_analysis(
     context = {
         "profile_label": corpus_profile.label,
         "language_hints": ", ".join(corpus_profile.language_hints),
+        "primary_language": corpus_profile.language_hints[0] if corpus_profile.language_hints else "la",
         "script_type": corpus_profile.script_type.value,
     }
     prompt_text = load_and_render_prompt(prompt_abs_path, context)
@@ -109,8 +110,8 @@ def run_primary_analysis(
         model_id=model_config.selected_model_id,
     )
 
-    # ── 4. Écriture gemini_raw.json TOUJOURS EN PREMIER (R05) ───────────────
-    write_gemini_raw(raw_text, raw_path)
+    # ── 4. Écriture ai_raw.json TOUJOURS EN PREMIER (R05) ─────────────────
+    write_ai_raw(raw_text, raw_path)
 
     # ── 5. Parsing + validation (ParseError si JSON invalide) ───────────────
     layout, ocr = parse_ai_response(raw_text)

backend/app/services/ai/master_writer.py

@@ -1,8 +1,8 @@
 """
-Écriture des fichiers gemini_raw.json et master.json (R02, R05).
+Écriture des fichiers ai_raw.json et master.json (R02, R05).
 
 Règle R05 non négociable :
-  1. gemini_raw.json est TOUJOURS écrit en premier.
+  1. ai_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
@@ -16,8 +16,8 @@ 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).
+def write_ai_raw(raw_text: str, output_path: Path) -> None:
+    """Écrit la réponse brute de l'IA dans ai_raw.json (R05).
 
     Toujours appelé AVANT toute tentative de parsing.
     Le contenu est enveloppé dans un objet JSON pour garantir un fichier valide,
@@ -31,9 +31,9 @@ def write_gemini_raw(raw_text: str, output_path: Path) -> None:
             encoding="utf-8",
         )
     except OSError as exc:
-        logger.error("Écriture gemini_raw.json échouée", extra={"path": str(output_path), "error": str(exc)})
+        logger.error("Écriture ai_raw.json échouée", extra={"path": str(output_path), "error": str(exc)})
         raise
-    logger.info("gemini_raw.json écrit", extra={"path": str(output_path)})
+    logger.info("ai_raw.json écrit", extra={"path": str(output_path)})
 
 
 def write_master_json(page_master: PageMaster, output_path: Path) -> None:

backend/app/services/export/alto.py

@@ -1,7 +1,7 @@
 """
 Générateur ALTO v4 depuis un PageMaster validé (R02).
 
-Source canonique : PageMaster uniquement — jamais la réponse brute gemini_raw.json.
+Source canonique : PageMaster uniquement — jamais la réponse brute ai_raw.json.
 bbox [x, y, width, height] → HPOS / VPOS / WIDTH / HEIGHT (correspondance directe).
 
 Mapping RegionType → élément ALTO :
@@ -82,7 +82,7 @@ def _build_text_block(
         text = fallback_text
 
     if not text:
-        return  # TextBlock vide — valide ALTO
+        return  # TextBlock sans TextLine — valide ALTO, région visible dans le layout
 
     x, y, w, h = region.bbox
     line_el = etree.SubElement(

backend/app/services/export/iiif.py

@@ -74,7 +74,7 @@ def generate_manifest(
 
     manuscript_id = manuscript_meta["manuscript_id"]
     label         = manuscript_meta["label"]
-    language      = manuscript_meta.get("language") or "none"
+    language      = manuscript_meta.get("language") or "en"
 
     # Pages dans l'ordre de séquence (règle absolue — structMap PHYSICAL)
     pages = sorted(masters, key=lambda m: m.sequence)
@@ -112,7 +112,7 @@ def generate_manifest(
         canvas: dict = {
             "id":     canvas_id,
             "type":   "Canvas",
-            "label":  {"none": [f"Folio {page.folio_label}"]},
+            "label":  {language: [f"Folio {page.folio_label}"]},
             "width":  width,
             "height": height,
             "items": [

backend/app/services/export/mets.py

@@ -195,8 +195,13 @@ def generate_mets(
             f"{_XL}type": "simple",
         })
 
-        # ALTO
+        # ALTO (référence conditionnelle — warning si le fichier n'existe pas encore)
         alto_p = _alto_path(corpus_slug, page.folio_label, base_data_dir)
+        if not Path(alto_p).exists():
+            logger.warning(
+                "Fichier ALTO absent — la référence METS sera cassée tant que l'ALTO n'est pas généré",
+                extra={"alto_path": alto_p, "page_id": page.page_id},
+            )
         f_alto = _el(grp_alto, f"{_M}file", {"ID": f"ALTO_{sid}", "MIMETYPE": "text/xml"})
         _el(f_alto, f"{_M}FLocat", {
             "LOCTYPE": "OTHER",

backend/app/services/ingest/iiif_fetcher.py

@@ -17,7 +17,6 @@ _HEADERS = {
         "+https://huggingface.co/spaces/Ma-Ri-Ba-Ku/scriptorium-ai)"
     ),
     "Accept": "image/jpeg,image/png,image/*,*/*",
-    "Referer": "https://gallica.bnf.fr/",
 }
 
 

backend/tests/test_ai_analyzer.py

@@ -3,7 +3,7 @@ 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
+  - master_writer  : écriture ai_raw.json et master.json
   - analyzer       : run_primary_analysis (end-to-end mocké)
 """
 # 1. stdlib
@@ -31,7 +31,7 @@ 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.master_writer import write_ai_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
 
@@ -390,35 +390,35 @@ def test_parse_empty_regions_list():
 
 
 # ---------------------------------------------------------------------------
-# Tests — write_gemini_raw / write_master_json
+# Tests — write_ai_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)
+def test_write_ai_raw_creates_file(tmp_path):
+    out = tmp_path / "page" / "ai_raw.json"
+    write_ai_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)
+def test_write_ai_raw_valid_json(tmp_path):
+    out = tmp_path / "ai_raw.json"
+    write_ai_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)
+def test_write_ai_raw_creates_parent_dirs(tmp_path):
+    out = tmp_path / "deep" / "nested" / "dir" / "ai_raw.json"
+    write_ai_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)
+def test_write_ai_raw_with_non_json_text(tmp_path):
+    """Même si le texte brut est invalide, ai_raw.json est créé."""
+    out = tmp_path / "ai_raw.json"
+    write_ai_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"
@@ -444,7 +444,7 @@ def _make_page_master() -> PageMaster:
             "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",
+            "raw_response_path": "/data/ai_raw.json",
             "processed_at": datetime.now(tz=timezone.utc),
         },
     )
@@ -569,12 +569,12 @@ def test_run_primary_analysis_files_created(tmp_path):
         )
 
     page_dir = tmp_path / "data" / "corpora" / "test-corpus" / "pages" / "0001r"
-    assert (page_dir / "gemini_raw.json").exists()
+    assert (page_dir / "ai_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)."""
+    """ai_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)
@@ -597,8 +597,8 @@ def test_run_primary_analysis_raw_written_before_parse(tmp_path):
                 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"
+    # ai_raw.json existe malgré l'échec de parsing
+    raw_path = tmp_path / "data" / "corpora" / "test-corpus" / "pages" / "0001r" / "ai_raw.json"
     assert raw_path.exists()
 
     # master.json N'existe PAS (parsing a échoué)

backend/tests/test_export_alto.py

@@ -56,7 +56,7 @@ def _make_master(
             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",
+            raw_response_path="/data/ai_raw.json",
             processed_at=datetime(2024, 6, 15, 12, 0, 0, tzinfo=timezone.utc),
         )
     return PageMaster(

backend/tests/test_export_iiif.py

@@ -193,11 +193,11 @@ def test_manifest_label_uses_language_key(simple_manifest):
 
 
 def test_manifest_label_without_language_uses_none():
-    """Sans champ language, la clé de label est 'none'."""
+    """Sans champ language, la clé de label est 'en' (défaut IIIF-compliant)."""
     pages = [_make_page("ms-0001r", "0001r", 1)]
-    meta = _base_meta()  # pas de language
+    meta = _base_meta()  # pas de language → défaut "en"
     manifest = generate_manifest(pages, meta, _BASE_URL)
-    assert "none" in manifest["label"]
+    assert "en" in manifest["label"]
 
 
 def test_manifest_label_fr(chroniques_pages, chroniques_meta):
@@ -272,7 +272,7 @@ def test_canvas_order_respects_sequence():
         _make_page("ms-f002r", "f002r", 2),
     ]
     manifest = generate_manifest(pages, _base_meta(), _BASE_URL)
-    labels = [c["label"]["none"][0] for c in manifest["items"]]
+    labels = [c["label"]["en"][0] for c in manifest["items"]]
     assert labels == ["Folio f001r", "Folio f002r", "Folio f003r"]
 
 
@@ -283,7 +283,7 @@ def test_canvas_order_large_sequence():
     random.shuffle(pages)
     manifest = generate_manifest(pages, _base_meta(), _BASE_URL)
     sequences_in_label = [
-        int(c["label"]["none"][0].replace("Folio f", "").replace("r", ""))
+        int(c["label"]["en"][0].replace("Folio f", "").replace("r", ""))
         for c in manifest["items"]
     ]
     assert sequences_in_label == list(range(1, 11))

backend/tests/test_export_mets.py

@@ -70,7 +70,7 @@ def _make_page(
             model_id="gemini-2.0-flash",
             model_display_name="Gemini 2.0 Flash",
             prompt_version="prompts/medieval-illuminated/primary_v1.txt",
-            raw_response_path=f"/data/corpora/test/pages/{folio_label}/gemini_raw.json",
+            raw_response_path=f"/data/corpora/test/pages/{folio_label}/ai_raw.json",
             processed_at=datetime(2024, 6, 15, 12, 0, 0, tzinfo=timezone.utc),
         )
     ocr = OCRResult(diplomatic_text=ocr_text, language="la", confidence=0.90) if ocr_text else None

backend/tests/test_image_pipeline.py

@@ -278,7 +278,6 @@ def test_fetch_iiif_image_success():
                 "+https://huggingface.co/spaces/Ma-Ri-Ba-Ku/scriptorium-ai)"
             ),
             "Accept": "image/jpeg,image/png,image/*,*/*",
-            "Referer": "https://gallica.bnf.fr/",
         },
         follow_redirects=True,
         timeout=60.0,

prompts/early-modern-print/primary_v1.txt

@@ -28,7 +28,7 @@ Format de sortie JSON attendu :
     "diplomatic_text": "",
     "blocks": [],
     "lines": [],
-    "language": "la",
+    "language": "{{primary_language}}",
     "confidence": 0.0,
     "uncertain_segments": []
   }

prompts/medieval-illuminated/primary_v1.txt

@@ -28,7 +28,7 @@ Format de sortie JSON attendu :
     "diplomatic_text": "",
     "blocks": [],
     "lines": [],
-    "language": "la",
+    "language": "{{primary_language}}",
     "confidence": 0.0,
     "uncertain_segments": []
   }

prompts/medieval-textual/primary_v1.txt

@@ -28,7 +28,7 @@ Format de sortie JSON attendu :
     "diplomatic_text": "",
     "blocks": [],
     "lines": [],
-    "language": "la",
+    "language": "{{primary_language}}",
     "confidence": 0.0,
     "uncertain_segments": []
   }

prompts/modern-handwritten/primary_v1.txt

@@ -28,7 +28,7 @@ Format de sortie JSON attendu :
     "diplomatic_text": "",
     "blocks": [],
     "lines": [],
-    "language": "fr",
+    "language": "{{primary_language}}",
     "confidence": 0.0,
     "uncertain_segments": []
   }