Merge pull request #5 from maribakulj/claude/repo-audit-deployment-71Dac

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: pytest --tb=short -q
+      - run: pytest --cov=src --cov-report=term-missing --cov-fail-under=90

Dockerfile

@@ -16,6 +16,13 @@ COPY src/ src/
 COPY frontend/ frontend/
 COPY AGENTS.md ./
 
+# HF Spaces requires a non-root user
+RUN useradd -m -u 1000 appuser \
+    && mkdir -p /app/data /data \
+    && chown -R appuser:appuser /app /data
+
+USER appuser
+
 # Default storage root — overridden in Space mode via /data
 ENV STORAGE_ROOT=/app/data
 ENV HOST=0.0.0.0

README.md

@@ -1,3 +1,15 @@
+---
+title: XmLLM
+emoji: "\U0001F4C4"
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+short_description: "Document structure engine: OCR output to ALTO XML & PAGE XML"
+---
+
 # XmLLM
 
 **Canonical-first document structure engine** that converts OCR/VLM provider outputs into validated **ALTO XML** and **PAGE XML**, via an internal canonical representation.

pyproject.toml

@@ -54,7 +54,7 @@ line-length = 100
 src = ["src", "tests"]
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
 
 [tool.mypy]
 python_version = "3.11"

src/app/api/__init__.py

@@ -6,10 +6,14 @@ JobService, scoped to the application lifespan.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from src.app.jobs.service import JobService
 from src.app.persistence.db import Database
 from src.app.persistence.file_store import FileStore
-from src.app.settings import Settings
+
+if TYPE_CHECKING:
+    from src.app.settings import Settings
 
 # Module-level singletons, initialized during lifespan startup.
 _db: Database | None = None

src/app/api/routes_exports.py

@@ -28,7 +28,10 @@ async def get_canonical(job_id: str) -> dict[str, Any]:
     store = get_file_store()
     data = store.load_canonical(job_id)
     if data is None:
-        raise HTTPException(status_code=404, detail=f"Canonical document not found for job '{job_id}'")
+        raise HTTPException(
+            status_code=404,
+            detail=f"Canonical document not found for job '{job_id}'",
+        )
     return data
 
 

src/app/api/routes_jobs.py

@@ -29,12 +29,15 @@ async def create_job(
     """
     svc = get_job_service()
 
-    # Read raw payload
-    content = await raw_payload_file.read()
+    # Read raw payload (limit to 50 MB to prevent DoS)
+    max_size = 52_428_800
+    content = await raw_payload_file.read(max_size + 1)
+    if len(content) > max_size:
+        raise HTTPException(status_code=413, detail="Payload too large (max 50 MB)")
     try:
         payload_data = json.loads(content)
     except json.JSONDecodeError as e:
-        raise HTTPException(status_code=422, detail=f"Invalid JSON payload: {e}")
+        raise HTTPException(status_code=422, detail=f"Invalid JSON payload: {e}") from None
 
     raw = RawProviderPayload(
         provider_id=provider_id,

src/app/domain/errors/__init__.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-from enum import Enum
+from enum import StrEnum
 
 from pydantic import BaseModel, ConfigDict, Field
 
 
-class Severity(str, Enum):
+class Severity(StrEnum):
     """Severity level for validation entries."""
 
     ERROR = "error"
@@ -22,7 +22,10 @@ class ValidationEntry(BaseModel):
 
     validator: str = Field(min_length=1)
     severity: Severity
-    path: str = Field(min_length=1, description="Path in the document, e.g. pages[0].text_regions[1].lines[3]")
+    path: str = Field(
+        min_length=1,
+        description="Path in the document, e.g. pages[0].text_regions[1].lines[3]",
+    )
     message: str = Field(min_length=1)
     code: str | None = None
 

src/app/domain/models/__init__.py

@@ -17,8 +17,8 @@ from src.app.domain.models.canonical_document import (
     Word,
 )
 from src.app.domain.models.geometry import (
-    BBox,
     Baseline,
+    BBox,
     ClipRect,
     Geometry,
     GeometryContext,

src/app/domain/models/canonical_document.py

@@ -11,10 +11,10 @@ Every node carries geometry + provenance.  No exceptions.
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from src.app.domain.models.geometry import Geometry
 from src.app.domain.models.provenance import Provenance
@@ -33,7 +33,6 @@ from src.app.domain.models.status import (
     Unit,
 )
 
-
 # -- Source ------------------------------------------------------------------
 
 
@@ -238,7 +237,7 @@ class CanonicalDocument(BaseModel):
     schema_version: str = Field(default="1.0.0", pattern=r"^\d+\.\d+\.\d+$")
     document_id: str = Field(min_length=1)
     source: Source
-    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
     pages: list[Page] = Field(min_length=1)
 

src/app/domain/models/geometry.py

@@ -15,7 +15,6 @@ from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from src.app.domain.models.status import CoordinateOrigin, GeometryStatus, Unit
 
-
 # -- Primitives --------------------------------------------------------------
 
 

src/app/domain/models/raw_payload.py

@@ -7,7 +7,7 @@ It is never used for export or rendering.
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -26,7 +26,7 @@ class RawProviderPayload(BaseModel):
     payload: dict[str, Any] | list[Any]
     """The raw JSON-serialisable output from the provider."""
 
-    received_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    received_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
 
     image_width: int | None = Field(default=None, gt=0)
     image_height: int | None = Field(default=None, gt=0)

src/app/domain/models/status.py

@@ -6,13 +6,12 @@ and viewer projection models. They carry no logic — only values.
 
 from __future__ import annotations
 
-from enum import Enum
-
+from enum import StrEnum
 
 # -- Geometry ----------------------------------------------------------------
 
 
-class GeometryStatus(str, Enum):
+class GeometryStatus(StrEnum):
     """How a piece of geometry was obtained."""
 
     EXACT = "exact"
@@ -21,13 +20,13 @@ class GeometryStatus(str, Enum):
     UNKNOWN = "unknown"
 
 
-class CoordinateOrigin(str, Enum):
+class CoordinateOrigin(StrEnum):
     """Origin of the coordinate system.  Always top_left in canonical model."""
 
     TOP_LEFT = "top_left"
 
 
-class Unit(str, Enum):
+class Unit(StrEnum):
     """Measurement unit.  Always px in canonical model."""
 
     PX = "px"
@@ -36,7 +35,7 @@ class Unit(str, Enum):
 # -- Provenance --------------------------------------------------------------
 
 
-class EvidenceType(str, Enum):
+class EvidenceType(StrEnum):
     """How a piece of data was produced."""
 
     PROVIDER_NATIVE = "provider_native"
@@ -48,7 +47,7 @@ class EvidenceType(str, Enum):
 # -- Document structure ------------------------------------------------------
 
 
-class BlockRole(str, Enum):
+class BlockRole(StrEnum):
     """Semantic role of a text block within the page."""
 
     BODY = "body"
@@ -62,7 +61,7 @@ class BlockRole(str, Enum):
     OTHER = "other"
 
 
-class NonTextKind(str, Enum):
+class NonTextKind(StrEnum):
     """Type of non-textual region."""
 
     ILLUSTRATION = "illustration"
@@ -76,7 +75,7 @@ class NonTextKind(str, Enum):
 # -- Source ------------------------------------------------------------------
 
 
-class InputType(str, Enum):
+class InputType(StrEnum):
     """Type of the original input document."""
 
     IMAGE = "image"
@@ -92,7 +91,7 @@ class InputType(str, Enum):
 # -- Readiness ---------------------------------------------------------------
 
 
-class ReadinessLevel(str, Enum):
+class ReadinessLevel(StrEnum):
     """How ready a document / page / element is for export."""
 
     FULL = "full"
@@ -101,7 +100,7 @@ class ReadinessLevel(str, Enum):
     NONE = "none"
 
 
-class MissingCapability(str, Enum):
+class MissingCapability(StrEnum):
     """Specific capabilities that may be missing for export readiness."""
 
     PAGE_DIMENSIONS = "page_dimensions"
@@ -117,7 +116,7 @@ class MissingCapability(str, Enum):
 # -- Overlay (viewer) --------------------------------------------------------
 
 
-class OverlayLevel(str, Enum):
+class OverlayLevel(StrEnum):
     """Granularity level for viewer overlays."""
 
     BLOCK = "block"

src/app/enrichers/__init__.py

@@ -13,10 +13,13 @@ Every enricher MUST:
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
 
-from src.app.domain.models import CanonicalDocument
 from src.app.policies.document_policy import DocumentPolicy
 
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+
 
 class BaseEnricher(ABC):
     """Abstract base for enrichers."""

src/app/enrichers/bbox_repair_light.py

@@ -8,12 +8,16 @@ Light repair only:
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument
+from typing import TYPE_CHECKING
+
 from src.app.domain.models.status import GeometryStatus
 from src.app.enrichers import BaseEnricher
 from src.app.geometry.bbox import contains
 from src.app.geometry.transforms import clip_bbox_to_page
-from src.app.policies.document_policy import DocumentPolicy
+
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+    from src.app.policies.document_policy import DocumentPolicy
 
 
 class BboxRepairLightEnricher(BaseEnricher):

src/app/enrichers/hyphenation_basic.py

@@ -6,9 +6,13 @@ a lowercase word, marks both as hyphenated with the combined full_form.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from src.app.domain.models import CanonicalDocument, Hyphenation, TextLine
 from src.app.enrichers import BaseEnricher
-from src.app.policies.document_policy import DocumentPolicy
+
+if TYPE_CHECKING:
+    from src.app.policies.document_policy import DocumentPolicy
 
 
 class HyphenationBasicEnricher(BaseEnricher):
@@ -52,7 +56,7 @@ class HyphenationBasicEnricher(BaseEnricher):
                 continue
 
             last_word = line_a.words[-1]
-            first_word = line_b.words[-0]
+            first_word = line_b.words[0]
 
             # Skip if already hyphenated
             if last_word.hyphenation is not None:

src/app/enrichers/lang_propagation.py

@@ -6,9 +6,13 @@ propagated downward. The word's provenance is not changed — only lang is set.
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument
+from typing import TYPE_CHECKING
+
 from src.app.enrichers import BaseEnricher
-from src.app.policies.document_policy import DocumentPolicy
+
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+    from src.app.policies.document_policy import DocumentPolicy
 
 
 class LangPropagationEnricher(BaseEnricher):

src/app/enrichers/polygon_to_bbox.py

@@ -6,11 +6,15 @@ axis-aligned bounding box and marks the geometry as 'inferred'.
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument, Geometry, Provenance
-from src.app.domain.models.status import EvidenceType, GeometryStatus
+from typing import TYPE_CHECKING
+
+from src.app.domain.models.status import GeometryStatus
 from src.app.enrichers import BaseEnricher
 from src.app.geometry.polygon import polygon_to_bbox as _poly_to_bbox
-from src.app.policies.document_policy import DocumentPolicy
+
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+    from src.app.policies.document_policy import DocumentPolicy
 
 
 class PolygonToBboxEnricher(BaseEnricher):

src/app/enrichers/reading_order_simple.py

@@ -6,10 +6,14 @@ left-to-right using the center of each region's bbox.
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument
+from typing import TYPE_CHECKING
+
 from src.app.enrichers import BaseEnricher
 from src.app.geometry.bbox import center
-from src.app.policies.document_policy import DocumentPolicy
+
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+    from src.app.policies.document_policy import DocumentPolicy
 
 
 class ReadingOrderSimpleEnricher(BaseEnricher):

src/app/enrichers/text_consistency.py

@@ -7,9 +7,13 @@ This enricher does NOT modify text — it only adds warnings.
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument
+from typing import TYPE_CHECKING
+
 from src.app.enrichers import BaseEnricher
-from src.app.policies.document_policy import DocumentPolicy
+
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+    from src.app.policies.document_policy import DocumentPolicy
 
 
 class TextConsistencyEnricher(BaseEnricher):

src/app/geometry/baseline.py

@@ -5,7 +5,6 @@ A baseline is defined by a sequence of points, typically from left to right.
 
 from __future__ import annotations
 
-
 BaselinePoints = list[tuple[float, float]]
 
 

src/app/geometry/bbox.py

@@ -6,7 +6,6 @@ x = left edge, y = top edge, width > 0, height > 0.
 
 from __future__ import annotations
 
-
 # Type alias for the canonical bbox tuple
 BBoxTuple = tuple[float, float, float, float]
 

src/app/geometry/normalization.py

@@ -7,9 +7,13 @@ always (x, y, width, height) with origin at top_left, unit px.
 
 from __future__ import annotations
 
-from src.app.geometry.bbox import BBoxTuple
+from typing import TYPE_CHECKING
+
 from src.app.geometry.polygon import PolygonPoints, polygon_to_bbox
 
+if TYPE_CHECKING:
+    from src.app.geometry.bbox import BBoxTuple
+
 
 def xyxy_to_xywh(xyxy: tuple[float, float, float, float]) -> BBoxTuple:
     """Convert (x1, y1, x2, y2) to canonical (x, y, width, height).

src/app/geometry/polygon.py

@@ -5,8 +5,10 @@ Polygons are represented as list[tuple[float, float]] — ordered (x, y) vertice
 
 from __future__ import annotations
 
-from src.app.geometry.bbox import BBoxTuple
+from typing import TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from src.app.geometry.bbox import BBoxTuple
 
 PolygonPoints = list[tuple[float, float]]
 

src/app/geometry/quantization.py

@@ -8,12 +8,14 @@ rounding and tolerance for containment checks.
 from __future__ import annotations
 
 import math
-from enum import Enum
+from enum import StrEnum
+from typing import TYPE_CHECKING
 
-from src.app.geometry.bbox import BBoxTuple
+if TYPE_CHECKING:
+    from src.app.geometry.bbox import BBoxTuple
 
 
-class RoundingStrategy(str, Enum):
+class RoundingStrategy(StrEnum):
     """How to round float coordinates to integers."""
 
     ROUND = "round"

src/app/geometry/transforms.py

@@ -6,10 +6,11 @@ is allowed in serializers (see AGENTS.md rule §5).
 
 from __future__ import annotations
 
-import math
+from typing import TYPE_CHECKING
 
-from src.app.geometry.bbox import BBoxTuple
-from src.app.geometry.polygon import PolygonPoints
+if TYPE_CHECKING:
+    from src.app.geometry.bbox import BBoxTuple
+    from src.app.geometry.polygon import PolygonPoints
 
 
 def rescale_bbox(bbox: BBoxTuple, factor: float) -> BBoxTuple:

src/app/jobs/events.py

@@ -4,14 +4,17 @@ from __future__ import annotations
 
 import time
 from contextlib import contextmanager
-from datetime import datetime, timezone
-from enum import Enum
-from typing import Generator
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import TYPE_CHECKING
 
 from pydantic import BaseModel, Field
 
+if TYPE_CHECKING:
+    from collections.abc import Generator
 
-class JobStep(str, Enum):
+
+class JobStep(StrEnum):
     """Named steps in the processing pipeline."""
 
     RECEIVE_FILE = "receive_file"
@@ -34,7 +37,7 @@ class JobEvent(BaseModel):
 
     step: JobStep
     status: str = "started"  # started, completed, failed, skipped
-    started_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     completed_at: datetime | None = None
     duration_ms: float | None = None
     message: str | None = None
@@ -67,7 +70,7 @@ class EventLog:
             idx = len(self._events) - 1
             self._events[idx] = event.model_copy(update={
                 "status": "completed",
-                "completed_at": datetime.now(timezone.utc),
+                "completed_at": datetime.now(UTC),
                 "duration_ms": elapsed,
             })
         except Exception as exc:
@@ -75,7 +78,7 @@ class EventLog:
             idx = len(self._events) - 1
             self._events[idx] = event.model_copy(update={
                 "status": "failed",
-                "completed_at": datetime.now(timezone.utc),
+                "completed_at": datetime.now(UTC),
                 "duration_ms": elapsed,
                 "error": str(exc),
             })
@@ -86,7 +89,7 @@ class EventLog:
         self._events.append(JobEvent(
             step=step,
             status="skipped",
-            completed_at=datetime.now(timezone.utc),
+            completed_at=datetime.now(UTC),
             message=reason,
         ))
 

src/app/jobs/models.py

@@ -2,14 +2,14 @@
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
-from enum import Enum
+from datetime import UTC, datetime
+from enum import StrEnum
 from typing import Any
 
 from pydantic import BaseModel, Field
 
 
-class JobStatus(str, Enum):
+class JobStatus(StrEnum):
     """State machine for job lifecycle."""
 
     QUEUED = "queued"
@@ -40,7 +40,7 @@ class Job(BaseModel):
     has_viewer: bool = False
 
     # Timing
-    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
     started_at: datetime | None = None
     completed_at: datetime | None = None
 

src/app/jobs/service.py

@@ -19,10 +19,9 @@ Pipeline steps (§23.1):
 from __future__ import annotations
 
 import uuid
-from datetime import datetime, timezone
-from pathlib import Path
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
 
-from src.app.domain.models import CanonicalDocument, RawProviderPayload
 from src.app.domain.models.geometry import GeometryContext
 from src.app.enrichers import EnricherPipeline
 from src.app.enrichers.bbox_repair_light import BboxRepairLightEnricher
@@ -34,8 +33,6 @@ from src.app.enrichers.text_consistency import TextConsistencyEnricher
 from src.app.jobs.events import EventLog, JobStep
 from src.app.jobs.models import Job, JobStatus
 from src.app.normalization.pipeline import normalize
-from src.app.persistence.db import Database
-from src.app.persistence.file_store import FileStore
 from src.app.policies.document_policy import DocumentPolicy
 from src.app.policies.export_policy import check_alto_export, check_page_export
 from src.app.serializers.alto_xml import serialize_alto
@@ -44,6 +41,13 @@ from src.app.validators.export_eligibility_validator import compute_export_eligi
 from src.app.validators.structural_validator import validate_structure
 from src.app.viewer.projection_builder import build_projection
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from src.app.domain.models import CanonicalDocument, RawProviderPayload
+    from src.app.persistence.db import Database
+    from src.app.persistence.file_store import FileStore
+
 
 def _default_enricher_pipeline() -> EnricherPipeline:
     return EnricherPipeline([
@@ -103,7 +107,7 @@ class JobService:
         events = EventLog()
         job = job.model_copy(update={
             "status": JobStatus.RUNNING,
-            "started_at": datetime.now(timezone.utc),
+            "started_at": datetime.now(UTC),
             "image_width": image_width,
             "image_height": image_height,
         })
@@ -193,24 +197,23 @@ class JobService:
                 self._store.save_events(job.job_id, events.to_dicts())
 
             # Determine final status
-            if job.has_alto or job.has_page_xml:
-                if job.has_alto and job.has_page_xml:
-                    final_status = JobStatus.SUCCEEDED
-                else:
-                    final_status = JobStatus.PARTIAL_SUCCESS
-            else:
+            if job.has_alto and job.has_page_xml:
+                final_status = JobStatus.SUCCEEDED
+            elif job.has_alto or job.has_page_xml:
                 final_status = JobStatus.PARTIAL_SUCCESS
+            else:
+                final_status = JobStatus.FAILED
 
             job = job.model_copy(update={
                 "status": final_status,
-                "completed_at": datetime.now(timezone.utc),
+                "completed_at": datetime.now(UTC),
                 "warnings": warnings,
             })
 
         except Exception as exc:
             job = job.model_copy(update={
                 "status": JobStatus.FAILED,
-                "completed_at": datetime.now(timezone.utc),
+                "completed_at": datetime.now(UTC),
                 "error": str(exc),
                 "warnings": warnings,
             })

src/app/main.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import AsyncIterator
+from typing import TYPE_CHECKING
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -22,6 +22,9 @@ from src.app.api.routes_providers import router as providers_router
 from src.app.api.routes_viewer import router as viewer_router
 from src.app.settings import get_settings
 
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncIterator[None]:
@@ -43,7 +46,7 @@ app = FastAPI(
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"],
-    allow_credentials=True,
+    allow_credentials=False,
     allow_methods=["*"],
     allow_headers=["*"],
 )

src/app/normalization/pipeline.py

@@ -8,10 +8,14 @@ The pipeline:
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument, RawProviderPayload
-from src.app.domain.models.geometry import GeometryContext
+from typing import TYPE_CHECKING
+
 from src.app.providers.registry import get_adapter
 
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument, RawProviderPayload
+    from src.app.domain.models.geometry import GeometryContext
+
 
 def normalize(
     raw: RawProviderPayload,

src/app/persistence/db.py

@@ -8,11 +8,14 @@ from __future__ import annotations
 
 import json
 import sqlite3
-from pathlib import Path
-from typing import Any
+from datetime import UTC
+from typing import TYPE_CHECKING, Any
 
 from src.app.jobs.models import Job, JobStatus
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS jobs (
     job_id TEXT PRIMARY KEY,
@@ -146,12 +149,16 @@ class Database:
     # -- Providers ------------------------------------------------------------
 
     def save_provider_record(self, provider_id: str, data: dict) -> None:
-        from datetime import datetime, timezone
+        from datetime import datetime
 
-        now = datetime.now(timezone.utc).isoformat()
+        now = datetime.now(UTC).isoformat()
         self.conn.execute(
-            """INSERT OR REPLACE INTO providers (provider_id, data, created_at, updated_at)
-               VALUES (?, ?, COALESCE((SELECT created_at FROM providers WHERE provider_id = ?), ?), ?)""",
+            """INSERT OR REPLACE INTO providers
+               (provider_id, data, created_at, updated_at)
+               VALUES (?, ?, COALESCE(
+                   (SELECT created_at FROM providers WHERE provider_id = ?),
+                   ?
+               ), ?)""",
             (provider_id, json.dumps(data, default=str), provider_id, now, now),
         )
         self.conn.commit()

src/app/persistence/file_store.py

@@ -36,8 +36,15 @@ class FileStore:
 
     # -- Job directory --------------------------------------------------------
 
+    @staticmethod
+    def _sanitize_id(value: str) -> str:
+        """Reject path-traversal attempts in identifiers."""
+        if not value or "/" in value or "\\" in value or ".." in value:
+            raise ValueError(f"Invalid identifier (path traversal rejected): {value!r}")
+        return value
+
     def job_dir(self, job_id: str) -> Path:
-        d = self._jobs_dir / job_id
+        d = self._jobs_dir / self._sanitize_id(job_id)
         d.mkdir(parents=True, exist_ok=True)
         return d
 
@@ -52,7 +59,8 @@ class FileStore:
     def save_json(self, job_id: str, filename: str, data: Any) -> Path:
         """Save a JSON-serializable object."""
         dest = self.job_dir(job_id) / filename
-        dest.write_text(json.dumps(data, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
+        content = json.dumps(data, ensure_ascii=False, indent=2, default=str)
+        dest.write_text(content, encoding="utf-8")
         return dest
 
     def save_bytes(self, job_id: str, filename: str, data: bytes) -> Path:
@@ -83,14 +91,14 @@ class FileStore:
 
     def load_json(self, job_id: str, filename: str) -> Any:
         """Load a JSON file from the job directory. Returns None if not found."""
-        path = self._jobs_dir / job_id / filename
+        path = self._jobs_dir / self._sanitize_id(job_id) / filename
         if not path.exists():
             return None
         return json.loads(path.read_text(encoding="utf-8"))
 
     def load_bytes(self, job_id: str, filename: str) -> bytes | None:
         """Load raw bytes. Returns None if not found."""
-        path = self._jobs_dir / job_id / filename
+        path = self._jobs_dir / self._sanitize_id(job_id) / filename
         if not path.exists():
             return None
         return path.read_bytes()
@@ -121,19 +129,21 @@ class FileStore:
         if not d.exists():
             return None
         for f in d.iterdir():
-            if f.stem == "input" and f.suffix in (".png", ".jpg", ".jpeg", ".tif", ".tiff", ".webp"):
+            valid = (".png", ".jpg", ".jpeg", ".tif", ".tiff", ".webp")
+            if f.stem == "input" and f.suffix in valid:
                 return f
         return None
 
     # -- Provider profiles ----------------------------------------------------
 
     def save_provider(self, provider_id: str, data: dict) -> Path:
-        dest = self._providers_dir / f"{provider_id}.json"
-        dest.write_text(json.dumps(data, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
+        dest = self._providers_dir / f"{self._sanitize_id(provider_id)}.json"
+        content = json.dumps(data, ensure_ascii=False, indent=2, default=str)
+        dest.write_text(content, encoding="utf-8")
         return dest
 
     def load_provider(self, provider_id: str) -> dict | None:
-        path = self._providers_dir / f"{provider_id}.json"
+        path = self._providers_dir / f"{self._sanitize_id(provider_id)}.json"
         if not path.exists():
             return None
         return json.loads(path.read_text(encoding="utf-8"))
@@ -144,7 +154,7 @@ class FileStore:
         return [f.stem for f in self._providers_dir.glob("*.json")]
 
     def delete_provider(self, provider_id: str) -> bool:
-        path = self._providers_dir / f"{provider_id}.json"
+        path = self._providers_dir / f"{self._sanitize_id(provider_id)}.json"
         if path.exists():
             path.unlink()
             return True

src/app/policies/document_policy.py

@@ -7,12 +7,12 @@ that controls what the system may or may not do.
 
 from __future__ import annotations
 
-from enum import Enum
+from enum import StrEnum
 
 from pydantic import BaseModel, ConfigDict
 
 
-class PolicyMode(str, Enum):
+class PolicyMode(StrEnum):
     """Named policy presets."""
 
     STRICT = "strict"

src/app/policies/export_policy.py

@@ -7,11 +7,14 @@ decision for each export format.
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
-from src.app.domain.models.readiness import ExportEligibility
 from src.app.domain.models.status import ReadinessLevel
 from src.app.policies.document_policy import DocumentPolicy
 
+if TYPE_CHECKING:
+    from src.app.domain.models.readiness import ExportEligibility
+
 
 @dataclass(frozen=True)
 class ExportDecision:
@@ -36,7 +39,10 @@ def check_alto_export(
         return ExportDecision(
             allowed=False,
             level=level,
-            reason="ALTO export not possible: missing required data (word text/geometry or line geometry)",
+            reason=(
+                "ALTO export not possible: missing required data"
+                " (word text/geometry or line geometry)"
+            ),
         )
 
     if level == ReadinessLevel.PARTIAL and not policy.allow_partial_alto:

src/app/providers/adapters/base.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
 
-from src.app.domain.models import CanonicalDocument, RawProviderPayload
-from src.app.domain.models.geometry import GeometryContext
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument, RawProviderPayload
+    from src.app.domain.models.geometry import GeometryContext
 
 
 class BaseAdapter(ABC):

src/app/providers/adapters/line_box_json.py

@@ -17,19 +17,23 @@ since the provider doesn't segment words. The block is inferred.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from src.app.domain.models import (
     CanonicalDocument,
     Geometry,
     Provenance,
     RawProviderPayload,
 )
-from src.app.domain.models.geometry import GeometryContext
 from src.app.domain.models.status import EvidenceType, GeometryStatus, InputType
 from src.app.geometry.bbox import union_all
 from src.app.geometry.normalization import xyxy_to_xywh
 from src.app.normalization.canonical_builder import CanonicalBuilder
 from src.app.providers.adapters.base import BaseAdapter
 
+if TYPE_CHECKING:
+    from src.app.domain.models.geometry import GeometryContext
+
 
 class LineBoxJsonAdapter(BaseAdapter):
     """Adapter for the line_box_json family."""

src/app/providers/adapters/text_only.py

@@ -19,17 +19,21 @@ will show text without positioned overlays.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from src.app.domain.models import (
     CanonicalDocument,
     Geometry,
     Provenance,
     RawProviderPayload,
 )
-from src.app.domain.models.geometry import GeometryContext
 from src.app.domain.models.status import EvidenceType, GeometryStatus, InputType
 from src.app.normalization.canonical_builder import CanonicalBuilder
 from src.app.providers.adapters.base import BaseAdapter
 
+if TYPE_CHECKING:
+    from src.app.domain.models.geometry import GeometryContext
+
 
 class TextOnlyAdapter(BaseAdapter):
     """Adapter for the text_only family (mLLM without geometry)."""
@@ -76,7 +80,11 @@ class TextOnlyAdapter(BaseAdapter):
         # Extract text blocks
         blocks = payload.get("blocks")
         if blocks and isinstance(blocks, list):
-            texts = [str(b.get("text", "")) for b in blocks if isinstance(b, dict) and b.get("text")]
+            texts = [
+                str(b.get("text", ""))
+                for b in blocks
+                if isinstance(b, dict) and b.get("text")
+            ]
         else:
             # Single text blob — split into paragraphs
             full_text = str(payload.get("text", ""))
@@ -102,7 +110,7 @@ class TextOnlyAdapter(BaseAdapter):
             )
 
             # Split block into lines
-            lines = [l.strip() for l in block_text.split("\n") if l.strip()]
+            lines = [ln.strip() for ln in block_text.split("\n") if ln.strip()]
             if not lines:
                 lines = [block_text]
 

src/app/providers/adapters/word_box_json.py

@@ -13,13 +13,14 @@ within a single inferred text block.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from src.app.domain.models import (
     CanonicalDocument,
     Geometry,
     Provenance,
     RawProviderPayload,
 )
-from src.app.domain.models.geometry import GeometryContext
 from src.app.domain.models.status import (
     EvidenceType,
     GeometryStatus,
@@ -30,6 +31,9 @@ from src.app.geometry.normalization import four_point_to_polygon, four_point_to_
 from src.app.normalization.canonical_builder import CanonicalBuilder
 from src.app.providers.adapters.base import BaseAdapter
 
+if TYPE_CHECKING:
+    from src.app.domain.models.geometry import GeometryContext
+
 
 class WordBoxJsonAdapter(BaseAdapter):
     """Adapter for the word_box_json family (PaddleOCR, etc.)."""
@@ -163,8 +167,9 @@ class WordBoxJsonAdapter(BaseAdapter):
         points = item[0]
         text_conf = item[1]
         if not isinstance(points, list) or len(points) != 4:
+            got = len(points) if isinstance(points, list) else type(points).__name__
             raise ValueError(
-                f"Item {idx}: expected 4 polygon points, got {len(points) if isinstance(points, list) else type(points).__name__}"
+                f"Item {idx}: expected 4 polygon points, got {got}"
             )
         return points, text_conf
 

src/app/providers/profiles.py

@@ -2,28 +2,28 @@
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
-from enum import Enum
+from datetime import UTC, datetime
+from enum import StrEnum
 
 from pydantic import BaseModel, ConfigDict, Field
 
 from src.app.providers.capabilities import CapabilityMatrix
 
 
-class RuntimeType(str, Enum):
+class RuntimeType(StrEnum):
     LOCAL = "local"
     HUB = "hub"
     API = "api"
 
 
-class ProviderFamily(str, Enum):
+class ProviderFamily(StrEnum):
     WORD_BOX_JSON = "word_box_json"
     LINE_BOX_JSON = "line_box_json"
     REGION_LINE_WORD_POLYGON = "region_line_word_polygon"
     TEXT_ONLY = "text_only"
 
 
-class AuthMode(str, Enum):
+class AuthMode(StrEnum):
     NONE = "none"
     API_KEY = "api_key"
     BEARER = "bearer"
@@ -51,5 +51,5 @@ class ProviderProfile(BaseModel):
     prompt_template: str | None = None
 
     last_test_status: str | None = None
-    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
-    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

src/app/providers/registry.py

@@ -2,16 +2,20 @@
 
 from __future__ import annotations
 
-from src.app.providers.adapters.base import BaseAdapter
+from typing import TYPE_CHECKING
+
 from src.app.providers.adapters.line_box_json import LineBoxJsonAdapter
 from src.app.providers.adapters.text_only import TextOnlyAdapter
 from src.app.providers.adapters.word_box_json import WordBoxJsonAdapter
 from src.app.providers.profiles import ProviderFamily, RuntimeType
 from src.app.providers.runtimes.api_runtime import ApiRuntime
-from src.app.providers.runtimes.base import BaseRuntime
 from src.app.providers.runtimes.hub_runtime import HubRuntime
 from src.app.providers.runtimes.local_runtime import LocalRuntime
 
+if TYPE_CHECKING:
+    from src.app.providers.adapters.base import BaseAdapter
+    from src.app.providers.runtimes.base import BaseRuntime
+
 # -- Adapter registry ---------------------------------------------------------
 
 _ADAPTER_REGISTRY: dict[str, type[BaseAdapter]] = {

src/app/providers/resolver.py

@@ -2,16 +2,25 @@
 
 from __future__ import annotations
 
-from src.app.providers.adapters.base import BaseAdapter
-from src.app.providers.profiles import ProviderProfile
+from typing import TYPE_CHECKING
+
 from src.app.providers.registry import get_adapter, get_runtime
-from src.app.providers.runtimes.base import BaseRuntime
+
+if TYPE_CHECKING:
+    from src.app.providers.adapters.base import BaseAdapter
+    from src.app.providers.profiles import ProviderProfile
+    from src.app.providers.runtimes.base import BaseRuntime
 
 
 class ResolvedProvider:
     """A fully resolved provider: runtime + adapter, ready to execute."""
 
-    def __init__(self, profile: ProviderProfile, runtime: BaseRuntime, adapter: BaseAdapter) -> None:
+    def __init__(
+        self,
+        profile: ProviderProfile,
+        runtime: BaseRuntime,
+        adapter: BaseAdapter,
+    ) -> None:
         self.profile = profile
         self.runtime = runtime
         self.adapter = adapter

src/app/providers/runtimes/api_runtime.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from src.app.domain.models import RawProviderPayload
 from src.app.providers.runtimes.base import BaseRuntime
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from src.app.domain.models import RawProviderPayload
+
 
 class ApiRuntime(BaseRuntime):
     """Runtime that calls an external API endpoint.

src/app/providers/runtimes/base.py

@@ -3,10 +3,12 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from src.app.domain.models import RawProviderPayload
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from src.app.domain.models import RawProviderPayload
 
 
 class BaseRuntime(ABC):

src/app/providers/runtimes/hub_runtime.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from src.app.domain.models import RawProviderPayload
 from src.app.providers.runtimes.base import BaseRuntime
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from src.app.domain.models import RawProviderPayload
+
 
 class HubRuntime(BaseRuntime):
     """Runtime for models loaded from the Hugging Face Hub.

src/app/providers/runtimes/local_runtime.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from src.app.domain.models import RawProviderPayload
 from src.app.providers.runtimes.base import BaseRuntime
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from src.app.domain.models import RawProviderPayload
+
 
 class LocalRuntime(BaseRuntime):
     """Runtime for locally installed models.

src/app/serializers/alto_xml.py

@@ -29,11 +29,15 @@ Coordinate mapping:
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from lxml import etree
 
-from src.app.domain.models import CanonicalDocument, Page, TextLine, TextRegion, Word
 from src.app.geometry.quantization import RoundingStrategy, quantize_bbox
 
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument, Page, TextLine, TextRegion, Word
+
 ALTO_NS = "http://www.loc.gov/standards/alto/ns-v4#"
 XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
 SCHEMA_LOCATION = (

src/app/serializers/page_xml.py

@@ -26,21 +26,24 @@ Namespace: http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15
 
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
 
 from lxml import etree
 
-from src.app.domain.models import (
-    CanonicalDocument,
-    Page,
-    TextLine,
-    TextRegion,
-    Word,
-)
 from src.app.domain.models.status import BlockRole
 from src.app.geometry.polygon import bbox_to_polygon
 from src.app.geometry.quantization import RoundingStrategy, quantize_value
 
+if TYPE_CHECKING:
+    from src.app.domain.models import (
+        CanonicalDocument,
+        Page,
+        TextLine,
+        TextRegion,
+        Word,
+    )
+
 PAGE_NS = "http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15"
 XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
 SCHEMA_LOCATION = (
@@ -119,9 +122,9 @@ def _build_page_tree(
     creator = etree.SubElement(metadata, f"{{{PAGE_NS}}}Creator")
     creator.text = "XmLLM"
     created = etree.SubElement(metadata, f"{{{PAGE_NS}}}Created")
-    created.text = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+    created.text = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
     last_change = etree.SubElement(metadata, f"{{{PAGE_NS}}}LastChange")
-    last_change.text = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+    last_change.text = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
 
     # One <Page> per canonical page (PAGE XML is per-page, but we handle multi-page)
     for page in doc.pages:
@@ -226,10 +229,7 @@ def _add_coords(
     """
     coords = etree.SubElement(parent, f"{{{PAGE_NS}}}Coords")
 
-    if polygon and len(polygon) >= 3:
-        points = polygon
-    else:
-        points = bbox_to_polygon(bbox)
+    points = polygon if polygon and len(polygon) >= 3 else bbox_to_polygon(bbox)
 
     points_str = " ".join(
         f"{quantize_value(x, rounding)},{quantize_value(y, rounding)}"

src/app/settings.py

@@ -7,14 +7,15 @@ via the SPACE_ID environment variable.
 from __future__ import annotations
 
 import os
-from enum import Enum
+from enum import StrEnum
+from functools import lru_cache
 from pathlib import Path
 
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
-class AppMode(str, Enum):
+class AppMode(StrEnum):
     LOCAL = "local"
     SPACE = "space"
 
@@ -113,6 +114,7 @@ class Settings(BaseSettings):
                 os.environ.setdefault("HF_HOME", str(self.hf_home))
 
 
+@lru_cache(maxsize=1)
 def get_settings() -> Settings:
-    """Factory for dependency injection (FastAPI Depends)."""
+    """Factory for dependency injection (FastAPI Depends). Cached singleton."""
     return Settings()

src/app/validators/export_eligibility_validator.py

@@ -6,7 +6,8 @@ an ExportEligibility decision for the whole document.
 
 from __future__ import annotations
 
-from src.app.domain.models import CanonicalDocument
+from typing import TYPE_CHECKING
+
 from src.app.domain.models.readiness import ExportEligibility
 from src.app.domain.models.status import ReadinessLevel
 from src.app.policies.document_policy import DocumentPolicy
@@ -15,6 +16,9 @@ from src.app.validators.readiness_validator import (
     compute_page_pagexml_readiness,
 )
 
+if TYPE_CHECKING:
+    from src.app.domain.models import CanonicalDocument
+
 
 def compute_export_eligibility(
     doc: CanonicalDocument,
@@ -70,10 +74,10 @@ def _aggregate_levels(levels: list[ReadinessLevel]) -> ReadinessLevel:
     if not levels:
         return ReadinessLevel.NONE
 
-    if all(l == ReadinessLevel.FULL for l in levels):
+    if all(lv == ReadinessLevel.FULL for lv in levels):
         return ReadinessLevel.FULL
-    if all(l == ReadinessLevel.NONE for l in levels):
+    if all(lv == ReadinessLevel.NONE for lv in levels):
         return ReadinessLevel.NONE
-    if any(l in (ReadinessLevel.FULL, ReadinessLevel.PARTIAL) for l in levels):
+    if any(lv in (ReadinessLevel.FULL, ReadinessLevel.PARTIAL) for lv in levels):
         return ReadinessLevel.PARTIAL
     return ReadinessLevel.DEGRADED