AGENTS.md

AGENTS.md — XmLLM Project Rules

What this project is

XmLLM is a canonical-first document structure engine that converts images (and later PDFs) into structured ALTO XML and PAGE XML, via an internal canonical representation (CanonicalDocument).

Architecture invariants

These rules are non-negotiable. Any code change that violates them must be rejected.

1. Canonical-first

• The system is never provider-first, ALTO-first, PAGE-first, or viewer-first.
• All processing flows through CanonicalDocument.
• ALTO XML and PAGE XML are output serializations, not internal representations.

2. Three internal objects

Object	Role	Never used for
RawProviderPayload	Source truth	Export, rendering
CanonicalDocument	Business truth	Direct UI rendering
ViewerProjection	Rendering truth	Validation, export decisions

3. Domain independence

• Anneau A (domain) must not depend on FastAPI, frontend, or OpenSeadragon.
• Anneau B (execution) may depend on domain.
• Anneau C (API) may depend on domain and execution.
• Anneau D (presentation) may depend on the API layer only.

4. Provenance on every node

Every node in CanonicalDocument must carry a provenance with:

• provider: source engine name
• adapter: adapter version
• source_ref: path in the raw output
• evidence_type: provider_native | derived | repaired | manual
• derived_from: list of canonical IDs (empty if native)

5. Geometry conventions

• bbox format: [x, y, width, height] — always. x = left edge, y = top edge.
• coordinate origin: top_left — always in internal representation.
• unit: px — always in the canonical model.
• polygon: list[tuple[float, float]] | None — optional, preserved when available.
• Providers returning [x1, y1, x2, y2] must be converted in their adapter.
• No serializer may perform implicit heavy geometry conversion. All geometry must be normalized before it reaches a serializer.

6. Serializer rules

Serializers (ALTO, PAGE) must not:

• Call any model or provider
• Reconstruct segmentation
• Correct text
• Invent coordinates
• Make export eligibility decisions

They receive a validated CanonicalDocument and produce deterministic XML.

7. Export eligibility

• Every export decision must pass through validators + document policy.
• A serializer is never called when export eligibility is none.
• ALTO and PAGE eligibility are computed independently.

8. Enricher rules

Every enricher must:

• Set provenance.evidence_type to derived or inferred
• Update geometry.status if geometry was modified
• Add warnings to the document when appropriate
• Respect the active DocumentPolicy

Enrichers must not:

• Hallucinate text
• Invent fine-grained coordinates without geometric basis
• Claim provider_native evidence

9. Viewer rules

• The viewer never parses ALTO or PAGE XML.
• It works exclusively from ViewerProjection.
• No business logic in the presentation layer.

10. Single codebase

The same code runs:

• Locally (bare Python)
• In Docker
• On Hugging Face Spaces

The only difference is STORAGE_ROOT and environment detection.

Bbox containment tolerance

Bbox containment checks (child within parent) use a configurable tolerance (default: 5px). This is set via BBOX_CONTAINMENT_TOLERANCE in the environment.

Coding conventions

• Python 3.11+
• Pydantic v2 for all models
• lxml for XML serialization
• Type hints everywhere
• No Any types in domain models
• Tests alongside implementation — no sprint ships without tests