Skip to content

[arch] image-service: production ML pipeline with model hot-swap #112

Description

@cofade

Background

docs/01-introduction-and-goals/README.md notes that the image-service classifier is a stub today and that real ML integration is "planned." This issue makes that pipeline real and operable so that downstream features can plug in without a Dockerfile rebuild for every model swap.

Why it matters

Almost every feature on the wishlist (cell-occupation timeline, hatching prediction, species ID, time-lapse triage) depends on a real model running in image-service. Without a hot-swap-capable pipeline, every new model is a redeploy.

Proposal

  1. Model directory mounted as a volume: /models/<name>/<version>/{weights, config.json, README.md}.
  2. Model registry loaded at startup, with optional reload-on-SIGHUP (or admin endpoint) for swap-in.
  3. Inference contract: each model exposes a common predict(image) -> {detections, scores, model_version} interface.
  4. Telemetry: every inference logs model_version so downstream consumers can filter or retroactively understand drift.
  5. First real model: a small object detector (YOLO-nano-class or similar) replacing the stub — even baseline accuracy is fine; the point is the integration, not SOTA numbers.

Acceptance criteria

  • /models/... volume mount in docker-compose.yml
  • Model registry + at least 2 loadable models (the existing stub plus one new)
  • model_version recorded with every output that crosses a service boundary
  • New ADR in docs/09-architecture-decisions/ covering the choice + model lifecycle
  • arc42 chapter 05 (image-service file) updated to describe the new internal structure
  • Unit + smoke tests covering "swap a model without restarting the container"

Out of scope

  • Choosing the production model — that is a follow-up tracked separately.
  • GPU inference — CPU-only is fine for now (ESP-side latencies dwarf inference time).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions