Sprint 0: project foundation — structure, settings, FastAPI skeleton

Set up the complete project scaffolding for the XmLLM document structure
engine (canonical-first architecture for image → ALTO XML / PAGE XML):

- pyproject.toml with core deps (FastAPI, Pydantic v2, lxml, Pillow) and dev deps
- Full directory structure matching the 4-anneau architecture (domain, execution, API, presentation)
- SettingsService with auto-detection of local vs HF Space mode
- FastAPI app skeleton with /health endpoint
- AGENTS.md with all non-negotiable architecture rules
- .env.example with documented configuration variables
- Test suite foundation with 6 passing tests (settings + health)

https://claude.ai/code/session_01Cuzvc9Pjfo5u46eT3ta2Cg

.env.example

@@ -0,0 +1,68 @@
+# =============================================================================
+# XmLLM — Environment Configuration
+# =============================================================================
+# Copy this file to .env and adjust values for your environment.
+
+# -----------------------------------------------------------------------------
+# Execution mode
+# -----------------------------------------------------------------------------
+# "local" or "space" — auto-detected from SPACE_ID if not set
+APP_MODE=local
+
+# -----------------------------------------------------------------------------
+# Storage
+# -----------------------------------------------------------------------------
+# Root directory for all persistent data (jobs, providers, exports, db).
+# On HF Spaces with persistent storage, use /data
+STORAGE_ROOT=./data
+
+# SQLite database path (relative to STORAGE_ROOT)
+DB_NAME=app.db
+
+# -----------------------------------------------------------------------------
+# HuggingFace (only relevant in Space mode)
+# -----------------------------------------------------------------------------
+# Set by HF automatically in Spaces — do not set manually in local mode
+# SPACE_ID=
+# HF_HOME=/data/.huggingface
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+HOST=0.0.0.0
+PORT=7860
+LOG_LEVEL=info
+
+# -----------------------------------------------------------------------------
+# Upload limits
+# -----------------------------------------------------------------------------
+# Maximum upload file size in bytes (default: 50 MB)
+MAX_UPLOAD_SIZE=52428800
+
+# Allowed MIME types for upload (comma-separated)
+ALLOWED_MIME_TYPES=image/png,image/jpeg,image/tiff,image/webp
+
+# -----------------------------------------------------------------------------
+# Provider defaults
+# -----------------------------------------------------------------------------
+# Default timeout for provider execution in seconds
+PROVIDER_TIMEOUT=120
+
+# Default timeout for API-based providers in seconds
+API_PROVIDER_TIMEOUT=60
+
+# Maximum retries for API-based providers
+API_PROVIDER_MAX_RETRIES=2
+
+# -----------------------------------------------------------------------------
+# Geometry
+# -----------------------------------------------------------------------------
+# Tolerance in pixels for bbox containment checks (child bbox may exceed parent
+# by this many pixels without triggering a validation error)
+BBOX_CONTAINMENT_TOLERANCE=5
+
+# -----------------------------------------------------------------------------
+# Secrets (referenced by name in provider profiles, never serialized)
+# -----------------------------------------------------------------------------
+# SECRET_OPENAI_API_KEY=sk-...
+# SECRET_HF_TOKEN=hf_...

.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+.env.local
+.env.production
+
+# Storage (local dev data)
+data/
+*.db
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Uploads and job artifacts (local)
+uploads/
+exports/
+
+# HuggingFace cache (local)
+.huggingface/
+
+# Node (frontend)
+frontend/node_modules/
+frontend/dist/

AGENTS.md

@@ -0,0 +1,111 @@
+# 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

README.md

@@ -0,0 +1,3 @@
+# XmLLM
+
+Document structure engine: image → canonical model → ALTO XML / PAGE XML.

pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xmllm"
+version = "0.1.0"
+description = "Document structure engine: image → canonical model → ALTO XML / PAGE XML"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [
+    { name = "XmLLM contributors" },
+]
+
+dependencies = [
+    "fastapi>=0.115,<1",
+    "uvicorn[standard]>=0.30,<1",
+    "pydantic>=2.7,<3",
+    "pydantic-settings>=2.3,<3",
+    "lxml>=5.2,<6",
+    "Pillow>=10.3,<11",
+    "python-multipart>=0.0.9",
+    "aiosqlite>=0.20,<1",
+    "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2,<9",
+    "pytest-asyncio>=0.23,<1",
+    "pytest-cov>=5,<6",
+    "httpx>=0.27,<1",
+    "ruff>=0.4,<1",
+    "mypy>=1.10,<2",
+    "lxml-stubs>=0.5",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: unit tests",
+    "integration: integration tests",
+    "e2e: end-to-end tests",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["lxml.*"]
+ignore_missing_imports = true

src/app/main.py

@@ -0,0 +1,51 @@
+"""XmLLM — Document Structure Engine.
+
+FastAPI application entry point.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from src.app.settings import Settings, get_settings
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Startup / shutdown lifecycle."""
+    settings: Settings = get_settings()
+    settings.ensure_directories()
+    yield
+
+
+app = FastAPI(
+    title="XmLLM",
+    description="Document structure engine: image → canonical model → ALTO XML / PAGE XML",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# -- Health route (always available) ------------------------------------------
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    settings = get_settings()
+    return {
+        "status": "ok",
+        "version": "0.1.0",
+        "mode": settings.app_mode.value,
+    }