Sprint 3: vertical slice — PaddleOCR adapter, normalization pipeline, ALTO serializer

First end-to-end flow: image provider output → CanonicalDocument → ALTO XML.

Provider system skeleton:
- BaseRuntime ABC (execute, is_available)
- BaseAdapter ABC (family, version, normalize)
- ProviderProfile model (runtime_type, family, capabilities, auth, timeouts)
- CapabilityMatrix model (11 boolean capabilities)

Normalization:
- CanonicalBuilder: fluent builder pattern for constructing CanonicalDocuments
(builder.add_page → page.add_text_region → region.add_line → line.add_word)
- WordBoxJsonAdapter: converts PaddleOCR 4-point polygon format to canonical
model with full provenance (native for words, inferred for block)
- NormalizationPipeline: resolves adapter by family, runs normalization

ALTO XML serializer (lxml):
- Deterministic mapping: Page→Page, TextRegion→TextBlock, TextLine→TextLine,
Word→String with HPOS/VPOS/WIDTH/HEIGHT/CONTENT/WC attributes
- Hyphenation support (SUBS_TYPE, SUBS_CONTENT)
- SP elements between words
- Description with MeasurementUnit, fileName, Processing
- ALTO v4 namespace

42 new tests (adapter: 16, ALTO serializer: 17, builder: 7, integration: 2)
283 total tests passing. Integration test validates full pipeline:
raw PaddleOCR JSON → normalize → canonical → ALTO XML with correct structure.

https://claude.ai/code/session_01Cuzvc9Pjfo5u46eT3ta2Cg

src/app/normalization/canonical_builder.py

@@ -0,0 +1,332 @@
+"""CanonicalBuilder — builder pattern for constructing CanonicalDocuments.
+
+Usage:
+    builder = CanonicalBuilder("doc_001", InputType.IMAGE, "page.png")
+    page = builder.add_page(page_id="p1", width=2480, height=3508)
+    region = page.add_text_region("tb1", geometry=geo, provenance=prov)
+    line = region.add_line("tl1", geometry=geo, provenance=prov)
+    line.add_word("w1", text="Hello", geometry=geo, provenance=prov, confidence=0.95)
+    doc = builder.build()
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src.app.domain.models import (
+    AltoReadiness,
+    CanonicalDocument,
+    Geometry,
+    Hyphenation,
+    NonTextRegion,
+    Page,
+    PageXmlReadiness,
+    Provenance,
+    Source,
+    TextLine,
+    TextRegion,
+    Word,
+)
+from src.app.domain.models.status import (
+    BlockRole,
+    InputType,
+    NonTextKind,
+    ReadinessLevel,
+)
+
+
+class WordBuilder:
+    """Accumulates word data before the line is finalized."""
+
+    def __init__(
+        self,
+        word_id: str,
+        text: str,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        confidence: float | None = None,
+        lang: str | None = None,
+        hyphenation: Hyphenation | None = None,
+        normalized_text: str | None = None,
+        style_refs: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._data = {
+            "id": word_id,
+            "text": text,
+            "geometry": geometry,
+            "provenance": provenance,
+            "confidence": confidence,
+            "lang": lang,
+            "hyphenation": hyphenation,
+            "normalized_text": normalized_text,
+            "style_refs": style_refs or [],
+            "metadata": metadata,
+        }
+
+    def build(self) -> Word:
+        return Word(**self._data)
+
+
+class LineBuilder:
+    """Accumulates words for a single line."""
+
+    def __init__(
+        self,
+        line_id: str,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        confidence: float | None = None,
+        lang: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._line_id = line_id
+        self._geometry = geometry
+        self._provenance = provenance
+        self._confidence = confidence
+        self._lang = lang
+        self._metadata = metadata
+        self._words: list[WordBuilder] = []
+
+    def add_word(
+        self,
+        word_id: str,
+        text: str,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        confidence: float | None = None,
+        lang: str | None = None,
+        hyphenation: Hyphenation | None = None,
+        normalized_text: str | None = None,
+        style_refs: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> WordBuilder:
+        wb = WordBuilder(
+            word_id,
+            text,
+            geometry,
+            provenance,
+            confidence=confidence,
+            lang=lang,
+            hyphenation=hyphenation,
+            normalized_text=normalized_text,
+            style_refs=style_refs,
+            metadata=metadata,
+        )
+        self._words.append(wb)
+        return wb
+
+    def build(self) -> TextLine:
+        if not self._words:
+            raise ValueError(f"Line {self._line_id} has no words")
+        return TextLine(
+            id=self._line_id,
+            geometry=self._geometry,
+            provenance=self._provenance,
+            confidence=self._confidence,
+            lang=self._lang,
+            words=[w.build() for w in self._words],
+            metadata=self._metadata,
+        )
+
+
+class RegionBuilder:
+    """Accumulates lines for a text region (block)."""
+
+    def __init__(
+        self,
+        region_id: str,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        role: BlockRole | None = None,
+        confidence: float | None = None,
+        lang: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._region_id = region_id
+        self._geometry = geometry
+        self._provenance = provenance
+        self._role = role
+        self._confidence = confidence
+        self._lang = lang
+        self._metadata = metadata
+        self._lines: list[LineBuilder] = []
+
+    def add_line(
+        self,
+        line_id: str,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        confidence: float | None = None,
+        lang: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> LineBuilder:
+        lb = LineBuilder(
+            line_id,
+            geometry,
+            provenance,
+            confidence=confidence,
+            lang=lang,
+            metadata=metadata,
+        )
+        self._lines.append(lb)
+        return lb
+
+    def build(self) -> TextRegion:
+        if not self._lines:
+            raise ValueError(f"Region {self._region_id} has no lines")
+        return TextRegion(
+            id=self._region_id,
+            role=self._role,
+            geometry=self._geometry,
+            provenance=self._provenance,
+            confidence=self._confidence,
+            lang=self._lang,
+            lines=[ln.build() for ln in self._lines],
+            metadata=self._metadata,
+        )
+
+
+class PageBuilder:
+    """Accumulates regions for a single page."""
+
+    def __init__(
+        self,
+        page_id: str,
+        page_index: int,
+        width: float,
+        height: float,
+    ) -> None:
+        self._page_id = page_id
+        self._page_index = page_index
+        self._width = width
+        self._height = height
+        self._text_regions: list[RegionBuilder] = []
+        self._non_text_regions: list[NonTextRegion] = []
+        self._reading_order: list[str] = []
+        self._warnings: list[str] = []
+        self._metadata: dict[str, Any] | None = None
+
+    def add_text_region(
+        self,
+        region_id: str,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        role: BlockRole | None = None,
+        confidence: float | None = None,
+        lang: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RegionBuilder:
+        rb = RegionBuilder(
+            region_id,
+            geometry,
+            provenance,
+            role=role,
+            confidence=confidence,
+            lang=lang,
+            metadata=metadata,
+        )
+        self._text_regions.append(rb)
+        self._reading_order.append(region_id)
+        return rb
+
+    def add_non_text_region(
+        self,
+        region_id: str,
+        kind: NonTextKind,
+        geometry: Geometry,
+        provenance: Provenance,
+        *,
+        confidence: float | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._non_text_regions.append(
+            NonTextRegion(
+                id=region_id,
+                kind=kind,
+                geometry=geometry,
+                provenance=provenance,
+                confidence=confidence,
+                metadata=metadata,
+            )
+        )
+
+    def add_warning(self, warning: str) -> None:
+        self._warnings.append(warning)
+
+    def set_metadata(self, metadata: dict[str, Any]) -> None:
+        self._metadata = metadata
+
+    def build(self) -> Page:
+        return Page(
+            id=self._page_id,
+            page_index=self._page_index,
+            width=self._width,
+            height=self._height,
+            alto_readiness=AltoReadiness(
+                level=ReadinessLevel.NONE, missing=["word_text"]
+            ),
+            page_readiness=PageXmlReadiness(
+                level=ReadinessLevel.NONE, missing=["word_text"]
+            ),
+            reading_order=self._reading_order,
+            text_regions=[r.build() for r in self._text_regions],
+            non_text_regions=self._non_text_regions,
+            warnings=self._warnings,
+            metadata=self._metadata,
+        )
+
+
+class CanonicalBuilder:
+    """Top-level builder for constructing a CanonicalDocument."""
+
+    def __init__(
+        self,
+        document_id: str,
+        input_type: InputType,
+        filename: str | None = None,
+        *,
+        mime_type: str | None = None,
+        checksum: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self._document_id = document_id
+        self._source = Source(
+            input_type=input_type,
+            filename=filename,
+            mime_type=mime_type,
+            checksum=checksum,
+        )
+        self._pages: list[PageBuilder] = []
+        self._metadata = metadata
+
+    def add_page(
+        self,
+        page_id: str,
+        page_index: int,
+        width: float,
+        height: float,
+    ) -> PageBuilder:
+        pb = PageBuilder(page_id, page_index, width, height)
+        self._pages.append(pb)
+        return pb
+
+    def build(self) -> CanonicalDocument:
+        """Build and validate the CanonicalDocument.
+
+        Raises pydantic.ValidationError if the resulting document is invalid.
+        """
+        if not self._pages:
+            raise ValueError("Document must have at least one page")
+        return CanonicalDocument(
+            document_id=self._document_id,
+            source=self._source,
+            pages=[p.build() for p in self._pages],
+            metadata=self._metadata,
+        )

src/app/normalization/pipeline.py

@@ -0,0 +1,62 @@
+"""Normalization pipeline — orchestrates raw → canonical conversion.
+
+The pipeline:
+  1. Resolves the adapter from the provider profile
+  2. Runs the adapter to produce a CanonicalDocument
+  3. Returns the document (enrichers and validators are separate steps)
+"""
+
+from __future__ import annotations
+
+from src.app.domain.models import CanonicalDocument, RawProviderPayload
+from src.app.domain.models.geometry import GeometryContext
+from src.app.providers.adapters.base import BaseAdapter
+from src.app.providers.adapters.word_box_json import WordBoxJsonAdapter
+
+# Registry of available adapters by family name
+_ADAPTERS: dict[str, type[BaseAdapter]] = {
+    "word_box_json": WordBoxJsonAdapter,
+}
+
+
+def get_adapter(family: str) -> BaseAdapter:
+    """Instantiate an adapter for the given provider family.
+
+    Raises KeyError if the family is not registered.
+    """
+    adapter_cls = _ADAPTERS.get(family)
+    if adapter_cls is None:
+        raise KeyError(
+            f"No adapter registered for family '{family}'. "
+            f"Available: {list(_ADAPTERS.keys())}"
+        )
+    return adapter_cls()
+
+
+def normalize(
+    raw: RawProviderPayload,
+    family: str,
+    geometry_context: GeometryContext,
+    *,
+    document_id: str,
+    source_filename: str | None = None,
+) -> CanonicalDocument:
+    """Run the normalization pipeline: raw payload → CanonicalDocument.
+
+    Args:
+        raw: The raw provider output.
+        family: Provider family name (determines which adapter to use).
+        geometry_context: Coordinate space of the provider output.
+        document_id: ID for the produced document.
+        source_filename: Original input filename.
+
+    Returns:
+        A validated CanonicalDocument.
+    """
+    adapter = get_adapter(family)
+    return adapter.normalize(
+        raw,
+        geometry_context,
+        document_id=document_id,
+        source_filename=source_filename,
+    )

src/app/providers/adapters/base.py

@@ -0,0 +1,51 @@
+"""Base adapter ABC — defines how raw provider output is normalized."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from src.app.domain.models import CanonicalDocument, RawProviderPayload
+from src.app.domain.models.geometry import GeometryContext
+
+
+class BaseAdapter(ABC):
+    """Abstract base for provider adapters.
+
+    An adapter takes a RawProviderPayload and produces a CanonicalDocument.
+    It handles the translation from provider-specific format to the canonical
+    model, including geometry normalization and provenance tagging.
+    """
+
+    @property
+    @abstractmethod
+    def family(self) -> str:
+        """The provider family this adapter handles (e.g. 'word_box_json')."""
+        ...
+
+    @property
+    @abstractmethod
+    def version(self) -> str:
+        """Adapter version string (e.g. 'adapter.paddle.v1')."""
+        ...
+
+    @abstractmethod
+    def normalize(
+        self,
+        raw: RawProviderPayload,
+        geometry_context: GeometryContext,
+        *,
+        document_id: str,
+        source_filename: str | None = None,
+    ) -> CanonicalDocument:
+        """Convert raw provider output to a CanonicalDocument.
+
+        Args:
+            raw: The raw provider payload.
+            geometry_context: Describes the coordinate space of the provider output.
+            document_id: ID for the produced CanonicalDocument.
+            source_filename: Original filename of the input image.
+
+        Returns:
+            A validated CanonicalDocument.
+        """
+        ...

src/app/providers/adapters/word_box_json.py

@@ -0,0 +1,183 @@
+"""word_box_json adapter — handles PaddleOCR and similar providers.
+
+PaddleOCR output format (standard):
+    [
+        [[[x1,y1],[x2,y2],[x3,y3],[x4,y4]], ("text", confidence)],
+        ...
+    ]
+
+Each item is a detected text line/word with a 4-point polygon and
+a (text, confidence) tuple.  This adapter treats each item as a word
+within a single inferred text block.
+"""
+
+from __future__ import annotations
+
+from src.app.domain.models import (
+    CanonicalDocument,
+    Geometry,
+    Provenance,
+    RawProviderPayload,
+)
+from src.app.domain.models.geometry import GeometryContext
+from src.app.domain.models.status import (
+    EvidenceType,
+    GeometryStatus,
+    InputType,
+)
+from src.app.geometry.bbox import union_all
+from src.app.geometry.normalization import four_point_to_polygon, four_point_to_xywh
+from src.app.normalization.canonical_builder import CanonicalBuilder
+from src.app.providers.adapters.base import BaseAdapter
+
+
+class WordBoxJsonAdapter(BaseAdapter):
+    """Adapter for the word_box_json family (PaddleOCR, etc.)."""
+
+    @property
+    def family(self) -> str:
+        return "word_box_json"
+
+    @property
+    def version(self) -> str:
+        return "adapter.word_box_json.v1"
+
+    def normalize(
+        self,
+        raw: RawProviderPayload,
+        geometry_context: GeometryContext,
+        *,
+        document_id: str,
+        source_filename: str | None = None,
+    ) -> CanonicalDocument:
+        payload = raw.payload
+        if not isinstance(payload, list):
+            raise ValueError(
+                f"word_box_json expects a list payload, got {type(payload).__name__}"
+            )
+
+        builder = CanonicalBuilder(
+            document_id=document_id,
+            input_type=InputType.IMAGE,
+            filename=source_filename,
+        )
+
+        page = builder.add_page(
+            page_id="p1",
+            page_index=0,
+            width=geometry_context.source_width,
+            height=geometry_context.source_height,
+        )
+
+        # Collect all word bboxes for building a block-level bbox
+        word_bboxes: list[tuple[float, float, float, float]] = []
+        word_data: list[dict] = []
+
+        for idx, item in enumerate(payload):
+            points, text_conf = self._parse_item(item, idx)
+            text, confidence = self._parse_text_conf(text_conf, idx)
+
+            bbox = four_point_to_xywh(points)
+            polygon = four_point_to_polygon(points)
+
+            # Apply resize factor if present
+            if geometry_context.resize_factor and geometry_context.resize_factor != 1.0:
+                factor = 1.0 / geometry_context.resize_factor
+                bbox = (bbox[0] * factor, bbox[1] * factor, bbox[2] * factor, bbox[3] * factor)
+                polygon = [(x * factor, y * factor) for x, y in polygon]
+
+            word_bboxes.append(bbox)
+            word_data.append({
+                "bbox": bbox,
+                "polygon": polygon,
+                "text": text,
+                "confidence": confidence,
+                "source_idx": idx,
+            })
+
+        if not word_data:
+            raise ValueError("word_box_json payload contains no items")
+
+        # Build a single inferred text block containing all items as words
+        # Each PaddleOCR item is treated as a line with one word
+        block_bbox = union_all(word_bboxes)
+        block_prov = Provenance(
+            provider=raw.provider_id,
+            adapter=self.version,
+            source_ref="$",
+            evidence_type=EvidenceType.DERIVED,
+            derived_from=[f"w{i+1}" for i in range(len(word_data))],
+        )
+
+        region = page.add_text_region(
+            region_id="tb1",
+            geometry=Geometry(
+                bbox=block_bbox,
+                status=GeometryStatus.INFERRED,
+            ),
+            provenance=block_prov,
+        )
+
+        for i, wd in enumerate(word_data):
+            word_id = f"w{i + 1}"
+            line_id = f"tl{i + 1}"
+
+            prov = Provenance(
+                provider=raw.provider_id,
+                adapter=self.version,
+                source_ref=f"$[{wd['source_idx']}]",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+            )
+
+            geo = Geometry(
+                bbox=wd["bbox"],
+                polygon=wd["polygon"],
+                status=GeometryStatus.EXACT,
+            )
+
+            # Each PaddleOCR detection becomes a line with one word
+            line = region.add_line(line_id, geometry=geo, provenance=prov)
+            line.add_word(
+                word_id,
+                text=wd["text"],
+                geometry=geo,
+                provenance=prov,
+                confidence=wd["confidence"],
+            )
+
+        return builder.build()
+
+    # -- Private helpers ---------------------------------------------------------
+
+    @staticmethod
+    def _parse_item(item: object, idx: int) -> tuple[list, object]:
+        """Extract (points, text_conf) from a PaddleOCR result item."""
+        if not isinstance(item, (list, tuple)) or len(item) != 2:
+            raise ValueError(
+                f"Item {idx}: expected [points, (text, conf)], got {type(item).__name__}"
+            )
+        points = item[0]
+        text_conf = item[1]
+        if not isinstance(points, list) or len(points) != 4:
+            raise ValueError(
+                f"Item {idx}: expected 4 polygon points, got {len(points) if isinstance(points, list) else type(points).__name__}"
+            )
+        return points, text_conf
+
+    @staticmethod
+    def _parse_text_conf(text_conf: object, idx: int) -> tuple[str, float | None]:
+        """Extract (text, confidence) from the second element."""
+        if isinstance(text_conf, (list, tuple)) and len(text_conf) == 2:
+            text = str(text_conf[0])
+            try:
+                confidence = float(text_conf[1])
+                confidence = max(0.0, min(1.0, confidence))
+            except (TypeError, ValueError):
+                confidence = None
+            return text, confidence
+        if isinstance(text_conf, str):
+            return text_conf, None
+        raise ValueError(
+            f"Item {idx}: expected (text, confidence) or text string, "
+            f"got {type(text_conf).__name__}"
+        )

src/app/providers/capabilities.py

@@ -0,0 +1,27 @@
+"""Capability matrix — describes what a provider can produce."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CapabilityMatrix(BaseModel):
+    """Explicit description of a provider's output capabilities.
+
+    Used to decide which enrichers to activate, which exports to authorize,
+    and how to inform the user about data completeness.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    block_geometry: bool = False
+    line_geometry: bool = False
+    word_geometry: bool = False
+    polygon_geometry: bool = False
+    baseline: bool = False
+    reading_order: bool = False
+    text_confidence: bool = False
+    language: bool = False
+    non_text_regions: bool = False
+    tables: bool = False
+    rotation_info: bool = False

src/app/providers/profiles.py

@@ -0,0 +1,55 @@
+"""Provider profiles — describes a concrete configured provider instance."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.app.providers.capabilities import CapabilityMatrix
+
+
+class RuntimeType(str, Enum):
+    LOCAL = "local"
+    HUB = "hub"
+    API = "api"
+
+
+class ProviderFamily(str, Enum):
+    WORD_BOX_JSON = "word_box_json"
+    LINE_BOX_JSON = "line_box_json"
+    REGION_LINE_WORD_POLYGON = "region_line_word_polygon"
+    TEXT_ONLY = "text_only"
+
+
+class AuthMode(str, Enum):
+    NONE = "none"
+    API_KEY = "api_key"
+    BEARER = "bearer"
+    HF_TOKEN = "hf_token"
+
+
+class ProviderProfile(BaseModel):
+    """A concrete, persisted provider configuration."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: str = Field(min_length=1)
+    display_name: str = Field(min_length=1)
+    runtime_type: RuntimeType
+    model_id_or_path: str = Field(min_length=1)
+
+    endpoint: str | None = None
+    auth_mode: AuthMode = AuthMode.NONE
+    auth_secret_ref: str | None = None
+
+    family: ProviderFamily
+    capabilities: CapabilityMatrix = Field(default_factory=CapabilityMatrix)
+
+    timeout: int = Field(default=120, gt=0)
+    prompt_template: str | None = None
+
+    last_test_status: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

src/app/providers/runtimes/base.py

@@ -0,0 +1,38 @@
+"""Base runtime ABC — defines how a provider is executed."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from src.app.domain.models import RawProviderPayload
+
+
+class BaseRuntime(ABC):
+    """Abstract base for provider runtimes (local, hub, api)."""
+
+    @abstractmethod
+    def execute(
+        self,
+        image_path: Path,
+        model_id: str,
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> RawProviderPayload:
+        """Run the provider on an image and return the raw output.
+
+        Args:
+            image_path: Path to the input image file.
+            model_id: Model identifier (local path, hub ID, or API model name).
+            options: Additional provider-specific options.
+
+        Returns:
+            RawProviderPayload wrapping the provider's raw JSON output.
+        """
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if this runtime is usable in the current environment."""
+        ...

src/app/serializers/alto_xml.py

@@ -0,0 +1,219 @@
+"""ALTO XML serializer — deterministic conversion from CanonicalDocument to ALTO v4.
+
+This serializer is a pure output transformation.  It MUST NOT:
+  - Call any model or provider
+  - Reconstruct segmentation
+  - Correct text
+  - Invent coordinates
+  - Make export eligibility decisions
+
+It receives a validated CanonicalDocument and produces ALTO XML bytes.
+
+ALTO mapping:
+  Page         → <Page>
+  TextRegion   → <TextBlock>
+  TextLine     → <TextLine>
+  Word         → <String>
+
+Coordinate mapping:
+  bbox[0] → HPOS
+  bbox[1] → VPOS
+  bbox[2] → WIDTH
+  bbox[3] → HEIGHT
+  text    → CONTENT
+  confidence → WC
+  hyphenation.part=1 → SUBS_TYPE="HypPart1"
+  hyphenation.part=2 → SUBS_TYPE="HypPart2"
+  hyphenation.full_form → SUBS_CONTENT
+"""
+
+from __future__ import annotations
+
+from lxml import etree
+
+from src.app.domain.models import CanonicalDocument, Page, TextLine, TextRegion, Word
+from src.app.geometry.quantization import RoundingStrategy, quantize_bbox
+
+ALTO_NS = "http://www.loc.gov/standards/alto/ns-v4#"
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+SCHEMA_LOCATION = (
+    "http://www.loc.gov/standards/alto/ns-v4# "
+    "http://www.loc.gov/standards/alto/v4/alto-4-2.xsd"
+)
+
+NSMAP = {
+    None: ALTO_NS,
+    "xsi": XSI_NS,
+}
+
+
+def serialize_alto(
+    doc: CanonicalDocument,
+    *,
+    rounding: RoundingStrategy = RoundingStrategy.ROUND,
+    pretty_print: bool = True,
+    encoding: str = "UTF-8",
+) -> bytes:
+    """Serialize a CanonicalDocument to ALTO v4 XML bytes.
+
+    Args:
+        doc: The validated canonical document.
+        rounding: Strategy for converting float coordinates to integers.
+        pretty_print: Whether to indent the XML output.
+        encoding: Output encoding.
+
+    Returns:
+        The ALTO XML as bytes.
+    """
+    root = _build_alto_tree(doc, rounding)
+    return etree.tostring(
+        root,
+        pretty_print=pretty_print,
+        xml_declaration=True,
+        encoding=encoding,
+    )
+
+
+def serialize_alto_to_string(
+    doc: CanonicalDocument,
+    *,
+    rounding: RoundingStrategy = RoundingStrategy.ROUND,
+) -> str:
+    """Serialize to a UTF-8 string (convenience for tests)."""
+    return serialize_alto(doc, rounding=rounding).decode("utf-8")
+
+
+# -- Tree construction --------------------------------------------------------
+
+
+def _build_alto_tree(
+    doc: CanonicalDocument, rounding: RoundingStrategy
+) -> etree._Element:
+    root = etree.Element(f"{{{ALTO_NS}}}alto", nsmap=NSMAP)
+    root.set(f"{{{XSI_NS}}}schemaLocation", SCHEMA_LOCATION)
+
+    # <Description>
+    desc = etree.SubElement(root, f"{{{ALTO_NS}}}Description")
+    _add_description(desc, doc)
+
+    # <Layout>
+    layout = etree.SubElement(root, f"{{{ALTO_NS}}}Layout")
+    for page in doc.pages:
+        _add_page(layout, page, rounding)
+
+    return root
+
+
+def _add_description(desc: etree._Element, doc: CanonicalDocument) -> None:
+    """Add <Description> metadata."""
+    measurement = etree.SubElement(desc, f"{{{ALTO_NS}}}MeasurementUnit")
+    measurement.text = "pixel"
+
+    src_info = etree.SubElement(desc, f"{{{ALTO_NS}}}sourceImageInformation")
+    file_name = etree.SubElement(src_info, f"{{{ALTO_NS}}}fileName")
+    file_name.text = doc.source.filename or doc.document_id
+
+    # Processing info
+    processing = etree.SubElement(desc, f"{{{ALTO_NS}}}Processing")
+    processing.set("ID", "proc_1")
+    sw = etree.SubElement(processing, f"{{{ALTO_NS}}}processingSoftware")
+    sw_name = etree.SubElement(sw, f"{{{ALTO_NS}}}softwareName")
+    sw_name.text = "XmLLM"
+    sw_version = etree.SubElement(sw, f"{{{ALTO_NS}}}softwareVersion")
+    sw_version.text = doc.schema_version
+
+
+def _add_page(
+    layout: etree._Element, page: Page, rounding: RoundingStrategy
+) -> None:
+    """Add a <Page> with its <PrintSpace> and blocks."""
+    page_el = etree.SubElement(layout, f"{{{ALTO_NS}}}Page")
+    page_el.set("ID", page.id)
+    page_el.set("PHYSICAL_IMG_NR", str(page.page_index + 1))
+    page_el.set("WIDTH", str(int(page.width)))
+    page_el.set("HEIGHT", str(int(page.height)))
+
+    # <PrintSpace> covers the entire page
+    ps = etree.SubElement(page_el, f"{{{ALTO_NS}}}PrintSpace")
+    ps.set("HPOS", "0")
+    ps.set("VPOS", "0")
+    ps.set("WIDTH", str(int(page.width)))
+    ps.set("HEIGHT", str(int(page.height)))
+
+    for region in page.text_regions:
+        _add_text_block(ps, region, rounding)
+
+
+def _add_text_block(
+    parent: etree._Element, region: TextRegion, rounding: RoundingStrategy
+) -> None:
+    """Add a <TextBlock> with its lines."""
+    tb = etree.SubElement(parent, f"{{{ALTO_NS}}}TextBlock")
+    tb.set("ID", region.id)
+    _set_bbox_attrs(tb, region.geometry.bbox, rounding)
+
+    if region.lang:
+        tb.set("LANG", region.lang)
+
+    for line in region.lines:
+        _add_text_line(tb, line, rounding)
+
+
+def _add_text_line(
+    parent: etree._Element, line: TextLine, rounding: RoundingStrategy
+) -> None:
+    """Add a <TextLine> with its strings."""
+    tl = etree.SubElement(parent, f"{{{ALTO_NS}}}TextLine")
+    tl.set("ID", line.id)
+    _set_bbox_attrs(tl, line.geometry.bbox, rounding)
+
+    for i, word in enumerate(line.words):
+        if i > 0:
+            _add_sp(tl)
+        _add_string(tl, word, rounding)
+
+
+def _add_string(
+    parent: etree._Element, word: Word, rounding: RoundingStrategy
+) -> None:
+    """Add a <String> element for a word."""
+    s = etree.SubElement(parent, f"{{{ALTO_NS}}}String")
+    s.set("ID", word.id)
+    _set_bbox_attrs(s, word.geometry.bbox, rounding)
+    s.set("CONTENT", word.text)
+
+    if word.confidence is not None:
+        s.set("WC", f"{word.confidence:.2f}")
+
+    if word.lang:
+        s.set("LANG", word.lang)
+
+    # Hyphenation
+    if word.hyphenation and word.hyphenation.is_hyphenated:
+        if word.hyphenation.part == 1:
+            s.set("SUBS_TYPE", "HypPart1")
+        elif word.hyphenation.part == 2:
+            s.set("SUBS_TYPE", "HypPart2")
+        if word.hyphenation.full_form:
+            s.set("SUBS_CONTENT", word.hyphenation.full_form)
+
+
+def _add_sp(parent: etree._Element) -> None:
+    """Add a <SP> (space) element between words."""
+    etree.SubElement(parent, f"{{{ALTO_NS}}}SP")
+
+
+# -- Helpers ------------------------------------------------------------------
+
+
+def _set_bbox_attrs(
+    el: etree._Element,
+    bbox: tuple[float, float, float, float],
+    rounding: RoundingStrategy,
+) -> None:
+    """Set HPOS, VPOS, WIDTH, HEIGHT attributes from a canonical bbox."""
+    hpos, vpos, width, height = quantize_bbox(bbox, rounding)
+    el.set("HPOS", str(hpos))
+    el.set("VPOS", str(vpos))
+    el.set("WIDTH", str(width))
+    el.set("HEIGHT", str(height))

tests/fixtures/paddle_ocr_sample.json

@@ -0,0 +1,22 @@
+[
+  [
+    [[100, 200], [300, 200], [300, 240], [100, 240]],
+    ["Bonjour", 0.96]
+  ],
+  [
+    [[320, 200], [450, 200], [450, 240], [320, 240]],
+    ["le", 0.99]
+  ],
+  [
+    [[470, 200], [620, 200], [620, 240], [470, 240]],
+    ["monde", 0.94]
+  ],
+  [
+    [[100, 280], [550, 280], [550, 320], [100, 320]],
+    ["Ceci est une seconde ligne", 0.91]
+  ],
+  [
+    [[100, 360], [500, 360], [500, 400], [100, 400]],
+    ["Troisième ligne de texte", 0.88]
+  ]
+]

tests/integration/test_paddle_to_alto.py

@@ -0,0 +1,148 @@
+"""Integration test: PaddleOCR raw output → CanonicalDocument → ALTO XML.
+
+This is the Sprint 3 vertical slice end-to-end test.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from lxml import etree
+
+from src.app.domain.models import RawProviderPayload
+from src.app.domain.models.geometry import GeometryContext
+from src.app.normalization.pipeline import normalize
+from src.app.serializers.alto_xml import ALTO_NS, serialize_alto
+
+
+class TestPaddleToAlto:
+    """Full pipeline: raw fixture → normalize → serialize → valid ALTO."""
+
+    def test_end_to_end(self, fixtures_dir: Path) -> None:
+        # 1. Load raw PaddleOCR output
+        with open(fixtures_dir / "paddle_ocr_sample.json") as f:
+            paddle_output = json.load(f)
+
+        raw = RawProviderPayload(
+            provider_id="paddleocr",
+            adapter_id="adapter.word_box_json.v1",
+            runtime_type="local",
+            payload=paddle_output,
+            image_width=2480,
+            image_height=3508,
+        )
+
+        geo_ctx = GeometryContext(source_width=2480, source_height=3508)
+
+        # 2. Normalize to CanonicalDocument
+        doc = normalize(
+            raw,
+            family="word_box_json",
+            geometry_context=geo_ctx,
+            document_id="integration_test_001",
+            source_filename="page_001.png",
+        )
+
+        # Verify canonical document structure
+        assert doc.document_id == "integration_test_001"
+        assert doc.source.filename == "page_001.png"
+        assert len(doc.pages) == 1
+
+        page = doc.pages[0]
+        assert page.width == 2480
+        assert page.height == 3508
+        assert len(page.text_regions) >= 1
+
+        # Count total words
+        all_words = [
+            w
+            for r in page.text_regions
+            for l in r.lines
+            for w in l.words
+        ]
+        assert len(all_words) == 5
+
+        # Verify provenance chain
+        for word in all_words:
+            assert word.provenance.provider == "paddleocr"
+            assert word.geometry.polygon is not None
+
+        # 3. Serialize to ALTO XML
+        alto_bytes = serialize_alto(doc)
+        assert alto_bytes  # not empty
+
+        # 4. Parse and validate ALTO structure
+        root = etree.fromstring(alto_bytes)
+        assert root.tag == f"{{{ALTO_NS}}}alto"
+
+        # Verify page
+        alto_page = root.find(f".//{{{ALTO_NS}}}Page")
+        assert alto_page is not None
+        assert alto_page.get("WIDTH") == "2480"
+        assert alto_page.get("HEIGHT") == "3508"
+
+        # Verify strings
+        strings = root.findall(f".//{{{ALTO_NS}}}String")
+        assert len(strings) == 5
+
+        # First word content matches
+        assert strings[0].get("CONTENT") == "Bonjour"
+
+        # Coordinates are integers
+        for s in strings:
+            assert s.get("HPOS").isdigit()
+            assert s.get("VPOS").isdigit()
+            assert s.get("WIDTH").isdigit()
+            assert s.get("HEIGHT").isdigit()
+
+        # Confidence present
+        assert strings[0].get("WC") == "0.96"
+
+        # SP elements between words within a line
+        text_lines = root.findall(f".//{{{ALTO_NS}}}TextLine")
+        assert len(text_lines) == 5  # each paddle item = 1 line
+
+    def test_canonical_json_roundtrip(self, fixtures_dir: Path) -> None:
+        """The canonical doc produced by the pipeline survives JSON serialization."""
+        with open(fixtures_dir / "paddle_ocr_sample.json") as f:
+            paddle_output = json.load(f)
+
+        raw = RawProviderPayload(
+            provider_id="paddleocr",
+            adapter_id="v1",
+            runtime_type="local",
+            payload=paddle_output,
+            image_width=2480,
+            image_height=3508,
+        )
+
+        geo_ctx = GeometryContext(source_width=2480, source_height=3508)
+        doc = normalize(
+            raw,
+            family="word_box_json",
+            geometry_context=geo_ctx,
+            document_id="roundtrip_test",
+        )
+
+        # Serialize to JSON and back
+        json_str = doc.model_dump_json()
+        from src.app.domain.models import CanonicalDocument
+
+        doc2 = CanonicalDocument.model_validate_json(json_str)
+
+        # Same structure
+        assert doc2.document_id == doc.document_id
+        assert len(doc2.pages) == 1
+        words_original = [
+            w.text for r in doc.pages[0].text_regions for l in r.lines for w in l.words
+        ]
+        words_restored = [
+            w.text for r in doc2.pages[0].text_regions for l in r.lines for w in l.words
+        ]
+        assert words_original == words_restored
+
+        # Same ALTO output
+        alto1 = serialize_alto(doc)
+        alto2 = serialize_alto(doc2)
+        assert alto1 == alto2

tests/unit/test_adapter_word_box.py

@@ -0,0 +1,229 @@
+"""Tests for the word_box_json adapter (PaddleOCR format)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from src.app.domain.models import (
+    EvidenceType,
+    GeometryStatus,
+    RawProviderPayload,
+)
+from src.app.domain.models.geometry import GeometryContext
+from src.app.providers.adapters.word_box_json import WordBoxJsonAdapter
+
+
+@pytest.fixture
+def adapter() -> WordBoxJsonAdapter:
+    return WordBoxJsonAdapter()
+
+
+@pytest.fixture
+def paddle_payload(fixtures_dir: Path) -> list:
+    with open(fixtures_dir / "paddle_ocr_sample.json") as f:
+        return json.load(f)
+
+
+@pytest.fixture
+def raw(paddle_payload: list) -> RawProviderPayload:
+    return RawProviderPayload(
+        provider_id="paddleocr",
+        adapter_id="adapter.word_box_json.v1",
+        runtime_type="local",
+        payload=paddle_payload,
+        image_width=2480,
+        image_height=3508,
+    )
+
+
+@pytest.fixture
+def geo_ctx() -> GeometryContext:
+    return GeometryContext(source_width=2480, source_height=3508)
+
+
+class TestWordBoxJsonAdapter:
+    def test_family(self, adapter: WordBoxJsonAdapter) -> None:
+        assert adapter.family == "word_box_json"
+
+    def test_version(self, adapter: WordBoxJsonAdapter) -> None:
+        assert "v1" in adapter.version
+
+    def test_normalize_produces_valid_document(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(
+            raw, geo_ctx, document_id="test_doc", source_filename="test.png"
+        )
+        assert doc.document_id == "test_doc"
+        assert doc.source.filename == "test.png"
+        assert len(doc.pages) == 1
+
+    def test_page_dimensions(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        page = doc.pages[0]
+        assert page.width == 2480
+        assert page.height == 3508
+
+    def test_correct_word_count(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        page = doc.pages[0]
+        # 5 items in fixture → 5 lines, each with 1 word
+        total_words = sum(
+            len(line.words)
+            for region in page.text_regions
+            for line in region.lines
+        )
+        assert total_words == 5
+
+    def test_word_text_preserved(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        words = [
+            w.text
+            for r in doc.pages[0].text_regions
+            for l in r.lines
+            for w in l.words
+        ]
+        assert words[0] == "Bonjour"
+        assert words[1] == "le"
+        assert words[2] == "monde"
+
+    def test_confidence_preserved(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        first_word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert first_word.confidence == pytest.approx(0.96)
+
+    def test_geometry_is_exact(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        first_word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert first_word.geometry.status == GeometryStatus.EXACT
+
+    def test_polygon_preserved(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        first_word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert first_word.geometry.polygon is not None
+        assert len(first_word.geometry.polygon) == 4
+
+    def test_bbox_correct(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        first_word = doc.pages[0].text_regions[0].lines[0].words[0]
+        # From fixture: [[100,200],[300,200],[300,240],[100,240]]
+        # → bbox = (100, 200, 200, 40)
+        x, y, w, h = first_word.geometry.bbox
+        assert x == pytest.approx(100)
+        assert y == pytest.approx(200)
+        assert w == pytest.approx(200)
+        assert h == pytest.approx(40)
+
+    def test_provenance_native(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        first_word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert first_word.provenance.evidence_type == EvidenceType.PROVIDER_NATIVE
+        assert first_word.provenance.provider == "paddleocr"
+        assert "$[0]" in first_word.provenance.source_ref
+
+    def test_block_is_inferred(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        region = doc.pages[0].text_regions[0]
+        assert region.geometry.status == GeometryStatus.INFERRED
+        assert region.provenance.evidence_type == EvidenceType.DERIVED
+
+    def test_reading_order(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        assert doc.pages[0].reading_order == ["tb1"]
+
+    def test_empty_payload_rejected(
+        self,
+        adapter: WordBoxJsonAdapter,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="test",
+            adapter_id="v1",
+            runtime_type="local",
+            payload=[],
+        )
+        with pytest.raises(ValueError, match="no items"):
+            adapter.normalize(raw, geo_ctx, document_id="test_doc")
+
+    def test_dict_payload_rejected(
+        self,
+        adapter: WordBoxJsonAdapter,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="test",
+            adapter_id="v1",
+            runtime_type="local",
+            payload={"not": "a list"},
+        )
+        with pytest.raises(ValueError, match="list payload"):
+            adapter.normalize(raw, geo_ctx, document_id="test_doc")
+
+    def test_json_roundtrip(
+        self,
+        adapter: WordBoxJsonAdapter,
+        raw: RawProviderPayload,
+        geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_doc")
+        data = doc.model_dump(mode="json")
+        from src.app.domain.models import CanonicalDocument
+
+        doc2 = CanonicalDocument.model_validate(data)
+        assert doc2.document_id == doc.document_id

tests/unit/test_alto_serializer.py

@@ -0,0 +1,285 @@
+"""Tests for the ALTO XML serializer."""
+
+from __future__ import annotations
+
+from lxml import etree
+
+from src.app.domain.models import (
+    AltoReadiness,
+    CanonicalDocument,
+    EvidenceType,
+    Geometry,
+    GeometryStatus,
+    Hyphenation,
+    Page,
+    PageXmlReadiness,
+    Provenance,
+    ReadinessLevel,
+    Source,
+    TextLine,
+    TextRegion,
+    Word,
+)
+from src.app.domain.models.status import BlockRole, InputType
+from src.app.serializers.alto_xml import ALTO_NS, serialize_alto, serialize_alto_to_string
+
+
+def _prov(ref: str = "$.test") -> Provenance:
+    return Provenance(
+        provider="test",
+        adapter="test.v1",
+        source_ref=ref,
+        evidence_type=EvidenceType.PROVIDER_NATIVE,
+    )
+
+
+def _geo(x: float = 100, y: float = 200, w: float = 300, h: float = 50) -> Geometry:
+    return Geometry(bbox=(x, y, w, h), status=GeometryStatus.EXACT)
+
+
+def _simple_doc() -> CanonicalDocument:
+    """A simple one-page document with one block, one line, two words."""
+    return CanonicalDocument(
+        document_id="doc_alto_test",
+        source=Source(input_type=InputType.IMAGE, filename="test.png"),
+        pages=[
+            Page(
+                id="p1",
+                page_index=0,
+                width=2480,
+                height=3508,
+                alto_readiness=AltoReadiness(level=ReadinessLevel.FULL),
+                page_readiness=PageXmlReadiness(level=ReadinessLevel.FULL),
+                reading_order=["tb1"],
+                text_regions=[
+                    TextRegion(
+                        id="tb1",
+                        role=BlockRole.BODY,
+                        geometry=_geo(100, 200, 1200, 900),
+                        lang="fra",
+                        provenance=_prov(),
+                        lines=[
+                            TextLine(
+                                id="tl1",
+                                geometry=_geo(110, 220, 1100, 42),
+                                lang="fra",
+                                provenance=_prov(),
+                                words=[
+                                    Word(
+                                        id="w1",
+                                        text="Bonjour",
+                                        geometry=_geo(110, 220, 90, 40),
+                                        lang="fra",
+                                        confidence=0.96,
+                                        provenance=_prov(),
+                                    ),
+                                    Word(
+                                        id="w2",
+                                        text="monde",
+                                        geometry=_geo(220, 220, 80, 40),
+                                        lang="fra",
+                                        confidence=0.94,
+                                        provenance=_prov(),
+                                    ),
+                                ],
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+
+class TestAltoSerialization:
+    def test_produces_valid_xml(self) -> None:
+        doc = _simple_doc()
+        xml_bytes = serialize_alto(doc)
+        # Should parse without error
+        root = etree.fromstring(xml_bytes)
+        assert root.tag == f"{{{ALTO_NS}}}alto"
+
+    def test_has_description(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        desc = root.find(f"{{{ALTO_NS}}}Description")
+        assert desc is not None
+
+    def test_has_layout(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        layout = root.find(f"{{{ALTO_NS}}}Layout")
+        assert layout is not None
+
+    def test_page_attributes(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        page = root.find(f".//{{{ALTO_NS}}}Page")
+        assert page is not None
+        assert page.get("ID") == "p1"
+        assert page.get("WIDTH") == "2480"
+        assert page.get("HEIGHT") == "3508"
+
+    def test_text_block_exists(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        tb = root.find(f".//{{{ALTO_NS}}}TextBlock")
+        assert tb is not None
+        assert tb.get("ID") == "tb1"
+
+    def test_text_block_bbox(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        tb = root.find(f".//{{{ALTO_NS}}}TextBlock")
+        assert tb.get("HPOS") == "100"
+        assert tb.get("VPOS") == "200"
+        assert tb.get("WIDTH") == "1200"
+        assert tb.get("HEIGHT") == "900"
+
+    def test_text_line_exists(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        tl = root.find(f".//{{{ALTO_NS}}}TextLine")
+        assert tl is not None
+        assert tl.get("ID") == "tl1"
+
+    def test_strings_exist(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        strings = root.findall(f".//{{{ALTO_NS}}}String")
+        assert len(strings) == 2
+
+    def test_string_content(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        strings = root.findall(f".//{{{ALTO_NS}}}String")
+        assert strings[0].get("CONTENT") == "Bonjour"
+        assert strings[1].get("CONTENT") == "monde"
+
+    def test_string_bbox(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        s = root.findall(f".//{{{ALTO_NS}}}String")[0]
+        assert s.get("HPOS") == "110"
+        assert s.get("VPOS") == "220"
+        assert s.get("WIDTH") == "90"
+        assert s.get("HEIGHT") == "40"
+
+    def test_string_confidence(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        s = root.findall(f".//{{{ALTO_NS}}}String")[0]
+        assert s.get("WC") == "0.96"
+
+    def test_string_lang(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        tb = root.find(f".//{{{ALTO_NS}}}TextBlock")
+        assert tb.get("LANG") == "fra"
+
+    def test_sp_between_words(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        tl = root.find(f".//{{{ALTO_NS}}}TextLine")
+        children = list(tl)
+        # Should be: String, SP, String
+        tags = [c.tag.split("}")[-1] for c in children]
+        assert tags == ["String", "SP", "String"]
+
+    def test_measurement_unit(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        mu = root.find(f".//{{{ALTO_NS}}}MeasurementUnit")
+        assert mu is not None
+        assert mu.text == "pixel"
+
+    def test_filename_in_description(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_alto(doc))
+        fn = root.find(f".//{{{ALTO_NS}}}fileName")
+        assert fn is not None
+        assert fn.text == "test.png"
+
+    def test_string_output(self) -> None:
+        doc = _simple_doc()
+        xml_str = serialize_alto_to_string(doc)
+        assert '<?xml version=' in xml_str
+        assert "Bonjour" in xml_str
+        assert "monde" in xml_str
+
+
+class TestAltoHyphenation:
+    def test_hyphenated_words(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc_hyph",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[
+                Page(
+                    id="p1",
+                    page_index=0,
+                    width=1000,
+                    height=1000,
+                    alto_readiness=AltoReadiness(level=ReadinessLevel.FULL),
+                    page_readiness=PageXmlReadiness(level=ReadinessLevel.FULL),
+                    text_regions=[
+                        TextRegion(
+                            id="tb1",
+                            geometry=_geo(0, 0, 1000, 500),
+                            provenance=_prov(),
+                            lines=[
+                                TextLine(
+                                    id="tl1",
+                                    geometry=_geo(0, 0, 500, 40),
+                                    provenance=_prov(),
+                                    words=[
+                                        Word(
+                                            id="w1",
+                                            text="patri-",
+                                            geometry=_geo(0, 0, 80, 30),
+                                            provenance=_prov(),
+                                            hyphenation=Hyphenation(
+                                                is_hyphenated=True,
+                                                part=1,
+                                                full_form="patrimoine",
+                                            ),
+                                        ),
+                                    ],
+                                ),
+                                TextLine(
+                                    id="tl2",
+                                    geometry=_geo(0, 50, 500, 40),
+                                    provenance=_prov(),
+                                    words=[
+                                        Word(
+                                            id="w2",
+                                            text="moine",
+                                            geometry=_geo(0, 50, 70, 30),
+                                            provenance=_prov(),
+                                            hyphenation=Hyphenation(
+                                                is_hyphenated=True,
+                                                part=2,
+                                                full_form="patrimoine",
+                                            ),
+                                        ),
+                                    ],
+                                ),
+                            ],
+                        ),
+                    ],
+                ),
+            ],
+        )
+
+        root = etree.fromstring(serialize_alto(doc))
+        strings = root.findall(f".//{{{ALTO_NS}}}String")
+        assert len(strings) == 2
+
+        s1 = strings[0]
+        assert s1.get("CONTENT") == "patri-"
+        assert s1.get("SUBS_TYPE") == "HypPart1"
+        assert s1.get("SUBS_CONTENT") == "patrimoine"
+
+        s2 = strings[1]
+        assert s2.get("CONTENT") == "moine"
+        assert s2.get("SUBS_TYPE") == "HypPart2"
+        assert s2.get("SUBS_CONTENT") == "patrimoine"

tests/unit/test_canonical_builder.py

@@ -0,0 +1,102 @@
+"""Tests for the CanonicalBuilder."""
+
+from __future__ import annotations
+
+import pytest
+
+from src.app.domain.models import (
+    EvidenceType,
+    Geometry,
+    GeometryStatus,
+    Provenance,
+)
+from src.app.domain.models.status import BlockRole, InputType
+from src.app.normalization.canonical_builder import CanonicalBuilder
+
+
+def _geo() -> Geometry:
+    return Geometry(bbox=(100, 200, 300, 50), status=GeometryStatus.EXACT)
+
+
+def _prov(ref: str = "$.test") -> Provenance:
+    return Provenance(
+        provider="test",
+        adapter="test.v1",
+        source_ref=ref,
+        evidence_type=EvidenceType.PROVIDER_NATIVE,
+    )
+
+
+class TestCanonicalBuilder:
+    def test_minimal_document(self) -> None:
+        builder = CanonicalBuilder("doc1", InputType.IMAGE, "test.png")
+        page = builder.add_page("p1", 0, 2480, 3508)
+        region = page.add_text_region("tb1", _geo(), _prov(), role=BlockRole.BODY)
+        line = region.add_line("tl1", _geo(), _prov())
+        line.add_word("w1", "Hello", _geo(), _prov(), confidence=0.95)
+
+        doc = builder.build()
+        assert doc.document_id == "doc1"
+        assert len(doc.pages) == 1
+        assert len(doc.pages[0].text_regions) == 1
+        assert doc.pages[0].text_regions[0].lines[0].words[0].text == "Hello"
+
+    def test_reading_order_auto_built(self) -> None:
+        builder = CanonicalBuilder("doc1", InputType.IMAGE)
+        page = builder.add_page("p1", 0, 100, 100)
+        page.add_text_region("tb1", _geo(), _prov()).\
+            add_line("tl1", _geo(), _prov()).\
+            add_word("w1", "A", _geo(), _prov())
+        page.add_text_region("tb2", _geo(), _prov()).\
+            add_line("tl2", _geo(), _prov()).\
+            add_word("w2", "B", _geo(), _prov())
+
+        doc = builder.build()
+        assert doc.pages[0].reading_order == ["tb1", "tb2"]
+
+    def test_no_pages_raises(self) -> None:
+        builder = CanonicalBuilder("doc1", InputType.IMAGE)
+        with pytest.raises(ValueError, match="at least one page"):
+            builder.build()
+
+    def test_empty_region_raises(self) -> None:
+        builder = CanonicalBuilder("doc1", InputType.IMAGE)
+        page = builder.add_page("p1", 0, 100, 100)
+        page.add_text_region("tb1", _geo(), _prov())
+        with pytest.raises(ValueError, match="no lines"):
+            builder.build()
+
+    def test_empty_line_raises(self) -> None:
+        builder = CanonicalBuilder("doc1", InputType.IMAGE)
+        page = builder.add_page("p1", 0, 100, 100)
+        region = page.add_text_region("tb1", _geo(), _prov())
+        region.add_line("tl1", _geo(), _prov())
+        with pytest.raises(ValueError, match="no words"):
+            builder.build()
+
+    def test_multiple_words_per_line(self) -> None:
+        builder = CanonicalBuilder("doc1", InputType.IMAGE)
+        page = builder.add_page("p1", 0, 1000, 1000)
+        region = page.add_text_region("tb1", _geo(), _prov())
+        line = region.add_line("tl1", _geo(), _prov())
+        line.add_word("w1", "Hello", _geo(), _prov())
+        line.add_word("w2", "world", _geo(), _prov())
+
+        doc = builder.build()
+        assert len(doc.pages[0].text_regions[0].lines[0].words) == 2
+        assert doc.pages[0].text_regions[0].lines[0].text == "Hello world"
+
+    def test_with_metadata(self) -> None:
+        builder = CanonicalBuilder(
+            "doc1", InputType.IMAGE, metadata={"project": "test"}
+        )
+        page = builder.add_page("p1", 0, 100, 100)
+        page.set_metadata({"page_quality": "good"})
+        region = page.add_text_region("tb1", _geo(), _prov())
+        line = region.add_line("tl1", _geo(), _prov())
+        line.add_word("w1", "ok", _geo(), _prov(), metadata={"custom": True})
+
+        doc = builder.build()
+        assert doc.metadata == {"project": "test"}
+        assert doc.pages[0].metadata == {"page_quality": "good"}
+        assert doc.pages[0].text_regions[0].lines[0].words[0].metadata == {"custom": True}