feat(ingest): IIIF-native Sprint 2 — detect IIIF Image Service at ingestion

Extract IIIF Image Service URL and canvas dimensions during manifest ingestion:

- New _extract_iiif_service(): detects IIIF Image Service from canvas data
with 4-level cascade: IIIF 3.0 service[] → IIIF 2.x service → URL pattern
detection (Gallica, etc.) → fallback None (static image).
- New _detect_iiif_service_from_url(): extracts service URL from IIIF Image
API URL pattern ({base}/full/{size}/{rot}/{qual}.{fmt}).
- _create_page() now accepts iiif_service_url, canvas_width, canvas_height,
manifest_url and stores them in PageModel.
- ingest_iiif_manifest: calls _extract_iiif_service for each canvas, stores
service URL + dimensions + manifest_url on each page.
- ingest_iiif_images: attempts URL pattern detection on direct image URLs.

14 new tests covering: IIIF 3.0/2.x service detection, dict vs list service,
Gallica URL pattern, trailing slash stripping, empty canvas, static fallback.

583 tests pass (+14 new), 0 regressions.

https://claude.ai/code/session_01UB4he7RdRPHLvNjky4X8Sw

backend/app/api/v1/ingest.py

@@ -144,6 +144,10 @@ async def _create_page(
     folio_label: str,
     sequence: int,
     image_master_path: str | None = None,
+    iiif_service_url: str | None = None,
+    canvas_width: int | None = None,
+    canvas_height: int | None = None,
+    manifest_url: str | None = None,
 ) -> PageModel | None:
     """Crée une page si elle n'existe pas déjà.  Retourne None si l'ID est déjà pris."""
     existing = await db.get(PageModel, page_id)
@@ -157,6 +161,10 @@ async def _create_page(
         folio_label=folio_label,
         sequence=sequence,
         image_master_path=image_master_path,
+        iiif_service_url=iiif_service_url,
+        canvas_width=canvas_width,
+        canvas_height=canvas_height,
+        manifest_url=manifest_url,
         processing_status="INGESTED",
     )
     db.add(page)
@@ -214,6 +222,78 @@ def _extract_canvas_label(canvas: dict, index: int) -> str:
     return f"f{index + 1:03d}r"
 
 
+# Pattern IIIF Image API : {service}/full/{size}/{rotation}/{quality}.{format}
+_IIIF_IMAGE_API_RE = re.compile(
+    r"^(https?://.+)/full/[^/]+/\d+/default\.\w+$"
+)
+
+
+def _extract_iiif_service(canvas: dict) -> tuple[str | None, int | None, int | None]:
+    """Détecte le IIIF Image Service d'un canvas et ses dimensions.
+
+    Retourne (service_url, canvas_width, canvas_height).
+    service_url est None si aucun service IIIF trouvé (image statique).
+    """
+    canvas_w = canvas.get("width")
+    canvas_h = canvas.get("height")
+
+    # ── IIIF 3.0 : body → service[] ─────────────────────────────────────
+    items = canvas.get("items") or []
+    if items:
+        ann_items = (items[0].get("items") or []) if items else []
+        if ann_items:
+            body = ann_items[0].get("body") or {}
+            if isinstance(body, dict):
+                # Chercher un service IIIF sur le body
+                services = body.get("service") or []
+                if isinstance(services, dict):
+                    services = [services]
+                for svc in services:
+                    svc_type = svc.get("type") or svc.get("@type") or ""
+                    if "ImageService" in svc_type:
+                        svc_url = (svc.get("id") or svc.get("@id") or "").rstrip("/")
+                        if svc_url:
+                            return svc_url, canvas_w, canvas_h
+
+                # Fallback : détecter le pattern Image API dans body.id
+                body_id = body.get("id") or body.get("@id") or ""
+                m = _IIIF_IMAGE_API_RE.match(body_id)
+                if m:
+                    return m.group(1), canvas_w, canvas_h
+
+    # ── IIIF 2.x : resource → service ───────────────────────────────────
+    images = canvas.get("images") or []
+    if images:
+        resource = images[0].get("resource") or {}
+        services = resource.get("service") or []
+        if isinstance(services, dict):
+            services = [services]
+        for svc in services:
+            svc_type = svc.get("@type") or svc.get("type") or ""
+            if "ImageService" in svc_type:
+                svc_url = (svc.get("@id") or svc.get("id") or "").rstrip("/")
+                if svc_url:
+                    return svc_url, canvas_w, canvas_h
+
+        # Fallback : pattern Image API dans resource @id
+        res_id = resource.get("@id") or resource.get("id") or ""
+        m = _IIIF_IMAGE_API_RE.match(res_id)
+        if m:
+            return m.group(1), canvas_w, canvas_h
+
+    return None, canvas_w, canvas_h
+
+
+def _detect_iiif_service_from_url(url: str) -> str | None:
+    """Tente de détecter une URL de service IIIF à partir d'une URL d'image directe.
+
+    Si l'URL suit le pattern IIIF Image API ({base}/full/{size}/{rot}/{qual}.{fmt}),
+    retourne la base. Sinon retourne None.
+    """
+    m = _IIIF_IMAGE_API_RE.match(url)
+    return m.group(1) if m else None
+
+
 def _extract_canvas_image_url(canvas: dict) -> str | None:
     """Extrait l'URL de l'image principale d'un canvas IIIF (3.0 ou 2.x)."""
     # IIIF 3.0
@@ -385,9 +465,14 @@ async def ingest_iiif_manifest(
         folio_label = labels[i]
         page_id = _make_page_id(corpus.slug, folio_label, seq + i, dupes)
         image_url = _extract_canvas_image_url(canvas)
+        service_url, c_width, c_height = _extract_iiif_service(canvas)
         page = await _create_page(
             db, ms.id, page_id, folio_label, seq + i,
             image_master_path=image_url,
+            iiif_service_url=service_url,
+            canvas_width=c_width,
+            canvas_height=c_height,
+            manifest_url=body.manifest_url,
         )
         if page is None:
             skipped += 1
@@ -406,7 +491,13 @@ async def ingest_iiif_manifest(
 
     logger.info(
         "Manifest IIIF ingéré",
-        extra={"corpus_id": corpus_id, "url": body.manifest_url, "created": len(created), "skipped": skipped},
+        extra={
+            "corpus_id": corpus_id,
+            "url": body.manifest_url,
+            "created": len(created),
+            "skipped": skipped,
+            "iiif_service_detected": sum(1 for p in created if p.iiif_service_url),
+        },
     )
     return IngestResponse(
         corpus_id=corpus_id,
@@ -446,9 +537,12 @@ async def ingest_iiif_images(
     skipped = 0
     for i, (url, folio_label) in enumerate(zip(body.urls, sanitized_labels)):
         page_id = _make_page_id(corpus.slug, folio_label, seq + i, dupes)
+        # Tenter de détecter un service IIIF à partir du pattern URL
+        service_url = _detect_iiif_service_from_url(url)
         page = await _create_page(
             db, ms.id, page_id, folio_label, seq + i,
             image_master_path=url,
+            iiif_service_url=service_url,
         )
         if page is None:
             skipped += 1

backend/tests/test_iiif_service_detection.py

@@ -0,0 +1,247 @@
+"""
+Tests de détection du IIIF Image Service à l'ingestion.
+
+Vérifie :
+- Extraction depuis un canvas IIIF 3.0 avec ImageService3
+- Extraction depuis un canvas IIIF 2.x avec service @id
+- Détection par pattern URL (Gallica, etc.)
+- Fallback quand aucun service n'est trouvé
+- Détection depuis URL directe (ingest/iiif-images)
+"""
+import pytest
+
+from app.api.v1.ingest import (
+    _detect_iiif_service_from_url,
+    _extract_iiif_service,
+)
+
+
+# ---------------------------------------------------------------------------
+# _extract_iiif_service — IIIF 3.0
+# ---------------------------------------------------------------------------
+
+def test_extract_iiif3_with_image_service3():
+    """Canvas IIIF 3.0 avec service ImageService3 explicite."""
+    canvas = {
+        "width": 3543,
+        "height": 4724,
+        "items": [{
+            "items": [{
+                "body": {
+                    "id": "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29/full/max/0/default.jpg",
+                    "type": "Image",
+                    "service": [{
+                        "id": "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29",
+                        "type": "ImageService3",
+                        "profile": "level2",
+                    }],
+                },
+            }],
+        }],
+    }
+    svc_url, w, h = _extract_iiif_service(canvas)
+    assert svc_url == "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29"
+    assert w == 3543
+    assert h == 4724
+
+
+def test_extract_iiif3_with_image_service2():
+    """Canvas IIIF 3.0 avec un service de type ImageService2."""
+    canvas = {
+        "width": 2000,
+        "height": 3000,
+        "items": [{
+            "items": [{
+                "body": {
+                    "id": "https://example.com/image/1/full/max/0/default.jpg",
+                    "type": "Image",
+                    "service": [{
+                        "id": "https://example.com/image/1",
+                        "type": "ImageService2",
+                        "profile": "level1",
+                    }],
+                },
+            }],
+        }],
+    }
+    svc_url, w, h = _extract_iiif_service(canvas)
+    assert svc_url == "https://example.com/image/1"
+    assert w == 2000
+
+
+def test_extract_iiif3_service_as_dict():
+    """Le champ service peut être un dict au lieu d'une liste."""
+    canvas = {
+        "width": 1000,
+        "height": 1500,
+        "items": [{
+            "items": [{
+                "body": {
+                    "id": "https://example.com/img/full/max/0/default.jpg",
+                    "service": {
+                        "id": "https://example.com/img",
+                        "type": "ImageService3",
+                    },
+                },
+            }],
+        }],
+    }
+    svc_url, _, _ = _extract_iiif_service(canvas)
+    assert svc_url == "https://example.com/img"
+
+
+def test_extract_iiif3_fallback_url_pattern():
+    """Sans service explicite, détecte le pattern Image API dans body.id."""
+    canvas = {
+        "width": 3000,
+        "height": 4000,
+        "items": [{
+            "items": [{
+                "body": {
+                    "id": "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29/full/max/0/default.jpg",
+                    "type": "Image",
+                    # Pas de "service" !
+                },
+            }],
+        }],
+    }
+    svc_url, w, h = _extract_iiif_service(canvas)
+    assert svc_url == "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29"
+    assert w == 3000
+
+
+def test_extract_iiif3_no_service_no_pattern():
+    """Canvas sans service et sans pattern Image API → None."""
+    canvas = {
+        "width": 800,
+        "height": 600,
+        "items": [{
+            "items": [{
+                "body": {
+                    "id": "https://example.com/static/page1.jpg",
+                    "type": "Image",
+                },
+            }],
+        }],
+    }
+    svc_url, w, h = _extract_iiif_service(canvas)
+    assert svc_url is None
+    assert w == 800
+    assert h == 600
+
+
+# ---------------------------------------------------------------------------
+# _extract_iiif_service — IIIF 2.x
+# ---------------------------------------------------------------------------
+
+def test_extract_iiif2_with_service():
+    """Canvas IIIF 2.x avec service dans resource."""
+    canvas = {
+        "width": 4000,
+        "height": 5000,
+        "images": [{
+            "resource": {
+                "@id": "https://example.com/image/2/full/full/0/default.jpg",
+                "service": {
+                    "@id": "https://example.com/image/2",
+                    "@type": "ImageService2",
+                },
+            },
+        }],
+    }
+    svc_url, w, h = _extract_iiif_service(canvas)
+    assert svc_url == "https://example.com/image/2"
+    assert w == 4000
+
+
+def test_extract_iiif2_fallback_url_pattern():
+    """IIIF 2.x : détection par pattern dans resource @id."""
+    canvas = {
+        "width": 2500,
+        "height": 3500,
+        "images": [{
+            "resource": {
+                "@id": "https://iiif.bodleian.ox.ac.uk/image/abc123/full/full/0/default.jpg",
+            },
+        }],
+    }
+    svc_url, _, _ = _extract_iiif_service(canvas)
+    assert svc_url == "https://iiif.bodleian.ox.ac.uk/image/abc123"
+
+
+def test_extract_iiif2_no_service():
+    """IIIF 2.x sans service et URL statique → None."""
+    canvas = {
+        "width": 1200,
+        "height": 1600,
+        "images": [{
+            "resource": {
+                "@id": "https://example.com/images/scan.png",
+            },
+        }],
+    }
+    svc_url, w, h = _extract_iiif_service(canvas)
+    assert svc_url is None
+    assert w == 1200
+
+
+# ---------------------------------------------------------------------------
+# _extract_iiif_service — cas limites
+# ---------------------------------------------------------------------------
+
+def test_extract_empty_canvas():
+    """Canvas vide → None sans crash."""
+    svc_url, w, h = _extract_iiif_service({})
+    assert svc_url is None
+    assert w is None
+    assert h is None
+
+
+def test_extract_service_url_trailing_slash_stripped():
+    """L'URL du service ne doit pas se terminer par /."""
+    canvas = {
+        "width": 1000,
+        "height": 1000,
+        "items": [{
+            "items": [{
+                "body": {
+                    "id": "https://example.com/img/full/max/0/default.jpg",
+                    "service": [{
+                        "id": "https://example.com/img/",
+                        "type": "ImageService3",
+                    }],
+                },
+            }],
+        }],
+    }
+    svc_url, _, _ = _extract_iiif_service(canvas)
+    assert svc_url == "https://example.com/img"
+    assert not svc_url.endswith("/")
+
+
+# ---------------------------------------------------------------------------
+# _detect_iiif_service_from_url — détection depuis URL directe
+# ---------------------------------------------------------------------------
+
+def test_detect_from_gallica_url():
+    """URL Gallica complète → service URL déduit."""
+    url = "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29/full/max/0/default.jpg"
+    assert _detect_iiif_service_from_url(url) == "https://gallica.bnf.fr/iiif/ark:/12148/btv1b8432314s/f29"
+
+
+def test_detect_from_iiif_url_with_size():
+    """URL avec taille spécifique → service URL déduit."""
+    url = "https://example.com/iiif/img1/full/!1500,1500/0/default.jpg"
+    assert _detect_iiif_service_from_url(url) == "https://example.com/iiif/img1"
+
+
+def test_detect_from_static_url_returns_none():
+    """URL statique (pas de pattern IIIF) → None."""
+    url = "https://example.com/images/page1.jpg"
+    assert _detect_iiif_service_from_url(url) is None
+
+
+def test_detect_from_iiif_url_different_format():
+    """URL avec format PNG au lieu de JPEG."""
+    url = "https://example.com/iiif/img2/full/max/0/default.png"
+    assert _detect_iiif_service_from_url(url) == "https://example.com/iiif/img2"