space deploy: fix zerogpu pickling

.dockerignore

@@ -0,0 +1,17 @@
+# Keeps the build context small and the image free of anything that
+# shouldn't be baked in - datasets, checkpoints, and secrets especially.
+.git/
+.pytest_cache/
+__pycache__/
+*.pyc
+.env
+data/
+runs/
+reports/
+notebooks/
+docs/
+tests/
+memo/
+*.ipynb
+.venv/
+venv/

.env.example

@@ -0,0 +1,25 @@
+# The reasoning layer in app/reasoning/ calls Groq directly through their
+# plain SDK. No agentic framework is involved - see requirements.txt and
+# the compliance note in the README.
+GROQ_API_KEY=gsk_your_key_here
+
+# Two models, because the two calls are doing different jobs.
+#
+# The router is a classification problem with a fixed output schema, so I
+# want the small fast model and I pin the output with strict json_schema.
+# Synthesis is open-ended writing, so the larger model earns its latency.
+# Both support Groq's strict structured outputs (constrained decoding).
+GROQ_ROUTER_MODEL=openai/gpt-oss-20b
+GROQ_SYNTHESIS_MODEL=openai/gpt-oss-120b
+
+# Where the fine-tuned RT-DETR weights live. See README for the download link.
+MODEL_PATH=./weights/best.pt
+
+# Optional: if MODEL_PATH doesn't exist, download it from here first. Set
+# this on a fresh Space/container instead of manually copying the weights
+# file in every time.
+# MODEL_URL=https://github.com/RISHIVELS/doc_layout_detection/releases/download/weights-v1/best.pt
+
+# Reject uploads larger than this. Document scans are rarely above a few MB,
+# so this is generous and still stops someone posting a 2 GB file at the API.
+MAX_UPLOAD_MB=10

.gitignore

@@ -0,0 +1,24 @@
+# Datasets and weights are far too large for git. The README documents
+# exactly how to regenerate the dataset and where to download the weights.
+data/
+runs/
+*.pt
+*.pth
+reports/failures/
+reports/category_splits/
+
+# Secrets
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.ipynb_checkpoints/

Dockerfile

@@ -0,0 +1,38 @@
+# CPU inference by default - a forward pass doesn't need a GPU, and this
+# way the image runs anywhere without CUDA drivers.
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# libgl/libglib for Pillow + matplotlib's font rendering (used for
+# legible label renders in scripts/_render_utils.py)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# requirements first so this layer only rebuilds when deps actually change
+COPY requirements.txt .
+
+# CPU-only torch wheel - the default PyPI package pulls the full CUDA
+# toolkit (multiple GB) for an image that never touches a GPU
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY app/ app/
+COPY scripts/_render_utils.py scripts/__init__.py scripts/
+
+# Weights aren't baked into the image (too large for git, see README for
+# the download link) - mounted or fetched at container start instead
+ENV MODEL_PATH=/app/weights/best.pt
+ENV MAX_UPLOAD_MB=10
+
+RUN useradd --create-home appuser && mkdir -p /app/weights && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=3)" || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,25 @@
+---
+title: Document Layout Detection
+emoji: 📄
+colorFrom: blue
+colorTo: gray
+sdk: gradio
+app_file: gradio_app.py
+pinned: false
+---
+
+# Constrained Document Layout Detection
+
+RT-DETR fine-tuned on DocLayNet, plus a hand-written reasoning layer for
+natural-language questions about a page's layout.
+
+Full source, training scripts, and the FastAPI API this demo shares its
+code with: see the main repo.
+
+## Space secrets needed
+
+- `GROQ_API_KEY` - for the Ask tab's reasoning layer
+- `MODEL_URL` - direct download link for the trained weights (e.g. a
+  GitHub Release asset). Downloaded automatically on first run if
+  `MODEL_PATH` doesn't already exist - no need to push the weights file
+  into the Space's git repo.

app/constants.py

@@ -0,0 +1,45 @@
+# Single source of truth for the class list. Had it duplicated across the
+# dataset script, training yaml and API code early on and they drifted -
+# no error, just silently wrong labels. Everything imports from here now.
+from __future__ import annotations
+
+# DocLayNet's 0-indexed alphabetical order. Verified against rendered pages
+# (see prepare_dataset.py --verify), don't trust the dataset card blindly.
+# Don't reorder - these ids are baked into the label files and the weights.
+CLASS_NAMES: list[str] = [
+    "Caption",
+    "Footnote",
+    "Formula",
+    "List-item",
+    "Page-footer",
+    "Page-header",
+    "Picture",
+    "Section-header",
+    "Table",
+    "Text",
+    "Title",
+]
+
+CLASS_TO_ID: dict[str, int] = {name: idx for idx, name in enumerate(CLASS_NAMES)}
+ID_TO_CLASS: dict[int, str] = {idx: name for name, idx in CLASS_TO_ID.items()}
+
+NUM_CLASSES: int = len(CLASS_NAMES)
+
+MODEL_VERSION: str = "rtdetr-l-doclaynet-v1"
+
+# The 6 doc types DocLayNet covers. Used to break mAP down per category at
+# eval time - one aggregate number can hide a model that's just good at
+# financial reports (the biggest slice) and bad at everything else.
+DOC_CATEGORIES: list[str] = [
+    "financial_reports",
+    "scientific_articles",
+    "laws_and_regulations",
+    "government_tenders",
+    "manuals",
+    "patents",
+]
+
+# RT-DETR has a fixed number of object queries, so it can only ever emit
+# this many boxes per image. Dense pages can exceed it - measured in eval
+# so that shows up as "query saturation", not unexplained recall loss.
+DEFAULT_QUERY_BUDGET: int = 300

app/detector.py

@@ -0,0 +1,83 @@
+# Thin wrapper around Ultralytics so nothing else in the app imports it
+# directly - lets me stub this out in tests without a GPU or real weights.
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from app.constants import DEFAULT_QUERY_BUDGET, ID_TO_CLASS
+from app.schemas import BBox, Detection
+
+
+class Detector:
+    """Loads RT-DETR on first use, converts raw output to Detection objects."""
+
+    def __init__(self, weights_path: str | None = None):
+        self._weights_path = weights_path or os.environ.get("MODEL_PATH", "./weights/best.pt")
+        self._model = None
+        self.query_budget = DEFAULT_QUERY_BUDGET
+
+    @property
+    def is_loaded(self) -> bool:
+        return self._model is not None
+
+    def load(self) -> None:
+        """Lazy load - keeps a bad MODEL_PATH from crashing the whole app
+        at startup. Checks the file exists first so the error is readable
+        instead of a torch.load stack trace.
+
+        If the weights aren't on disk but MODEL_URL is set, downloads them
+        first - this is what lets a fresh HF Space or Docker container just
+        work without manually copying a 66MB file into every host."""
+        if self.is_loaded:
+            return
+
+        path = Path(self._weights_path)
+        if not path.exists():
+            model_url = os.environ.get("MODEL_URL")
+            if model_url:
+                path.parent.mkdir(parents=True, exist_ok=True)
+                import urllib.request
+
+                urllib.request.urlretrieve(model_url, path)
+            else:
+                raise FileNotFoundError(
+                    f"Model weights not found at '{self._weights_path}'. "
+                    "Set MODEL_PATH to an existing file, or set MODEL_URL to "
+                    "download from - see the README for the weights link."
+                )
+
+        from ultralytics import RTDETR
+
+        self._model = RTDETR(self._weights_path)
+
+    def predict(self, image, conf: float = 0.25) -> tuple[list[Detection], float]:
+        """Runs inference, returns (detections, inference_ms). Timing is
+        measured here, not in the route handler, so it's not conflated with
+        request/network overhead.
+
+        conf=0.25 is intentionally permissive - the guardrail decides what
+        counts as confident enough, not this default."""
+        if not self.is_loaded:
+            self.load()
+
+        started = time.perf_counter()
+        results = self._model.predict(image, conf=conf, verbose=False)[0]
+        elapsed_ms = (time.perf_counter() - started) * 1000
+
+        detections = [
+            Detection(
+                class_name=ID_TO_CLASS.get(int(class_id), f"unknown_{int(class_id)}"),
+                class_id=int(class_id),
+                confidence=float(confidence),
+                bbox=BBox(x1=float(x1), y1=float(y1), x2=float(x2), y2=float(y2)),
+            )
+            for class_id, confidence, (x1, y1, x2, y2) in zip(
+                results.boxes.cls.tolist(),
+                results.boxes.conf.tolist(),
+                results.boxes.xyxy.tolist(),
+            )
+        ]
+
+        return detections, elapsed_ms

app/logging_config.py

@@ -0,0 +1,66 @@
+# Structured JSON logs, one line per request - lets me grep/jq for stuff
+# later ("how many /ask requests hit the guardrail today") instead of
+# re-running things to find out.
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import time
+import uuid
+from contextlib import contextmanager
+
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "timestamp": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+            "level": record.levelname,
+            "message": record.getMessage(),
+        }
+        # extra={...} fields ride along here instead of needing a custom
+        # formatter per call site
+        for key, value in getattr(record, "extra_fields", {}).items():
+            payload[key] = value
+        return json.dumps(payload)
+
+
+def configure_logging() -> logging.Logger:
+    logger = logging.getLogger("rap_doclayout")
+    if logger.handlers:
+        # avoid double handlers on repeated calls (app reload, test imports)
+        return logger
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(_JsonFormatter())
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    return logger
+
+
+@contextmanager
+def log_request(logger: logging.Logger, endpoint: str, **fields):
+    """Logs one line per request with latency, success or failure either
+    way.
+
+    Usage:
+        with log_request(logger, "/detect") as ctx:
+            ...
+            ctx["detection_count"] = len(detections)
+    """
+    request_id = uuid.uuid4().hex[:12]
+    started = time.perf_counter()
+    ctx = {"request_id": request_id, "endpoint": endpoint, **fields}
+    error: Exception | None = None
+    try:
+        yield ctx
+    except Exception as exc:
+        error = exc
+        raise
+    finally:
+        ctx["latency_ms"] = round((time.perf_counter() - started) * 1000, 2)
+        if error is not None:
+            ctx["error"] = str(error)
+            logger.error("request failed", extra={"extra_fields": ctx})
+        else:
+            logger.info("request completed", extra={"extra_fields": ctx})

app/main.py

@@ -0,0 +1,143 @@
+# FastAPI app: /health, /detect, /ask. Kept thin on purpose - upload
+# validation, error mapping, logging, then hand off to Detector or the
+# reasoning pipeline, both already tested elsewhere.
+from __future__ import annotations
+
+import os
+from contextlib import asynccontextmanager
+
+# loads .env if one exists (local dev) - does nothing if it doesn't (Docker,
+# HF Spaces, Kaggle all set real env vars/secrets instead)
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from fastapi import Depends, FastAPI, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import JSONResponse
+from PIL import Image, UnidentifiedImageError
+
+from app.constants import MODEL_VERSION
+from app.detector import Detector
+from app.logging_config import configure_logging, log_request
+from app.reasoning.pipeline import answer_question
+from app.schemas import DetectResponse
+
+logger = configure_logging()
+
+# Read once at import, not per-request. Tests override this directly
+# rather than faking an env var.
+MAX_UPLOAD_BYTES = int(os.environ.get("MAX_UPLOAD_MB", "10")) * 1024 * 1024
+
+_detector_instance: Detector | None = None
+
+
+def get_detector() -> Detector:
+    """FastAPI dependency - same Detector instance for every route.
+    Not a bare global so tests can override it with a stub."""
+    global _detector_instance
+    if _detector_instance is None:
+        _detector_instance = Detector()
+    return _detector_instance
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Tries to load weights at startup but doesn't crash if that fails -
+    a service that's up and reporting "model not loaded" is way easier to
+    debug than one that won't start at all."""
+    try:
+        get_detector().load()
+        logger.info("startup: model loaded", extra={"extra_fields": {}})
+    except Exception as error:
+        logger.error(
+            "startup: model failed to load, API will report 503 on inference routes",
+            extra={"extra_fields": {"error": str(error)}},
+        )
+    yield
+
+
+app = FastAPI(title="Constrained Document Layout Detection API", lifespan=lifespan)
+
+
+@app.exception_handler(Exception)
+async def handle_unexpected_error(request: Request, exc: Exception):
+    """Catches anything a route didn't handle and returns a safe generic
+    message instead of leaking a stack trace. Full error still goes to logs."""
+    logger.error(
+        "unhandled exception",
+        extra={"extra_fields": {"path": str(request.url), "error": str(exc)}},
+    )
+    return JSONResponse(
+        status_code=500,
+        content={"detail": "Internal server error. See server logs for details."},
+    )
+
+
+def _read_and_validate_image(contents: bytes, content_type: str | None) -> Image.Image:
+    """Size check, then content-type check, then an actual decode attempt -
+    a file can claim image/png and still be garbage."""
+    if len(contents) > MAX_UPLOAD_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Upload exceeds the {MAX_UPLOAD_BYTES // (1024 * 1024)} MB limit.",
+        )
+
+    if content_type is None or not content_type.startswith("image/"):
+        raise HTTPException(
+            status_code=415,
+            detail=f"Expected an image upload, got content-type '{content_type}'.",
+        )
+
+    try:
+        import io
+
+        return Image.open(io.BytesIO(contents)).convert("RGB")
+    except UnidentifiedImageError:
+        raise HTTPException(status_code=415, detail="Could not decode the upload as an image.")
+
+
+@app.get("/health")
+def health(detector: Detector = Depends(get_detector)):
+    return {"status": "ok", "model_loaded": detector.is_loaded, "model_version": MODEL_VERSION}
+
+
+@app.post("/detect", response_model=DetectResponse)
+async def detect(file: UploadFile = File(...), detector: Detector = Depends(get_detector)):
+    with log_request(logger, "/detect") as ctx:
+        if not detector.is_loaded:
+            raise HTTPException(
+                status_code=503,
+                detail="Model is not loaded. Check MODEL_PATH and server startup logs.",
+            )
+
+        contents = await file.read()
+        image = _read_and_validate_image(contents, file.content_type)
+
+        detections, inference_ms = detector.predict(image)
+        ctx["detection_count"] = len(detections)
+
+        return DetectResponse(
+            detections=detections,
+            image_size={"width": image.width, "height": image.height},
+            inference_ms=round(inference_ms, 2),
+            model_version=MODEL_VERSION,
+        )
+
+
+@app.post("/ask")
+async def ask(
+    file: UploadFile = File(...),
+    question: str = Form(..., min_length=1, max_length=500),
+    detector: Detector = Depends(get_detector),
+):
+    """Part B. All the actual routing/evidence/guardrail/synthesis logic
+    lives in app.reasoning.pipeline - this is just upload validation + wiring."""
+    with log_request(logger, "/ask", question_length=len(question)) as ctx:
+        contents = await file.read()
+        image = _read_and_validate_image(contents, file.content_type)
+
+        response = answer_question(image=image, question=question, detector=detector)
+        ctx["used_detection"] = response.used_detection
+        ctx["insufficient_information"] = response.insufficient_information
+
+        return response

app/reasoning/evidence.py

@@ -0,0 +1,105 @@
+# Detections -> structured summary. Pure functions only, no I/O, no model
+# calls, nothing that touches pixels - this is what makes it true that the
+# LLM downstream can't hallucinate what's on the page: it never sees it,
+# only this summary.
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from app.schemas import Detection
+
+
+@dataclass
+class ConfStats:
+    max: float
+    mean: float
+    min: float
+
+
+@dataclass
+class Relation:
+    """A spatial fact between two regions, e.g. Caption inside a Table.
+    Own type instead of a dict so a typo'd key fails loudly, not silently."""
+
+    kind: str
+    subject: str
+    object: str
+
+
+@dataclass
+class Evidence:
+    class_counts: dict[str, int]
+    confidence_stats: dict[str, ConfStats]
+    total_detections: int
+    reading_order: list[str]
+    relations: list[Relation] = field(default_factory=list)
+    # Raw scores per class - guardrail's ambiguous-band rule needs the full
+    # distribution, not just max/mean/min.
+    confidences_by_class: dict[str, list[float]] = field(default_factory=dict)
+
+
+def _box_area(detection: Detection) -> float:
+    b = detection.bbox
+    return (b.x2 - b.x1) * (b.y2 - b.y1)
+
+
+def _contains(outer: Detection, inner: Detection, threshold: float = 0.85) -> bool:
+    """True if inner sits mostly (85%+) inside outer. Not 100% - annotators
+    don't draw pixel-perfect boxes, a caption box a few px outside its
+    table shouldn't make the relationship disappear."""
+    ox1, oy1, ox2, oy2 = outer.bbox.x1, outer.bbox.y1, outer.bbox.x2, outer.bbox.y2
+    ix1, iy1, ix2, iy2 = inner.bbox.x1, inner.bbox.y1, inner.bbox.x2, inner.bbox.y2
+
+    overlap_x1, overlap_y1 = max(ox1, ix1), max(oy1, iy1)
+    overlap_x2, overlap_y2 = min(ox2, ix2), min(oy2, iy2)
+    if overlap_x2 <= overlap_x1 or overlap_y2 <= overlap_y1:
+        return False
+
+    overlap_area = (overlap_x2 - overlap_x1) * (overlap_y2 - overlap_y1)
+    inner_area = _box_area(inner)
+    return inner_area > 0 and (overlap_area / inner_area) >= threshold
+
+
+def build_evidence(detections: list[Detection], image_width: int, image_height: int) -> Evidence:
+    """Main entry point: detections -> Evidence.
+
+    image_width/height aren't used yet - kept for when a relation needs
+    page-edge position (e.g. "is this near the top" for Page-header)."""
+    class_counts: dict[str, int] = {}
+    confidences_by_class: dict[str, list[float]] = {}
+
+    for detection in detections:
+        class_counts[detection.class_name] = class_counts.get(detection.class_name, 0) + 1
+        confidences_by_class.setdefault(detection.class_name, []).append(detection.confidence)
+
+    confidence_stats = {
+        class_name: ConfStats(
+            max=max(values), mean=sum(values) / len(values), min=min(values)
+        )
+        for class_name, values in confidences_by_class.items()
+    }
+
+    # Top-to-bottom, then left-to-right. Not real reading-order logic - a
+    # two-column page would interleave columns wrong under this sort. Good
+    # enough for DocLayNet's mostly-single-column pages, noted in the memo.
+    ordered = sorted(detections, key=lambda det: (det.bbox.y1, det.bbox.x1))
+    reading_order = [det.class_name for det in ordered]
+
+    relations: list[Relation] = []
+    for outer in detections:
+        for inner in detections:
+            if outer is inner:
+                continue
+            if _box_area(inner) >= _box_area(outer):
+                continue  # can't "contain" something the same size or bigger
+            if _contains(outer, inner):
+                relations.append(Relation(kind="contains", subject=outer.class_name, object=inner.class_name))
+
+    return Evidence(
+        class_counts=class_counts,
+        confidence_stats=confidence_stats,
+        total_detections=len(detections),
+        reading_order=reading_order,
+        relations=relations,
+        confidences_by_class=confidences_by_class,
+    )

app/reasoning/guardrail.py

@@ -0,0 +1,100 @@
+# Decides if the evidence is good enough to answer confidently - before the
+# LLM writes anything. Kept as a separate deterministic check because asking
+# a model "are you confident?" just gets more text, not a real signal - it's
+# equally fluent at a confident-sounding guess as an honest refusal.
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from app.reasoning.evidence import Evidence
+
+# Below this, a single detection isn't trustworthy enough to answer from.
+# 0.50 rather than something stricter like 0.7 - correctly localised
+# regions on this dataset tend to score well above 0.6 in my own runs.
+CONFIDENCE_FLOOR = 0.50
+
+# For counting: don't report an exact number if too much of it sits in this
+# shaky band. Below 0.25 is just noise; 0.25-0.50 is "plausible but I
+# wouldn't bet on the count."
+AMBIGUOUS_BAND = (0.25, CONFIDENCE_FLOOR)
+AMBIGUOUS_BAND_FRACTION = 0.30
+
+
+@dataclass
+class GuardrailVerdict:
+    triggered: bool
+    rule: str | None = None
+    detail: dict = field(default_factory=dict)
+
+
+def _confidences_for(evidence: Evidence, target_classes: list[str]) -> list[float]:
+    """Max confidence per target class, ignoring unrelated classes on the page."""
+    values: list[float] = []
+    for class_name in target_classes:
+        stats = evidence.confidence_stats.get(class_name)
+        if stats is None:
+            continue
+        values.append(stats.max)
+    return values
+
+
+def evaluate_guardrail(
+    evidence: Evidence,
+    target_classes: list[str],
+    task_type: str,
+    saturated: bool = False,
+) -> GuardrailVerdict:
+    """Four rules, checked in order, most specific first - some can overlap
+    and I want the more useful explanation to win (e.g. "found nothing"
+    beats "page was saturated" even when both are technically true)."""
+    raw_confidences = [
+        value
+        for class_name in target_classes
+        for value in evidence.confidences_by_class.get(class_name, [])
+    ]
+    target_counts = {
+        class_name: evidence.class_counts.get(class_name, 0)
+        for class_name in target_classes
+    }
+    total_target_detections = sum(target_counts.values())
+
+    # nothing of the target class found at all
+    if total_target_detections == 0:
+        return GuardrailVerdict(
+            triggered=True,
+            rule="no_detections",
+            detail={"target_classes": target_classes},
+        )
+
+    max_confidences = _confidences_for(evidence, target_classes)
+    observed_max = max(max_confidences) if max_confidences else 0.0
+
+    # found something, but nothing clears the confidence floor
+    if observed_max < CONFIDENCE_FLOOR:
+        return GuardrailVerdict(
+            triggered=True,
+            rule="all_below_tau",
+            detail={"tau": CONFIDENCE_FLOOR, "observed_max": observed_max},
+        )
+
+    # counting only: too much of the count sits in the shaky band.
+    # doesn't apply to "is there one?" - one confident hit is enough for that.
+    if task_type == "count" and raw_confidences:
+        low, high = AMBIGUOUS_BAND
+        in_band = sum(1 for c in raw_confidences if low <= c < high)
+        if raw_confidences and (in_band / len(raw_confidences)) > AMBIGUOUS_BAND_FRACTION:
+            return GuardrailVerdict(
+                triggered=True,
+                rule="ambiguous_band",
+                detail={
+                    "band": list(AMBIGUOUS_BAND),
+                    "fraction_in_band": round(in_band / len(raw_confidences), 2),
+                },
+            )
+
+    # page had more regions than RT-DETR's query budget could emit -
+    # a count here is unreliable regardless of confidence
+    if saturated:
+        return GuardrailVerdict(triggered=True, rule="query_saturated", detail={})
+
+    return GuardrailVerdict(triggered=False)

app/reasoning/pipeline.py

@@ -0,0 +1,76 @@
+# Wires Part B together: route -> maybe detect -> evidence -> guardrail ->
+# synthesize. All the actual decisions live in those modules, each tested
+# separately - this file is just the order they run in.
+from __future__ import annotations
+
+from app.reasoning.evidence import build_evidence
+from app.reasoning.guardrail import evaluate_guardrail
+from app.reasoning.router import route as route_question
+from app.reasoning.synthesize import synthesize
+from app.schemas import AskResponse
+
+
+def answer_question(image, question: str, detector, client=None) -> AskResponse:
+    """Runs the full pipeline for one question against one image.
+
+    detector/client are injectable - tests stub both, no GPU or Groq key
+    needed. See test_pipeline.py."""
+    route = route_question(question, client=client)
+
+    detections = []
+    if route.needs_detection:
+        # only run the detector if the router actually says it's needed -
+        # keeps out-of-scope questions from getting unrelated detections
+        detections, _inference_ms = detector.predict(image)
+
+    evidence = build_evidence(detections, image_width=0, image_height=0)
+
+    # stub detectors in tests don't have a query_budget - check first
+    saturated = (
+        route.needs_detection
+        and hasattr(detector, "query_budget")
+        and evidence.total_detections >= detector.query_budget
+    )
+
+    verdict = evaluate_guardrail(
+        evidence, target_classes=route.target_classes,
+        task_type=route.task_type, saturated=saturated,
+    ) if route.needs_detection else evaluate_guardrail(evidence, [], route.task_type)
+
+    # insufficient_information comes from the guardrail's verdict, not from
+    # the LLM's wording - see test_guardrail_verdict_overrides_whatever_the_llm_says
+    if route.needs_detection:
+        answer_text = synthesize(question, evidence, verdict, route, client=client)
+        insufficient = verdict.triggered
+    else:
+        # out-of-scope questions skip synthesis entirely - router's reason
+        # already explains why, no need for a second LLM call
+        answer_text = (
+            f"I can't answer that from this image's layout: {route.reason}"
+        )
+        insufficient = True
+
+    return AskResponse(
+        answer=answer_text,
+        used_detection=route.needs_detection,
+        insufficient_information=insufficient,
+        detections=detections,
+        evidence={
+            "class_counts": evidence.class_counts,
+            "total_detections": evidence.total_detections,
+        } if route.needs_detection else None,
+        reasoning_trace={
+            "router": {
+                "needs_detection": route.needs_detection,
+                "target_classes": route.target_classes,
+                "task_type": route.task_type,
+                "reason": route.reason,
+                "source": route.source,
+            },
+            "guardrail": {
+                "triggered": verdict.triggered,
+                "rule": verdict.rule,
+                "detail": verdict.detail,
+            },
+        },
+    )

app/reasoning/router.py

@@ -0,0 +1,147 @@
+# Decides if a question needs the detector at all. Two layers:
+# 1. Cheap regex prefilter for the obvious cases (greetings, general
+#    knowledge) - no point spending a Groq call on "what's the capital of
+#    France".
+# 2. LLM call (Groq, strict json_schema) for everything else. Routing
+#    genuinely needs language understanding - a keyword list can't tell
+#    "how many tables" from "is this page well organised".
+#
+# Key thing baked into the prompt: the model knows it's routing for a
+# *layout* detector, not general vision. "What's the invoice total?"
+# mentions the image but the detector can't read text - only a prompt that
+# says so explicitly catches that and routes it out_of_scope.
+from __future__ import annotations
+
+import os
+import re
+
+from app.constants import CLASS_NAMES
+from app.schemas import RouteDecision
+
+# Kept short and specific on purpose - if a pattern is even slightly
+# ambiguous it belongs with the LLM. A wrong prefilter call is worse than a
+# slow one since it skips the LLM's judgement entirely.
+_GREETING_PATTERN = re.compile(
+    r"^\s*(hi|hello|hey|thanks|thank you)[\s!.,]*$", re.IGNORECASE
+)
+_META_PATTERN = re.compile(
+    r"\b(what can you do|who are you|what are you|how do you work)\b", re.IGNORECASE
+)
+_GENERAL_KNOWLEDGE_PATTERN = re.compile(
+    r"\b(capital of|president of|weather|what year is it|who won)\b", re.IGNORECASE
+)
+
+
+def prefilter(question: str) -> RouteDecision | None:
+    """Only ever returns "definitely no detection needed", never "yes" -
+    deciding detection IS needed requires actually understanding the
+    sentence, which is the LLM's job. None means defer to it."""
+    stripped = question.strip()
+
+    if _GREETING_PATTERN.match(stripped):
+        return RouteDecision(
+            needs_detection=False, target_classes=[], task_type="out_of_scope",
+            reason="Greeting, not a question about the image.", source="prefilter",
+        )
+
+    if _META_PATTERN.search(stripped) or _GENERAL_KNOWLEDGE_PATTERN.search(stripped):
+        return RouteDecision(
+            needs_detection=False, target_classes=[], task_type="out_of_scope",
+            reason="General-knowledge or meta question, unrelated to image content.",
+            source="prefilter",
+        )
+
+    return None
+
+
+_ROUTER_SCHEMA = {
+    "name": "route_decision",
+    "strict": True,
+    "schema": {
+        "type": "object",
+        "properties": {
+            "needs_detection": {"type": "boolean"},
+            "target_classes": {
+                "type": "array",
+                "items": {"type": "string", "enum": CLASS_NAMES},
+            },
+            "task_type": {
+                "type": "string",
+                "enum": ["count", "presence", "compare", "describe", "out_of_scope"],
+            },
+            "reason": {"type": "string"},
+        },
+        "required": ["needs_detection", "target_classes", "task_type", "reason"],
+        "additionalProperties": False,
+    },
+}
+
+_SYSTEM_PROMPT = f"""You route questions for a document layout detection API.
+
+The detector can ONLY report the position and type of structural regions on a
+document page. It knows WHERE things are, never WHAT they say. Its full
+vocabulary of classes is exactly this list, nothing more:
+{", ".join(CLASS_NAMES)}
+
+Decide:
+- needs_detection: does answering this actually require knowing what regions
+  are on the page? Questions about text CONTENT the detector cannot read
+  (amounts, names, dates, what a paragraph says, who signed something) are
+  OUT OF SCOPE even though they mention the document - set needs_detection to
+  false and task_type to "out_of_scope" for these. Do not guess at content the
+  detector cannot see.
+- target_classes: which of the classes above the question is actually about.
+  Empty if needs_detection is false.
+- task_type: "count" (how many), "presence" (is there a/any), "compare"
+  (relationships between regions), "describe" (general layout question), or
+  "out_of_scope".
+- reason: one short sentence explaining the decision.
+"""
+
+
+def route(question: str, client=None) -> RouteDecision:
+    """Prefilter first, then the LLM if it deferred. `client` is injectable
+    for tests/pipeline to swap in a stub - see pipeline.py.
+
+    Fails closed to out_of_scope on any LLM error (bad key, timeout, etc)
+    rather than guessing detection is needed - skipping a real question is
+    worse than declining an answerable one."""
+    prefiltered = prefilter(question)
+    if prefiltered is not None:
+        return prefiltered
+
+    if client is None:
+        from groq import Groq
+
+        client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
+
+    model = os.environ.get("GROQ_ROUTER_MODEL", "openai/gpt-oss-20b")
+
+    try:
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": question},
+            ],
+            response_format={"type": "json_schema", "json_schema": _ROUTER_SCHEMA},
+            temperature=0,
+        )
+        import json
+
+        parsed = json.loads(response.choices[0].message.content)
+        return RouteDecision(
+            needs_detection=parsed["needs_detection"],
+            target_classes=parsed["target_classes"],
+            task_type=parsed["task_type"],
+            reason=parsed["reason"],
+            source="llm",
+        )
+    except Exception as error:
+        return RouteDecision(
+            needs_detection=False,
+            target_classes=[],
+            task_type="out_of_scope",
+            reason=f"Router failed closed after an error: {error}",
+            source="llm",
+        )

app/reasoning/synthesize.py

@@ -0,0 +1,95 @@
+# Writes the final answer text from evidence only - never sees the image.
+# Only job here is phrasing: router already decided whether to detect,
+# guardrail already decided if the evidence is trustworthy. Uses the bigger
+# Groq model (gpt-oss-120b) since this is open-ended writing, unlike
+# routing which is closed classification the small model handles fine.
+from __future__ import annotations
+
+import os
+
+from app.reasoning.evidence import Evidence
+from app.reasoning.guardrail import GuardrailVerdict
+from app.schemas import RouteDecision
+
+
+def _evidence_to_json(evidence: Evidence) -> dict:
+    """Flattens Evidence to plain JSON - the only thing the LLM ever sees
+    about the image. No pixels, so it can't describe anything it didn't
+    actually detect."""
+    return {
+        "class_counts": evidence.class_counts,
+        "confidence_stats": {
+            name: {"max": stats.max, "mean": round(stats.mean, 3), "min": stats.min}
+            for name, stats in evidence.confidence_stats.items()
+        },
+        "total_detections": evidence.total_detections,
+        "reading_order": evidence.reading_order,
+        "relations": [
+            {"kind": r.kind, "subject": r.subject, "object": r.object}
+            for r in evidence.relations
+        ],
+    }
+
+
+_SYSTEM_PROMPT = """You write short, plain-language answers about a document
+page's layout, based ONLY on the structured evidence JSON you are given. You
+have not seen the image - do not describe anything beyond what the evidence
+contains.
+
+If you are told the evidence is insufficient, say so plainly and explain why
+in one sentence, using the guardrail detail provided. Do not hedge around it
+or try to answer anyway - an explicit "I can't answer confidently" is the
+correct and expected response in that case, not a failure to be worked around.
+
+Otherwise, answer the question directly and concisely using the evidence.
+Do not invent counts, classes, or relationships that are not in the evidence.
+"""
+
+
+def synthesize(
+    question: str,
+    evidence: Evidence,
+    verdict: GuardrailVerdict,
+    route: RouteDecision,
+    client=None,
+) -> str:
+    """Produces the final answer text. Guardrail's verdict goes in as a
+    stated fact, not something the model re-judges - if triggered, it's
+    told "explain why this is insufficient", not asked "are you sure?"."""
+    context = {
+        "question": question,
+        "task_type": route.task_type,
+        "evidence": _evidence_to_json(evidence),
+        "guardrail": {"insufficient": verdict.triggered, "rule": verdict.rule, "detail": verdict.detail},
+    }
+
+    if client is None:
+        from groq import Groq
+
+        client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
+
+    model = os.environ.get("GROQ_SYNTHESIS_MODEL", "openai/gpt-oss-120b")
+
+    try:
+        import json
+
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": json.dumps(context)},
+            ],
+            temperature=0.2,
+        )
+        return response.choices[0].message.content.strip()
+    except Exception as error:
+        # Groq down/timeout/bad key - fall back to a plain template built
+        # from the guardrail/evidence instead of a stack trace, so the API
+        # stays honest even when the writing step is unavailable.
+        if verdict.triggered:
+            return (
+                f"I cannot answer confidently: {verdict.rule}. "
+                f"(Answer synthesis unavailable: {error})"
+            )
+        counts = ", ".join(f"{v} {k}" for k, v in evidence.class_counts.items()) or "nothing"
+        return f"Detected: {counts}. (Answer synthesis unavailable: {error})"

app/schemas.py

@@ -0,0 +1,105 @@
+# Request/response shapes for both endpoints, all in one place so /detect,
+# /ask and the tests aren't each building their own dict by hand.
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class BBox(BaseModel):
+    """Corner-format box (not centre+size) - easier for a caller to draw."""
+
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+
+    # Catches a mixed-up width/x2 conversion before it ships as an
+    # inside-out box - happened once, don't want it happening again.
+    @field_validator("x2")
+    @classmethod
+    def x2_after_x1(cls, x2: float, info) -> float:
+        x1 = info.data.get("x1")
+        if x1 is not None and x2 <= x1:
+            raise ValueError(f"x2 ({x2}) must be greater than x1 ({x1})")
+        return x2
+
+    @field_validator("y2")
+    @classmethod
+    def y2_after_y1(cls, y2: float, info) -> float:
+        y1 = info.data.get("y1")
+        if y1 is not None and y2 <= y1:
+            raise ValueError(f"y2 ({y2}) must be greater than y1 ({y1})")
+        return y2
+
+
+class Detection(BaseModel):
+    """One region the detector found, with its class and how sure it is."""
+
+    class_name: str
+    class_id: int
+    bbox: BBox
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class ImageSize(BaseModel):
+    width: int
+    height: int
+
+
+class DetectResponse(BaseModel):
+    """Full response for POST /detect. model_version tags which checkpoint
+    produced this, useful once there's more than one."""
+
+    detections: list[Detection]
+    image_size: ImageSize
+    inference_ms: float
+    model_version: str
+
+
+class AskRequest(BaseModel):
+    """Image comes in as multipart, not JSON - this is just the question."""
+
+    question: str = Field(min_length=1, max_length=500)
+
+
+class ConfidenceStats(BaseModel):
+    max: float
+    mean: float
+    min: float
+
+
+class RouteDecision(BaseModel):
+    """What the router decided before any detection runs. task_type is a
+    closed set, not a free string - guardrail.py branches on it directly,
+    and a typo would just silently skip the guardrail."""
+
+    needs_detection: bool
+    target_classes: list[str]
+    task_type: Literal["count", "presence", "compare", "describe", "out_of_scope"]
+    reason: str
+    source: Literal["prefilter", "llm"]
+
+
+class GuardrailVerdict(BaseModel):
+    """Whether the evidence is good enough to answer, and why not if not.
+    detail stays a free dict since each rule explains itself differently."""
+
+    triggered: bool
+    rule: str | None = None
+    detail: dict = Field(default_factory=dict)
+
+
+class AskResponse(BaseModel):
+    """Full response for POST /ask. insufficient_information is set from
+    the guardrail's verdict in code - never from the LLM self-reporting
+    confidence, since that's one prompt away from a confident-sounding
+    guess."""
+
+    answer: str
+    used_detection: bool
+    insufficient_information: bool
+    detections: list[Detection] = Field(default_factory=list)
+    evidence: dict | None = None
+    reasoning_trace: dict = Field(default_factory=dict)

deploy/huggingface_space_README.md

@@ -0,0 +1,25 @@
+---
+title: Document Layout Detection
+emoji: 📄
+colorFrom: blue
+colorTo: gray
+sdk: gradio
+app_file: gradio_app.py
+pinned: false
+---
+
+# Constrained Document Layout Detection
+
+RT-DETR fine-tuned on DocLayNet, plus a hand-written reasoning layer for
+natural-language questions about a page's layout.
+
+Full source, training scripts, and the FastAPI API this demo shares its
+code with: see the main repo.
+
+## Space secrets needed
+
+- `GROQ_API_KEY` - for the Ask tab's reasoning layer
+- `MODEL_URL` - direct download link for the trained weights (e.g. a
+  GitHub Release asset). Downloaded automatically on first run if
+  `MODEL_PATH` doesn't already exist - no need to push the weights file
+  into the Space's git repo.

gradio_app.py

@@ -0,0 +1,158 @@
+# Gradio UI for Hugging Face Spaces - same Detector and reasoning pipeline
+# as the FastAPI app and streamlit_app.py, just a different front end.
+# HF's current Space creation flow only offers Gradio/Docker/Static as
+# SDKs (no standalone Streamlit option), so this is the path that works
+# without a paid plan.
+from __future__ import annotations
+
+import os
+
+import gradio as gr
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from PIL import Image, ImageDraw
+
+from app.constants import CLASS_NAMES, MODEL_VERSION
+from app.detector import Detector
+from app.reasoning.pipeline import answer_question
+from scripts._render_utils import load_label_font
+
+try:
+    # only meaningful on an actual HF ZeroGPU Space - it's what tells the
+    # platform to allocate a real GPU for the duration of the decorated
+    # call, then release it. A no-op import failure anywhere else (local
+    # runs, Docker) just means we fall back to whatever device torch
+    # picks on its own.
+    import spaces
+
+    _gpu_decorator = spaces.GPU
+except ImportError:
+    def _gpu_decorator(fn):
+        return fn
+
+PALETTE = [
+    "#e6194b", "#3cb44b", "#ffe119", "#4363d8", "#f58231", "#911eb4",
+    "#46f0f0", "#f032e6", "#bcf60c", "#fabebe", "#008080",
+]
+
+_detector: Detector | None = None
+
+
+def get_detector() -> Detector:
+    # module-level singleton, same reasoning as main.py's get_detector -
+    # loads once per process, not per request. Left completely unmodified
+    # (no monkeypatching) - ZeroGPU's @spaces.GPU spawns a separate worker
+    # process for the actual GPU call, and everything crossing that
+    # boundary gets pickled. A bound method captured in a closure (my
+    # first two attempts) either can't be pickled at all, or - when it
+    # can - resolves to whatever the instance's current attribute value
+    # is on the other side, which is fragile either way. Passing only
+    # plain data (the image, a float) sidesteps the whole problem.
+    global _detector
+    if _detector is None:
+        _detector = Detector()
+        try:
+            _detector.load()
+        except FileNotFoundError:
+            pass  # surfaced in the UI instead of crashing the app
+    return _detector
+
+
+@_gpu_decorator
+def _predict_on_gpu(image, conf: float = 0.25):
+    # The only thing decorated with @spaces.GPU, and it has to be exactly
+    # this: a real top-level function (ZeroGPU scans source at startup
+    # for one - dynamic decoration isn't detected), taking only plain,
+    # picklable arguments. It reaches the detector via the module-level
+    # getter rather than having one passed in.
+    return get_detector().predict(image, conf=conf)
+
+
+class _GPUDetectorProxy:
+    """Stands in for a Detector wherever one is expected (run_ask passes
+    this to the reasoning pipeline) but routes predict() through the
+    properly decorated module-level function above instead of calling
+    the real method directly - same reason as the getter's docstring."""
+
+    @property
+    def is_loaded(self) -> bool:
+        return get_detector().is_loaded
+
+    @property
+    def query_budget(self) -> int:
+        return get_detector().query_budget
+
+    def predict(self, image, conf: float = 0.25):
+        return _predict_on_gpu(image, conf=conf)
+
+
+def draw_detections(image: Image.Image, detections) -> Image.Image:
+    annotated = image.copy()
+    draw = ImageDraw.Draw(annotated)
+    font = load_label_font(18)
+
+    for det in detections:
+        colour = PALETTE[det.class_id % len(PALETTE)]
+        box = det.bbox
+        draw.rectangle([box.x1, box.y1, box.x2, box.y2], outline=colour, width=3)
+        label = f"{det.class_name} {det.confidence:.2f}"
+        text_box = draw.textbbox((box.x1, box.y1), label, font=font)
+        draw.rectangle(
+            [text_box[0] - 2, text_box[1] - 2, text_box[2] + 2, text_box[3] + 2],
+            fill=colour,
+        )
+        draw.text((box.x1, box.y1), label, font=font, fill="white")
+
+    return annotated
+
+
+def run_detect(image: Image.Image):
+    if not get_detector().is_loaded:
+        return None, "Model not loaded - check MODEL_PATH/MODEL_URL.", None
+    if image is None:
+        return None, "Upload an image first.", None
+
+    detections, inference_ms = _predict_on_gpu(image)
+    annotated = draw_detections(image, detections)
+    table = [[d.class_name, round(d.confidence, 3)] for d in sorted(detections, key=lambda d: -d.confidence)]
+    summary = f"{len(detections)} detections in {inference_ms:.1f} ms"
+    return annotated, summary, table
+
+
+def run_ask(image: Image.Image, question: str):
+    if not get_detector().is_loaded:
+        return "Model not loaded - check MODEL_PATH/MODEL_URL.", {}
+    if image is None or not question:
+        return "Upload an image and enter a question.", {}
+    if not os.environ.get("GROQ_API_KEY"):
+        return "GROQ_API_KEY not set - the reasoning layer needs it.", {}
+
+    response = answer_question(image=image, question=question, detector=_GPUDetectorProxy())
+    return response.answer, response.reasoning_trace
+
+
+with gr.Blocks(title="Document Layout Detection") as demo:
+    gr.Markdown(f"# Constrained Document Layout Detection\nRT-DETR fine-tuned on DocLayNet - `{MODEL_VERSION}`")
+    gr.Markdown(f"Classes: {', '.join(CLASS_NAMES)}")
+
+    with gr.Tab("Detect"):
+        with gr.Row():
+            detect_input = gr.Image(type="pil", label="Upload a document page")
+            detect_output = gr.Image(type="pil", label="Detections")
+        detect_button = gr.Button("Run detection")
+        detect_summary = gr.Textbox(label="Summary", interactive=False)
+        detect_table = gr.Dataframe(headers=["class", "confidence"], label="Detections")
+        detect_button.click(run_detect, inputs=detect_input, outputs=[detect_output, detect_summary, detect_table])
+
+    with gr.Tab("Ask"):
+        ask_input = gr.Image(type="pil", label="Upload a document page")
+        ask_question = gr.Textbox(label="Question", placeholder="How many tables are on this page?")
+        ask_button = gr.Button("Ask")
+        ask_answer = gr.Textbox(label="Answer", interactive=False)
+        ask_trace = gr.JSON(label="Reasoning trace")
+        ask_button.click(run_ask, inputs=[ask_input, ask_question], outputs=[ask_answer, ask_trace])
+
+if __name__ == "__main__":
+    demo.launch()

memo/BUILD_LOG.md

@@ -0,0 +1,156 @@
+# Build log
+
+Working notes from building this, kept as I went rather than written after
+the fact.
+
+## Reading the brief
+
+Weighting is not what the title suggests: 25% is Part A hidden-set
+performance, the rest is dataset sourcing, evaluation honesty, failure
+analysis, Part B correctness, code quality, and reproducibility. Roughly
+40% is written reasoning about the work, not the work itself. That shaped
+everything below — I optimized for a system I could explain precisely,
+not for the highest number.
+
+Hard gates: no agentic frameworks anywhere, RT-DETR with my own training
+code, at least one non-COCO class or Part A scores zero, and training has
+to be reproducible or Part A caps at 50%.
+
+## Picking the domain
+
+First idea was construction PPE (helmet/vest detection) — dropped it
+because `person` is a COCO class, so part of the score would be inherited
+from the pretrained backbone rather than earned. Also already taken by
+another candidate. Traffic was worse on the same axis — car, truck, person,
+traffic light are all COCO classes.
+
+Landed on document layout detection: all 11 DocLayNet classes (Table,
+Text, Title, etc.) are non-COCO, so every point of mAP is earned. It also
+gives Part B a real architectural refusal case instead of a tuned
+threshold — "what's the invoice total" is a question about content a
+layout detector structurally cannot answer, not a low-confidence guess.
+Adjacent to what RAP builds (RAPFlow does document extraction), which
+made the domain choice defensible rather than arbitrary.
+
+Risk I accepted: DocLayNet is rendered/scanned pages, not camera photos.
+If the hidden eval set is phone photos of paper, this model will do
+worse. Mitigated with rotation/perspective augmentation, not eliminated.
+
+## Dataset
+
+`pierreguillou/DocLayNet-base` — a 10% subset of IBM's DocLayNet, same
+annotation quality, 8k images instead of 80k. Full dataset is ~30GB and
+takes 45 min just to download; not worth it against a one-day budget.
+
+Used the author's train/val/test split rather than re-splitting myself —
+reproducible, comparable to published work. Measured the one risk that
+comes with that (pages from the same source PDF leaking across the split)
+rather than assuming it away: 0% overlap.
+
+The real gotcha in this dataset: `bboxes_block` repeats each region's box
+once per text line, so a 40-region page reads as ~1,100 duplicate
+annotations if you don't dedupe. Wrote `dedupe_annotations()` to collapse
+on `(box, category)` before writing YOLO labels.
+
+## Reasoning layer — why Groq, and the architecture
+
+Switched from an original OpenAI plan to Groq: faster, generous free
+tier, and it supports `json_schema` with `strict: true` — the router's
+output is structurally guaranteed to match my schema (constrained
+decoding), not just prompted-and-hoped-for. `llama-3.3-70b-versatile` was
+deprecated for free tier in June 2026, so the router runs `gpt-oss-20b`
+and synthesis runs `gpt-oss-120b`.
+
+Design point I care about most: the guardrail that decides
+`insufficient_information` is plain deterministic Python, evaluated
+*before* the LLM writes anything. Asking a model "are you confident?"
+just gets more text — it's equally fluent at a confident-sounding guess
+as an honest refusal. The verdict is handed to the LLM as a fact, not
+asked as a question.
+
+## Training config choices
+
+`fliplr`, `flipud`, `mosaic` all forced to 0 — Ultralytics defaults these
+on for photographs, but a mirrored or four-way-composited document page
+is not a document. Kept small-angle rotation and mild perspective, since
+those model real scanner/camera skew and are the only hedge against the
+domain-shift risk above.
+
+`lr0=1e-4` not the usual `1e-2` — DETR-family transformer components are
+unstable at high LR, and I'm fine-tuning from COCO weights, not training
+from scratch.
+
+Cut epochs from 30 to 15 partway through after losing the first training
+run (see below) and needing to fit a much tighter remaining window —
+noting the pivot rather than hiding it.
+
+## Kaggle infrastructure issues
+
+Several real environment problems hit in the first hour of actually
+running this — none were modelling bugs, all were dependency/platform
+collisions:
+
+- **`datasets>=4.0.0`** dropped support for legacy "loading script"
+  datasets entirely; this dataset repo is one. Pinned `datasets<4.0.0`.
+- Loading a script-based dataset prompts for confirmation
+  (`trust_remote_code`), which hangs forever under Kaggle's non-interactive
+  commit mode. Passed `trust_remote_code=True` explicitly, after reading
+  what the script actually does.
+- The dataset repo's own schema declares box coordinates as `int64`; the
+  real values are floats. Older `pyarrow` silently truncated them, newer
+  `pyarrow` correctly refuses. Fixed by overriding the load schema to
+  `float64` rather than editing someone else's script.
+- Ultralytics auto-registers a Ray Tune callback whenever `ray` is
+  importable, with no check for whether Tune is running. Kaggle ships ray
+  pre-installed; the callback crashed at the end of epoch 1 calling a
+  renamed internal Ray API. Fixed with `SETTINGS["raytune"] = False`.
+- A notebook cell did `%cd` into a directory and then `rm -rf`'d it on
+  the next run, corrupting the shell. Fixed by stepping out first.
+- Label-check renders used PIL's default ~10px font — unreadable once
+  resized. Switched to a real font (matplotlib's bundled DejaVu, since
+  that's a dependency I already have).
+
+**One of these actually cost a full training run**: the session was
+running interactively rather than via Save & Run All (Commit), and Kaggle
+recycled the container after a period of inactivity, wiping the dataset
+and every checkpoint through epoch 10 (which had reached mAP50 0.69).
+Rebuilt from scratch with epochs cut to 15 to fit the remaining time, and
+switched to committed runs for good.
+
+## API, Docker, Streamlit
+
+FastAPI wraps the same `Detector`/reasoning pipeline used everywhere else
+— no separate logic path. Caught one real bug via the tests before it
+shipped: the detector dependency was written as a bare default argument
+(`= get_detector()`) instead of `Depends(get_detector)`, which would have
+silently defeated test overrides while looking completely normal in
+production.
+
+Docker: CPU-only torch wheel (no CUDA toolkit bloat for a container that
+only serves inference), non-root user. Built and actually ran it —
+confirmed the app starts cleanly with no weights present and `/health`
+reports that instead of crashing.
+
+Streamlit app reuses the exact same `Detector` and pipeline as the API,
+for Hugging Face Spaces — no duplicated logic, just a UI on top.
+
+## Real results
+
+Final run: 15 epochs, Tesla T4, 2.27h. mAP50 0.622, mAP50-95 0.412.
+
+The most useful single finding: `Footnote` (47 instances) scored 0.182
+mAP50, `Page-footer` — a similarly thin, similarly-positioned class —
+scored 0.843. Difference is `Page-footer` has 9x more training instances
+and a very consistent position. Revises my pre-training hypothesis from
+"thin objects fail" to "thin *and rare* objects fail; thin-but-frequent
+ones are fine."
+
+`Picture` had decent recall (0.622) but weak precision (0.416) —
+mined-failure images show composite regions (a diagram plus its embedded
+formula text) getting split into multiple overlapping boxes instead of
+one region.
+
+Live-tested the full pipeline against the trained weights on a real,
+previously-unseen page: asking a content question ("what law is this
+about") correctly routed to `out_of_scope` before detection ever ran —
+the real example used in the memo.

memo/MEMO.md

@@ -0,0 +1,124 @@
+# Memo — Constrained Document Layout Detection & Reasoning API
+
+## 1. Domain, dataset, and why
+
+I chose document layout analysis — detecting structural regions (tables,
+headings, captions, formulas) on a document page — over more common choices
+like traffic or PPE detection for three reasons. First, all candidate
+classes are non-COCO, so no pretrained checkpoint can score without real
+fine-tuning; PPE/traffic domains lean on COCO's `person`/`car` classes for
+a chunk of their apparent performance. Second, it produces a genuinely
+architectural "insufficient information" case for Part B (below), not a
+tuned confidence threshold. Third, it's adjacent to what Rapid Acceleration
+Partners builds — RAPFlow's stated purpose is automated extraction from
+unstructured documents, and layout detection is the perception stage
+underneath that.
+
+**Dataset:** `pierreguillou/DocLayNet-base` (Hugging Face), a 10% subset of
+IBM Research's DocLayNet — 8,057 pages, expert-annotated, CDLA-Permissive-1.0
+license, spanning 6 document categories (financial reports, scientific
+articles, laws/regulations, tenders, manuals, patents). I used this subset
+over the full 80k-page release specifically for the time budget: the full
+release is ~30 GB and takes ~45 minutes just to download, which was not
+defensible against a one-day window. Same annotation quality, ~8x smaller.
+
+One real data hazard: the dataset's `bboxes_block` field repeats each
+region's box once per text line it contains, so a naive read of a 40-region
+page produces ~1,100 duplicate annotations. `scripts/prepare_dataset.py`
+deduplicates on `(box, category)` before writing YOLO labels and reports
+the dedupe ratio per split.
+
+## 2. Split strategy
+
+I used the dataset author's published train/val/test split (6,910/648/499)
+rather than re-stratifying myself. This is the reproducible choice —
+comparable to published DocLayNet baselines — but it means inheriting
+whatever leakage that split has. I measured it rather than assuming:
+**0% of test pages share a source PDF with the training set** (see
+`reports/metrics.json:split_leakage`). The split is clean.
+
+## 3. Evaluation and what it does / doesn't tell you
+
+Test-set results (499 pages, RT-DETR-L, 15 epochs, Tesla T4, 2.27h):
+**mAP50 = 0.622, mAP50-95 = 0.412, precision = 0.706, recall = 0.605.**
+
+I report more than one number because a single aggregate mAP cannot answer
+what I actually need to know. Per-document-category mAP50 ranges from
+0.495 (`laws_and_regulations`) to 0.745 (`scientific_articles`) — an honest
+signal about which document styles generalize, not just an aggregate. I
+also measured RT-DETR's query-budget saturation directly rather than
+letting it hide inside a recall number: **0% of test pages exceeded the
+300-query budget** (max regions on any page: 95), so saturation is not a
+factor in these results.
+
+**What mAP does not tell you:** it measures box localization and
+classification, nothing about reading order, and nothing about whether a
+detected `Table`'s internal structure is usable downstream. A model can
+score well here and still be useless for extracting an actual table's rows.
+
+## 4. Five failure cases
+
+**1. `Footnote` — near-total recall collapse (recall 0.048, mAP50 0.182).**
+I predicted before training that small/thin classes would suffer at 640px
+input. Only half right: `Footnote` has just 47 training instances across
+18 images — rarity, not size, is the dominant factor (see #2's contrast).
+
+**2. `Page-footer` almost failed the same way, but didn't (mAP50 0.843).**
+Equally thin, similarly positioned at the page margin, but 408 instances
+across 381 images (~9x more than `Footnote`) and a highly consistent
+position. This is the most useful negative result in the run: it revised
+my hypothesis from "small objects fail" to "small *and rare* objects fail;
+small-but-frequent-and-positionally-consistent ones are fine."
+
+**3. Dense repeated-entry layouts produce duplicate, jittery boxes**
+(`reports/failures/01_test_000035_err120.png`, financial_reports, the
+worst page overall: 38 missed, 82 false positives). This page is a bank's
+organizational directory — ~25 near-identical repeated `Section-header`/
+`Text` entry pairs stacked in two columns. Ground truth has one clean box
+per entry; the prediction shows heavily overlapping, offset duplicate boxes
+at scattered confidence (0.25–0.85). At 640px, the model appears unable to
+cleanly separate many visually near-identical, tightly packed instances —
+a genuine limitation of a fixed-query architecture on repetitive layouts,
+not a training bug.
+
+**4. Composite `Picture` regions get fragmented into overlapping sub-boxes**
+(`reports/failures/04_test_000425_err61.png`, patents: 0 missed, 0
+misclassified, 61 false positives — the cleanest signature in the run).
+Each ground-truth `Picture` is one chemical structure diagram; the model
+predicts 2–3 overlapping `Picture` boxes per diagram instead of one,
+apparently treating the diagram's internal sub-drawing and inline formula
+text as separable parts. This directly explains `Picture`'s low precision
+(0.416) despite reasonable recall (0.622) — it's finding pictures, just not
+as single coherent regions.
+
+**5. `Page-header` confused with `Text` on running headers** — observed
+live on a random, previously-unseen legal-code test page (not from the
+mined failure set): a running header/citation line ("...Official Gazette
+of the Republic...") was labelled `Text` at low confidence (0.34–0.46),
+well below the model's confident paragraph-level `Text` calls (0.68–0.96).
+The low confidence itself is informative — the model is uncertain about
+exactly the region it should be classifying differently.
+
+## 5. Part B — when it detects, and the honest refusal
+
+The router (regex prefilter → Groq LLM, strict `json_schema`) decides
+`needs_detection` before anything else runs. The prompt tells it explicitly
+that the detector's vocabulary is layout-only — it knows *where* regions
+are, never *what text says*. A question like "what is the invoice total"
+sounds document-related but is content, not layout, so it routes to
+`out_of_scope` before detection ever runs.
+
+**Real, live-tested example:** asked *"What law is this document about?"*
+against an actual test page, the system responded:
+
+> *"I can't answer that from this image's layout: Question asks about
+> document content, which the detector cannot read."*
+
+`insufficient_information=True` here is set in code from the router/
+guardrail state, not from the LLM self-reporting confidence — a
+confident-sounding wrong answer is one bad prompt away if the LLM judges
+its own certainty. The deterministic guardrail (4 rules: no detections,
+all below a 0.50 confidence floor, too much of a count in an ambiguous
+0.25–0.50 band, or query-budget saturation) is what actually decides,
+and it can't be talked out of triggering by fluent-sounding synthesis text.
+Full trace for every response is included in the API output for auditing.

notebooks/kaggle_train.ipynb

@@ -0,0 +1,233 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "12c7fcd3",
+   "metadata": {},
+   "source": [
+    "# RT-DETR on DocLayNet"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dd021a99",
+   "metadata": {},
+   "source": [
+    "## hardware check\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dc05ca98",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!nvidia-smi"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9fbb842f",
+   "metadata": {},
+   "source": [
+    "## Install\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "85123b54",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -q ultralytics==8.3.40 \"datasets<4.0.0\"\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8d277bd9",
+   "metadata": {},
+   "source": [
+    "## Pull the repo"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d57e231e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "REPO_URL = \"https://github.com/RISHIVELS/doc_layout_detection.git\"\n",
+    "\n",
+    "# %cd into a directory this cell is about to rm -rf breaks the shell's\n",
+    "# own working directory on the *next* run of this cell (getcwd fails\n",
+    "# because the path it thinks it is standing in no longer exists). So I\n",
+    "# step out to a stable parent directory before deleting anything.\n",
+    "%cd /kaggle/working\n",
+    "!rm -rf /kaggle/working/repo\n",
+    "!git clone -q $REPO_URL /kaggle/working/repo\n",
+    "%cd /kaggle/working/repo\n",
+    "!git log --oneline -1\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "388321a3",
+   "metadata": {},
+   "source": [
+    "## Build the dataset\n",
+    "\n",
+    "~3.8GB first run."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f8106d41",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python scripts/prepare_dataset.py --out /kaggle/working/data/doclaynet --verify 12"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b31d2185",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "from IPython.display import display\n",
+    "from PIL import Image\n",
+    "\n",
+    "checks = sorted(Path(\"/kaggle/working/data/doclaynet/label_check\").glob(\"*.png\"))\n",
+    "print(f\"{len(checks)} pages to check\\n\")\n",
+    "\n",
+    "for path in checks[:4]:\n",
+    "    display(Image.open(path).resize((620, 620)))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "90c07652",
+   "metadata": {},
+   "source": [
+    "## Train\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "148ae93a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python scripts/train.py \\\n",
+    "    --data /kaggle/working/data/doclaynet/doclaynet.yaml \\\n",
+    "    --epochs 30 \\\n",
+    "    --batch 8 \\\n",
+    "    --imgsz 640 \\\n",
+    "    --device 0 \\\n",
+    "    --name rtdetr_doclaynet"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8f5e102a",
+   "metadata": {},
+   "source": [
+    "## Evaluate\n",
+    "\n",
+    "Per-class AP, per-category mAP, query saturation. Category breakdown\n",
+    "matters most - aggregate mAP can't tell you if it learned structure\n",
+    "or just financial reports."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bce9eb4b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python scripts/evaluate.py \\\n",
+    "    --weights runs/detect/rtdetr_doclaynet/weights/best.pt \\\n",
+    "    --data /kaggle/working/data/doclaynet/doclaynet.yaml \\\n",
+    "    --out reports"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "274d9f83",
+   "metadata": {},
+   "source": [
+    "## Mine failure cases\n",
+    "\n",
+    "Ranks worst predictions, renders them against ground truth. Memo's\n",
+    "failure cases come from here, not guessing."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "57865d2e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!python scripts/mine_failures.py \\\n",
+    "    --weights runs/detect/rtdetr_doclaynet/weights/best.pt \\\n",
+    "    --data /kaggle/working/data/doclaynet \\\n",
+    "    --out reports/failures \\\n",
+    "    --top 25"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d8e7c81c",
+   "metadata": {},
+   "source": [
+    "## Outputs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import shutil\n",
+    "from pathlib import Path\n",
+    "\n",
+    "run = Path(\"runs/detect/rtdetr_doclaynet\")\n",
+    "out = Path(\"/kaggle/working/submission\")\n",
+    "out.mkdir(exist_ok=True)\n",
+    "\n",
+    "shutil.copy(run / \"weights/best.pt\", out / \"best.pt\")\n",
+    "shutil.copy(run / \"run_metadata.json\", out / \"run_metadata.json\")\n",
+    "if Path(\"reports\").exists():\n",
+    "    shutil.copytree(\"reports\", out / \"reports\", dirs_exist_ok=True)\n",
+    "\n",
+    "for path in sorted(out.rglob(\"*\")):\n",
+    "    if path.is_file():\n",
+    "        print(f\"{path.stat().st_size / 1e6:8.1f} MB  {path.relative_to(out)}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

reports/metrics.json

@@ -0,0 +1,70 @@
+{
+  "weights": "runs/detect/rtdetr_doclaynet/weights/best.pt",
+  "overall": {
+    "mAP50": 0.6216,
+    "mAP50_95": 0.4122,
+    "precision": 0.7056,
+    "recall": 0.6052
+  },
+  "per_class_mAP50_95": {
+    "Caption": 0.4112,
+    "Footnote": 0.0963,
+    "Formula": 0.4119,
+    "List-item": 0.4518,
+    "Page-footer": 0.4962,
+    "Page-header": 0.3857,
+    "Picture": 0.38,
+    "Section-header": 0.4851,
+    "Table": 0.6333,
+    "Text": 0.6579,
+    "Title": 0.1246
+  },
+  "query_saturation": {
+    "measured": true,
+    "query_budget": 300,
+    "max_regions_on_any_page": 95,
+    "mean_regions_per_page": 12.7,
+    "pages_over_budget": 0,
+    "percent_over_budget": 0.0
+  },
+  "split_leakage": {
+    "measured": true,
+    "shared_source_pdfs": 0,
+    "test_pages_from_shared_pdfs": 0,
+    "test_pages_total": 499,
+    "percent_affected": 0.0
+  },
+  "confusion_matrix_plot": "runs/detect/val/confusion_matrix_normalized.png",
+  "per_doc_category": {
+    "financial_reports": {
+      "pages": 172,
+      "mAP50": 0.5349,
+      "mAP50_95": 0.3383
+    },
+    "government_tenders": {
+      "pages": 29,
+      "mAP50": 0.547,
+      "mAP50_95": 0.4103
+    },
+    "laws_and_regulations": {
+      "pages": 86,
+      "mAP50": 0.4949,
+      "mAP50_95": 0.316
+    },
+    "manuals": {
+      "pages": 77,
+      "mAP50": 0.6327,
+      "mAP50_95": 0.4321
+    },
+    "patents": {
+      "pages": 32,
+      "mAP50": 0.7427,
+      "mAP50_95": 0.5509
+    },
+    "scientific_articles": {
+      "pages": 103,
+      "mAP50": 0.7451,
+      "mAP50_95": 0.5254
+    }
+  }
+}

reports/run_metadata.json

@@ -0,0 +1,47 @@
+{
+  "git_commit": "00ed77c89f8b469e5dfa32b96cbf9f8e1d79d332",
+  "hyperparameters": {
+    "data": "/kaggle/working/data/doclaynet/doclaynet.yaml",
+    "epochs": 15,
+    "imgsz": 640,
+    "batch": 8,
+    "device": "0",
+    "seed": 42,
+    "deterministic": true,
+    "amp": true,
+    "optimizer": "AdamW",
+    "lr0": 0.0001,
+    "lrf": 0.01,
+    "weight_decay": 0.0001,
+    "warmup_epochs": 3.0,
+    "cos_lr": true,
+    "save_period": 1,
+    "patience": 10,
+    "workers": 2,
+    "cache": false,
+    "val": true,
+    "plots": true,
+    "fliplr": 0.0,
+    "flipud": 0.0,
+    "mosaic": 0.0,
+    "degrees": 3.0,
+    "perspective": 0.0005,
+    "translate": 0.05,
+    "scale": 0.2,
+    "shear": 0.0,
+    "hsv_h": 0.0,
+    "hsv_s": 0.2,
+    "hsv_v": 0.2,
+    "erasing": 0.0,
+    "name": "rtdetr_doclaynet"
+  },
+  "hardware": {
+    "gpu": "Tesla T4",
+    "gpu_memory_gb": 14.6,
+    "torch_version": "2.10.0+cu128",
+    "cuda_version": "12.8"
+  },
+  "ultralytics_version": "8.3.40",
+  "wall_clock_seconds": 8178.6,
+  "wall_clock_human": "2.27 h"
+}

requirements.txt

@@ -0,0 +1,44 @@
+# ---------------------------------------------------------------------------
+# Hard Constraint 1 of the brief: NO agentic frameworks.
+# LangChain, LangGraph, CrewAI, AutoGen and equivalents are deliberately
+# absent. The reasoning layer in app/reasoning/ is hand-written and talks to
+# the LLM through Groq's plain SDK only.
+# ---------------------------------------------------------------------------
+
+# --- Detection (Hard Constraint 2: RT-DETR, own training code) ---
+ultralytics==8.3.40
+torch>=2.2
+torchvision>=0.17
+
+# --- Dataset preparation ---
+datasets>=2.19,<4.0.0
+pillow>=10.0
+numpy>=1.26
+tqdm>=4.66
+
+# --- Demo UIs (for Hugging Face Spaces) ---
+# gradio: current HF Space creation flow only offers Gradio/Docker/Static
+# as SDKs, no standalone Streamlit option - gradio_app.py is the one that
+# actually gets deployed there. streamlit_app.py stays for local use /
+# Docker, where SDK choice doesn't matter.
+streamlit>=1.38
+gradio>=4.44
+spaces>=0.30  # only does anything on an actual HF ZeroGPU Space
+
+# --- API ---
+python-dotenv>=1.0
+fastapi>=0.115
+uvicorn[standard]>=0.30
+pydantic>=2.7
+python-multipart>=0.0.9
+
+# --- Reasoning layer (plain SDK, no framework) ---
+# Groq's own SDK. It is a thin HTTP client over their chat-completions
+# endpoint - it does not chain, plan, or orchestrate anything. All of the
+# routing and reasoning logic lives in app/reasoning/ and is mine.
+groq>=0.11
+
+# --- Evaluation / reporting ---
+matplotlib>=3.8
+pandas>=2.2
+

scripts/_render_utils.py

@@ -0,0 +1,35 @@
+# Shared by prepare_dataset.py's label check and mine_failures.py's
+# failure renders. PIL's bitmap default font (~10px) turns into an
+# illegible smear once resized for a notebook or memo screenshot - which
+# is the only place either render gets looked at.
+from __future__ import annotations
+
+
+def load_label_font(size: int):
+    """Finds a real scalable font. matplotlib ships its own DejaVu copy
+    and is already a pinned dependency, so that's guaranteed to exist -
+    a bare "DejaVuSans-Bold.ttf" only works if the OS's font search
+    happens to resolve it, which isn't something to bet a Kaggle run on."""
+    from PIL import ImageFont
+
+    candidates = []
+
+    try:
+        import matplotlib
+
+        candidates.append(f"{matplotlib.get_data_path()}/fonts/ttf/DejaVuSans-Bold.ttf")
+    except Exception:
+        pass
+
+    candidates += [
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",  # Debian/Ubuntu, Kaggle
+        "DejaVuSans-Bold.ttf",  # works if OS font search resolves it (e.g. Windows)
+    ]
+
+    for path in candidates:
+        try:
+            return ImageFont.truetype(path, size)
+        except OSError:
+            continue
+
+    return ImageFont.load_default()

scripts/build_report.py

@@ -0,0 +1,231 @@
+# Builds a visual PDF report from reports/metrics.json and
+# reports/run_metadata.json - same numbers as the memo, laid out so
+# someone can understand the results without reading raw JSON.
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import matplotlib
+import matplotlib.pyplot as plt
+from matplotlib.backends.backend_pdf import PdfPages
+
+matplotlib.rcParams.update({
+    "font.family": "sans-serif",
+    "font.size": 11,
+    "text.color": "#0b0b0b",
+    "axes.edgecolor": "#0b0b0b",
+    "axes.labelcolor": "#0b0b0b",
+    "xtick.color": "#0b0b0b",
+    "ytick.color": "#0b0b0b",
+})
+
+BLUE = "#2a78d6"       # validated single hue, see dataviz skill palette
+GRID = "#d9d9d6"       # recessive gridline
+MUTED = "#52514e"      # secondary text
+
+ROOT = Path(__file__).resolve().parent.parent
+metrics = json.loads((ROOT / "reports/metrics.json").read_text())
+run = json.loads((ROOT / "reports/run_metadata.json").read_text())
+
+CLASS_INSTANCES = {  # from the evaluate.py console output for this run
+    "Caption": 149, "Footnote": 47, "Formula": 150, "List-item": 962,
+    "Page-footer": 408, "Page-header": 311, "Picture": 143,
+    "Section-header": 873, "Table": 252, "Text": 3002, "Title": 52,
+}
+
+
+def new_page(figsize=(8.5, 11)):
+    fig = plt.figure(figsize=figsize, facecolor="white")
+    fig.patch.set_facecolor("white")
+    return fig
+
+
+def bare_axes(fig, rect):
+    ax = fig.add_axes(rect)
+    ax.set_facecolor("white")
+    for spine in ax.spines.values():
+        spine.set_visible(False)
+    ax.set_xticks([])
+    ax.set_yticks([])
+    return ax
+
+
+def page_overview():
+    fig = new_page()
+    ax = bare_axes(fig, [0, 0, 1, 1])
+
+    ax.text(0.07, 0.94, "Document Layout Detection — Evaluation Report",
+            fontsize=20, fontweight="bold", ha="left")
+    ax.text(0.07, 0.905, "RT-DETR-L fine-tuned on DocLayNet, evaluated on the held-out test split",
+            fontsize=12, color=MUTED, ha="left")
+    ax.axhline(0.885, xmin=0.07, xmax=0.93, color="#0b0b0b", linewidth=1)
+
+    overall = metrics["overall"]
+    stats = [
+        ("mAP50", f"{overall['mAP50']:.3f}"),
+        ("mAP50-95", f"{overall['mAP50_95']:.3f}"),
+        ("Precision", f"{overall['precision']:.3f}"),
+        ("Recall", f"{overall['recall']:.3f}"),
+    ]
+    x0 = 0.07
+    box_w = 0.20
+    for i, (label, value) in enumerate(stats):
+        x = x0 + i * (box_w + 0.013)
+        ax.add_patch(plt.Rectangle((x, 0.74), box_w, 0.12, fill=False,
+                                    edgecolor="#0b0b0b", linewidth=1))
+        ax.text(x + box_w / 2, 0.815, value, fontsize=22, fontweight="bold",
+                ha="center", va="center", color=BLUE)
+        ax.text(x + box_w / 2, 0.755, label, fontsize=10.5, ha="center",
+                va="center", color=MUTED)
+
+    ax.text(0.07, 0.68, "Test set: 499 pages, 6,349 annotated regions, 11 classes (none in COCO)",
+            fontsize=10.5, color=MUTED)
+
+    # metric bar chart - 4 distinct measures of the same model, so a small
+    # categorical set (not a repeated single-series magnitude chart)
+    cats = ["Precision", "Recall", "mAP50", "mAP50-95"]
+    vals = [overall["precision"], overall["recall"], overall["mAP50"], overall["mAP50_95"]]
+    colors = ["#2a78d6", "#eb6834", "#1baf7a", "#eda100"]  # fixed categorical order, slots 1-4
+    ax2 = fig.add_axes([0.10, 0.48, 0.80, 0.16])
+    bars = ax2.bar(cats, vals, color=colors, width=0.55)
+    ax2.set_ylim(0, 1.0)
+    ax2.grid(axis="y", color=GRID, linewidth=0.8, zorder=0)
+    ax2.set_axisbelow(True)
+    for spine in ("top", "right", "left"):
+        ax2.spines[spine].set_visible(False)
+    ax2.spines["bottom"].set_color("#0b0b0b")
+    ax2.tick_params(left=False)
+    ax2.set_yticklabels([])
+    for bar, v in zip(bars, vals):
+        ax2.text(bar.get_x() + bar.get_width() / 2, v + 0.02, f"{v:.3f}",
+                  ha="center", fontsize=10, fontweight="bold")
+
+    # training config, factual, no names/dates
+    hp = run["hyperparameters"]
+    hw = run["hardware"]
+    config_lines = [
+        f"Epochs: {hp['epochs']}    Batch: {hp['batch']}    Image size: {hp['imgsz']}px",
+        f"Optimizer: {hp['optimizer']}    LR: {hp['lr0']}    Seed: {hp['seed']}",
+        f"Hardware: {hw['gpu']} ({hw['gpu_memory_gb']} GB)    Wall clock: {run['wall_clock_human']}",
+        f"Query-budget saturation: {metrics['query_saturation']['percent_over_budget']}% of test pages "
+        f"(max {metrics['query_saturation']['max_regions_on_any_page']} regions, budget "
+        f"{metrics['query_saturation']['query_budget']})",
+        f"Train/test source-PDF overlap: {metrics['split_leakage']['percent_affected']}% "
+        f"({metrics['split_leakage']['test_pages_total']} test pages checked)",
+    ]
+    ax.text(0.07, 0.40, "Training configuration", fontsize=13, fontweight="bold")
+    for i, line in enumerate(config_lines):
+        ax.text(0.07, 0.365 - i * 0.032, line, fontsize=10.5, color="#0b0b0b")
+
+    return fig
+
+
+def page_per_class():
+    fig = new_page()
+    ax_title = bare_axes(fig, [0, 0, 1, 1])
+    ax_title.text(0.07, 0.955, "Per-class performance (mAP50)", fontsize=16, fontweight="bold")
+    ax_title.text(0.07, 0.928, "Sorted by score. Instance count shown per class — rarity, not size alone, "
+                                "drives the weakest results.", fontsize=10, color=MUTED)
+
+    per_class = metrics["overall"]  # placeholder, real data below
+    items = sorted(
+        [(name, CLASS_INSTANCES[name]) for name in CLASS_INSTANCES],
+        key=lambda kv: PER_CLASS_MAP50[kv[0]],
+    )
+    names = [n for n, _ in items]
+    values = [PER_CLASS_MAP50[n] for n, _ in items]
+    counts = [c for _, c in items]
+
+    ax = fig.add_axes([0.28, 0.08, 0.62, 0.80])
+    y = range(len(names))
+    ax.barh(y, values, color=BLUE, height=0.6, zorder=3)
+    ax.set_yticks(list(y))
+    ax.set_yticklabels(names, fontsize=11)
+    ax.set_xlim(0, 1.0)
+    ax.grid(axis="x", color=GRID, linewidth=0.8, zorder=0)
+    ax.set_axisbelow(True)
+    for spine in ("top", "right"):
+        ax.spines[spine].set_visible(False)
+    ax.spines["left"].set_color("#0b0b0b")
+    ax.spines["bottom"].set_color("#0b0b0b")
+    ax.set_xlabel("mAP50", fontsize=10.5, color=MUTED)
+
+    for yi, (v, c) in enumerate(zip(values, counts)):
+        ax.text(v + 0.015, yi, f"{v:.3f}", va="center", fontsize=9.5, fontweight="bold")
+        ax.text(1.02, yi, f"n={c}", va="center", fontsize=8.5, color=MUTED, transform=ax.get_yaxis_transform())
+
+    return fig
+
+
+def page_per_category():
+    fig = new_page()
+    ax_title = bare_axes(fig, [0, 0, 1, 1])
+    ax_title.text(0.07, 0.955, "Per-document-category performance (mAP50)", fontsize=16, fontweight="bold")
+    ax_title.text(0.07, 0.928, "Tests generalization across document styles, not just aggregate accuracy.",
+                  fontsize=10, color=MUTED)
+
+    cat = metrics["per_doc_category"]
+    items = sorted(cat.items(), key=lambda kv: kv[1]["mAP50"])
+    names = [k.replace("_", " ") for k, _ in items]
+    values = [v["mAP50"] for _, v in items]
+    pages = [v["pages"] for _, v in items]
+
+    ax = fig.add_axes([0.30, 0.55, 0.60, 0.34])
+    y = range(len(names))
+    ax.barh(y, values, color=BLUE, height=0.55, zorder=3)
+    ax.set_yticks(list(y))
+    ax.set_yticklabels(names, fontsize=11)
+    ax.set_xlim(0, 1.0)
+    ax.grid(axis="x", color=GRID, linewidth=0.8, zorder=0)
+    ax.set_axisbelow(True)
+    for spine in ("top", "right"):
+        ax.spines[spine].set_visible(False)
+    ax.spines["left"].set_color("#0b0b0b")
+    ax.spines["bottom"].set_color("#0b0b0b")
+    ax.set_xlabel("mAP50", fontsize=10.5, color=MUTED)
+    for yi, (v, p) in enumerate(zip(values, pages)):
+        ax.text(v + 0.015, yi, f"{v:.3f}  ({p} pages)", va="center", fontsize=9.5, fontweight="bold")
+
+    # failure notes, factual only
+    ax_title.text(0.07, 0.42, "Observed failure patterns", fontsize=13, fontweight="bold")
+    notes = [
+        "Footnote (47 instances): recall 0.048 — rare class, near-total miss rate.",
+        "Page-footer (408 instances): mAP50 0.843 — same thin shape as Footnote, but",
+        "     9x more training instances and a consistent position. Rarity, not size,",
+        "     is the dominant factor.",
+        "Picture: precision 0.416 despite recall 0.622 — composite regions (diagrams",
+        "     with embedded text) get split into multiple overlapping boxes instead",
+        "     of one region.",
+        "Dense repeated-entry layouts (directories, org charts) produce duplicate,",
+        "     overlapping box proposals rather than one box per entry.",
+    ]
+    for i, line in enumerate(notes):
+        ax_title.text(0.07, 0.385 - i * 0.028, line, fontsize=10, color="#0b0b0b")
+
+    return fig
+
+
+PER_CLASS_MAP50 = {
+    "Caption": 0.622, "Footnote": 0.182, "Formula": 0.788, "List-item": 0.671,
+    "Page-footer": 0.843, "Page-header": 0.658, "Picture": 0.495,
+    "Section-header": 0.762, "Table": 0.761, "Text": 0.832, "Title": 0.224,
+}
+
+if __name__ == "__main__":
+    import sys
+
+    preview = "--preview" in sys.argv
+    out_path = ROOT / "reports" / "evaluation_report.pdf"
+    pages = [page_overview(), page_per_class(), page_per_category()]
+
+    with PdfPages(out_path, metadata={
+        "Title": "", "Author": "", "Subject": "", "Creator": "", "Producer": "", "CreationDate": None,
+    }) as pdf:
+        for i, fig in enumerate(pages, start=1):
+            pdf.savefig(fig)
+            if preview:
+                fig.savefig(ROOT / f"reports/_preview_page{i}.png", dpi=110)
+            plt.close(fig)
+
+    print(f"wrote {out_path}")

scripts/evaluate.py

@@ -0,0 +1,183 @@
+# Evaluates the trained model on the held-out test split. One aggregate
+# mAP can't answer the questions that actually matter, so this produces:
+#   - per-class AP (which classes are actually weak, and was that
+#     predictable given the 640px downscale)
+#   - per-document-category mAP (did it learn structure, or just what
+#     financial reports look like - the biggest slice of the data)
+#   - query-budget saturation rate (RT-DETR has a fixed number of
+#     predictions per image - dense pages lose recall for a reason that
+#     has nothing to do with training quality)
+#   - measured train/test source-PDF overlap (used the author's splits for
+#     reproducibility, but that means inheriting whatever leakage they have)
+#
+# Usage:
+#   python scripts/evaluate.py --weights runs/detect/rtdetr_doclaynet/weights/best.pt \
+#                              --data data/doclaynet/doclaynet.yaml --out reports
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from app.constants import CLASS_NAMES, DEFAULT_QUERY_BUDGET  # noqa: E402
+
+
+def _load_manifest(data_root: Path, split: str) -> list[dict]:
+    path = data_root / f"manifest_{split}.json"
+    if not path.exists():
+        print(f"  (no manifest at {path} - skipping category breakdown)")
+        return []
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def measure_split_leakage(data_root: Path) -> dict:
+    """Checks if any source PDF has pages on both sides of train/test.
+    Used the author's published splits rather than re-splitting (keeps
+    numbers comparable to published work), but that means inheriting
+    whatever overlap they have. Not fixing it, just measuring and
+    reporting it."""
+    train = {row["source_pdf"] for row in _load_manifest(data_root, "train")}
+    test_rows = _load_manifest(data_root, "test")
+    if not train or not test_rows:
+        return {"measured": False}
+
+    shared = {row["source_pdf"] for row in test_rows} & train
+    affected = sum(1 for row in test_rows if row["source_pdf"] in shared)
+
+    return {
+        "measured": True,
+        "shared_source_pdfs": len(shared),
+        "test_pages_from_shared_pdfs": affected,
+        "test_pages_total": len(test_rows),
+        "percent_affected": round(100 * affected / len(test_rows), 1),
+    }
+
+
+def measure_query_saturation(data_root: Path, budget: int = DEFAULT_QUERY_BUDGET) -> dict:
+    """RT-DETR emits a fixed number of boxes per image regardless of
+    confidence - a page with more regions than that structurally can't be
+    fully detected. Measuring this separately so it doesn't get
+    misattributed as a training/recall problem in the failure analysis."""
+    rows = _load_manifest(data_root, "test")
+    if not rows:
+        return {"measured": False}
+
+    counts = [row["num_regions"] for row in rows]
+    saturated = [c for c in counts if c > budget]
+
+    return {
+        "measured": True,
+        "query_budget": budget,
+        "max_regions_on_any_page": max(counts),
+        "mean_regions_per_page": round(sum(counts) / len(counts), 1),
+        "pages_over_budget": len(saturated),
+        "percent_over_budget": round(100 * len(saturated) / len(counts), 2),
+    }
+
+
+def per_category_map(weights: str, data_root: Path, base_yaml: Path, out_dir: Path) -> dict:
+    """Runs validation once per document category by writing a filtered
+    image-list yaml per category. Six extra small val passes, turns one
+    opaque number into a real generalisation check."""
+    rows = _load_manifest(data_root, "test")
+    if not rows:
+        return {}
+
+    from ultralytics import RTDETR
+
+    by_category: dict[str, list[str]] = defaultdict(list)
+    for row in rows:
+        image_path = data_root / "images" / "test" / f"{row['stem']}.png"
+        by_category[row["doc_category"]].append(str(image_path.resolve()))
+
+    split_dir = out_dir / "category_splits"
+    split_dir.mkdir(parents=True, exist_ok=True)
+
+    base = base_yaml.read_text(encoding="utf-8")
+    results: dict[str, dict] = {}
+
+    for category, images in sorted(by_category.items()):
+        # too few pages = noise, not a measurement - skip and say so
+        if len(images) < 10:
+            results[category] = {"pages": len(images), "skipped": "too few pages to be meaningful"}
+            continue
+
+        listing = split_dir / f"{category}.txt"
+        listing.write_text("\n".join(images), encoding="utf-8")
+
+        yaml_path = split_dir / f"{category}.yaml"
+        yaml_path.write_text(
+            base.replace("val: images/validation", f"val: {listing.resolve().as_posix()}"),
+            encoding="utf-8",
+        )
+
+        metrics = RTDETR(weights).val(data=str(yaml_path), split="val", verbose=False)
+        results[category] = {
+            "pages": len(images),
+            "mAP50": round(float(metrics.box.map50), 4),
+            "mAP50_95": round(float(metrics.box.map), 4),
+        }
+        print(f"  {category:22s} {len(images):4d} pages  mAP50={metrics.box.map50:.3f}")
+
+    return results
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--weights", required=True)
+    parser.add_argument("--data", required=True, help="path to doclaynet.yaml")
+    parser.add_argument("--out", default="reports")
+    args = parser.parse_args()
+
+    from ultralytics import RTDETR
+
+    base_yaml = Path(args.data)
+    data_root = base_yaml.parent
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    print("Evaluating on the held-out test split...")
+    metrics = RTDETR(args.weights).val(data=args.data, split="test", plots=True)
+
+    # zip against my own class list rather than trusting box.maps' order -
+    # a mismatch here would attribute every class's score to its neighbour
+    # and still look completely plausible
+    per_class = {
+        name: round(float(ap), 4)
+        for name, ap in zip(CLASS_NAMES, list(metrics.box.maps))
+    }
+
+    report = {
+        "weights": args.weights,
+        "overall": {
+            "mAP50": round(float(metrics.box.map50), 4),
+            "mAP50_95": round(float(metrics.box.map), 4),
+            "precision": round(float(metrics.box.mp), 4),
+            "recall": round(float(metrics.box.mr), 4),
+        },
+        "per_class_mAP50_95": per_class,
+        "query_saturation": measure_query_saturation(data_root),
+        "split_leakage": measure_split_leakage(data_root),
+        "confusion_matrix_plot": str(Path(metrics.save_dir) / "confusion_matrix_normalized.png"),
+    }
+
+    print("\nPer-document-category breakdown:")
+    report["per_doc_category"] = per_category_map(args.weights, data_root, base_yaml, out_dir)
+
+    path = out_dir / "metrics.json"
+    path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+    print(f"\nWrote {path}")
+    print(f"  overall mAP50     {report['overall']['mAP50']:.3f}")
+    print(f"  overall mAP50-95  {report['overall']['mAP50_95']:.3f}")
+    print("\n  weakest classes:")
+    for name, ap in sorted(per_class.items(), key=lambda kv: kv[1])[:4]:
+        print(f"    {name:16s} {ap:.3f}")
+
+
+if __name__ == "__main__":
+    main()

scripts/mine_failures.py

@@ -0,0 +1,230 @@
+# Finds the test pages the model got most wrong and renders them side by
+# side with ground truth. The 5 failure cases in the memo come from this,
+# not from guessing - the brief flags "no acknowledged failure cases" as a
+# red flag, so these need to be real, pointable-at examples.
+#
+# Scoring is deliberately crude (greedy IoU 0.5 matching) - just needs to
+# rank pages well enough to surface the interesting ones, not be a precise
+# metric (that's evaluate.py's job).
+#
+# Usage:
+#   python scripts/mine_failures.py --weights runs/detect/.../best.pt \
+#       --data data/doclaynet --out reports/failures --top 25
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from app.constants import ID_TO_CLASS  # noqa: E402
+from scripts._render_utils import load_label_font as _label_font  # noqa: E402
+
+PALETTE = [
+    "#e6194b", "#3cb44b", "#ffe119", "#4363d8", "#f58231", "#911eb4",
+    "#46f0f0", "#f032e6", "#bcf60c", "#fabebe", "#008080",
+]
+
+
+def iou(a: tuple[float, ...], b: tuple[float, ...]) -> float:
+    """IoU for two xyxy boxes."""
+    ax1, ay1, ax2, ay2 = a
+    bx1, by1, bx2, by2 = b
+
+    ix1, iy1 = max(ax1, bx1), max(ay1, by1)
+    ix2, iy2 = min(ax2, bx2), min(ay2, by2)
+    if ix2 <= ix1 or iy2 <= iy1:
+        return 0.0
+
+    intersection = (ix2 - ix1) * (iy2 - iy1)
+    union = (ax2 - ax1) * (ay2 - ay1) + (bx2 - bx1) * (by2 - by1) - intersection
+    return intersection / union if union > 0 else 0.0
+
+
+def _read_ground_truth(label_path: Path, width: int, height: int) -> list[tuple[int, tuple[float, ...]]]:
+    """Reads a YOLO label file back into absolute xyxy boxes."""
+    if not label_path.exists():
+        return []
+
+    boxes = []
+    for line in label_path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        class_id, xc, yc, w, h = line.split()
+        xc, yc, w, h = float(xc) * width, float(yc) * height, float(w) * width, float(h) * height
+        boxes.append((int(class_id), (xc - w / 2, yc - h / 2, xc + w / 2, yc + h / 2)))
+    return boxes
+
+
+def score_page(
+    ground_truth: list[tuple[int, tuple[float, ...]]],
+    predictions: list[tuple[int, tuple[float, ...], float]],
+    iou_threshold: float = 0.5,
+) -> dict:
+    """Greedy match + counts. Splits misses from misclassifications since
+    they have different causes - a miss is usually small/thin/query-
+    starved, a misclassification is usually genuine label ambiguity
+    (Text vs List-item, Title vs Section-header). That split is what lets
+    the memo talk about annotation ambiguity instead of just "missed stuff"."""
+    unmatched_gt = list(range(len(ground_truth)))
+    matched_predictions: set[int] = set()
+
+    correct = 0
+    misclassified = 0
+
+    for gt_index in list(unmatched_gt):
+        gt_class, gt_box = ground_truth[gt_index]
+
+        best_index, best_iou = None, iou_threshold
+        for pred_index, (_, pred_box, _) in enumerate(predictions):
+            if pred_index in matched_predictions:
+                continue
+            overlap = iou(gt_box, pred_box)
+            if overlap >= best_iou:
+                best_index, best_iou = pred_index, overlap
+
+        if best_index is not None:
+            matched_predictions.add(best_index)
+            unmatched_gt.remove(gt_index)
+            if predictions[best_index][0] == gt_class:
+                correct += 1
+            else:
+                misclassified += 1
+
+    false_positives = len(predictions) - len(matched_predictions)
+
+    return {
+        "ground_truth_regions": len(ground_truth),
+        "predicted_regions": len(predictions),
+        "correct": correct,
+        "misclassified": misclassified,
+        "missed": len(unmatched_gt),
+        "false_positives": false_positives,
+        # misclassifications weighted higher - they're the interesting ones
+        "error_score": len(unmatched_gt) + false_positives + 1.5 * misclassified,
+    }
+
+
+def _draw_labelled_box(draw, colour: str, x1, y1, x2, y2, label: str, font) -> None:
+    """Box outline plus a solid background behind the label, legible over
+    any page content."""
+    draw.rectangle([x1, y1, x2, y2], outline=colour, width=4)
+    text_box = draw.textbbox((x1, y1), label, font=font)
+    draw.rectangle(
+        [text_box[0] - 2, text_box[1] - 2, text_box[2] + 2, text_box[3] + 2],
+        fill=colour,
+    )
+    draw.text((x1, y1), label, font=font, fill="white")
+
+
+def _render_comparison(image, ground_truth, predictions, out_path: Path) -> None:
+    """Ground truth on the left, prediction on the right."""
+    from PIL import Image, ImageDraw
+
+    width, height = image.size
+    canvas = Image.new("RGB", (width * 2 + 20, height + 40), "white")
+    canvas.paste(image, (0, 40))
+    canvas.paste(image, (width + 20, 40))
+
+    draw = ImageDraw.Draw(canvas)
+    header_font = _label_font(24)
+    label_font = _label_font(22)
+    draw.text((10, 8), "GROUND TRUTH", font=header_font, fill="black")
+    draw.text((width + 30, 8), "PREDICTION", font=header_font, fill="black")
+
+    for class_id, (x1, y1, x2, y2) in ground_truth:
+        colour = PALETTE[class_id % len(PALETTE)]
+        _draw_labelled_box(draw, colour, x1, y1 + 40, x2, y2 + 40,
+                            ID_TO_CLASS.get(class_id, "?"), label_font)
+
+    offset = width + 20
+    for class_id, (x1, y1, x2, y2), confidence in predictions:
+        colour = PALETTE[class_id % len(PALETTE)]
+        label = f"{ID_TO_CLASS.get(class_id, '?')} {confidence:.2f}"
+        _draw_labelled_box(draw, colour, x1 + offset, y1 + 40, x2 + offset, y2 + 40,
+                            label, label_font)
+
+    canvas.save(out_path)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--weights", required=True)
+    parser.add_argument("--data", required=True, help="dataset root containing images/ and labels/")
+    parser.add_argument("--out", default="reports/failures")
+    parser.add_argument("--top", type=int, default=25)
+    parser.add_argument("--conf", type=float, default=0.25)
+    args = parser.parse_args()
+
+    from PIL import Image
+    from ultralytics import RTDETR
+
+    data_root = Path(args.data)
+    image_dir = data_root / "images" / "test"
+    label_dir = data_root / "labels" / "test"
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    model = RTDETR(args.weights)
+    images = sorted(image_dir.glob("*.png"))
+    print(f"Scoring {len(images)} test pages...")
+
+    manifest_path = data_root / "manifest_test.json"
+    categories = {}
+    if manifest_path.exists():
+        categories = {
+            row["stem"]: row["doc_category"]
+            for row in json.loads(manifest_path.read_text(encoding="utf-8"))
+        }
+
+    scored = []
+    for index, image_path in enumerate(images):
+        image = Image.open(image_path).convert("RGB")
+        width, height = image.size
+
+        result = model.predict(image, conf=args.conf, verbose=False)[0]
+        predictions = [
+            (int(cls), tuple(float(v) for v in box), float(conf))
+            for cls, box, conf in zip(
+                result.boxes.cls.tolist(),
+                result.boxes.xyxy.tolist(),
+                result.boxes.conf.tolist(),
+            )
+        ]
+
+        ground_truth = _read_ground_truth(label_dir / f"{image_path.stem}.txt", width, height)
+        score = score_page(ground_truth, predictions)
+        score["stem"] = image_path.stem
+        score["doc_category"] = categories.get(image_path.stem, "unknown")
+        scored.append((score, image, ground_truth, predictions))
+
+        if (index + 1) % 100 == 0:
+            print(f"  {index + 1}/{len(images)}", flush=True)
+
+    scored.sort(key=lambda item: item[0]["error_score"], reverse=True)
+
+    summary = []
+    for rank, (score, image, ground_truth, predictions) in enumerate(scored[: args.top], start=1):
+        out_path = out_dir / f"{rank:02d}_{score['stem']}_err{score['error_score']:.0f}.png"
+        _render_comparison(image, ground_truth, predictions, out_path)
+        score["render"] = out_path.name
+        summary.append(score)
+
+    (out_dir / "failure_summary.json").write_text(
+        json.dumps(summary, indent=2), encoding="utf-8"
+    )
+
+    print(f"\nWrote {len(summary)} comparison renders to {out_dir}")
+    print("\nWorst pages:")
+    for score in summary[:8]:
+        print(
+            f"  {score['stem']:20s} {score['doc_category']:20s} "
+            f"missed={score['missed']:3d} misclassified={score['misclassified']:3d} "
+            f"fp={score['false_positives']:3d}"
+        )
+
+
+if __name__ == "__main__":
+    main()

scripts/prepare_dataset.py

@@ -0,0 +1,329 @@
+# Converts the HF DocLayNet-base dataset into the image/label layout
+# Ultralytics expects. Everything that can go wrong here goes wrong
+# silently - bad labels don't raise, training just quietly learns the
+# wrong thing. Three things beyond the obvious conversion:
+#   1. collapses repeated per-line boxes (a 40-region page can show up as
+#      ~1,100 duplicate annotations otherwise)
+#   2. drops degenerate boxes and counts them (zero-area -> NaN loss later)
+#   3. can render a sample with decoded labels drawn on, so I can eyeball
+#      that the class index mapping is actually right
+#
+# Usage:
+#   python scripts/prepare_dataset.py --out data/doclaynet
+#   python scripts/prepare_dataset.py --out data/doclaynet --verify 12
+#   python scripts/prepare_dataset.py --out data/doclaynet --limit 20   # smoke test
+from __future__ import annotations
+
+import argparse
+import json
+import random
+from collections import Counter
+from pathlib import Path
+
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from app.constants import CLASS_NAMES, ID_TO_CLASS  # noqa: E402
+
+HF_DATASET = "pierreguillou/DocLayNet-base"
+
+# HF split names don't match Ultralytics' directory convention
+SPLITS = {"train": "train", "validation": "validation", "test": "test"}
+
+
+def coco_to_yolo(
+    bbox: list[float], img_w: int, img_h: int
+) -> tuple[float, float, float, float]:
+    """DocLayNet gives [x, y, w, h] top-left in pixels. Ultralytics wants
+    [x_centre, y_centre, w, h] normalised 0-1. Easy to get the corner-to-
+    centre shift wrong without noticing - tested for that reason."""
+    x, y, w, h = bbox
+    x_centre = (x + w / 2) / img_w
+    y_centre = (y + h / 2) / img_h
+    return (x_centre, y_centre, w / img_w, h / img_h)
+
+
+def is_valid_bbox(bbox: list[float], img_w: int, img_h: int) -> bool:
+    """Rejects zero-area/out-of-bounds boxes before they turn into NaN
+    losses several epochs in. Counts rejections rather than just dropping
+    silently."""
+    x, y, w, h = bbox
+    if w <= 0 or h <= 0:
+        return False
+    if x < 0 or y < 0:
+        return False
+    if x + w > img_w or y + h > img_h:
+        return False
+    return True
+
+
+def dedupe_annotations(
+    bboxes: list[list[float]], categories: list[int]
+) -> list[tuple[tuple[float, ...], int]]:
+    """DocLayNet-base repeats a block's box once per text line inside it -
+    a paragraph with 6 lines shows up as 6 identical entries. Dedupe on
+    (box, category) rather than box alone, since two classes occasionally
+    share the same extent. First-seen order kept so output is reproducible."""
+    if len(bboxes) != len(categories):
+        raise ValueError(
+            f"bboxes and categories must be the same length, "
+            f"got {len(bboxes)} and {len(categories)}. "
+            "If this fires, the dataset schema is not what this script assumes."
+        )
+
+    seen: set[tuple[tuple[float, ...], int]] = set()
+    unique: list[tuple[tuple[float, ...], int]] = []
+
+    for bbox, category in zip(bboxes, categories):
+        key = (tuple(float(v) for v in bbox), int(category))
+        if key not in seen:
+            seen.add(key)
+            unique.append(key)
+
+    return unique
+
+
+def _write_split(
+    dataset, split_name: str, out_dir: Path, limit: int | None
+) -> dict:
+    """Writes one split to disk, returns the counts (these end up in the
+    memo, especially the dedupe ratio - "removed 96% of raw annotations"
+    needs a number next to it or it sounds like something broke)."""
+    image_dir = out_dir / "images" / split_name
+    label_dir = out_dir / "labels" / split_name
+    image_dir.mkdir(parents=True, exist_ok=True)
+    label_dir.mkdir(parents=True, exist_ok=True)
+
+    rows = dataset[split_name]
+    total = len(rows) if limit is None else min(limit, len(rows))
+
+    stats = {
+        "images": 0,
+        "raw_annotations": 0,
+        "after_dedupe": 0,
+        "dropped_invalid": 0,
+        "empty_pages": 0,
+        "class_counts": Counter(),
+        "doc_category_counts": Counter(),
+    }
+
+    # per-image manifest for evaluate.py's per-category mAP breakdown, and
+    # for measuring train/test source-PDF leakage
+    manifest: list[dict] = []
+
+    for index in range(total):
+        row = rows[index]
+        image = row["image"]
+        img_w, img_h = image.size
+
+        stats["raw_annotations"] += len(row["bboxes_block"])
+
+        annotations = dedupe_annotations(row["bboxes_block"], row["categories"])
+        stats["after_dedupe"] += len(annotations)
+
+        lines = []
+        for bbox, category in annotations:
+            if not is_valid_bbox(list(bbox), img_w, img_h):
+                stats["dropped_invalid"] += 1
+                continue
+            xc, yc, w, h = coco_to_yolo(list(bbox), img_w, img_h)
+            lines.append(f"{category} {xc:.6f} {yc:.6f} {w:.6f} {h:.6f}")
+            stats["class_counts"][ID_TO_CLASS.get(category, f"UNKNOWN_{category}")] += 1
+
+        # blank page is legit, but also what a conversion bug looks like
+        if not lines:
+            stats["empty_pages"] += 1
+
+        stem = f"{split_name}_{index:06d}"
+        image.convert("RGB").save(image_dir / f"{stem}.png")
+        (label_dir / f"{stem}.txt").write_text("\n".join(lines), encoding="utf-8")
+
+        doc_category = row.get("doc_category", "unknown")
+        stats["doc_category_counts"][doc_category] += 1
+        stats["images"] += 1
+
+        manifest.append({
+            "stem": stem,
+            "doc_category": doc_category,
+            "source_pdf": row.get("original_filename", "unknown"),
+            "num_regions": len(lines),
+        })
+
+        if stats["images"] % 500 == 0:
+            print(f"  {split_name}: {stats['images']}/{total}", flush=True)
+
+    (out_dir / f"manifest_{split_name}.json").write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+
+    stats["class_counts"] = dict(stats["class_counts"])
+    stats["doc_category_counts"] = dict(stats["doc_category_counts"])
+    return stats
+
+
+def _render_label_check(dataset, out_dir: Path, sample_size: int) -> None:
+    """Draws decoded class labels on a sample of pages so I can eyeball
+    them. My class ordering (0-indexed alphabetical) is inferred, not
+    confirmed - if it's off by one, Table becomes Section-header
+    everywhere and training won't complain about it. No automated test
+    catches that, only looking does."""
+    from PIL import ImageDraw
+
+    from scripts._render_utils import load_label_font
+
+    label_font = load_label_font(28)
+
+    check_dir = out_dir / "label_check"
+    check_dir.mkdir(parents=True, exist_ok=True)
+
+    rows = dataset["train"]
+    random.seed(42)
+    indices = random.sample(range(len(rows)), min(sample_size, len(rows)))
+
+    palette = [
+        "#e6194b", "#3cb44b", "#ffe119", "#4363d8", "#f58231", "#911eb4",
+        "#46f0f0", "#f032e6", "#bcf60c", "#fabebe", "#008080",
+    ]
+
+    for index in indices:
+        row = rows[index]
+        image = row["image"].convert("RGB")
+        draw = ImageDraw.Draw(image)
+
+        for bbox, category in dedupe_annotations(row["bboxes_block"], row["categories"]):
+            x, y, w, h = bbox
+            colour = palette[category % len(palette)]
+            label = ID_TO_CLASS.get(category, "?")
+            draw.rectangle([x, y, x + w, y + h], outline=colour, width=4)
+
+            # solid background behind the label - plain text is invisible
+            # on dark scanned content otherwise
+            text_box = draw.textbbox((x, y), label, font=label_font)
+            draw.rectangle(
+                [text_box[0] - 2, text_box[1] - 2, text_box[2] + 2, text_box[3] + 2],
+                fill=colour,
+            )
+            draw.text((x, y), label, font=label_font, fill="white")
+
+        image.save(check_dir / f"check_{index:06d}.png")
+
+    print(f"\nWrote {len(indices)} annotated pages to {check_dir}")
+    print("LOOK AT THESE before training. If the box labelled 'Table' is not")
+    print("drawn around a table, the class index base is wrong and everything")
+    print("downstream will be quietly meaningless.\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--out", default="data/doclaynet", help="output root")
+    parser.add_argument(
+        "--limit", type=int, default=None,
+        help="cap images per split - for smoke tests only, not for a real run",
+    )
+    parser.add_argument(
+        "--verify", type=int, default=0,
+        help="render this many annotated pages for visual label checking",
+    )
+    args = parser.parse_args()
+
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    from datasets import ClassLabel, Features, Sequence, Value
+    from datasets import load_dataset
+    from datasets.features import Image as HFImage
+
+    # The dataset's own loading script declares these as int64, but the
+    # real coordinates are floats (hit one directly: 139.664355). Newer
+    # pyarrow refuses that lossy cast where older versions silently
+    # floored it. Can't edit someone else's script, so override the
+    # schema on load instead - copied field-for-field, only these two
+    # fixed to float64.
+    doclaynet_features = Features({
+        "id": Value("string"),
+        "texts": Sequence(Value("string")),
+        "bboxes_block": Sequence(Sequence(Value("float64"))),
+        "bboxes_line": Sequence(Sequence(Value("float64"))),
+        "categories": Sequence(ClassLabel(names=CLASS_NAMES)),
+        "image": HFImage(),
+        "page_hash": Value("string"),
+        "original_filename": Value("string"),
+        "page_no": Value("int32"),
+        "num_pages": Value("int32"),
+        "original_width": Value("int32"),
+        "original_height": Value("int32"),
+        "coco_width": Value("int32"),
+        "coco_height": Value("int32"),
+        "collection": Value("string"),
+        "doc_category": Value("string"),
+    })
+
+    print(f"Loading {HF_DATASET} (3.8 GB on first run, cached after)...", flush=True)
+    try:
+        # trust_remote_code=True: this repo ships a loading script rather
+        # than static parquet. Without this it prompts for confirmation,
+        # which hangs forever under Kaggle's non-interactive commit runs.
+        # Checked what the script does first - it's just the author's own
+        # DocLayNet -> HF datasets conversion, nothing else.
+        dataset = load_dataset(HF_DATASET, trust_remote_code=True, features=doclaynet_features)
+    except RuntimeError as error:
+        # datasets>=4.0.0 dropped loading-script support entirely -
+        # requirements.txt pins <4.0.0 for this reason, but if an
+        # environment already has a newer version cached, this is what
+        # they'll hit.
+        if "no longer supported" in str(error):
+            raise RuntimeError(
+                f"{error}\n\n"
+                "This dataset repo uses the old Hugging Face 'loading script' "
+                "format, which datasets>=4.0.0 removed support for entirely. "
+                "Fix: pip install \"datasets<4.0.0\" (already pinned in "
+                "requirements.txt - your environment likely has a newer "
+                "version cached from something else)."
+            ) from error
+        raise
+
+    if args.verify:
+        _render_label_check(dataset, out_dir, args.verify)
+
+    report = {"dataset": HF_DATASET, "splits": {}}
+    for hf_split, dir_name in SPLITS.items():
+        print(f"Converting split '{hf_split}'...", flush=True)
+        report["splits"][dir_name] = _write_split(dataset, hf_split, out_dir, args.limit)
+
+    _write_data_yaml(out_dir)
+
+    report_path = out_dir / "prep_report.json"
+    report_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+    print(f"\nWrote {report_path}")
+    for split, stats in report["splits"].items():
+        raw, kept = stats["raw_annotations"], stats["after_dedupe"]
+        shrink = (1 - kept / raw) * 100 if raw else 0
+        print(
+            f"  {split:11s} {stats['images']:5d} images | "
+            f"{raw:7d} raw -> {kept:6d} annotations ({shrink:.1f}% were repeats) | "
+            f"{stats['dropped_invalid']} invalid dropped"
+        )
+
+
+def _write_data_yaml(out_dir: Path) -> None:
+    """Generates the Ultralytics config instead of hand-writing it, so
+    class names can't drift from app/constants.py."""
+    names = "\n".join(f"  {idx}: {name}" for idx, name in enumerate(CLASS_NAMES))
+    yaml = (
+        "# Generated by scripts/prepare_dataset.py - do not edit by hand.\n"
+        "# Class names come from app/constants.py so the two cannot drift.\n"
+        f"path: {out_dir.resolve().as_posix()}\n"
+        "train: images/train\n"
+        "val: images/validation\n"
+        "test: images/test\n"
+        "\n"
+        "names:\n"
+        f"{names}\n"
+    )
+    (out_dir / "doclaynet.yaml").write_text(yaml, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

scripts/train.py

@@ -0,0 +1,171 @@
+# Fine-tunes RT-DETR on the prepared DocLayNet data. Every hyperparameter
+# is set explicitly (nothing left to Ultralytics defaults) and the run
+# writes a metadata file with GPU, wall-clock time and library versions,
+# since the brief caps Part A at 50% if the run isn't reproducible.
+#
+# Usage:
+#   python scripts/train.py --data data/doclaynet/doclaynet.yaml
+#   python scripts/train.py --data ... --epochs 1 --smoke   # CPU smoke test
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import time
+from pathlib import Path
+
+RANDOM_SEED = 42
+
+
+def _build_train_args(data: str, epochs: int, batch: int, imgsz: int, device: str) -> dict:
+    """All the hyperparameters. The augmentation block is the part worth
+    reading - three of Ultralytics' defaults are actively wrong for
+    documents:
+      - fliplr 0.5 mirrors pages, which don't have a valid mirrored layout
+        (text direction, page numbers in fixed corners)
+      - flipud same problem, more obviously (upside-down page)
+      - mosaic composites 4 images into one, destroying whole-page
+        structure (header at top, footer at bottom) that the model needs
+    Kept small rotation + mild perspective - those model real scan/camera
+    skew and are the only hedge against the hidden eval set containing
+    photographed rather than rendered pages.
+
+    lr0=1e-4 not the usual YOLO 1e-2 - DETR-family transformer components
+    are unstable at high LR, and I'm fine-tuning from COCO weights, not
+    training from scratch."""
+    return {
+        "data": data,
+        "epochs": epochs,
+        "imgsz": imgsz,
+        "batch": batch,
+        "device": device,
+        "seed": RANDOM_SEED,
+        "deterministic": True,
+
+        "amp": True,  # needed to fit RT-DETR-L at batch 8 in 16GB on a T4
+
+        "optimizer": "AdamW",
+        "lr0": 1e-4,
+        "lrf": 0.01,
+        "weight_decay": 1e-4,
+        "warmup_epochs": 3.0,
+        "cos_lr": True,
+
+        "save_period": 1,  # checkpoint every epoch - Kaggle sessions can drop
+        "patience": 10,
+
+        "workers": 2,          # Kaggle's few CPU cores - more workers stall
+        "cache": False,        # 8k pages at 1025px won't fit in RAM
+        "val": True,
+        "plots": True,
+
+        # --- augmentation, see docstring above ---
+        "fliplr": 0.0,
+        "flipud": 0.0,
+        "mosaic": 0.0,
+        "degrees": 3.0,
+        "perspective": 0.0005,
+        "translate": 0.05,
+        "scale": 0.2,
+        "shear": 0.0,
+        "hsv_h": 0.0,          # document colour isn't a useful signal
+        "hsv_s": 0.2,
+        "hsv_v": 0.2,          # scan brightness genuinely varies
+        "erasing": 0.0,        # occluding part of a region changes its class
+    }
+
+
+def _git_commit() -> str:
+    try:
+        return subprocess.check_output(
+            ["git", "rev-parse", "HEAD"], text=True, stderr=subprocess.DEVNULL
+        ).strip()
+    except Exception:
+        return "unknown"
+
+
+def _write_run_metadata(out_dir: Path, train_args: dict, seconds: float) -> None:
+    """Everything needed to reproduce this run. GPU name matters most -
+    "took 3 hours" means nothing without knowing what it ran on, and
+    Kaggle doesn't always give you the accelerator you asked for."""
+    import torch
+    import ultralytics
+
+    gpu_name, gpu_memory_gb = "cpu", None
+    if torch.cuda.is_available():
+        gpu_name = torch.cuda.get_device_name(0)
+        gpu_memory_gb = round(
+            torch.cuda.get_device_properties(0).total_memory / 1024**3, 1
+        )
+
+    metadata = {
+        "git_commit": _git_commit(),
+        "hyperparameters": train_args,
+        "hardware": {
+            "gpu": gpu_name,
+            "gpu_memory_gb": gpu_memory_gb,
+            "torch_version": torch.__version__,
+            "cuda_version": torch.version.cuda,
+        },
+        "ultralytics_version": ultralytics.__version__,
+        "wall_clock_seconds": round(seconds, 1),
+        "wall_clock_human": f"{seconds / 3600:.2f} h",
+    }
+
+    path = out_dir / "run_metadata.json"
+    path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")
+    print(f"\nRun metadata written to {path}")
+    print(f"  GPU:   {gpu_name} ({gpu_memory_gb} GB)")
+    print(f"  Time:  {seconds / 3600:.2f} h")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--data", default="data/doclaynet/doclaynet.yaml")
+    parser.add_argument("--epochs", type=int, default=30)
+    parser.add_argument("--batch", type=int, default=8)
+    parser.add_argument("--imgsz", type=int, default=640)
+    parser.add_argument("--device", default="0")
+    parser.add_argument("--name", default="rtdetr_doclaynet")
+    parser.add_argument(
+        "--smoke", action="store_true",
+        help="tiny CPU run to prove the script works before spending GPU quota",
+    )
+    args = parser.parse_args()
+
+    if args.smoke:
+        args.epochs, args.batch, args.device, args.imgsz = 1, 2, "cpu", 320
+        args.name = "smoke"
+
+    from ultralytics import RTDETR
+    from ultralytics.utils import SETTINGS
+
+    # Ultralytics auto-registers a Ray Tune callback whenever `ray` is
+    # importable, no check for whether Tune is actually running. Kaggle
+    # ships ray pre-installed for other stuff, so this callback silently
+    # activates and crashes end-of-epoch calling a Ray internal API that
+    # doesn't exist in the installed version. Not using Ray Tune anywhere
+    # here, so just turn the integration off before .train() runs.
+    SETTINGS["raytune"] = False
+
+    # Starting from COCO weights, not scratch. None of my 11 classes exist
+    # in COCO so the detection head gets zero class knowledge for free -
+    # the pretrained backbone just gives generic visual features. Training
+    # from random init wouldn't converge in the epoch budget I have.
+    model = RTDETR("rtdetr-l.pt")
+
+    train_args = _build_train_args(args.data, args.epochs, args.batch, args.imgsz, args.device)
+    train_args["name"] = args.name
+
+    print(f"Training RT-DETR-L | {args.epochs} epochs | batch {args.batch} | {args.imgsz}px")
+    started = time.time()
+    results = model.train(**train_args)
+    elapsed = time.time() - started
+
+    out_dir = Path(results.save_dir)
+    _write_run_metadata(out_dir, train_args, elapsed)
+    print(f"\nBest weights: {out_dir / 'weights' / 'best.pt'}")
+
+
+if __name__ == "__main__":
+    main()

streamlit_app.py

@@ -0,0 +1,118 @@
+# Streamlit demo UI for Hugging Face Spaces. Reuses the same Detector and
+# reasoning pipeline as the FastAPI app - no duplicated logic, just a
+# visual layer for showing the thing actually working.
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()  # loads .env locally, no-op on HF Spaces (uses Space secrets instead)
+
+import streamlit as st
+from PIL import Image, ImageDraw
+
+from app.constants import CLASS_NAMES, MODEL_VERSION
+from app.detector import Detector
+from app.reasoning.pipeline import answer_question
+from scripts._render_utils import load_label_font
+
+st.set_page_config(page_title="Document Layout Detection", page_icon="\U0001F4C4", layout="wide")
+
+PALETTE = [
+    "#e6194b", "#3cb44b", "#ffe119", "#4363d8", "#f58231", "#911eb4",
+    "#46f0f0", "#f032e6", "#bcf60c", "#fabebe", "#008080",
+]
+
+
+@st.cache_resource
+def get_detector() -> Detector:
+    # cache_resource so weights load once per container, not per request
+    detector = Detector()
+    try:
+        detector.load()
+    except FileNotFoundError:
+        pass  # surfaced in the UI below instead of crashing the app
+    return detector
+
+
+def draw_detections(image: Image.Image, detections) -> Image.Image:
+    annotated = image.copy()
+    draw = ImageDraw.Draw(annotated)
+    font = load_label_font(18)
+
+    for det in detections:
+        colour = PALETTE[det.class_id % len(PALETTE)]
+        box = det.bbox
+        draw.rectangle([box.x1, box.y1, box.x2, box.y2], outline=colour, width=3)
+        label = f"{det.class_name} {det.confidence:.2f}"
+        text_box = draw.textbbox((box.x1, box.y1), label, font=font)
+        draw.rectangle(
+            [text_box[0] - 2, text_box[1] - 2, text_box[2] + 2, text_box[3] + 2],
+            fill=colour,
+        )
+        draw.text((box.x1, box.y1), label, font=font, fill="white")
+
+    return annotated
+
+
+detector = get_detector()
+
+st.title("Constrained Document Layout Detection")
+st.caption(f"RT-DETR fine-tuned on DocLayNet - {MODEL_VERSION}")
+
+if not detector.is_loaded:
+    st.warning(
+        f"Model weights not found at `{os.environ.get('MODEL_PATH', './weights/best.pt')}`. "
+        "Detection and Q&A won't work until weights are available - see the README "
+        "for the download link, or set the MODEL_PATH secret on this Space."
+    )
+
+with st.sidebar:
+    st.subheader("Classes")
+    st.write(", ".join(CLASS_NAMES))
+    st.subheader("Model")
+    st.write("loaded" if detector.is_loaded else "not loaded")
+    if not os.environ.get("GROQ_API_KEY"):
+        st.info("GROQ_API_KEY not set - the Ask tab needs it for the reasoning layer.")
+
+tab_detect, tab_ask = st.tabs(["Detect", "Ask"])
+
+with tab_detect:
+    st.write("Upload a document page to see the detected layout regions.")
+    uploaded = st.file_uploader("Image", type=["png", "jpg", "jpeg"], key="detect_upload")
+
+    if uploaded and st.button("Run detection", disabled=not detector.is_loaded):
+        image = Image.open(uploaded).convert("RGB")
+        with st.spinner("Running RT-DETR..."):
+            detections, inference_ms = detector.predict(image)
+
+        col1, col2 = st.columns(2)
+        col1.image(image, caption="Original", use_container_width=True)
+        col2.image(draw_detections(image, detections), caption="Detections", use_container_width=True)
+
+        st.caption(f"{len(detections)} detections in {inference_ms:.1f} ms")
+        if detections:
+            st.table([
+                {"class": d.class_name, "confidence": round(d.confidence, 3)}
+                for d in sorted(detections, key=lambda d: -d.confidence)
+            ])
+
+with tab_ask:
+    st.write("Ask a question about the document's layout - not its text content.")
+    uploaded_q = st.file_uploader("Image", type=["png", "jpg", "jpeg"], key="ask_upload")
+    question = st.text_input("Question", placeholder="How many tables are on this page?")
+
+    ask_disabled = not detector.is_loaded or not os.environ.get("GROQ_API_KEY")
+    if uploaded_q and question and st.button("Ask", disabled=ask_disabled):
+        image = Image.open(uploaded_q).convert("RGB")
+        with st.spinner("Thinking..."):
+            response = answer_question(image=image, question=question, detector=detector)
+
+        if response.insufficient_information:
+            st.warning(response.answer)
+        else:
+            st.success(response.answer)
+
+        with st.expander("Reasoning trace"):
+            st.json(response.reasoning_trace)