Sprint 9: complete provider system — runtimes, adapters, registry, resolver

Three runtimes (skeleton for V1, actual execution deferred):
- local_runtime.py: for locally installed models
- hub_runtime.py: for HF Hub models (detects huggingface_hub availability)
- api_runtime.py: for external HTTP endpoints (configurable timeout/retries)

Two new adapters:
- line_box_json: handles providers returning lines with bboxes but no word
segmentation. Converts xyxy→xywh. Each line becomes one word. Block inferred
- text_only: handles mLLM providers (Qwen, etc.) returning text without
geometry. Geometry marked 'unknown' — honest about data absence. Splits
text into paragraphs and lines. ALTO will be refused, PAGE may be partial

Provider infrastructure:
- registry.py: central index of adapters (3 families) and runtimes (3 types)
with get_adapter(), get_runtime(), list_*() functions
- resolver.py: ResolvedProvider — resolves ProviderProfile into concrete
runtime + adapter pair. No magic: profile declares family + runtime_type
- normalization/pipeline.py: updated to use registry instead of local map

28 new tests (line_box adapter: 8, text_only adapter: 8, registry: 9,
resolver: 3). 460 total passing.

https://claude.ai/code/session_01Cuzvc9Pjfo5u46eT3ta2Cg

src/app/normalization/pipeline.py

@@ -1,7 +1,7 @@
 """Normalization pipeline — orchestrates raw → canonical conversion.
 
 The pipeline:
-  1. Resolves the adapter from the provider profile
+  1. Resolves the adapter from the provider registry
   2. Runs the adapter to produce a CanonicalDocument
   3. Returns the document (enrichers and validators are separate steps)
 """
@@ -10,27 +10,7 @@ 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()
+from src.app.providers.registry import get_adapter
 
 
 def normalize(

src/app/providers/adapters/line_box_json.py

@@ -0,0 +1,149 @@
+"""line_box_json adapter — handles providers that return lines with bboxes but no word segmentation.
+
+Expected payload format:
+    [
+        {"text": "line text", "bbox": [x1, y1, x2, y2], "confidence": 0.95},
+        ...
+    ]
+    or:
+    [
+        {"text": "line text", "bbox": [x, y, w, h], "confidence": 0.95, "format": "xywh"},
+        ...
+    ]
+
+Each item is treated as a text line. A single word per line is created
+since the provider doesn't segment words. The block is inferred.
+"""
+
+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 xyxy_to_xywh
+from src.app.normalization.canonical_builder import CanonicalBuilder
+from src.app.providers.adapters.base import BaseAdapter
+
+
+class LineBoxJsonAdapter(BaseAdapter):
+    """Adapter for the line_box_json family."""
+
+    @property
+    def family(self) -> str:
+        return "line_box_json"
+
+    @property
+    def version(self) -> str:
+        return "adapter.line_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"line_box_json expects a list payload, got {type(payload).__name__}"
+            )
+        if not payload:
+            raise ValueError("line_box_json payload contains no items")
+
+        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,
+        )
+
+        line_bboxes: list[tuple[float, float, float, float]] = []
+        line_data: list[dict] = []
+
+        for idx, item in enumerate(payload):
+            if not isinstance(item, dict):
+                raise ValueError(f"Item {idx}: expected dict, got {type(item).__name__}")
+
+            text = str(item.get("text", ""))
+            if not text:
+                continue
+
+            raw_bbox = item.get("bbox")
+            if not raw_bbox or len(raw_bbox) != 4:
+                raise ValueError(f"Item {idx}: missing or invalid bbox")
+
+            # Determine format: default is xyxy, "xywh" if specified
+            fmt = item.get("format", "xyxy")
+            if fmt == "xywh":
+                bbox = (float(raw_bbox[0]), float(raw_bbox[1]),
+                        float(raw_bbox[2]), float(raw_bbox[3]))
+            else:
+                bbox = xyxy_to_xywh(tuple(float(v) for v in raw_bbox))
+
+            confidence = item.get("confidence")
+            if confidence is not None:
+                confidence = max(0.0, min(1.0, float(confidence)))
+
+            line_bboxes.append(bbox)
+            line_data.append({
+                "bbox": bbox,
+                "text": text,
+                "confidence": confidence,
+                "source_idx": idx,
+            })
+
+        if not line_data:
+            raise ValueError("line_box_json payload contains no valid items")
+
+        block_bbox = union_all(line_bboxes)
+        block_prov = Provenance(
+            provider=raw.provider_id,
+            adapter=self.version,
+            source_ref="$",
+            evidence_type=EvidenceType.DERIVED,
+            derived_from=[f"tl{i+1}" for i in range(len(line_data))],
+        )
+
+        region = page.add_text_region(
+            region_id="tb1",
+            geometry=Geometry(bbox=block_bbox, status=GeometryStatus.INFERRED),
+            provenance=block_prov,
+        )
+
+        for i, ld in enumerate(line_data):
+            line_id = f"tl{i + 1}"
+            word_id = f"w{i + 1}"
+
+            prov = Provenance(
+                provider=raw.provider_id,
+                adapter=self.version,
+                source_ref=f"$[{ld['source_idx']}]",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+            )
+
+            geo = Geometry(bbox=ld["bbox"], status=GeometryStatus.EXACT)
+
+            line = region.add_line(line_id, geometry=geo, provenance=prov)
+            line.add_word(
+                word_id,
+                text=ld["text"],
+                geometry=geo,
+                provenance=prov,
+                confidence=ld["confidence"],
+            )
+
+        return builder.build()

src/app/providers/adapters/text_only.py

@@ -0,0 +1,124 @@
+"""text_only adapter — handles providers that return structured text without geometry.
+
+Expected payload format:
+    {
+        "text": "full page text",
+        "blocks": [                     # optional
+            {"text": "block text"},
+            ...
+        ]
+    }
+    or simply:
+    {"text": "full text"}
+
+This adapter is honest: geometry is marked as 'unknown' since the
+provider doesn't supply coordinates. ALTO export will be refused
+(no word geometry), but PAGE export may be partial and the viewer
+will show text without positioned overlays.
+"""
+
+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.normalization.canonical_builder import CanonicalBuilder
+from src.app.providers.adapters.base import BaseAdapter
+
+
+class TextOnlyAdapter(BaseAdapter):
+    """Adapter for the text_only family (mLLM without geometry)."""
+
+    @property
+    def family(self) -> str:
+        return "text_only"
+
+    @property
+    def version(self) -> str:
+        return "adapter.text_only.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, dict):
+            raise ValueError(
+                f"text_only expects a dict payload, got {type(payload).__name__}"
+            )
+
+        builder = CanonicalBuilder(
+            document_id=document_id,
+            input_type=InputType.IMAGE,
+            filename=source_filename,
+        )
+
+        page_w = geometry_context.source_width
+        page_h = geometry_context.source_height
+
+        page = builder.add_page("p1", 0, page_w, page_h)
+
+        # Placeholder bbox covering the full page — marked unknown
+        full_page_geo = Geometry(
+            bbox=(0, 0, page_w, page_h),
+            status=GeometryStatus.UNKNOWN,
+        )
+
+        # Extract text blocks
+        blocks = payload.get("blocks")
+        if blocks and isinstance(blocks, list):
+            texts = [str(b.get("text", "")) for b in blocks if isinstance(b, dict) and b.get("text")]
+        else:
+            # Single text blob — split into paragraphs
+            full_text = str(payload.get("text", ""))
+            if not full_text.strip():
+                raise ValueError("text_only payload has no text content")
+            texts = [p.strip() for p in full_text.split("\n\n") if p.strip()]
+            if not texts:
+                texts = [full_text.strip()]
+
+        for bi, block_text in enumerate(texts):
+            block_id = f"tb{bi + 1}"
+            prov = Provenance(
+                provider=raw.provider_id,
+                adapter=self.version,
+                source_ref=f"$.blocks[{bi}]" if blocks else f"$.text.paragraph[{bi}]",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+            )
+
+            region = page.add_text_region(
+                region_id=block_id,
+                geometry=full_page_geo,
+                provenance=prov,
+            )
+
+            # Split block into lines
+            lines = [l.strip() for l in block_text.split("\n") if l.strip()]
+            if not lines:
+                lines = [block_text]
+
+            for li, line_text in enumerate(lines):
+                line_id = f"tl{bi + 1}_{li + 1}"
+                word_id = f"w{bi + 1}_{li + 1}"
+
+                line = region.add_line(
+                    line_id, geometry=full_page_geo, provenance=prov,
+                )
+                # Each line becomes a single word (no word segmentation available)
+                line.add_word(
+                    word_id,
+                    text=line_text,
+                    geometry=full_page_geo,
+                    provenance=prov,
+                )
+
+        return builder.build()

src/app/providers/registry.py

@@ -0,0 +1,60 @@
+"""Provider registry — central index of available adapters and runtimes."""
+
+from __future__ import annotations
+
+from src.app.providers.adapters.base import BaseAdapter
+from src.app.providers.adapters.line_box_json import LineBoxJsonAdapter
+from src.app.providers.adapters.text_only import TextOnlyAdapter
+from src.app.providers.adapters.word_box_json import WordBoxJsonAdapter
+from src.app.providers.profiles import ProviderFamily, RuntimeType
+from src.app.providers.runtimes.api_runtime import ApiRuntime
+from src.app.providers.runtimes.base import BaseRuntime
+from src.app.providers.runtimes.hub_runtime import HubRuntime
+from src.app.providers.runtimes.local_runtime import LocalRuntime
+
+# -- Adapter registry ---------------------------------------------------------
+
+_ADAPTER_REGISTRY: dict[str, type[BaseAdapter]] = {
+    ProviderFamily.WORD_BOX_JSON.value: WordBoxJsonAdapter,
+    ProviderFamily.LINE_BOX_JSON.value: LineBoxJsonAdapter,
+    ProviderFamily.TEXT_ONLY.value: TextOnlyAdapter,
+}
+
+
+def get_adapter(family: str) -> BaseAdapter:
+    """Instantiate an adapter for the given provider family."""
+    cls = _ADAPTER_REGISTRY.get(family)
+    if cls is None:
+        raise KeyError(
+            f"No adapter for family '{family}'. "
+            f"Available: {list(_ADAPTER_REGISTRY.keys())}"
+        )
+    return cls()
+
+
+def list_adapter_families() -> list[str]:
+    return list(_ADAPTER_REGISTRY.keys())
+
+
+# -- Runtime registry ---------------------------------------------------------
+
+_RUNTIME_REGISTRY: dict[str, type[BaseRuntime]] = {
+    RuntimeType.LOCAL.value: LocalRuntime,
+    RuntimeType.HUB.value: HubRuntime,
+    RuntimeType.API.value: ApiRuntime,
+}
+
+
+def get_runtime(runtime_type: str, **kwargs: object) -> BaseRuntime:
+    """Instantiate a runtime for the given type."""
+    cls = _RUNTIME_REGISTRY.get(runtime_type)
+    if cls is None:
+        raise KeyError(
+            f"No runtime for type '{runtime_type}'. "
+            f"Available: {list(_RUNTIME_REGISTRY.keys())}"
+        )
+    return cls(**kwargs)  # type: ignore[arg-type]
+
+
+def list_runtime_types() -> list[str]:
+    return list(_RUNTIME_REGISTRY.keys())

src/app/providers/resolver.py

@@ -0,0 +1,38 @@
+"""Provider resolver — resolves a ProviderProfile into runtime + adapter."""
+
+from __future__ import annotations
+
+from src.app.providers.adapters.base import BaseAdapter
+from src.app.providers.profiles import ProviderProfile
+from src.app.providers.registry import get_adapter, get_runtime
+from src.app.providers.runtimes.base import BaseRuntime
+
+
+class ResolvedProvider:
+    """A fully resolved provider: runtime + adapter, ready to execute."""
+
+    def __init__(self, profile: ProviderProfile, runtime: BaseRuntime, adapter: BaseAdapter) -> None:
+        self.profile = profile
+        self.runtime = runtime
+        self.adapter = adapter
+
+    @property
+    def provider_id(self) -> str:
+        return self.profile.provider_id
+
+    @property
+    def family(self) -> str:
+        return self.profile.family.value
+
+
+def resolve_provider(profile: ProviderProfile) -> ResolvedProvider:
+    """Resolve a provider profile into a runtime + adapter pair.
+
+    No magic: the profile explicitly declares its runtime_type and family.
+    We look them up in the registries.
+
+    Raises KeyError if the runtime or family is not registered.
+    """
+    runtime = get_runtime(profile.runtime_type.value)
+    adapter = get_adapter(profile.family.value)
+    return ResolvedProvider(profile=profile, runtime=runtime, adapter=adapter)

src/app/providers/runtimes/api_runtime.py

@@ -0,0 +1,37 @@
+"""API runtime — calls an external HTTP endpoint."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from src.app.domain.models import RawProviderPayload
+from src.app.providers.runtimes.base import BaseRuntime
+
+
+class ApiRuntime(BaseRuntime):
+    """Runtime that calls an external API endpoint.
+
+    Supports OpenAI-compatible and custom endpoints.
+    In V1 this is a skeleton — actual HTTP calls will be added
+    when API-based providers are integrated.
+    """
+
+    def __init__(self, timeout: int = 60, max_retries: int = 2) -> None:
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    def execute(
+        self,
+        image_path: Path,
+        model_id: str,
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> RawProviderPayload:
+        raise NotImplementedError(
+            "ApiRuntime.execute is not yet implemented. "
+            "In V1, provide raw payloads directly to the job service."
+        )
+
+    def is_available(self) -> bool:
+        return True

src/app/providers/runtimes/hub_runtime.py

@@ -0,0 +1,35 @@
+"""Hub runtime — loads a model from the Hugging Face Hub."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from src.app.domain.models import RawProviderPayload
+from src.app.providers.runtimes.base import BaseRuntime
+
+
+class HubRuntime(BaseRuntime):
+    """Runtime for models loaded from the Hugging Face Hub.
+
+    Uses HF_HOME for caching. In V1 this is a skeleton.
+    """
+
+    def execute(
+        self,
+        image_path: Path,
+        model_id: str,
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> RawProviderPayload:
+        raise NotImplementedError(
+            "HubRuntime.execute is not yet implemented. "
+            "In V1, provide raw payloads directly to the job service."
+        )
+
+    def is_available(self) -> bool:
+        try:
+            import huggingface_hub  # noqa: F401
+            return True
+        except ImportError:
+            return False

src/app/providers/runtimes/local_runtime.py

@@ -0,0 +1,32 @@
+"""Local runtime — loads and runs a model from a local directory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from src.app.domain.models import RawProviderPayload
+from src.app.providers.runtimes.base import BaseRuntime
+
+
+class LocalRuntime(BaseRuntime):
+    """Runtime for locally installed models.
+
+    In V1 this is a skeleton — actual model loading will be integrated
+    when specific providers (PaddleOCR, etc.) are wired in.
+    """
+
+    def execute(
+        self,
+        image_path: Path,
+        model_id: str,
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> RawProviderPayload:
+        raise NotImplementedError(
+            "LocalRuntime.execute is not yet implemented. "
+            "In V1, provide raw payloads directly to the job service."
+        )
+
+    def is_available(self) -> bool:
+        return True

tests/fixtures/line_box_sample.json

@@ -0,0 +1,5 @@
+[
+  {"text": "Bonjour le monde", "bbox": [100, 200, 600, 240], "confidence": 0.95},
+  {"text": "Ceci est une ligne", "bbox": [100, 260, 550, 300], "confidence": 0.92},
+  {"text": "Troisième ligne ici", "bbox": [100, 320, 520, 360], "confidence": 0.88}
+]

tests/fixtures/text_only_sample.json

@@ -0,0 +1,4 @@
+{
+  "text": "Bonjour le monde.\nCeci est la première ligne.\n\nDeuxième paragraphe.\nAvec deux lignes.",
+  "model": "qwen3-vl"
+}

tests/unit/test_provider_system.py

@@ -0,0 +1,282 @@
+"""Tests for the provider system: adapters, registry, resolver."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from src.app.domain.models import GeometryStatus, RawProviderPayload
+from src.app.domain.models.geometry import GeometryContext
+from src.app.providers.adapters.line_box_json import LineBoxJsonAdapter
+from src.app.providers.adapters.text_only import TextOnlyAdapter
+from src.app.providers.capabilities import CapabilityMatrix
+from src.app.providers.profiles import ProviderFamily, ProviderProfile, RuntimeType
+from src.app.providers.registry import (
+    get_adapter,
+    get_runtime,
+    list_adapter_families,
+    list_runtime_types,
+)
+from src.app.providers.resolver import resolve_provider
+
+
+@pytest.fixture
+def geo_ctx() -> GeometryContext:
+    return GeometryContext(source_width=2480, source_height=3508)
+
+
+# -- LineBoxJsonAdapter -------------------------------------------------------
+
+
+class TestLineBoxJsonAdapter:
+    @pytest.fixture
+    def adapter(self) -> LineBoxJsonAdapter:
+        return LineBoxJsonAdapter()
+
+    @pytest.fixture
+    def raw(self, fixtures_dir: Path) -> RawProviderPayload:
+        with open(fixtures_dir / "line_box_sample.json") as f:
+            payload = json.load(f)
+        return RawProviderPayload(
+            provider_id="line_model", adapter_id="v1", runtime_type="local",
+            payload=payload, image_width=2480, image_height=3508,
+        )
+
+    def test_family(self, adapter: LineBoxJsonAdapter) -> None:
+        assert adapter.family == "line_box_json"
+
+    def test_normalize_produces_document(
+        self, adapter: LineBoxJsonAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_line")
+        assert doc.document_id == "test_line"
+        assert len(doc.pages) == 1
+
+    def test_correct_line_count(
+        self, adapter: LineBoxJsonAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        total_lines = sum(
+            len(r.lines) for r in doc.pages[0].text_regions
+        )
+        assert total_lines == 3
+
+    def test_bbox_converted_from_xyxy(
+        self, adapter: LineBoxJsonAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        first_line = doc.pages[0].text_regions[0].lines[0]
+        x, y, w, h = first_line.geometry.bbox
+        # From fixture: [100, 200, 600, 240] → xyxy → xywh: (100, 200, 500, 40)
+        assert x == pytest.approx(100)
+        assert y == pytest.approx(200)
+        assert w == pytest.approx(500)
+        assert h == pytest.approx(40)
+
+    def test_text_preserved(
+        self, adapter: LineBoxJsonAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert word.text == "Bonjour le monde"
+
+    def test_geometry_status_exact(
+        self, adapter: LineBoxJsonAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        line = doc.pages[0].text_regions[0].lines[0]
+        assert line.geometry.status == GeometryStatus.EXACT
+
+    def test_empty_payload_rejected(
+        self, adapter: LineBoxJsonAdapter, geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="t", adapter_id="v1", runtime_type="local", payload=[],
+        )
+        with pytest.raises(ValueError, match="no items"):
+            adapter.normalize(raw, geo_ctx, document_id="test")
+
+    def test_dict_payload_rejected(
+        self, adapter: LineBoxJsonAdapter, geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="t", 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")
+
+
+# -- TextOnlyAdapter ----------------------------------------------------------
+
+
+class TestTextOnlyAdapter:
+    @pytest.fixture
+    def adapter(self) -> TextOnlyAdapter:
+        return TextOnlyAdapter()
+
+    @pytest.fixture
+    def raw(self, fixtures_dir: Path) -> RawProviderPayload:
+        with open(fixtures_dir / "text_only_sample.json") as f:
+            payload = json.load(f)
+        return RawProviderPayload(
+            provider_id="qwen3_vl", adapter_id="v1", runtime_type="api",
+            payload=payload, image_width=2480, image_height=3508,
+        )
+
+    def test_family(self, adapter: TextOnlyAdapter) -> None:
+        assert adapter.family == "text_only"
+
+    def test_normalize_produces_document(
+        self, adapter: TextOnlyAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test_text")
+        assert doc.document_id == "test_text"
+        assert len(doc.pages) == 1
+
+    def test_splits_paragraphs(
+        self, adapter: TextOnlyAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        # Fixture has 2 paragraphs separated by \n\n
+        assert len(doc.pages[0].text_regions) == 2
+
+    def test_geometry_is_unknown(
+        self, adapter: TextOnlyAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert word.geometry.status == GeometryStatus.UNKNOWN
+
+    def test_text_preserved(
+        self, adapter: TextOnlyAdapter, raw: RawProviderPayload, geo_ctx: GeometryContext,
+    ) -> None:
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        first_word = doc.pages[0].text_regions[0].lines[0].words[0]
+        assert "Bonjour" in first_word.text
+
+    def test_no_text_rejected(
+        self, adapter: TextOnlyAdapter, geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="t", adapter_id="v1", runtime_type="api",
+            payload={"text": ""},
+        )
+        with pytest.raises(ValueError, match="no text"):
+            adapter.normalize(raw, geo_ctx, document_id="test")
+
+    def test_list_payload_rejected(
+        self, adapter: TextOnlyAdapter, geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="t", adapter_id="v1", runtime_type="api",
+            payload=[1, 2, 3],
+        )
+        with pytest.raises(ValueError, match="dict payload"):
+            adapter.normalize(raw, geo_ctx, document_id="test")
+
+    def test_with_blocks(
+        self, adapter: TextOnlyAdapter, geo_ctx: GeometryContext,
+    ) -> None:
+        raw = RawProviderPayload(
+            provider_id="t", adapter_id="v1", runtime_type="api",
+            payload={
+                "text": "ignored",
+                "blocks": [
+                    {"text": "Block one line one\nBlock one line two"},
+                    {"text": "Block two"},
+                ],
+            },
+        )
+        doc = adapter.normalize(raw, geo_ctx, document_id="test")
+        assert len(doc.pages[0].text_regions) == 2
+        assert len(doc.pages[0].text_regions[0].lines) == 2
+
+
+# -- Registry -----------------------------------------------------------------
+
+
+class TestRegistry:
+    def test_list_families(self) -> None:
+        families = list_adapter_families()
+        assert "word_box_json" in families
+        assert "line_box_json" in families
+        assert "text_only" in families
+
+    def test_list_runtimes(self) -> None:
+        types = list_runtime_types()
+        assert "local" in types
+        assert "hub" in types
+        assert "api" in types
+
+    def test_get_adapter_word_box(self) -> None:
+        adapter = get_adapter("word_box_json")
+        assert adapter.family == "word_box_json"
+
+    def test_get_adapter_line_box(self) -> None:
+        adapter = get_adapter("line_box_json")
+        assert adapter.family == "line_box_json"
+
+    def test_get_adapter_text_only(self) -> None:
+        adapter = get_adapter("text_only")
+        assert adapter.family == "text_only"
+
+    def test_get_adapter_unknown(self) -> None:
+        with pytest.raises(KeyError, match="No adapter"):
+            get_adapter("unknown_family")
+
+    def test_get_runtime_local(self) -> None:
+        rt = get_runtime("local")
+        assert rt.is_available()
+
+    def test_get_runtime_api(self) -> None:
+        rt = get_runtime("api")
+        assert rt.is_available()
+
+    def test_get_runtime_unknown(self) -> None:
+        with pytest.raises(KeyError, match="No runtime"):
+            get_runtime("unknown_type")
+
+
+# -- Resolver -----------------------------------------------------------------
+
+
+class TestResolver:
+    def test_resolve_word_box_local(self) -> None:
+        profile = ProviderProfile(
+            provider_id="paddle_test",
+            display_name="PaddleOCR Test",
+            runtime_type=RuntimeType.LOCAL,
+            model_id_or_path="/models/paddle",
+            family=ProviderFamily.WORD_BOX_JSON,
+        )
+        resolved = resolve_provider(profile)
+        assert resolved.provider_id == "paddle_test"
+        assert resolved.family == "word_box_json"
+        assert resolved.adapter.family == "word_box_json"
+
+    def test_resolve_text_only_api(self) -> None:
+        profile = ProviderProfile(
+            provider_id="qwen_test",
+            display_name="Qwen Test",
+            runtime_type=RuntimeType.API,
+            model_id_or_path="qwen3-vl",
+            family=ProviderFamily.TEXT_ONLY,
+            endpoint="https://api.example.com/v1",
+        )
+        resolved = resolve_provider(profile)
+        assert resolved.family == "text_only"
+        assert resolved.runtime.is_available()
+
+    def test_resolve_line_box_hub(self) -> None:
+        profile = ProviderProfile(
+            provider_id="hub_test",
+            display_name="Hub Model",
+            runtime_type=RuntimeType.HUB,
+            model_id_or_path="user/model",
+            family=ProviderFamily.LINE_BOX_JSON,
+        )
+        resolved = resolve_provider(profile)
+        assert resolved.family == "line_box_json"