Domain features first reorganisation

AGENTS.md

@@ -5,7 +5,12 @@
 - Keep responsibilities separated by layer: API, use-case, model, data.
 - Prefer small, typed functions with explicit inputs/outputs.
 - Keep side effects at the edges (IO, network, logging).
-- Use stable naming and paths (`src/app`, `tests`, `scripts`, `label-dataset`).
+- Use stable naming and paths (`src/api`, `src/eval`, `tests`, `label-dataset`).
+
+## Structure
+
+- Use domain-first folders under `src/api` (`label_sets/`, `classify/`, `model/`, `common/`, `ui/`).
+- Keep schemas with their domain; only shared schema goes in `common/`.
 
 ## FastAPI (proven patterns)
 

Dockerfile

@@ -25,4 +25,4 @@ RUN uv sync --no-dev
 
 ENV PATH="$HOME/app/.venv/bin:$PATH"
 
-CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]
+CMD ["uvicorn", "api.app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

Makefile

@@ -39,7 +39,7 @@ local-install:
 	uv sync --extra dev --python 3.12
 
 local-run:
-	uv run uvicorn api.main:app --host 0.0.0.0 --port 7860 --reload
+	uv run uvicorn api.app:app --host 0.0.0.0 --port 7860 --reload
 
 local-test:
 	uv run pytest -q

README.md

@@ -43,7 +43,7 @@ Use these as starting points or create your own taxonomy.
 
 ## API quickstart
 
-1) Start the service (Docker or `uvicorn app:app`).
+1) Start the service (Docker or `uvicorn api.app:app`).
 2) Upload a label set.
 3) Optionally activate a label set.
 4) Classify images.
@@ -86,11 +86,13 @@ Guard policy example:
 
 ## Architecture
 
-- API layer: FastAPI endpoints and request/response schemas (`src/api/main.py`, `src/api/schemas.py`).
-- Use-case layer: two-stage classification (domain -> labels) (`src/api/clip_service.py`).
-- Model layer: CLIP model + processor + embedding banks (`src/api/clip_store.py`, `src/api/banks.py`).
-- Runtime support: registry, settings, logging, middleware (`src/api/registry.py`, `src/api/settings.py`,
-  `src/api/logging_utils.py`, `src/api/middleware.py`).
+Domain-first layout (URL-centric):
+
+- `label_sets/`: label set API + schemas + registry + hash.
+- `classify/`: classify API + schemas + two-stage classifier + results + banks.
+- `model/`: CLIP store and embedding encoding.
+- `common/`: settings, logging, deps, image IO, middleware.
+- `ui/`: splash + page templates.
 
 ## Coding rules (deeper)
 
@@ -223,25 +225,40 @@ uv run photo-eval prep --normalize-only --in-dir /path/to/images --out data_eval
 
 ## Project layout
 
+Note: root `app.py` is a lightweight HF Spaces placeholder that imports `api.app:app`.
+
 ```
 .
 ├── Dockerfile
+├── app.py
 ├── requirements.txt
 └── src
     ├── api
-    │   ├── banks.py
-    │   ├── clip_service.py
-    │   ├── clip_store.py
-    │   ├── deps.py
-    │   ├── image_io.py
-    │   ├── label_hash.py
-    │   ├── logging_utils.py
-    │   ├── main.py
-    │   ├── middleware.py
-    │   ├── registry.py
-    │   ├── results.py
-    │   ├── schemas.py
-    │   └── settings.py
+    │   ├── app.py
+    │   ├── app_factory.py
+    │   ├── common
+    │   │   ├── deps.py
+    │   │   ├── image_io.py
+    │   │   ├── logging.py
+    │   │   ├── middleware.py
+    │   │   └── settings.py
+    │   ├── classify
+    │   │   ├── banks.py
+    │   │   ├── results.py
+    │   │   ├── router.py
+    │   │   ├── schemas.py
+    │   │   └── service.py
+    │   ├── label_sets
+    │   │   ├── hash.py
+    │   │   ├── registry.py
+    │   │   ├── router.py
+    │   │   └── schemas.py
+    │   ├── model
+    │   │   └── clip_store.py
+    │   └── ui
+    │       ├── page-banner.html
+    │       ├── page.html
+    │       └── splash.html
     └── eval
         ├── README.md
         ├── cli.py
@@ -256,4 +273,3 @@ uv run photo-eval prep --normalize-only --in-dir /path/to/images --out data_eval
 Emmanuel Sandorfi / Knowledge at Lighton  
 
 01.2026  
-

STORY.md

@@ -74,4 +74,4 @@ Label sets aren’t just files; they’re the vocabulary of the system. Changing
 
 ### Deployment without drama
 
-HF Spaces drove a pragmatic discipline: CPU‑first defaults, deterministic builds, and a root `app.py` entrypoint to keep deployment friction low. The end result is a system that boots cleanly and behaves predictably in constrained environments.
+HF Spaces drove a pragmatic discipline: CPU‑first defaults, deterministic builds, and a root `app.py` shim (required by Spaces) that forwards to `api.app:app`. The end result is a system that boots cleanly and behaves predictably in constrained environments.

app.py

@@ -1,3 +1,9 @@
-from api.main import app
+"""HF Spaces placeholder entrypoint.
+
+HF Docker Spaces require an `app.py` file to exist. This shim is intentionally
+tiny and forwards the actual ASGI app from `src/api/app.py`.
+"""
+
+from api.app import app
 
 __all__ = ["app"]

src/api/{main.py → app.py}

@@ -2,31 +2,20 @@ from __future__ import annotations
 
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from typing import Optional
+from pathlib import Path
 
-from fastapi import Depends, FastAPI, HTTPException, Query, Request, Response
+from fastapi import FastAPI, Request, Response
 from fastapi.responses import HTMLResponse, JSONResponse
-from pathlib import Path
 
 import markdown
 
-from api.clip_store import ClipStore
-from api.clip_service import TwoStageClassifier
-from api.deps import get_request_id, resolve_bank
-from api.image_io import load_image_from_base64
-from api.logging_utils import setup_logging, log_json
-from api.middleware import RequestIdMiddleware
-from api.registry import LabelSetRegistry
-from api.schemas import (
-    ActivateResponse,
-    ClassifyRequest,
-    ClassifyResponse,
-    Hit,
-    LabelSet,
-    LabelSetCreateResponse,
-    LabelSetInfo,
-)
-from api.settings import settings
+from api.classify.router import router as classify_router
+from api.common.logging import log_json, setup_logging
+from api.common.middleware import RequestIdMiddleware
+from api.label_sets.router import router as label_sets_router
+from api.label_sets.registry import LabelSetRegistry
+from api.model.clip_store import ClipStore
+from api.classify.service import TwoStageClassifier
 
 
 logger = setup_logging()
@@ -72,20 +61,36 @@ async def lifespan(app: FastAPI):
         await _maybe_aclose(store)
 
 
-def get_resources(request: Request) -> Resources:
-    return request.app.state.resources
-
-
-def get_store(res: Resources = Depends(get_resources)) -> ClipStore:
-    return res.store
-
-
-def get_classifier(res: Resources = Depends(get_resources)) -> TwoStageClassifier:
-    return res.classifier
-
+def render_page(md_path: Path, *, title: str) -> HTMLResponse:
+    header_path = Path(__file__).resolve().parent / "ui" / "page-banner.html"
+    page_template_path = Path(__file__).resolve().parent / "ui" / "page.html"
+    try:
+        header_html = header_path.read_text(encoding="utf-8")
+        template_html = page_template_path.read_text(encoding="utf-8")
+    except Exception:
+        return HTMLResponse(content="internal server error", status_code=500)
+    try:
+        md_text = md_path.read_text(encoding="utf-8")
+    except Exception:
+        return HTMLResponse(content="internal server error", status_code=500)
+
+    if md_text.lstrip().startswith("---"):
+        parts = md_text.split("---", 2)
+        if len(parts) == 3:
+            md_text = parts[2].lstrip()
+
+    content_html = markdown.markdown(
+        md_text,
+        extensions=["fenced_code", "tables"],
+        output_format="html5",
+    )
 
-def get_registry(res: Resources = Depends(get_resources)) -> LabelSetRegistry:
-    return res.registry
+    html = (
+        template_html.replace("{{HEADER}}", header_html)
+        .replace("{{CONTENT}}", content_html)
+        .replace("{{TITLE}}", title)
+    )
+    return HTMLResponse(content=html)
 
 
 def create_app(*, resources: Resources | None = None) -> FastAPI:
@@ -129,48 +134,17 @@ def create_app(*, resources: Resources | None = None) -> FastAPI:
 
     @app.get("/", include_in_schema=False)
     def home() -> HTMLResponse:
-        splash_path = Path(__file__).with_name("splash.html")
+        splash_path = Path(__file__).resolve().parent / "ui" / "splash.html"
         try:
             html = splash_path.read_text(encoding="utf-8")
         except Exception:
-            html = f"<h1>Photo Class</h1><p>Missing {splash_path}</p>"
-        return HTMLResponse(content=html)
-
-    def render_page(md_path: Path, *, title: str) -> HTMLResponse:
-        header_path = Path(__file__).with_name("page-banner.html")
-        page_template_path = Path(__file__).with_name("page.html")
-        try:
-            header_html = header_path.read_text(encoding="utf-8")
-            template_html = page_template_path.read_text(encoding="utf-8")
-        except Exception:
-            return HTMLResponse(content="internal server error", status_code=500)
-        try:
-            md_text = md_path.read_text(encoding="utf-8")
-        except Exception:
-            return HTMLResponse(content="internal server error", status_code=500)
-
-        if md_text.lstrip().startswith("---"):
-            parts = md_text.split("---", 2)
-            if len(parts) == 3:
-                md_text = parts[2].lstrip()
-
-        content_html = markdown.markdown(
-            md_text,
-            extensions=["fenced_code", "tables"],
-            output_format="html5",
-        )
-
-        html = (
-            template_html.replace("{{HEADER}}", header_html)
-            .replace("{{CONTENT}}", content_html)
-            .replace("{{TITLE}}", title)
-        )
+            html = f"<h1>Photo Classification</h1><p>Missing {splash_path}</p>"
         return HTMLResponse(content=html)
 
     @app.get("/readme", include_in_schema=False)
     def readme() -> HTMLResponse:
         readme_path = Path(__file__).resolve().parents[2] / "README.md"
-        return render_page(readme_path, title="Readme")
+        return render_page(readme_path, title="README")
 
     @app.get("/story", include_in_schema=False)
     def story() -> HTMLResponse:
@@ -183,120 +157,8 @@ def create_app(*, resources: Resources | None = None) -> FastAPI:
         log_json(logger, event="error.unhandled", request_id=rid, error=str(exc), path=str(request.url.path))
         return JSONResponse(status_code=500, content={"detail": "internal server error"})
 
-    @app.post("/api/v1/label-sets", response_model=LabelSetCreateResponse)
-    def create_label_set(
-        payload: LabelSet,
-        request_id: str = Depends(get_request_id),
-        store: ClipStore = Depends(get_store),
-        registry: LabelSetRegistry = Depends(get_registry),
-    ) -> LabelSetCreateResponse:
-        bank = store.build_bank(payload)
-        registry.upsert(bank)
-
-        label_count = sum(len(b.ids) for b in bank.labels_by_domain.values())
-        is_default = (registry.default_hash == bank.label_set_hash)
-
-        log_json(
-            logger,
-            event="label_sets.upsert",
-            request_id=request_id,
-            label_set_hash=bank.label_set_hash,
-            name=bank.name,
-            domain_count=len(bank.domains.ids),
-            label_count=label_count,
-            is_default=is_default,
-        )
-
-        return LabelSetCreateResponse(
-            label_set_hash=bank.label_set_hash,
-            name=bank.name,
-            domain_count=len(bank.domains.ids),
-            label_count=label_count,
-            is_default=is_default,
-        )
-
-    @app.get("/api/v1/label-sets", response_model=list[LabelSetInfo])
-    def list_label_sets(
-        request_id: str = Depends(get_request_id),
-        registry: LabelSetRegistry = Depends(get_registry),
-    ) -> list[LabelSetInfo]:
-        out: list[LabelSetInfo] = []
-        for bank in registry.banks.values():
-            label_count = sum(len(b.ids) for b in bank.labels_by_domain.values())
-            out.append(
-                LabelSetInfo(
-                    label_set_hash=bank.label_set_hash,
-                    name=bank.name,
-                    domain_count=len(bank.domains.ids),
-                    label_count=label_count,
-                    is_default=(registry.default_hash == bank.label_set_hash),
-                )
-            )
-
-        log_json(logger, event="label_sets.list", request_id=request_id, count=len(out))
-        return out
-
-    @app.post("/api/v1/label-sets/{label_set_hash}/activate", response_model=ActivateResponse)
-    def activate_label_set(
-        label_set_hash: str,
-        request_id: str = Depends(get_request_id),
-        registry: LabelSetRegistry = Depends(get_registry),
-    ) -> ActivateResponse:
-        try:
-            registry.activate(label_set_hash)
-        except KeyError:
-            raise HTTPException(status_code=404, detail="Unknown label_set_hash")
-
-        log_json(logger, event="label_sets.activate", request_id=request_id, default_label_set_hash=label_set_hash)
-        return ActivateResponse(default_label_set_hash=label_set_hash)
-
-    @app.post("/api/v1/classify", response_model=ClassifyResponse)
-    def classify(
-        payload: ClassifyRequest,
-        request: Request,
-        request_id: str = Depends(get_request_id),
-        label_set_hash: Optional[str] = Query(default=None, description="If omitted, uses the default label set."),
-        classifier: TwoStageClassifier = Depends(get_classifier),
-        registry: LabelSetRegistry = Depends(get_registry),
-    ) -> ClassifyResponse:
-        bank = resolve_bank(registry, label_set_hash)
-
-        image = load_image_from_base64(
-            payload.image_base64,
-            max_bytes=settings.max_image_mb * 1024 * 1024,
-        )
-
-        res = classifier.classify(
-            bank=bank,
-            image=image,
-            domain_top_n=payload.domain_top_n or settings.default_domain_top_n,
-            top_k=payload.top_k or settings.default_top_k,
-        )
-
-        log_json(
-            logger,
-            event="classify",
-            request_id=request_id,
-            label_set_hash=bank.label_set_hash,
-            model_id=settings.clip_model_id,
-            domain_top_n=payload.domain_top_n,
-            top_k=payload.top_k,
-            chosen_domains=res.chosen_domains,
-            elapsed_ms=res.timings.total_ms,
-            elapsed_domain_ms=res.timings.domain_ms,
-            elapsed_labels_ms=res.timings.labels_ms,
-        )
-
-        return ClassifyResponse(
-            label_set_hash=bank.label_set_hash,
-            model_id=settings.clip_model_id,
-            domain_hits=[Hit(id=i, score=s) for i, s in res.domain_hits],
-            chosen_domains=res.chosen_domains,
-            label_hits=[Hit(id=i, score=s) for i, s in res.label_hits],
-            elapsed_ms=res.timings.total_ms,
-            elapsed_domain_ms=res.timings.domain_ms,
-            elapsed_labels_ms=res.timings.labels_ms,
-        )
+    app.include_router(label_sets_router)
+    app.include_router(classify_router)
 
     return app
 

src/api/app_factory.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from fastapi import FastAPI
-from api.main import build_app  # we'll define build_app in main.py
+from api.app import build_app  # we'll define build_app in app.py
 
 def create_app() -> FastAPI:
     return build_app()

src/api/classify/__init__.py

@@ -0,0 +1 @@
+"""Classification domain."""

src/api/{banks.py → classify/banks.py}

@@ -3,13 +3,11 @@ from __future__ import annotations
 from dataclasses import dataclass
 import torch
 
-Tensor = torch.Tensor
-
 
 @dataclass(frozen=True, slots=True)
 class EmbeddingBank:
     ids: tuple[str, ...]
-    feats: Tensor  # (N, D) normalized
+    feats: torch.Tensor  # (N, D) normalized
 
 
 @dataclass(frozen=True, slots=True)

src/api/classify/router.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query, Request
+
+from api.classify.schemas import ClassifyRequest, ClassifyResponse, Hit
+from api.common.deps import get_classifier, get_registry, get_request_id, resolve_bank
+from api.common.logging import log_json, setup_logging
+from api.common.image_io import load_image_from_base64
+from api.common.settings import settings
+
+
+logger = setup_logging()
+router = APIRouter(prefix="/api/v1", tags=["classify"])
+
+
+@router.post("/classify", response_model=ClassifyResponse)
+def classify(
+    payload: ClassifyRequest,
+    request: Request,
+    request_id: str = Depends(get_request_id),
+    label_set_hash: Optional[str] = Query(default=None, description="If omitted, uses the default label set."),
+    classifier=Depends(get_classifier),
+    registry=Depends(get_registry),
+) -> ClassifyResponse:
+    bank = resolve_bank(registry, label_set_hash)
+
+    image = load_image_from_base64(
+        payload.image_base64,
+        max_bytes=settings.max_image_mb * 1024 * 1024,
+    )
+
+    res = classifier.classify(
+        bank=bank,
+        image=image,
+        domain_top_n=payload.domain_top_n or settings.default_domain_top_n,
+        top_k=payload.top_k or settings.default_top_k,
+    )
+
+    log_json(
+        logger,
+        event="classify",
+        request_id=request_id,
+        label_set_hash=bank.label_set_hash,
+        model_id=settings.clip_model_id,
+        domain_top_n=payload.domain_top_n,
+        top_k=payload.top_k,
+        chosen_domains=res.chosen_domains,
+        elapsed_ms=res.timings.total_ms,
+        elapsed_domain_ms=res.timings.domain_ms,
+        elapsed_labels_ms=res.timings.labels_ms,
+    )
+
+    return ClassifyResponse(
+        label_set_hash=bank.label_set_hash,
+        model_id=settings.clip_model_id,
+        domain_hits=[Hit(id=i, score=s) for i, s in res.domain_hits],
+        chosen_domains=res.chosen_domains,
+        label_hits=[Hit(id=i, score=s) for i, s in res.label_hits],
+        elapsed_ms=res.timings.total_ms,
+        elapsed_domain_ms=res.timings.domain_ms,
+        elapsed_labels_ms=res.timings.labels_ms,
+    )

src/api/classify/schemas.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import List
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class ClassifyRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    image_base64: str = Field(..., description="Base64-encoded image bytes (jpg/png/webp).")
+    domain_top_n: int = Field(default=2, ge=1, le=3)
+    top_k: int = Field(default=5, ge=1, le=20)
+
+
+class Hit(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    id: str
+    score: float
+
+
+class ClassifyResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid", protected_namespaces=())
+    label_set_hash: str
+    model_id: str
+    domain_hits: List[Hit]
+    chosen_domains: List[str]
+    label_hits: List[Hit]
+    elapsed_ms: int
+    elapsed_domain_ms: int
+    elapsed_labels_ms: int

src/api/{clip_service.py → classify/service.py}

@@ -5,9 +5,9 @@ from dataclasses import dataclass
 
 import torch
 
-from api.banks import EmbeddingBank, LabelSetBank
-from api.clip_store import ClipStore
-from api.results import ClassificationResult, StageTimings
+from api.classify.banks import EmbeddingBank, LabelSetBank
+from api.model.clip_store import ClipStore
+from api.classify.results import ClassificationResult, StageTimings
 
 
 @dataclass(slots=True)

src/api/common/__init__.py

@@ -0,0 +1 @@
+"""Shared utilities for the API."""

src/api/{deps.py → common/deps.py}

@@ -4,8 +4,10 @@ from typing import Optional
 
 from fastapi import Depends, HTTPException, Query, Request
 
-from api.banks import LabelSetBank
-from api.registry import LabelSetRegistry
+from api.classify.banks import LabelSetBank
+from api.label_sets.registry import LabelSetRegistry
+from api.model.clip_store import ClipStore
+from api.classify.service import TwoStageClassifier
 
 
 def get_request_id(request: Request) -> str:
@@ -36,3 +38,15 @@ def get_bank(
     label_set_hash: Optional[str] = Depends(get_label_set_hash),
 ) -> LabelSetBank:
     return resolve_bank(registry, label_set_hash)
+
+
+def get_store(request: Request) -> ClipStore:
+    return request.app.state.resources.store
+
+
+def get_classifier(request: Request) -> TwoStageClassifier:
+    return request.app.state.resources.classifier
+
+
+def get_registry(request: Request) -> LabelSetRegistry:
+    return request.app.state.resources.registry

src/api/label_sets/__init__.py

@@ -0,0 +1 @@
+"""Label set domain."""

src/api/{registry.py → label_sets/registry.py}

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import Optional
-from api.banks import LabelSetBank
+from api.classify.banks import LabelSetBank
 
 
 @dataclass(slots=True)

src/api/label_sets/router.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from api.common.logging import log_json, setup_logging
+from api.common.deps import get_request_id, get_registry, get_store
+from api.label_sets.schemas import ActivateResponse, LabelSet, LabelSetCreateResponse, LabelSetInfo
+
+
+logger = setup_logging()
+router = APIRouter(prefix="/api/v1/label-sets", tags=["label-sets"])
+
+
+@router.post("", response_model=LabelSetCreateResponse)
+def create_label_set(
+    payload: LabelSet,
+    request_id: str = Depends(get_request_id),
+    store=Depends(get_store),
+    registry=Depends(get_registry),
+) -> LabelSetCreateResponse:
+    bank = store.build_bank(payload)
+    registry.upsert(bank)
+
+    label_count = sum(len(b.ids) for b in bank.labels_by_domain.values())
+    is_default = registry.default_hash == bank.label_set_hash
+
+    log_json(
+        logger,
+        event="label_sets.upsert",
+        request_id=request_id,
+        label_set_hash=bank.label_set_hash,
+        name=bank.name,
+        domain_count=len(bank.domains.ids),
+        label_count=label_count,
+        is_default=is_default,
+    )
+
+    return LabelSetCreateResponse(
+        label_set_hash=bank.label_set_hash,
+        name=bank.name,
+        domain_count=len(bank.domains.ids),
+        label_count=label_count,
+        is_default=is_default,
+    )
+
+
+@router.get("", response_model=list[LabelSetInfo])
+def list_label_sets(
+    request_id: str = Depends(get_request_id),
+    registry=Depends(get_registry),
+) -> list[LabelSetInfo]:
+    out: list[LabelSetInfo] = []
+    for bank in registry.banks.values():
+        label_count = sum(len(b.ids) for b in bank.labels_by_domain.values())
+        out.append(
+            LabelSetInfo(
+                label_set_hash=bank.label_set_hash,
+                name=bank.name,
+                domain_count=len(bank.domains.ids),
+                label_count=label_count,
+                is_default=(registry.default_hash == bank.label_set_hash),
+            )
+        )
+
+    log_json(logger, event="label_sets.list", request_id=request_id, count=len(out))
+    return out
+
+
+@router.post("/{label_set_hash}/activate", response_model=ActivateResponse)
+def activate_label_set(
+    label_set_hash: str,
+    request_id: str = Depends(get_request_id),
+    registry=Depends(get_registry),
+) -> ActivateResponse:
+    try:
+        registry.activate(label_set_hash)
+    except KeyError:
+        raise HTTPException(status_code=404, detail="Unknown label_set_hash")
+
+    log_json(logger, event="label_sets.activate", request_id=request_id, default_label_set_hash=label_set_hash)
+    return ActivateResponse(default_label_set_hash=label_set_hash)

src/api/{schemas.py → label_sets/schemas.py}

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-from typing import Dict, List, Optional
-from pydantic import BaseModel, Field, ConfigDict
+from typing import Dict, List
+from pydantic import BaseModel, ConfigDict
 
 
 class LabelItem(BaseModel):
@@ -44,28 +44,3 @@ class LabelSetCreateResponse(BaseModel):
 class ActivateResponse(BaseModel):
     model_config = ConfigDict(extra="forbid")
     default_label_set_hash: str
-
-
-class ClassifyRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-    image_base64: str = Field(..., description="Base64-encoded image bytes (jpg/png/webp).")
-    domain_top_n: int = Field(default=2, ge=1, le=3)
-    top_k: int = Field(default=5, ge=1, le=20)
-
-
-class Hit(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-    id: str
-    score: float
-
-
-class ClassifyResponse(BaseModel):
-    model_config = ConfigDict(extra="forbid", protected_namespaces=())
-    label_set_hash: str
-    model_id: str
-    domain_hits: List[Hit]
-    chosen_domains: List[str]
-    label_hits: List[Hit]
-    elapsed_ms: int
-    elapsed_domain_ms: int
-    elapsed_labels_ms: int

src/api/model/__init__.py

@@ -0,0 +1 @@
+"""Model layer."""

src/api/{clip_store.py → model/clip_store.py}

@@ -5,10 +5,10 @@ import warnings
 import torch
 from transformers import CLIPModel, CLIPProcessor
 
-from api.banks import EmbeddingBank, LabelSetBank
-from api.label_hash import stable_hash
-from api.schemas import LabelSet
-from api.settings import settings
+from api.classify.banks import EmbeddingBank, LabelSetBank
+from api.label_sets.hash import stable_hash
+from api.label_sets.schemas import LabelSet
+from api.common.settings import settings
 
 
 class ClipStore:

src/api/ui/__init__.py

@@ -0,0 +1 @@
+"""UI templates."""

src/api/{splash.html → ui/splash.html}

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Photo Class</title>
+    <title>Photo Classification</title>
     <style>
       :root {
         --bg: #f8fafc;
@@ -69,7 +69,8 @@
       <h1>Photo Classification</h1>
       <p>A small, prompt-driven photo classification API built on CLIP. Upload a label set, classify images, and inspect timings.</p>
       <p>This project grew through an intensive dialog with Codex — a steady build from core API to eval tooling and HF Spaces deployment.</p>
-      <p>01.2026 by Emmanuel Sandorfi / Knowledge @ Lighton</p>
+      <p>Emmanuel Sandorfi / Knowledge @ Lighton.ai</p>
+      <p>2026, January</p> 
       <div class="actions">
         <a class="button primary" href="/docs">API Docs</a>
         <a class="button" href="/story">Read the Story</a>

tests/conftest.py

@@ -6,7 +6,7 @@ import pytest
 from PIL import Image
 from fastapi.testclient import TestClient
 
-from api.main import build_app
+from api.app import build_app
 from tests.fakes import FakeClipStore, FakeTwoStageClassifier
 
 

tests/fakes.py

@@ -2,10 +2,10 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from api.banks import EmbeddingBank, LabelSetBank
-from api.label_hash import stable_hash
-from api.results import ClassificationResult, StageTimings
-from api.schemas import LabelSet
+from api.classify.banks import EmbeddingBank, LabelSetBank
+from api.label_sets.hash import stable_hash
+from api.classify.results import ClassificationResult, StageTimings
+from api.label_sets.schemas import LabelSet
 
 
 class FakeClipStore:

tests/test_integration_real_clip.py

@@ -6,9 +6,9 @@ import pytest
 from PIL import Image
 from fastapi.testclient import TestClient
 
-from api.main import build_app
-from api.clip_store import ClipStore
-from api.clip_service import TwoStageClassifier
+from api.app import build_app
+from api.model.clip_store import ClipStore
+from api.classify.service import TwoStageClassifier
 
 
 @pytest.mark.integration