feat(pipeline): IIIF-native Sprint 3 — in-memory image fetch for AI analysis

Replace disk-based image pipeline with IIIF-native streaming for pages
that have a IIIF Image Service URL:

- fetch_iiif_derivative(): fetches a 1500px JPEG via IIIF Image API
({service_url}/full/!1500,1500/0/default.jpg) — server-side resize
- fetch_ai_derivative_bytes(): returns (jpeg_bytes, w, h) in memory,
never writes to disk. Falls back to full download + in-memory resize
for non-IIIF sources.
- analyzer.py: now accepts derivative_image_bytes (bytes) OR
derivative_image_path (Path). New _scale_bbox_coordinates() scales
bounding boxes from derivative space to original canvas space when
dimensions differ (e.g., 1500px derivative → 5000px original).
- job_runner.py: 3 code paths:
1. IIIF native (iiif_service_url set): fetch in memory → analyze → discard
2. URL fallback (legacy): download → create_derivatives on disk → analyze
3. Local file (upload): read → create_derivatives on disk → analyze
- ImageInfo in master.json now stores iiif_service_url + original canvas
dimensions (not derivative dimensions) for IIIF-native pages.

2 new tests: IIIF bytes mode, bbox coordinate scaling (4x factor).
585 tests pass (+2 new), 0 regressions.

https://claude.ai/code/session_01UB4he7RdRPHLvNjky4X8Sw

backend/app/services/ai/analyzer.py

@@ -11,7 +11,7 @@ from pathlib import Path
 
 # 3. local
 from app.schemas.corpus_profile import CorpusProfile
-from app.schemas.image import ImageDerivativeInfo
+from app.schemas.image import ImageDerivativeInfo, ImageSourceInfo
 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_ai_raw, write_master_json
@@ -22,8 +22,32 @@ from app.services.ai.response_parser import ParseError, parse_ai_response  # noq
 logger = logging.getLogger(__name__)
 
 
+def _scale_bbox_coordinates(layout: dict, scale_x: float, scale_y: float) -> dict:
+    """Met à l'échelle les bbox de l'espace dérivé vers l'espace canvas original.
+
+    L'IA analyse un dérivé 1500px mais les coordonnées dans master.json
+    doivent être en pixels absolus du canvas original (convention IIIF).
+    """
+    if abs(scale_x - 1.0) < 0.01 and abs(scale_y - 1.0) < 0.01:
+        return layout  # pas de scaling nécessaire
+
+    regions = layout.get("regions", [])
+    for region in regions:
+        bbox = region.get("bbox")
+        if bbox and len(bbox) == 4:
+            region["bbox"] = [
+                round(bbox[0] * scale_x),
+                round(bbox[1] * scale_y),
+                round(bbox[2] * scale_x),
+                round(bbox[3] * scale_y),
+            ]
+    return layout
+
+
 def run_primary_analysis(
-    derivative_image_path: Path,
+    *,
+    derivative_image_bytes: bytes | None = None,
+    derivative_image_path: Path | None = None,
     corpus_profile: CorpusProfile,
     model_config: ModelConfig,
     page_id: str,
@@ -31,38 +55,22 @@ def run_primary_analysis(
     corpus_slug: str,
     folio_label: str,
     sequence: int,
-    image_info: ImageDerivativeInfo,
+    image_info: ImageDerivativeInfo | ImageSourceInfo,
+    derivative_width: int | None = None,
+    derivative_height: int | None = None,
     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 : 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 ;
-    Google AI Studio, Vertex et Mistral sont supportés de façon identique.
-
-    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é (ai_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).
+    Supporte deux modes :
+    - IIIF natif : derivative_image_bytes fourni (bytes en RAM, jamais sur disque)
+    - Legacy : derivative_image_path fourni (chemin fichier sur disque)
+
+    Respecte R05 : ai_raw.json toujours écrit en premier.
+
+    Si les dimensions originales (canvas) diffèrent du dérivé, les bbox sont
+    mises à l'échelle de l'espace dérivé vers l'espace canvas original.
     """
     # ── Chemins de sortie ───────────────────────────────────────────────────
     page_dir = base_data_dir / "corpora" / corpus_slug / "pages" / folio_label
@@ -85,13 +93,18 @@ def run_primary_analysis(
         extra={"template": prompt_rel_path, "corpus": corpus_slug, "folio": folio_label},
     )
 
-    # ── 2. Chargement de l'image dérivée ────────────────────────────────────
-    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
+    # ── 2. Obtention des bytes image ────────────────────────────────────────
+    if derivative_image_bytes is not None:
+        jpeg_bytes = derivative_image_bytes
+    elif derivative_image_path is not None:
+        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
+    else:
+        raise ValueError("Il faut fournir derivative_image_bytes ou derivative_image_path")
 
     # ── 3. Appel IA via le provider sélectionné ─────────────────────────────
     provider = get_provider(model_config.provider)
@@ -116,21 +129,45 @@ def run_primary_analysis(
     # ── 5. Parsing + validation (ParseError si JSON invalide) ───────────────
     layout, ocr = parse_ai_response(raw_text)
 
+    # ── 5b. Scaling bbox si les dimensions originales diffèrent du dérivé ──
+    is_iiif_source = isinstance(image_info, ImageSourceInfo)
+    original_w = image_info.original_width
+    original_h = image_info.original_height
+    deriv_w = derivative_width or (getattr(image_info, "derivative_width", None)) or original_w
+    deriv_h = derivative_height or (getattr(image_info, "derivative_height", None)) or original_h
+
+    if original_w > 0 and deriv_w > 0 and (original_w != deriv_w or original_h != deriv_h):
+        scale_x = original_w / deriv_w
+        scale_y = original_h / deriv_h
+        layout = _scale_bbox_coordinates(layout, scale_x, scale_y)
+
     # ── 6. Construction du PageMaster ───────────────────────────────────────
     processed_at = datetime.now(tz=timezone.utc)
+
+    if is_iiif_source:
+        image_block = ImageInfo(
+            master=image_info.original_url,
+            iiif_service_url=image_info.iiif_service_url,
+            manifest_url=image_info.manifest_url,
+            width=original_w,
+            height=original_h,
+        )
+    else:
+        image_block = ImageInfo(
+            master=image_info.original_url,
+            derivative_web=getattr(image_info, "derivative_path", None),
+            thumbnail=getattr(image_info, "thumbnail_path", None),
+            width=original_w,
+            height=original_h,
+        )
+
     page_master = PageMaster(
         page_id=page_id,
         corpus_profile=corpus_profile.profile_id,
         manuscript_id=manuscript_id,
         folio_label=folio_label,
         sequence=sequence,
-        image=ImageInfo(
-            master=image_info.original_url,
-            derivative_web=image_info.derivative_path,
-            thumbnail=image_info.thumbnail_path,
-            width=image_info.derivative_width,
-            height=image_info.derivative_height,
-        ),
+        image=image_block,
         layout=layout,
         ocr=ocr,
         processing=ProcessingInfo(
@@ -154,6 +191,7 @@ def run_primary_analysis(
             "corpus": corpus_slug,
             "folio": folio_label,
             "regions": len(layout.get("regions", [])),
+            "iiif_native": is_iiif_source,
         },
     )
     return page_master

backend/app/services/image/normalizer.py

@@ -143,3 +143,55 @@ def fetch_and_normalize(
     """
     source_bytes = fetch_iiif_image(url)
     return create_derivatives(source_bytes, url, corpus_slug, folio_label, base_data_dir)
+
+
+# ── Mode IIIF natif : images en mémoire, jamais sur disque ───────────────────
+
+def fetch_ai_derivative_bytes(
+    iiif_service_url: str | None,
+    fallback_url: str | None,
+) -> tuple[bytes, int, int]:
+    """Retourne (jpeg_bytes, width, height) pour l'IA — jamais sauvé sur disque.
+
+    - Si iiif_service_url est fourni : utilise l'IIIF Image API pour demander
+      au serveur un dérivé 1500px directement redimensionné côté serveur.
+    - Sinon (fallback_url) : télécharge l'image complète et redimensionne
+      en mémoire.
+
+    Returns:
+        Tuple (jpeg_bytes, derivative_width, derivative_height).
+
+    Raises:
+        ValueError: si aucune source n'est fournie.
+        httpx.HTTPStatusError: si le serveur retourne une erreur.
+    """
+    from app.services.ingest.iiif_fetcher import fetch_iiif_derivative, fetch_iiif_image
+
+    if iiif_service_url:
+        raw_bytes = fetch_iiif_derivative(iiif_service_url, max_px=_MAX_DERIVATIVE_PX)
+    elif fallback_url:
+        raw_bytes = fetch_iiif_image(fallback_url)
+    else:
+        raise ValueError("Aucune source image fournie (ni iiif_service_url ni fallback_url)")
+
+    # Ouvrir en mémoire pour obtenir les dimensions (et redimensionner si fallback)
+    image = Image.open(io.BytesIO(raw_bytes))
+    if image.mode != "RGB":
+        image = image.convert("RGB")
+
+    if not iiif_service_url:
+        # Fallback : le serveur n'a pas redimensionné, on le fait en mémoire
+        image = _resize_to_max(image, _MAX_DERIVATIVE_PX)
+
+    w, h = image.size
+
+    # Encoder en JPEG en mémoire
+    buf = io.BytesIO()
+    image.save(buf, format="JPEG", quality=_DERIVATIVE_QUALITY)
+    jpeg_bytes = buf.getvalue()
+
+    logger.info(
+        "Dérivé IA en mémoire",
+        extra={"iiif": bool(iiif_service_url), "size": f"{w}x{h}", "bytes": len(jpeg_bytes)},
+    )
+    return jpeg_bytes, w, h

backend/app/services/ingest/iiif_fetcher.py

@@ -48,3 +48,38 @@ def fetch_iiif_image(url: str, timeout: float = _DEFAULT_TIMEOUT) -> bytes:
         extra={"url": url, "size_bytes": len(response.content)},
     )
     return response.content
+
+
+def fetch_iiif_derivative(
+    service_url: str,
+    max_px: int = 1500,
+    timeout: float = _DEFAULT_TIMEOUT,
+) -> bytes:
+    """Télécharge un dérivé via l'IIIF Image API — jamais stocké sur disque.
+
+    Construit l'URL : {service_url}/full/!{max_px},{max_px}/0/default.jpg
+    Le serveur IIIF retourne une image redimensionnée côté serveur.
+
+    Args:
+        service_url: URL du IIIF Image Service (sans le suffix /full/.../default.jpg).
+        max_px: taille max du grand côté (défaut : 1500).
+        timeout: délai maximal en secondes.
+
+    Returns:
+        Contenu brut de l'image JPEG en bytes.
+    """
+    # Pattern IIIF Image API : !w,h = "best fit" (le serveur choisit)
+    derivative_url = f"{service_url.rstrip('/')}/full/!{max_px},{max_px}/0/default.jpg"
+    logger.info("Fetching IIIF derivative", extra={"url": derivative_url, "max_px": max_px})
+    response = httpx.get(
+        derivative_url,
+        headers=_HEADERS,
+        follow_redirects=True,
+        timeout=httpx.Timeout(timeout, connect=10.0),
+    )
+    response.raise_for_status()
+    logger.info(
+        "IIIF derivative fetched",
+        extra={"url": derivative_url, "size_bytes": len(response.content)},
+    )
+    return response.content

backend/app/services/job_runner.py

@@ -32,8 +32,13 @@ from app.models.database import async_session_factory
 from app.models.job import JobModel
 from app.models.model_config_db import ModelConfigDB
 from app.schemas.corpus_profile import CorpusProfile
+from app.schemas.image import ImageSourceInfo
 from app.schemas.model_config import ModelConfig, ProviderType
-from app.services.image.normalizer import create_derivatives, fetch_and_normalize
+from app.services.image.normalizer import (
+    create_derivatives,
+    fetch_ai_derivative_bytes,
+    fetch_and_normalize,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -126,19 +131,65 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
             available_models=[],
         )
 
-        # ── 5. Normaliser l'image ────────────────────────────────────────────
+        # ── 5. Obtenir l'image pour l'IA ─────────────────────────────────────
         data_dir = _config_module.settings.data_dir
         image_source = page.image_master_path or ""
 
-        if image_source.startswith(("http://", "https://")):
+        from app.services.ai.analyzer import run_primary_analysis
+
+        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(
+                iiif_service_url=page.iiif_service_url,
+                fallback_url=None,
+            )
+            image_source_info = ImageSourceInfo(
+                original_url=image_source or page.iiif_service_url,
+                iiif_service_url=page.iiif_service_url,
+                manifest_url=page.manifest_url,
+                is_iiif=True,
+                original_width=page.canvas_width or deriv_w,
+                original_height=page.canvas_height or deriv_h,
+            )
+
+            # ── 6. Analyse primaire IA (R05 : double stockage) ───────────────
+            page_master = run_primary_analysis(
+                derivative_image_bytes=deriv_bytes,
+                derivative_width=deriv_w,
+                derivative_height=deriv_h,
+                corpus_profile=corpus_profile,
+                model_config=model_config,
+                page_id=page.id,
+                manuscript_id=manuscript.id,
+                corpus_slug=corpus.slug,
+                folio_label=page.folio_label,
+                sequence=page.sequence,
+                image_info=image_source_info,
+                base_data_dir=data_dir,
+                project_root=_PROJECT_ROOT,
+            )
+
+        elif image_source.startswith(("http://", "https://")):
+            # ── Mode fallback URL : télécharge + stocke sur disque (legacy) ──
             image_info = fetch_and_normalize(
                 image_source, corpus.slug, page.folio_label, data_dir
             )
+            page_master = run_primary_analysis(
+                derivative_image_path=Path(image_info.derivative_path),
+                corpus_profile=corpus_profile,
+                model_config=model_config,
+                page_id=page.id,
+                manuscript_id=manuscript.id,
+                corpus_slug=corpus.slug,
+                folio_label=page.folio_label,
+                sequence=page.sequence,
+                image_info=image_info,
+                base_data_dir=data_dir,
+                project_root=_PROJECT_ROOT,
+            )
+
         elif image_source:
-            # Validation anti path-traversal : le chemin résolu doit être
-            # sous data_dir. Empêche la lecture de fichiers arbitraires
-            # si image_master_path contient des séquences ../ ou un
-            # chemin absolu hors du répertoire de données.
+            # ── Mode fichier local (upload) ──────────────────────────────────
             source_path = Path(image_source).resolve()
             data_dir_resolved = data_dir.resolve()
             if not str(source_path).startswith(str(data_dir_resolved) + "/") and source_path != data_dir_resolved:
@@ -150,29 +201,26 @@ async def _run_job_impl(job_id: str, db: AsyncSession) -> None:
             image_info = create_derivatives(
                 source_bytes, image_source, corpus.slug, page.folio_label, data_dir
             )
+            page_master = run_primary_analysis(
+                derivative_image_path=Path(image_info.derivative_path),
+                corpus_profile=corpus_profile,
+                model_config=model_config,
+                page_id=page.id,
+                manuscript_id=manuscript.id,
+                corpus_slug=corpus.slug,
+                folio_label=page.folio_label,
+                sequence=page.sequence,
+                image_info=image_info,
+                base_data_dir=data_dir,
+                project_root=_PROJECT_ROOT,
+            )
+
         else:
             raise ValueError(
                 f"La page {page.id} n'a pas d'image source "
-                "(image_master_path vide ou None)"
+                "(ni iiif_service_url, ni image_master_path)"
             )
 
-        # ── 6. Analyse primaire IA (R05 : double stockage) ───────────────────
-        from app.services.ai.analyzer import run_primary_analysis
-
-        page_master = run_primary_analysis(
-            derivative_image_path=Path(image_info.derivative_path),
-            corpus_profile=corpus_profile,
-            model_config=model_config,
-            page_id=page.id,
-            manuscript_id=manuscript.id,
-            corpus_slug=corpus.slug,
-            folio_label=page.folio_label,
-            sequence=page.sequence,
-            image_info=image_info,
-            base_data_dir=data_dir,
-            project_root=_PROJECT_ROOT,
-        )
-
         # ── 7. Générer et écrire l'ALTO XML ──────────────────────────────────
         from app.services.export.alto import generate_alto, write_alto
 

backend/tests/test_ai_analyzer.py

@@ -663,8 +663,9 @@ def test_run_primary_analysis_image_dict(tmp_path):
         )
 
     assert result.image.master == image_info.original_url
-    assert result.image.width == image_info.derivative_width
-    assert result.image.height == image_info.derivative_height
+    # L'analyzer stocke désormais les dimensions originales (pas celles du dérivé)
+    assert result.image.width == image_info.original_width
+    assert result.image.height == image_info.original_height
 
 
 def test_run_primary_analysis_regions_in_layout(tmp_path):
@@ -866,3 +867,98 @@ def test_run_primary_analysis_invalid_region_skipped(tmp_path):
 
     assert len(result.layout["regions"]) == 1
     assert result.layout["regions"][0]["id"] == "r_good"
+
+
+# ---------------------------------------------------------------------------
+# Mode IIIF natif — bytes en mémoire
+# ---------------------------------------------------------------------------
+
+from app.schemas.image import ImageSourceInfo
+
+
+def _make_image_source_info() -> ImageSourceInfo:
+    return ImageSourceInfo(
+        original_url="https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29/full/max/0/default.jpg",
+        iiif_service_url="https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29",
+        manifest_url="https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/manifest.json",
+        is_iiif=True,
+        original_width=3543,
+        original_height=4724,
+    )
+
+
+def test_run_primary_analysis_iiif_bytes_mode(tmp_path):
+    """Mode IIIF natif : passe des bytes directement, pas de chemin fichier."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+
+    jpeg_bytes = _make_jpeg_bytes(200, 300)
+    mock_provider = _make_mock_provider(_valid_ai_json())
+
+    with patch("app.services.ai.analyzer.get_provider", return_value=mock_provider):
+        result = run_primary_analysis(
+            derivative_image_bytes=jpeg_bytes,
+            derivative_width=200,
+            derivative_height=300,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-iiif-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=_make_image_source_info(),
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    assert result.image.iiif_service_url == "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29"
+    assert result.image.manifest_url is not None
+    assert result.image.derivative_web is None
+    assert result.image.width == 3543  # dimensions originales, pas dérivé
+    assert result.image.height == 4724
+
+
+def test_run_primary_analysis_iiif_bbox_scaling(tmp_path):
+    """Les bbox sont mises à l'échelle du dérivé vers le canvas original."""
+    prompt_rel = "prompts/medieval-illuminated/primary_v1.txt"
+    _setup_prompt_file(tmp_path, prompt_rel)
+
+    # Image source : 4000x6000 original, dérivé 1000x1500
+    source_info = ImageSourceInfo(
+        original_url="https://example.com/img",
+        iiif_service_url="https://example.com/img",
+        is_iiif=True,
+        original_width=4000,
+        original_height=6000,
+    )
+
+    # Réponse IA avec bbox dans l'espace du dérivé (1000x1500)
+    ai_response = json.dumps({
+        "layout": {"regions": [
+            {"id": "r1", "type": "text_block", "bbox": [100, 200, 500, 300], "confidence": 0.9},
+        ]},
+        "ocr": {"diplomatic_text": "test", "language": "la", "confidence": 0.8},
+    })
+    mock_provider = _make_mock_provider(ai_response)
+
+    with patch("app.services.ai.analyzer.get_provider", return_value=mock_provider):
+        result = run_primary_analysis(
+            derivative_image_bytes=_make_jpeg_bytes(100, 150),
+            derivative_width=1000,
+            derivative_height=1500,
+            corpus_profile=_make_corpus_profile(prompt_rel_path=prompt_rel),
+            model_config=_make_model_config(),
+            page_id="test-scale-0001r",
+            manuscript_id="ms-test",
+            corpus_slug="test-corpus",
+            folio_label="0001r",
+            sequence=1,
+            image_info=source_info,
+            base_data_dir=tmp_path / "data",
+            project_root=tmp_path,
+        )
+
+    # Scale factor : 4000/1000 = 4.0, 6000/1500 = 4.0
+    bbox = result.layout["regions"][0]["bbox"]
+    assert bbox == [400, 800, 2000, 1200]  # 100*4, 200*4, 500*4, 300*4