@trillboards/edge-sdk 0.2.81 → 0.2.82

package/deploy/detector/trillboards_detector/loader.py

@@ -1,4 +1,4 @@
-"""Model lifecycle: load it, prove it, watch for the OTA, and say which.
+"""Model lifecycle: build the catalogue, watch the disk, and say which is up.
 
 WHY LOADING IS A BACKGROUND STATE MACHINE AND NOT A STARTUP STEP
 ---------------------------------------------------------------
@@ -25,21 +25,38 @@ Three constraints, none optional:
    synthetic frame before declaring ready, and `/health` reports that outcome
    rather than re-deriving anything — which is also how `/health` stays cheap
    and inference-free.
+
+WHAT THIS FILE IS AFTER THE MODEL LIBRARY
+-----------------------------------------
+It used to own the session, singular — its own docstring said so, and
+`docs/runbooks/sensing-model-library.md` §3 names that as the thing standing
+between here and a library of specialists. The residency policy (name -> session
+map, class index, lazy load, LRU eviction under a RAM budget, merging two
+models' answers) now lives in `registry.py`, which imports nothing heavier than
+the standard library and is therefore testable on every CI runner. What is left
+here is the half that genuinely needs onnxruntime and Pillow: building a real
+session, running a real probe frame through it, and the poll loop that watches
+the disk.
 """
 
 from __future__ import annotations
 
 import io
 import threading
-import time
 from pathlib import Path
 
-from .errors import DetectorNotReady
-from .session import DetectionBatch, ModelContractError, OnnxDetector
-
-STATE_LOADING = "loading"
-STATE_READY = "ready"
-STATE_UNAVAILABLE = "unavailable"
+from .detections import DetectionBatch
+from .errors import DetectorNotReady, UnknownClasses
+from .labels import BUILTIN_VOCABULARIES, ClassIndex, ModelVocabulary
+from .modelpath import resolve_model_path
+from .registry import (
+    STATE_LOADING,
+    STATE_READY,
+    STATE_UNAVAILABLE,
+    ModelEntry,
+    ModelRegistry,
+)
+from .session import OnnxDetector
 
 DEFAULT_POLL_INTERVAL_S = 30.0
 
@@ -58,8 +75,49 @@ def _warmup_jpeg() -> bytes:
     return buf.getvalue()
 
 
+def build_catalogue(
+    default_model_name: str,
+    default_model_path: "Path | None" = None,
+    vocabularies: "tuple[ModelVocabulary, ...]" = BUILTIN_VOCABULARIES,
+    env=None,
+) -> "list[ModelEntry]":
+    """Every model this build can label, bound to where it would live on THIS box.
+
+    One entry per committed vocabulary, each at `resolve_model_path(<name>)` —
+    the per-model-name directory layout that `modelpath.py` was already written
+    for ("the multi-model shape was anticipated at the path layer"). Nothing
+    here checks whether the file exists: presence is the watcher's business and
+    it changes under us, so deciding it once at startup would freeze a fact that
+    an OTA is about to move.
+
+    `default_model_name` names the PINNED entry — the general cascade gate, the
+    one `/health` reports and the one that is never evicted. It must be a
+    committed vocabulary: a name with no class list is a model nothing can
+    label, which is `yolov8_nano` exactly.
+    """
+    by_name = {v.model_name: v for v in vocabularies}
+    if default_model_name not in by_name:
+        raise ValueError(
+            f"no committed vocabulary for {default_model_name!r}; known: {sorted(by_name)}. "
+            "A model with no class list is a model nothing can label — see labels.py."
+        )
+    entries = []
+    for vocabulary in vocabularies:
+        pinned = vocabulary.model_name == default_model_name
+        if pinned and default_model_path is not None:
+            path = default_model_path
+        else:
+            path = resolve_model_path(vocabulary.model_name, env)
+        entries.append(ModelEntry(vocabulary, path, pinned=pinned))
+    # Pinned first, so catalogue order — which is what breaks a class-ownership
+    # tie — puts the general detector ahead of every specialist. `person` must
+    # keep coming from the model the 98.8/98.8 was measured on.
+    entries.sort(key=lambda e: (not e.pinned,))
+    return entries
+
+
 class DetectorLoader:
-    """Owns the session and the one word that describes it."""
+    """Owns the model CATALOGUE, the poll loop, and the words describing both."""
 
     def __init__(
         self,
@@ -67,30 +125,45 @@ class DetectorLoader:
         model_name: str,
         intra_op_threads: "int | None" = None,
         poll_interval_s: float = DEFAULT_POLL_INTERVAL_S,
+        ram_budget_bytes: "int | None" = None,
+        vocabularies: "tuple[ModelVocabulary, ...]" = BUILTIN_VOCABULARIES,
         log=print,
     ):
+        # `ram_budget_bytes=None` is NOT a default policy — it is the absence of
+        # one, and the registry refuses every portfolio decision in that state
+        # rather than inventing a number. See `registry.py`'s header: the
+        # allocation authority is server-side and a ceiling chosen here would be
+        # a second one that cannot see it.
         self.model_path = model_path
         self.model_name = model_name
         self._intra_op_threads = intra_op_threads
         self._poll_interval_s = poll_interval_s
         self._log = log
 
-        self._lock = threading.Lock()
-        self._detector: "OnnxDetector | None" = None
-        self._state = STATE_LOADING
-        self._reason: "str | None" = None
-        self._stamp: "tuple[int, int] | None" = None
-        self._warmup_ms: "float | None" = None
-        self._loaded_at: "float | None" = None
-
-        self._degenerate_dropped = 0
-        self._unnamed_class_dropped = 0
-        self._detect_count = 0
-        self._detect_failures = 0
+        self.registry = ModelRegistry(
+            entries=build_catalogue(model_name, model_path, vocabularies),
+            session_factory=self._build_session,
+            probe=self._probe,
+            ram_budget_bytes=ram_budget_bytes,
+            log=log,
+        )
 
         self._stop = threading.Event()
         self._thread = threading.Thread(target=self._run, name="detector-loader", daemon=True)
 
+    # ── the two halves that need a real runtime ──────────────────────────────
+
+    def _build_session(self, entry: ModelEntry) -> OnnxDetector:
+        return OnnxDetector(entry.path, entry.vocabulary, self._intra_op_threads)
+
+    def _probe(self, session: OnnxDetector) -> None:
+        """PROVE IT. A session that constructs is not a session that infers.
+
+        `0.99` keeps the probe's own post-processing trivial on a grey frame;
+        what is being established is that a forward pass completes at all.
+        """
+        session.detect(_warmup_jpeg(), 0.99, None)
+
     def start(self) -> None:
         self._thread.start()
 
@@ -102,156 +175,121 @@ class DetectorLoader:
 
     # ── what the server reads ────────────────────────────────────────────────
 
+    @staticmethod
+    def _top_level_state(pinned_state: str) -> str:
+        if pinned_state == STATE_READY:
+            return STATE_READY
+        if pinned_state == STATE_LOADING:
+            return STATE_LOADING
+        return STATE_UNAVAILABLE
+
     @property
     def state(self) -> str:
-        with self._lock:
-            return self._state
+        """The PINNED model's state, in the three words that shipped first.
+
+        `/health` has always answered 200 iff a load completed and a probe
+        inference succeeded, and `LocalDetectorClient.isHealthy()` turns
+        anything else into "detector down, send the frame to the VLM". So the
+        top-level word keeps describing the general cascade gate: a box whose
+        gate is missing cannot do the job it exists for, whatever specialists
+        happen to be resident. Per-model states — including `idle` and `absent`,
+        which have no top-level equivalent — are in `models` on the same
+        payload.
+        """
+        return self._top_level_state(self.registry.snapshot()["pinned_state"])
 
     @property
     def reason(self) -> "str | None":
-        with self._lock:
-            return self._reason
+        return self.registry.snapshot()["pinned"].get("reason")
+
+    def class_index(self) -> ClassIndex:
+        """The union vocabulary of every model whose artifact is on this box."""
+        return self.registry.class_index()
+
+    def resolve_classes(self, requested: "list[str]") -> "set[str]":
+        """Canonicalise, or raise `UnknownClasses` — which the server makes a 400."""
+        return self.registry.resolve_classes(requested)
 
     def info(self) -> dict:
-        with self._lock:
-            d = self._detector
-            payload = {
-                "state": self._state,
-                "model": self.model_name,
-                "model_path": str(self.model_path),
-                "detect_count": self._detect_count,
-                "detect_failures": self._detect_failures,
-                # Published because a drop nobody can see is the failure this
-                # whole stack keeps repeating. Both are normally 0.
-                "degenerate_boxes_dropped": self._degenerate_dropped,
-                "unnamed_class_dropped": self._unnamed_class_dropped,
-            }
-            if self._reason:
-                payload["reason"] = self._reason
-            if self._warmup_ms is not None:
-                payload["warmup_inference_ms"] = round(self._warmup_ms, 1)
-            if self._loaded_at is not None:
-                payload["loaded_at"] = self._loaded_at
-            if d is not None:
-                payload["input"] = f"{d.spec.width}x{d.spec.height}"
-                payload["classes"] = d.spec.num_classes
-                payload["providers"] = d.spec.providers
-            return payload
+        """The `/health` payload. Reads state that already exists; loads nothing.
+
+        THE TOP-LEVEL KEYS STILL DESCRIBE THE PINNED MODEL, unchanged, because
+        every existing reader — the three installers' post-install probes, the
+        integration test, an operator with `curl` — was written against them.
+        `models`, `resident_models` and the two RAM figures are additive.
+
+        ONE SNAPSHOT, not one per field. Reading `self.state` here would take a
+        SECOND snapshot, and the watcher thread can move between them — so
+        `/health` could answer `state: "ready"` next to a `models` map showing
+        the pinned model still loading. Neither half would be wrong and the
+        pair would describe no moment, which is precisely the shape
+        `postgres-tls-uri-override.md` records for two scans a minute apart. A
+        payload whose entire job is honesty about a load that happened must be
+        one read.
+        """
+        snap = self.registry.snapshot()
+        pinned = snap["pinned"]
+        payload = {
+            "state": self._top_level_state(snap["pinned_state"]),
+            "model": snap["pinned_model"],
+            "model_path": pinned["path"],
+            "detect_count": snap["detect_count"],
+            "detect_failures": snap["detect_failures"],
+            # Published because a drop nobody can see is the failure this
+            # whole stack keeps repeating. Both are normally 0. The per-model
+            # split is in `models`; these are the box-wide totals the existing
+            # readers already parse.
+            "degenerate_boxes_dropped": snap["degenerate_boxes_dropped"],
+            "unnamed_class_dropped": snap["unnamed_class_dropped"],
+            # WHICH MODELS ARE RESIDENT — `sensing-model-library.md` §3. Derived
+            # from the same state the loads wrote, so this stays a report and
+            # never becomes a probe.
+            "models": snap["models"],
+            "resident_models": snap["resident_models"],
+            # THE CEILING AS INJECTED, and whether one was injected at ALL —
+            # `ram_budget_bytes: null` alone is ambiguous with a reader that
+            # drops nulls, and the difference between "nobody has set a ceiling"
+            # and "the ceiling is X" is the difference between a policy hole and
+            # a policy. The service picks no number in either case.
+            "ram_budget_bytes": snap["ram_budget_bytes"],
+            "ram_ceiling_injected": snap["ram_ceiling_injected"],
+            "ram_resident_bytes": snap["ram_resident_bytes"],
+            # Non-zero means OVERSUBSCRIBED against what this box was allocated.
+            # Eviction is a safety valve, not the allocator, and a service
+            # quietly thrashing under a ceiling looks exactly like one working
+            # fine — so the count has to leave the process.
+            "evictions": snap["evictions"],
+            "known_class_count": snap["known_class_count"],
+        }
+        reason = pinned.get("reason")
+        if reason:
+            payload["reason"] = reason
+        for key in ("warmup_inference_ms", "loaded_at", "input", "classes", "providers"):
+            if key in pinned:
+                payload[key] = pinned[key]
+        return payload
 
     def detect(self, jpeg: bytes, min_confidence: float, wanted: "set[str] | None") -> DetectionBatch:
-        with self._lock:
-            detector, reason = self._detector, self._reason
-        if detector is None:
-            raise DetectorNotReady(reason or "model is not loaded")
-        try:
-            batch = detector.detect(jpeg, min_confidence, wanted)
-        except Exception:
-            with self._lock:
-                self._detect_failures += 1
-            raise
-        with self._lock:
-            self._detect_count += 1
-            self._degenerate_dropped += batch.degenerate_dropped
-            self._unnamed_class_dropped += batch.unnamed_class_dropped
-        if batch.degenerate_dropped or batch.unnamed_class_dropped:
-            self._log(
-                f"[detector] dropped {batch.degenerate_dropped} zero-extent box(es) and "
-                f"{batch.unnamed_class_dropped} unnamed-class detection(s) from one frame"
-            )
-        return batch
+        return self.registry.detect(jpeg, min_confidence, wanted)
 
     # ── the loop ─────────────────────────────────────────────────────────────
 
     def _run(self) -> None:
         while not self._stop.is_set():
             try:
-                self._tick()
+                self.registry.refresh()
             except Exception as err:  # never let the watcher die
-                self._set(STATE_UNAVAILABLE, f"loader crashed: {err}")
+                self._log(f"[detector] loader crashed: {type(err).__name__}: {err}")
             self._stop.wait(self._poll_interval_s)
 
-    def _tick(self) -> None:
-        stamp = self._file_stamp()
-        if stamp is None:
-            if self._state != STATE_UNAVAILABLE or self._detector is not None:
-                self._log(f"[detector] model artifact not present at {self.model_path}")
-            self._drop(
-                f"model artifact not found at {self.model_path}; it arrives over the air "
-                "and this service will pick it up within "
-                f"{int(self._poll_interval_s)}s of it landing"
-            )
-            return
-
-        with self._lock:
-            unchanged = self._detector is not None and self._stamp == stamp
-        if unchanged:
-            return
-
-        if self._detector is not None:
-            self._log(f"[detector] artifact changed on disk — reloading {self.model_path}")
-        self._load(stamp)
-
-    def _load(self, stamp: "tuple[int, int]") -> None:
-        self._set(STATE_LOADING, None)
-        try:
-            detector = OnnxDetector(self.model_path, self.model_name, self._intra_op_threads)
-        except ModelContractError as err:
-            self._drop(f"artifact loaded but does not match the detector contract: {err}")
-            return
-        except Exception as err:
-            self._drop(f"could not load {self.model_path}: {err}")
-            return
-
-        # PROVE IT. A session that constructs is not a session that infers.
-        try:
-            started = time.perf_counter()
-            detector.detect(_warmup_jpeg(), 0.99, None)
-            warmup_ms = (time.perf_counter() - started) * 1000.0
-        except Exception as err:
-            self._drop(f"artifact loaded but a probe inference failed: {err}")
-            return
-
-        with self._lock:
-            self._detector = detector
-            self._stamp = stamp
-            self._state = STATE_READY
-            self._reason = None
-            self._warmup_ms = warmup_ms
-            self._loaded_at = time.time()
-        self._log(
-            f"[detector] ready — {self.model_name} at {self.model_path} "
-            f"({detector.spec.width}x{detector.spec.height}, {detector.spec.num_classes} classes, "
-            f"probe {warmup_ms:.0f} ms, providers {detector.spec.providers})"
-        )
-
-    def _file_stamp(self) -> "tuple[int, int] | None":
-        try:
-            st = self.model_path.stat()
-        except OSError:
-            return None
-        if st.st_size == 0:
-            return None
-        return (st.st_size, st.st_mtime_ns)
-
-    def _drop(self, reason: str) -> None:
-        with self._lock:
-            self._detector = None
-            self._stamp = None
-            self._warmup_ms = None
-            self._loaded_at = None
-            self._state = STATE_UNAVAILABLE
-            self._reason = reason
-
-    def _set(self, state: str, reason: "str | None") -> None:
-        with self._lock:
-            self._state = state
-            self._reason = reason
-
 
 __all__ = [
+    "DEFAULT_POLL_INTERVAL_S",
     "DetectorLoader",
     "DetectorNotReady",
     "STATE_LOADING",
     "STATE_READY",
     "STATE_UNAVAILABLE",
+    "UnknownClasses",
+    "build_catalogue",
 ]

package/deploy/detector/trillboards_detector/modelpath.py

@@ -72,3 +72,35 @@ def resolve_model_path(
     if override:
         return Path(override)
     return resolve_data_dir(e) / "models" / model_name / MODEL_FILE_NAME
+
+
+def resolve_ram_budget_mb(
+    env: "os._Environ[str] | dict[str, str] | None" = None,
+) -> "int | None":
+    """`TRILLBOARDS_DETECTOR_RAM_BUDGET_MB`, or None to take the default.
+
+    An env override as well as a CLI flag because the three supervisor
+    definitions are the awkward place to add an argument — a launchd plist, a
+    systemd unit and a Windows Scheduled Task each hold their own hard-coded
+    `ProgramArguments`, and all three are rewritten by installers. An
+    environment variable reaches the process through all three without touching
+    any of them.
+
+    A malformed value RAISES rather than falling back to the default. Silently
+    ignoring `RAM_BUDGET_MB=1.5gb` would leave an operator convinced they had
+    raised a limit that never moved — an operation reporting success while doing
+    nothing, which is the failure shape this whole tree keeps catching.
+    """
+    e = os.environ if env is None else env
+    raw = (e.get("TRILLBOARDS_DETECTOR_RAM_BUDGET_MB") or "").strip()
+    if not raw:
+        return None
+    try:
+        value = int(raw)
+    except ValueError:
+        raise ValueError(
+            f"TRILLBOARDS_DETECTOR_RAM_BUDGET_MB must be an integer number of MiB, got {raw!r}"
+        ) from None
+    if value <= 0:
+        raise ValueError(f"TRILLBOARDS_DETECTOR_RAM_BUDGET_MB must be positive, got {value}")
+    return value