feat(sprint3-session-a): générateur ALTO v4 depuis PageMaster

- export/alto.py : generate_alto(PageMaster) → XML ALTO v4 valide
- Source canonique : PageMaster exclusivement (R02)
- bbox [x,y,w,h] → HPOS/VPOS/WIDTH/HEIGHT (correspondance directe, R03)
- text_block / margin / rubric → TextBlock
- miniature / decorated_initial → Illustration (avec TYPE=)
- other → ComposedBlock
- OCR par région (ocr.blocks avec region_id) ou fallback diplomatic_text
dans le premier TextBlock
- OCRProcessing avec model_id, prompt_version, datetime si processing présent
- Région invalide → ValueError explicite (jamais ALTO partiel silencieux)
- write_alto() pour écriture dans data/corpora/{slug}/pages/{folio}/alto.xml
- test_export_alto.py : 46 tests (XML valide, bbox exactes, mapping types,
OCR par région, scénarios réalistes Beatus HR/BR et Grandes Chroniques)

Total : 208 tests passent, 3 skippés (intégration réseau).

https://claude.ai/code/session_018woyEHc8HG2th7V4ewJ4Kg

backend/app/services/export/__init__.py

@@ -0,0 +1,9 @@
+"""
+Services d'export documentaire — ALTO, METS, Manifest IIIF (Sprint 3).
+"""
+from app.services.export.alto import generate_alto, write_alto
+
+__all__ = [
+    "generate_alto",
+    "write_alto",
+]

backend/app/services/export/alto.py

@@ -0,0 +1,272 @@
+"""
+Générateur ALTO v4 depuis un PageMaster validé (R02).
+
+Source canonique : PageMaster uniquement — jamais la réponse brute gemini_raw.json.
+bbox [x, y, width, height] → HPOS / VPOS / WIDTH / HEIGHT (correspondance directe).
+
+Mapping RegionType → élément ALTO :
+  text_block / margin / rubric  →  TextBlock
+  miniature / decorated_initial →  Illustration
+  other                         →  ComposedBlock
+"""
+# 1. stdlib
+import logging
+from pathlib import Path
+
+# 2. third-party
+from lxml import etree
+from pydantic import ValidationError
+
+# 3. local
+from app.schemas.page_master import OCRResult, PageMaster, Region, RegionType
+
+logger = logging.getLogger(__name__)
+
+# ── Namespaces ALTO v4 ──────────────────────────────────────────────────────
+_ALTO_NS = "http://www.loc.gov/standards/alto/ns-v4#"
+_XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+_SCHEMA_LOC = (
+    "http://www.loc.gov/standards/alto/ns-v4# "
+    "https://www.loc.gov/standards/alto/v4/alto-4-2.xsd"
+)
+
+# ── Classification des types de régions ─────────────────────────────────────
+_TEXT_REGION_TYPES = {RegionType.TEXT_BLOCK, RegionType.MARGIN, RegionType.RUBRIC}
+_ILLUSTRATION_TYPES = {RegionType.MINIATURE, RegionType.DECORATED_INITIAL}
+_COMPOSED_TYPES = {RegionType.OTHER}
+
+
+def _a(tag: str) -> str:
+    """Retourne le tag qualifié dans le namespace ALTO."""
+    return f"{{{_ALTO_NS}}}{tag}"
+
+
+def _bbox_attrib(region: Region) -> dict[str, str]:
+    """Retourne les attributs ALTO bbox depuis une Region (R03 → direct mapping)."""
+    x, y, w, h = region.bbox
+    return {"HPOS": str(x), "VPOS": str(y), "WIDTH": str(w), "HEIGHT": str(h)}
+
+
+def _build_text_block(
+    parent: etree._Element,
+    region: Region,
+    ocr_block: dict | None,
+    fallback_text: str,
+    language: str,
+    confidence: float,
+) -> None:
+    """Ajoute un élément TextBlock au parent.
+
+    Si un bloc OCR est disponible pour cette région ou si fallback_text est fourni,
+    ajoute un TextLine / String enfant. Sinon, le TextBlock reste vide (valide ALTO).
+    """
+    attrib = {"ID": region.id, "LANG": language, **_bbox_attrib(region)}
+    block_el = etree.SubElement(parent, _a("TextBlock"), attrib)
+
+    # Résolution du texte pour ce bloc
+    text = ""
+    block_confidence = confidence
+
+    if ocr_block:
+        text = (
+            ocr_block.get("text")
+            or ocr_block.get("diplomatic_text")
+            or ""
+        )
+        if not text and ocr_block.get("lines"):
+            text = " ".join(
+                ln.get("text", "") for ln in ocr_block["lines"] if ln.get("text")
+            )
+        block_confidence = float(ocr_block.get("confidence", confidence))
+    elif fallback_text:
+        text = fallback_text
+
+    if not text:
+        return  # TextBlock vide — valide ALTO
+
+    x, y, w, h = region.bbox
+    line_el = etree.SubElement(
+        block_el,
+        _a("TextLine"),
+        {"ID": f"{region.id}_l1", "HPOS": str(x), "VPOS": str(y), "WIDTH": str(w), "HEIGHT": str(h)},
+    )
+    etree.SubElement(
+        line_el,
+        _a("String"),
+        {
+            "ID": f"{region.id}_l1_s1",
+            "CONTENT": text,
+            "HPOS": str(x),
+            "VPOS": str(y),
+            "WIDTH": str(w),
+            "HEIGHT": str(h),
+            "WC": f"{block_confidence:.4f}",
+        },
+    )
+
+
+def generate_alto(master: PageMaster) -> str:
+    """Génère le XML ALTO v4 complet depuis un PageMaster.
+
+    Toutes les régions du layout sont validées avant la génération.
+    Un master.json avec une région invalide lève une ValueError explicite —
+    jamais d'ALTO partiel silencieux.
+
+    Args:
+        master: PageMaster Pydantic validé (source canonique, R02).
+
+    Returns:
+        Chaîne UTF-8 contenant le XML ALTO v4 (avec déclaration XML).
+
+    Raises:
+        ValueError: si une région du layout est invalide (bbox incorrecte, champ manquant).
+    """
+    # ── 1. Validation stricte de toutes les régions ─────────────────────────
+    raw_regions: list[dict] = (master.layout.get("regions") or [])
+    regions: list[Region] = []
+    for i, raw in enumerate(raw_regions):
+        try:
+            regions.append(Region.model_validate(raw))
+        except (ValidationError, Exception) as exc:
+            raise ValueError(
+                f"Région [{i}] invalide dans le layout de la page «{master.page_id}» : {exc}"
+            ) from exc
+
+    # ── 2. Index OCR par region_id ──────────────────────────────────────────
+    ocr: OCRResult | None = master.ocr
+    language = (ocr.language if ocr else "la") or "la"
+    global_confidence = ocr.confidence if ocr else 0.0
+    global_text = (ocr.diplomatic_text if ocr else "") or ""
+
+    ocr_by_region: dict[str, dict] = {}
+    if ocr:
+        for block in ocr.blocks:
+            rid = block.get("region_id")
+            if rid:
+                ocr_by_region[rid] = block
+
+    # Fallback : si aucun bloc OCR n'est référencé par region_id,
+    # le texte diplomatique global ira dans le premier TextBlock.
+    has_per_region_ocr = bool(ocr_by_region)
+    first_text_block_done = False
+
+    # ── 3. Construction de l'arbre XML ─────────────────────────────────────
+    nsmap = {None: _ALTO_NS, "xsi": _XSI_NS}
+    root = etree.Element(_a("alto"), nsmap=nsmap)
+    root.set(f"{{{_XSI_NS}}}schemaLocation", _SCHEMA_LOC)
+
+    # ── Description ────────────────────────────────────────────────────────
+    desc = etree.SubElement(root, _a("Description"))
+    etree.SubElement(desc, _a("MeasurementUnit")).text = "pixel"
+
+    src_info = etree.SubElement(desc, _a("sourceImageInformation"))
+    file_name = (
+        master.image.get("original_url")
+        or master.image.get("derivative_web")
+        or master.page_id
+    )
+    etree.SubElement(src_info, _a("fileName")).text = str(file_name)
+
+    if master.processing:
+        ocr_proc = etree.SubElement(desc, _a("OCRProcessing"), {"ID": "OCR_1"})
+        step = etree.SubElement(ocr_proc, _a("ocrProcessingStep"))
+        etree.SubElement(step, _a("processingDateTime")).text = (
+            master.processing.processed_at.isoformat()
+        )
+        software = etree.SubElement(step, _a("processingSoftware"))
+        etree.SubElement(software, _a("softwareCreator")).text = "Scriptorium AI"
+        etree.SubElement(software, _a("softwareName")).text = (
+            master.processing.model_display_name
+        )
+        etree.SubElement(software, _a("softwareVersion")).text = (
+            master.processing.prompt_version
+        )
+
+    # ── Layout ─────────────────────────────────────────────────────────────
+    layout_el = etree.SubElement(root, _a("Layout"))
+
+    width = int(master.image.get("width", 0))
+    height = int(master.image.get("height", 0))
+
+    page_id_safe = master.page_id.replace(" ", "_")
+    page_el = etree.SubElement(
+        layout_el,
+        _a("Page"),
+        {
+            "ID": f"P_{page_id_safe}",
+            "PHYSICAL_IMG_NR": str(master.sequence),
+            "WIDTH": str(width),
+            "HEIGHT": str(height),
+        },
+    )
+    print_space = etree.SubElement(
+        page_el,
+        _a("PrintSpace"),
+        {"HPOS": "0", "VPOS": "0", "WIDTH": str(width), "HEIGHT": str(height)},
+    )
+
+    # ── Régions ────────────────────────────────────────────────────────────
+    for region in regions:
+        if region.type in _TEXT_REGION_TYPES:
+            ocr_block = ocr_by_region.get(region.id)
+            fallback = ""
+            if not has_per_region_ocr and not first_text_block_done and global_text:
+                fallback = global_text
+                first_text_block_done = True
+
+            _build_text_block(
+                print_space,
+                region,
+                ocr_block=ocr_block,
+                fallback_text=fallback,
+                language=language,
+                confidence=global_confidence,
+            )
+
+        elif region.type in _ILLUSTRATION_TYPES:
+            etree.SubElement(
+                print_space,
+                _a("Illustration"),
+                {
+                    "ID": region.id,
+                    "TYPE": region.type.value,
+                    **_bbox_attrib(region),
+                },
+            )
+
+        else:  # _COMPOSED_TYPES (other)
+            etree.SubElement(
+                print_space,
+                _a("ComposedBlock"),
+                {"ID": region.id, **_bbox_attrib(region)},
+            )
+
+    logger.info(
+        "ALTO généré",
+        extra={
+            "page_id": master.page_id,
+            "regions": len(regions),
+        },
+    )
+
+    # ── 4. Sérialisation ───────────────────────────────────────────────────
+    return etree.tostring(
+        root,
+        xml_declaration=True,
+        encoding="UTF-8",
+        pretty_print=True,
+    ).decode("utf-8")
+
+
+def write_alto(alto_xml: str, output_path: Path) -> None:
+    """Écrit le XML ALTO dans le fichier de sortie.
+
+    Crée les dossiers parents si nécessaire.
+
+    Args:
+        alto_xml: chaîne XML retournée par generate_alto().
+        output_path: chemin de sortie (typiquement .../pages/{folio}/alto.xml).
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(alto_xml, encoding="utf-8")
+    logger.info("alto.xml écrit", extra={"path": str(output_path)})

backend/tests/test_export_alto.py

@@ -0,0 +1,650 @@
+"""
+Tests du générateur ALTO v4 (Sprint 3 — Session A).
+
+Vérifie :
+- XML produit est valide (parseable par lxml)
+- Correspondance exacte bbox → HPOS/VPOS/WIDTH/HEIGHT
+- text_block / margin / rubric → TextBlock
+- miniature / decorated_initial → Illustration
+- other → ComposedBlock
+- Texte OCR présent dans TextBlock quand disponible
+- Fallback diplomatic_text dans le premier TextBlock si aucun bloc OCR par région
+- Master sans régions → ALTO valide avec PrintSpace vide
+- Région invalide → ValueError explicite (jamais ALTO partiel)
+- Dimensions de page (WIDTH/HEIGHT) issues de master.image
+- OCRProcessing présent si master.processing, absent sinon
+- Attribut TYPE sur Illustration (valeur du RegionType)
+- Page ID contient le page_id du master
+"""
+# 1. stdlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+# 2. third-party
+import pytest
+from lxml import etree
+
+# 3. local
+from app.schemas.page_master import EditorialInfo, EditorialStatus, OCRResult, PageMaster, ProcessingInfo
+from app.services.export.alto import generate_alto, write_alto
+
+# ── Namespace ALTO v4 ─────────────────────────────────────────────────────
+_ALTO_NS = "http://www.loc.gov/standards/alto/ns-v4#"
+_A = f"{{{_ALTO_NS}}}"
+
+
+# ---------------------------------------------------------------------------
+# Helpers / Fixtures
+# ---------------------------------------------------------------------------
+
+def _make_master(
+    page_id: str = "test-ms-0001r",
+    sequence: int = 1,
+    regions: list | None = None,
+    ocr: OCRResult | None = None,
+    width: int = 1500,
+    height: int = 2000,
+    with_processing: bool = False,
+) -> PageMaster:
+    if regions is None:
+        regions = []
+    processing = None
+    if with_processing:
+        processing = ProcessingInfo(
+            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",
+            processed_at=datetime(2024, 6, 15, 12, 0, 0, tzinfo=timezone.utc),
+        )
+    return PageMaster(
+        page_id=page_id,
+        corpus_profile="medieval-illuminated",
+        manuscript_id="ms-test",
+        folio_label="0001r",
+        sequence=sequence,
+        image={
+            "original_url": "https://example.com/img.jpg",
+            "derivative_web": "/data/deriv.jpg",
+            "thumbnail": "/data/thumb.jpg",
+            "width": width,
+            "height": height,
+        },
+        layout={"regions": regions},
+        ocr=ocr,
+        processing=processing,
+        editorial=EditorialInfo(status=EditorialStatus.MACHINE_DRAFT),
+    )
+
+
+def _parse(xml_str: str) -> etree._Element:
+    """Parse une chaîne XML et retourne la racine."""
+    return etree.fromstring(xml_str.encode("utf-8"))
+
+
+def _xpath(root: etree._Element, path: str) -> list:
+    return root.xpath(path, namespaces={"a": _ALTO_NS})
+
+
+def _one(root: etree._Element, path: str) -> etree._Element:
+    results = _xpath(root, path)
+    assert len(results) == 1, f"Expected 1 match for {path!r}, got {len(results)}"
+    return results[0]
+
+
+# ---------------------------------------------------------------------------
+# Synthetic master.json fixtures (équivalents aux 3 master.json du Sprint 2)
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def master_text_only():
+    """Master simulant une page texte (seul TextBlock, OCR global)."""
+    return _make_master(
+        page_id="beatus-hr-0001r",
+        sequence=1,
+        regions=[
+            {"id": "r1", "type": "text_block", "bbox": [50, 100, 1400, 1800], "confidence": 0.92},
+        ],
+        ocr=OCRResult(
+            diplomatic_text="Incipit explanatio beati Ieronimi",
+            language="la",
+            confidence=0.92,
+        ),
+        width=1500,
+        height=2000,
+        with_processing=True,
+    )
+
+
+@pytest.fixture
+def master_mixed_regions():
+    """Master simulant un folio enluminé (texte + miniature + initial décoré)."""
+    return _make_master(
+        page_id="beatus-br-0013r",
+        sequence=13,
+        regions=[
+            {"id": "r1", "type": "miniature", "bbox": [0, 0, 1500, 800], "confidence": 0.95},
+            {"id": "r2", "type": "decorated_initial", "bbox": [50, 820, 200, 200], "confidence": 0.88},
+            {"id": "r3", "type": "text_block", "bbox": [260, 820, 1200, 200], "confidence": 0.90},
+            {"id": "r4", "type": "rubric", "bbox": [50, 1040, 1400, 80], "confidence": 0.85},
+            {"id": "r5", "type": "margin", "bbox": [0, 100, 45, 1800], "confidence": 0.70},
+        ],
+        ocr=OCRResult(
+            diplomatic_text="Sequitur de bestia",
+            language="la",
+            confidence=0.90,
+        ),
+        width=1500,
+        height=2000,
+    )
+
+
+@pytest.fixture
+def master_with_per_region_ocr():
+    """Master avec OCR indexé par region_id dans ocr.blocks."""
+    return _make_master(
+        page_id="chroniques-f016",
+        sequence=16,
+        regions=[
+            {"id": "r1", "type": "text_block", "bbox": [100, 100, 600, 400], "confidence": 0.91},
+            {"id": "r2", "type": "text_block", "bbox": [100, 520, 600, 300], "confidence": 0.87},
+            {"id": "r3", "type": "miniature", "bbox": [720, 100, 700, 800], "confidence": 0.96},
+        ],
+        ocr=OCRResult(
+            diplomatic_text="[global fallback]",
+            blocks=[
+                {"region_id": "r1", "text": "Cy commence le prologue", "confidence": 0.91},
+                {"region_id": "r2", "text": "Des grandes chroniques de France", "confidence": 0.87},
+            ],
+            language="fr",
+            confidence=0.89,
+        ),
+        width=1500,
+        height=2000,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tests — validité XML
+# ---------------------------------------------------------------------------
+
+def test_generate_alto_returns_string(master_text_only):
+    result = generate_alto(master_text_only)
+    assert isinstance(result, str)
+
+
+def test_generate_alto_valid_xml(master_text_only):
+    """Le XML produit doit être parseable par lxml sans erreur."""
+    xml_str = generate_alto(master_text_only)
+    root = _parse(xml_str)
+    assert root is not None
+
+
+def test_generate_alto_valid_xml_mixed(master_mixed_regions):
+    xml_str = generate_alto(master_mixed_regions)
+    root = _parse(xml_str)
+    assert root is not None
+
+
+def test_generate_alto_valid_xml_per_region_ocr(master_with_per_region_ocr):
+    xml_str = generate_alto(master_with_per_region_ocr)
+    root = _parse(xml_str)
+    assert root is not None
+
+
+def test_generate_alto_xml_declaration(master_text_only):
+    """Le XML doit commencer par la déclaration XML."""
+    xml_str = generate_alto(master_text_only)
+    assert xml_str.startswith("<?xml")
+
+
+def test_generate_alto_alto_namespace(master_text_only):
+    """L'élément racine doit utiliser le namespace ALTO v4."""
+    root = _parse(generate_alto(master_text_only))
+    assert root.tag == f"{{{_ALTO_NS}}}alto"
+
+
+def test_generate_alto_empty_regions():
+    """Un master sans régions produit un ALTO valide avec PrintSpace vide."""
+    master = _make_master(regions=[])
+    xml_str = generate_alto(master)
+    root = _parse(xml_str)
+    ps = _one(root, "//a:PrintSpace")
+    assert len(list(ps)) == 0  # aucun enfant
+
+
+# ---------------------------------------------------------------------------
+# Tests — bbox HPOS/VPOS/WIDTH/HEIGHT (R03 correspondance directe)
+# ---------------------------------------------------------------------------
+
+def test_text_block_bbox_exact(master_text_only):
+    """HPOS/VPOS/WIDTH/HEIGHT du TextBlock correspondent exactement à bbox [x,y,w,h]."""
+    root = _parse(generate_alto(master_text_only))
+    tb = _one(root, "//a:TextBlock[@ID='r1']")
+    assert tb.get("HPOS") == "50"
+    assert tb.get("VPOS") == "100"
+    assert tb.get("WIDTH") == "1400"
+    assert tb.get("HEIGHT") == "1800"
+
+
+def test_illustration_bbox_exact(master_mixed_regions):
+    """HPOS/VPOS/WIDTH/HEIGHT de l'Illustration correspondent exactement à bbox."""
+    root = _parse(generate_alto(master_mixed_regions))
+    ill = _one(root, "//a:Illustration[@ID='r1']")
+    assert ill.get("HPOS") == "0"
+    assert ill.get("VPOS") == "0"
+    assert ill.get("WIDTH") == "1500"
+    assert ill.get("HEIGHT") == "800"
+
+
+def test_decorated_initial_bbox_exact(master_mixed_regions):
+    root = _parse(generate_alto(master_mixed_regions))
+    ill = _one(root, "//a:Illustration[@ID='r2']")
+    assert ill.get("HPOS") == "50"
+    assert ill.get("VPOS") == "820"
+    assert ill.get("WIDTH") == "200"
+    assert ill.get("HEIGHT") == "200"
+
+
+def test_multiple_text_blocks_bbox(master_with_per_region_ocr):
+    root = _parse(generate_alto(master_with_per_region_ocr))
+    tb1 = _one(root, "//a:TextBlock[@ID='r1']")
+    tb2 = _one(root, "//a:TextBlock[@ID='r2']")
+
+    assert (tb1.get("HPOS"), tb1.get("VPOS"), tb1.get("WIDTH"), tb1.get("HEIGHT")) == (
+        "100", "100", "600", "400"
+    )
+    assert (tb2.get("HPOS"), tb2.get("VPOS"), tb2.get("WIDTH"), tb2.get("HEIGHT")) == (
+        "100", "520", "600", "300"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tests — mapping RegionType → élément ALTO
+# ---------------------------------------------------------------------------
+
+def test_text_block_produces_TextBlock(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    assert len(_xpath(root, "//a:TextBlock")) == 1
+    assert len(_xpath(root, "//a:Illustration")) == 0
+
+
+def test_miniature_produces_Illustration(master_mixed_regions):
+    root = _parse(generate_alto(master_mixed_regions))
+    ill = _one(root, "//a:Illustration[@ID='r1']")
+    assert ill.get("TYPE") == "miniature"
+
+
+def test_decorated_initial_produces_Illustration(master_mixed_regions):
+    root = _parse(generate_alto(master_mixed_regions))
+    ill = _one(root, "//a:Illustration[@ID='r2']")
+    assert ill.get("TYPE") == "decorated_initial"
+
+
+def test_rubric_produces_TextBlock(master_mixed_regions):
+    root = _parse(generate_alto(master_mixed_regions))
+    # r4 est rubric → doit être un TextBlock, pas une Illustration
+    tb = _one(root, "//a:TextBlock[@ID='r4']")
+    assert tb is not None
+    illustrations = _xpath(root, "//a:Illustration[@ID='r4']")
+    assert len(illustrations) == 0
+
+
+def test_margin_produces_TextBlock(master_mixed_regions):
+    root = _parse(generate_alto(master_mixed_regions))
+    tb = _one(root, "//a:TextBlock[@ID='r5']")
+    assert tb is not None
+
+
+def test_other_region_produces_ComposedBlock():
+    master = _make_master(
+        regions=[{"id": "r1", "type": "other", "bbox": [10, 10, 100, 100], "confidence": 0.5}]
+    )
+    root = _parse(generate_alto(master))
+    cb = _one(root, "//a:ComposedBlock[@ID='r1']")
+    assert cb.get("HPOS") == "10"
+    assert cb.get("VPOS") == "10"
+    assert cb.get("WIDTH") == "100"
+    assert cb.get("HEIGHT") == "100"
+    assert len(_xpath(root, "//a:TextBlock")) == 0
+    assert len(_xpath(root, "//a:Illustration")) == 0
+
+
+def test_mixed_regions_counts(master_mixed_regions):
+    """Folio enluminé : 3 TextBlock (text_block + rubric + margin) + 2 Illustration."""
+    root = _parse(generate_alto(master_mixed_regions))
+    assert len(_xpath(root, "//a:TextBlock")) == 3
+    assert len(_xpath(root, "//a:Illustration")) == 2
+
+
+# ---------------------------------------------------------------------------
+# Tests — contenu OCR dans les TextBlocks
+# ---------------------------------------------------------------------------
+
+def test_diplomatic_text_in_first_text_block(master_text_only):
+    """Le diplomatic_text global va dans le premier TextBlock si pas de per-region OCR."""
+    root = _parse(generate_alto(master_text_only))
+    strings = _xpath(root, "//a:TextBlock[@ID='r1']/a:TextLine/a:String")
+    assert len(strings) == 1
+    assert strings[0].get("CONTENT") == "Incipit explanatio beati Ieronimi"
+
+
+def test_per_region_ocr_blocks_used(master_with_per_region_ocr):
+    """Quand ocr.blocks contient des region_id, chaque TextBlock a son propre texte."""
+    root = _parse(generate_alto(master_with_per_region_ocr))
+
+    s1 = _one(root, "//a:TextBlock[@ID='r1']/a:TextLine/a:String")
+    s2 = _one(root, "//a:TextBlock[@ID='r2']/a:TextLine/a:String")
+
+    assert s1.get("CONTENT") == "Cy commence le prologue"
+    assert s2.get("CONTENT") == "Des grandes chroniques de France"
+
+
+def test_per_region_ocr_no_fallback_in_second_block(master_with_per_region_ocr):
+    """Le fallback global N'est PAS répété dans d'autres blocs quand per-region OCR existe."""
+    root = _parse(generate_alto(master_with_per_region_ocr))
+    strings = _xpath(root, "//a:String[@CONTENT='[global fallback]']")
+    assert len(strings) == 0
+
+
+def test_no_ocr_text_block_is_empty():
+    """TextBlock sans OCR disponible reste vide (valide ALTO)."""
+    master = _make_master(
+        regions=[{"id": "r1", "type": "text_block", "bbox": [0, 0, 100, 100], "confidence": 0.8}],
+        ocr=None,
+    )
+    root = _parse(generate_alto(master))
+    tb = _one(root, "//a:TextBlock[@ID='r1']")
+    assert len(list(tb)) == 0  # pas d'enfants TextLine
+
+
+def test_text_content_not_in_illustration():
+    """Les Illustrations ne doivent pas contenir de TextLine."""
+    master = _make_master(
+        regions=[{"id": "r1", "type": "miniature", "bbox": [0, 0, 500, 500], "confidence": 0.9}],
+        ocr=OCRResult(diplomatic_text="Some text that shouldn't be in illustration"),
+    )
+    root = _parse(generate_alto(master))
+    assert len(_xpath(root, "//a:Illustration/a:TextLine")) == 0
+    assert len(_xpath(root, "//a:Illustration/a:String")) == 0
+
+
+def test_string_wc_attribute_present(master_text_only):
+    """L'attribut WC (word confidence) est présent sur les éléments String."""
+    root = _parse(generate_alto(master_text_only))
+    strings = _xpath(root, "//a:String")
+    for s in strings:
+        assert s.get("WC") is not None
+        wc = float(s.get("WC"))
+        assert 0.0 <= wc <= 1.0
+
+
+def test_string_bbox_matches_region_bbox(master_text_only):
+    """Le String hérite des coordonnées bbox de sa région."""
+    root = _parse(generate_alto(master_text_only))
+    s = _one(root, "//a:TextBlock[@ID='r1']/a:TextLine/a:String")
+    assert s.get("HPOS") == "50"
+    assert s.get("VPOS") == "100"
+    assert s.get("WIDTH") == "1400"
+    assert s.get("HEIGHT") == "1800"
+
+
+# ---------------------------------------------------------------------------
+# Tests — dimensions de page
+# ---------------------------------------------------------------------------
+
+def test_page_width_height_from_image(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    page = _one(root, "//a:Page")
+    assert page.get("WIDTH") == "1500"
+    assert page.get("HEIGHT") == "2000"
+
+
+def test_print_space_dimensions_match_page(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    ps = _one(root, "//a:PrintSpace")
+    assert ps.get("HPOS") == "0"
+    assert ps.get("VPOS") == "0"
+    assert ps.get("WIDTH") == "1500"
+    assert ps.get("HEIGHT") == "2000"
+
+
+def test_page_physical_img_nr_is_sequence(master_mixed_regions):
+    root = _parse(generate_alto(master_mixed_regions))
+    page = _one(root, "//a:Page")
+    assert page.get("PHYSICAL_IMG_NR") == "13"
+
+
+def test_page_id_contains_page_id(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    page = _one(root, "//a:Page")
+    assert "beatus-hr-0001r" in page.get("ID", "")
+
+
+# ---------------------------------------------------------------------------
+# Tests — OCRProcessing (metadata de traitement)
+# ---------------------------------------------------------------------------
+
+def test_ocr_processing_present_when_processing_info(master_text_only):
+    """OCRProcessing est présent si master.processing est défini."""
+    root = _parse(generate_alto(master_text_only))
+    ocr_proc = _one(root, "//a:OCRProcessing")
+    assert ocr_proc is not None
+
+
+def test_ocr_processing_model_name(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    name = _one(root, "//a:processingSoftware/a:softwareName")
+    assert name.text == "Gemini 2.0 Flash"
+
+
+def test_ocr_processing_prompt_version(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    version = _one(root, "//a:processingSoftware/a:softwareVersion")
+    assert "primary_v1.txt" in version.text
+
+
+def test_ocr_processing_datetime(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    dt = _one(root, "//a:processingDateTime")
+    assert "2024-06-15" in dt.text
+
+
+def test_ocr_processing_absent_without_processing_info():
+    """OCRProcessing est absent si master.processing est None."""
+    master = _make_master(with_processing=False)
+    root = _parse(generate_alto(master))
+    assert len(_xpath(root, "//a:OCRProcessing")) == 0
+
+
+def test_software_creator_is_scriptorium_ai(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    creator = _one(root, "//a:processingSoftware/a:softwareCreator")
+    assert creator.text == "Scriptorium AI"
+
+
+# ---------------------------------------------------------------------------
+# Tests — source image
+# ---------------------------------------------------------------------------
+
+def test_source_filename_from_original_url(master_text_only):
+    root = _parse(generate_alto(master_text_only))
+    fn = _one(root, "//a:fileName")
+    assert fn.text == "https://example.com/img.jpg"
+
+
+# ---------------------------------------------------------------------------
+# Tests — erreur explicite sur region invalide
+# ---------------------------------------------------------------------------
+
+def test_invalid_region_raises_value_error():
+    """Une région avec bbox invalide dans le layout lève ValueError (jamais ALTO partiel)."""
+    master = _make_master(
+        regions=[
+            {"id": "r1", "type": "text_block", "bbox": [0, 0, 0, 100], "confidence": 0.9},
+        ]
+    )
+    with pytest.raises(ValueError, match="Région"):
+        generate_alto(master)
+
+
+def test_invalid_region_negative_bbox_raises():
+    master = _make_master(
+        regions=[
+            {"id": "r1", "type": "text_block", "bbox": [-5, 0, 100, 100], "confidence": 0.9},
+        ]
+    )
+    with pytest.raises(ValueError, match="Région"):
+        generate_alto(master)
+
+
+def test_invalid_region_missing_field_raises():
+    """Une région sans champ 'type' lève ValueError."""
+    master = _make_master(
+        regions=[
+            {"id": "r1", "bbox": [0, 0, 100, 100], "confidence": 0.9},  # manque 'type'
+        ]
+    )
+    with pytest.raises(ValueError, match="Région"):
+        generate_alto(master)
+
+
+def test_valid_region_after_nothing_invalid_no_partial_output():
+    """Si la première région est invalide, aucun ALTO n'est produit (pas de sortie partielle)."""
+    master = _make_master(
+        regions=[
+            {"id": "r_bad", "type": "text_block", "bbox": [0, 0, -1, 100], "confidence": 0.9},
+            {"id": "r_good", "type": "miniature", "bbox": [0, 0, 100, 100], "confidence": 0.9},
+        ]
+    )
+    with pytest.raises(ValueError):
+        generate_alto(master)
+
+
+# ---------------------------------------------------------------------------
+# Tests — write_alto
+# ---------------------------------------------------------------------------
+
+def test_write_alto_creates_file(tmp_path):
+    master = _make_master()
+    xml_str = generate_alto(master)
+    out = tmp_path / "alto.xml"
+    write_alto(xml_str, out)
+    assert out.exists()
+
+
+def test_write_alto_creates_parent_dirs(tmp_path):
+    master = _make_master()
+    xml_str = generate_alto(master)
+    out = tmp_path / "data" / "corpora" / "test" / "pages" / "0001r" / "alto.xml"
+    write_alto(xml_str, out)
+    assert out.exists()
+
+
+def test_write_alto_content_is_valid_xml(tmp_path):
+    master = _make_master(
+        regions=[{"id": "r1", "type": "text_block", "bbox": [0, 0, 100, 100], "confidence": 0.8}]
+    )
+    xml_str = generate_alto(master)
+    out = tmp_path / "alto.xml"
+    write_alto(xml_str, out)
+    root = etree.parse(str(out)).getroot()
+    assert root.tag == f"{{{_ALTO_NS}}}alto"
+
+
+# ---------------------------------------------------------------------------
+# Tests — scénarios réalistes Sprint 2 (3 "master.json" simulés)
+# ---------------------------------------------------------------------------
+
+def test_beatus_hr_folio_alto():
+    """Simule le folio Beatus HR : page texte dense avec OCR global."""
+    master = _make_master(
+        page_id="beatus-lat8878-hr-f233",
+        sequence=233,
+        regions=[
+            {"id": "r1", "type": "text_block", "bbox": [42, 58, 1410, 1880], "confidence": 0.93},
+            {"id": "r2", "type": "rubric", "bbox": [42, 58, 400, 40], "confidence": 0.88},
+            {"id": "r3", "type": "margin", "bbox": [1460, 58, 40, 1880], "confidence": 0.60},
+        ],
+        ocr=OCRResult(
+            diplomatic_text="Et post hec uidit angelum descendentem de celo",
+            language="la",
+            confidence=0.93,
+        ),
+        width=1500,
+        height=2000,
+        with_processing=True,
+    )
+    root = _parse(generate_alto(master))
+    assert len(_xpath(root, "//a:TextBlock")) == 3
+    assert len(_xpath(root, "//a:Illustration")) == 0
+    # OCR dans le premier TextBlock
+    strings = _xpath(root, "//a:String")
+    assert any("angelum" in (s.get("CONTENT") or "") for s in strings)
+
+
+def test_beatus_br_folio_alto():
+    """Simule le folio Beatus BR : miniature + texte."""
+    master = _make_master(
+        page_id="beatus-lat8878-br-f233",
+        sequence=233,
+        regions=[
+            {"id": "r1", "type": "miniature", "bbox": [0, 0, 1500, 900], "confidence": 0.97},
+            {"id": "r2", "type": "decorated_initial", "bbox": [42, 920, 120, 120], "confidence": 0.85},
+            {"id": "r3", "type": "text_block", "bbox": [180, 920, 1280, 120], "confidence": 0.91},
+        ],
+        ocr=OCRResult(
+            diplomatic_text="Incipit liber beati",
+            language="la",
+            confidence=0.91,
+        ),
+        width=1500,
+        height=2000,
+    )
+    root = _parse(generate_alto(master))
+    # Miniature + initial → Illustration
+    assert len(_xpath(root, "//a:Illustration")) == 2
+    # Un TextBlock
+    assert len(_xpath(root, "//a:TextBlock")) == 1
+    # Les Illustrations ne sont pas des TextBlocks
+    ill_ids = {el.get("ID") for el in _xpath(root, "//a:Illustration")}
+    tb_ids = {el.get("ID") for el in _xpath(root, "//a:TextBlock")}
+    assert ill_ids.isdisjoint(tb_ids)
+
+
+def test_grandes_chroniques_folio_alto():
+    """Simule le folio Grandes Chroniques : texte en français, OCR par région."""
+    master = _make_master(
+        page_id="chroniques-btv1b84472995-f16",
+        sequence=16,
+        regions=[
+            {"id": "r1", "type": "miniature", "bbox": [20, 20, 700, 600], "confidence": 0.96},
+            {"id": "r2", "type": "text_block", "bbox": [740, 20, 720, 600], "confidence": 0.89},
+            {"id": "r3", "type": "text_block", "bbox": [20, 640, 1440, 1300], "confidence": 0.91},
+        ],
+        ocr=OCRResult(
+            diplomatic_text="",
+            blocks=[
+                {"region_id": "r2", "text": "Ci commence le prolog", "confidence": 0.89},
+                {"region_id": "r3", "text": "Des roys de france", "confidence": 0.91},
+            ],
+            language="fr",
+            confidence=0.90,
+        ),
+        width=1460,
+        height=1960,
+    )
+    root = _parse(generate_alto(master))
+    assert len(_xpath(root, "//a:Illustration")) == 1
+    assert len(_xpath(root, "//a:TextBlock")) == 2
+
+    s2 = _one(root, "//a:TextBlock[@ID='r2']/a:TextLine/a:String")
+    s3 = _one(root, "//a:TextBlock[@ID='r3']/a:TextLine/a:String")
+    assert s2.get("CONTENT") == "Ci commence le prolog"
+    assert s3.get("CONTENT") == "Des roys de france"
+
+    # Dimensions de page correctes
+    page = _one(root, "//a:Page")
+    assert page.get("WIDTH") == "1460"
+    assert page.get("HEIGHT") == "1960"