@trillboards/edge-sdk 0.2.81 → 0.2.82

package/deploy/detector/trillboards_detector/server.py

@@ -32,8 +32,7 @@ import sys as _sys
 import threading
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 
-from .errors import DetectorNotReady
-from .labels import KNOWN_CLASS_NAMES, resolve_requested_classes
+from .errors import DetectorNotReady, UnknownClasses
 
 #: Loopback only. litert-lm owns 9379; this is a SECOND service, not a route on
 #: that one — see `LocalDetectorClient.ts` for why (its own uv tool, its own
@@ -68,14 +67,24 @@ class WireError(Exception):
         self.message = message
 
 
-def parse_detect_request(raw: bytes) -> tuple[bytes, float, "set[str] | None"]:
-    """Body bytes -> (jpeg, min_confidence, wanted classes or None for all).
+def parse_detect_request(raw: bytes) -> tuple[bytes, float, "list[str] | None"]:
+    """Body bytes -> (jpeg, min_confidence, requested class names or None for all).
 
     Every refusal here is a 400: the caller sent something this service cannot
     act on, and saying so beats guessing. Guessing is how a profile naming a
     class the model cannot emit returns an empty frame forever while looking
     healthy — `yolov8_nano`, offered to ~97 of 114 profiles and loadable
     nowhere, `vehicle_count` at ~0% fleet-wide for six months.
+
+    THE CLASS NAMES COME BACK RAW, deliberately. Which classes exist is a
+    property of the models on THIS BOX at THIS MOMENT — a specialist's ONNX
+    lands over the air and widens the vocabulary with no restart — so it cannot
+    be a constant in the wire layer, which is what `KNOWN_CLASS_NAMES` used to
+    be. `docs/runbooks/sensing-model-library.md` §3 puts class -> model routing
+    in the service "because the service is the only component that knows what is
+    resident", and the loader is the half of the service that knows. The
+    resolution and the 400 still happen BEFORE any inference; only the authority
+    moved.
     """
     try:
         payload = json.loads(raw.decode("utf-8"))
@@ -113,38 +122,7 @@ def parse_detect_request(raw: bytes) -> tuple[bytes, float, "set[str] | None"]:
         raise WireError(400, "`classes` must be an array of strings")
     if not raw_classes:
         raise WireError(400, "`classes` was an empty array; omit the key to mean every class")
-
-    wanted, unknown = resolve_requested_classes(raw_classes)
-    # ANY unknown class is a 400, not just all of them.
-    #
-    # This used to reject only when `wanted` came back empty, so a request for
-    # ["person", "glove"] against a COCO-only model returned person detections
-    # and dropped `glove` on the floor. `resolve_requested_classes` keeps its own
-    # promise — it returns the unknowns rather than discarding them — and its
-    # docstring says exactly why: "a profile naming a class the model cannot emit
-    # is exactly the `yolov8_nano` shape". The caller then discarded them one
-    # level up, which is where the promise was actually broken.
-    #
-    # The partial case is the dangerous one and it becomes the COMMON one the
-    # moment specialist models exist: a PPE profile asks for `glove` and
-    # `hairnet` alongside `person`, and on a box holding only the general
-    # detector the operator would get person counts and silence about gloves.
-    #
-    # Refusing loses the person detections too, which is the cost. It is the
-    # right trade: which models are resident is decided upstream by the profile
-    # push, so a class the box cannot answer is a configuration error, and the
-    # client maps a 400 to `DetectorUnavailableError` -> shadow mode records
-    # `unavailable`. A wrong configuration becomes visible instead of becoming a
-    # quieter answer.
-    if unknown:
-        raise WireError(
-            400,
-            f"requested classes not in this model's vocabulary: {unknown}. "
-            f"Known classes: {sorted(KNOWN_CLASS_NAMES)}",
-        )
-    if not wanted:
-        raise WireError(400, "`classes` resolved to nothing requestable")
-    return jpeg, min_confidence, wanted
+    return jpeg, min_confidence, raw_classes
 
 
 def _assert_wire_safe(detections: list) -> None:
@@ -177,7 +155,26 @@ def _assert_wire_safe(detections: list) -> None:
             )
 
 
-def build_detect_response(batch, model_name: str) -> dict:
+#: How several models' names are joined into the one `model` string the wire
+#: carries. `LocalDetectorClient` types it `string | null` and never branches on
+#: it (`LocalDetectorClient.ts`: `model: typeof parsed?.model === 'string' &&
+#: parsed.model ? parsed.model : null`), so a joined string is contract-safe —
+#: verified against the client rather than assumed. It is an ATTRIBUTION field,
+#: and losing the second name would make a merged answer indistinguishable from
+#: a single-model one when a specialist later turns out to be wrong.
+MODEL_JOIN = "+"
+
+
+def build_detect_response(batch) -> dict:
+    models = list(getattr(batch, "models", []) or [])
+    if not models:
+        # An unattributed result. `model` would serialise as `""` -> the client
+        # reads null, and every downstream reader loses the ability to say which
+        # artifact produced a detection. `cctv-detector-tier.md` §5 rule 2 is a
+        # whole scar about exactly that class of missing provenance, so this is
+        # a 500 rather than a plausible 200.
+        raise ValueError("batch names no model; a detection that cannot be attributed must not ship")
+
     body = {
         "detections": [
             {
@@ -192,7 +189,10 @@ def build_detect_response(batch, model_name: str) -> dict:
         # ~63 ms in `docs/runbooks/cctv-detector-tier.md` — a decode cost folded
         # in here would quietly invalidate that comparison later.
         "inference_ms": batch.inference_ms,
-        "model": model_name,
+        # THE SET THAT ANSWERED — `sensing-model-library.md` §3. One name on a
+        # single-model box, so the shipped payload is byte-identical to what it
+        # was before the library existed.
+        "model": MODEL_JOIN.join(models),
     }
     # A non-finite timing would serialise as a bare `NaN`, which is INVALID JSON
     # (`json.dumps` emits it by default; `JSON.parse` refuses it). The client
@@ -272,11 +272,30 @@ class DetectorHandler(BaseHTTPRequestHandler):
         loader = self.server.loader  # type: ignore[attr-defined]
         try:
             raw = self._read_body()
-            jpeg, min_confidence, wanted = parse_detect_request(raw)
+            jpeg, min_confidence, requested = parse_detect_request(raw)
         except WireError as err:
             self._json(err.status, {"error": err.message})
             return
 
+        wanted = None
+        if requested is not None:
+            try:
+                wanted = loader.resolve_classes(requested)
+            except UnknownClasses as err:
+                # 400, BEFORE INFERENCE, on ANY unknown — not just on all of
+                # them. The partial case is the dangerous one and it becomes the
+                # COMMON one the moment specialists exist: a PPE profile asks for
+                # `glove` and `hairnet` alongside `person`, and on a box holding
+                # only the general detector two thirds of the question would
+                # vanish into a 200 that looks like an answer. Refusing costs the
+                # `person` detections too; that is the right trade, because which
+                # models are on the box was decided upstream by the profile push,
+                # so a class this box cannot answer is a configuration error and
+                # the client maps 400 to `DetectorUnavailableError`. Visible
+                # beats quieter.
+                self._json(400, {"error": err.detail or str(err)})
+                return
+
         try:
             batch = loader.detect(jpeg, min_confidence, wanted)
         except DetectorNotReady as err:
@@ -290,7 +309,7 @@ class DetectorHandler(BaseHTTPRequestHandler):
             return
 
         try:
-            body = build_detect_response(batch, loader.model_name)
+            body = build_detect_response(batch)
         except ValueError as err:
             self._log(f"[detector] REFUSING to emit a malformed payload: {err}")
             self._json(500, {"error": f"refused to emit a malformed payload: {err}"})

package/deploy/detector/trillboards_detector/session.py

@@ -39,7 +39,9 @@ import numpy as np
 import onnxruntime as ort
 from PIL import Image
 
-from .labels import COCO91_CLASS_NAMES, EXPECTED_LOGIT_SLOTS
+from .detections import Detection, DetectionBatch
+from .errors import ModelContractError
+from .labels import ModelVocabulary
 
 #: `rfdetr/detr.py` — ImageNet statistics, applied AFTER scaling to [0,1].
 IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32).reshape(3, 1, 1)
@@ -52,34 +54,6 @@ IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32).reshape(3, 1, 1
 NUM_SELECT = 300
 
 
-@dataclass(frozen=True)
-class Detection:
-    """One wire-shaped detection. Pixel box, canonical label, [0,1] confidence."""
-
-    label: str
-    confidence: float
-    x: float
-    y: float
-    width: float
-    height: float
-
-
-@dataclass
-class DetectionBatch:
-    detections: list[Detection]
-    #: The ORT forward pass alone, in ms — directly comparable to the ~63 ms in
-    #: `docs/runbooks/cctv-detector-tier.md`. Decode and post-processing are
-    #: reported separately (`total_ms`) so a slow JPEG decode cannot hide inside
-    #: a number the runbook will later be checked against.
-    inference_ms: float = 0.0
-    total_ms: float = 0.0
-    #: Boxes that survived the threshold but cover no pixels after clamping to
-    #: the frame. Counted, never silently swallowed — see `_to_wire`.
-    degenerate_dropped: int = 0
-    #: Detections whose argmax landed on one of the eleven COCO id gaps.
-    unnamed_class_dropped: int = 0
-
-
 @dataclass
 class GraphSpec:
     """What the loaded artifact actually is, read off the graph, never assumed."""
@@ -94,10 +68,6 @@ class GraphSpec:
     providers: list[str] = field(default_factory=list)
 
 
-class ModelContractError(RuntimeError):
-    """The artifact loaded, but it is not the graph this service can label."""
-
-
 def preprocess(jpeg: bytes, width: int, height: int) -> tuple[np.ndarray, int, int]:
     """JPEG bytes -> NCHW float32, plus the SUBMITTED frame's pixel size.
 
@@ -126,6 +96,8 @@ def postprocess(
     frame_h: int,
     min_confidence: float,
     wanted: "set[str] | None" = None,
+    *,
+    vocabulary: ModelVocabulary,
 ) -> DetectionBatch:
     """Raw graph outputs -> wire detections, in the submitted frame's pixels.
 
@@ -134,6 +106,14 @@ def postprocess(
     `wanted` filters HERE, at the service, because the alternative is shipping
     every box across loopback to throw most away — `LocalDetectorClient`'s own
     reasoning, and the reason `classes` rides the wire at all.
+
+    `vocabulary` IS REQUIRED AND HAS NO DEFAULT. It used to be the module-level
+    COCO-91 map, which is exactly what made a specialist inexpressible — and a
+    default naming the shipped model would be worse than the constant it
+    replaces: a PPE model would silently get COCO names for its own slots and
+    every number downstream would stay plausible. That is `cctv-detector-tier.md`
+    §5 rule 2 with the sign flipped, and it is the reason the argument is
+    keyword-only: a positional one could be filled by the wrong thing.
     """
     # (1, Q, C) -> (Q, C); the graph is batch-1 by construction.
     prob = _sigmoid(logits[0])
@@ -161,7 +141,7 @@ def postprocess(
     x1 = np.clip((cx + 0.5 * w) * frame_w, 0.0, frame_w)
     y1 = np.clip((cy + 0.5 * h) * frame_h, 0.0, frame_h)
 
-    return _to_wire(scores, class_idx, x0, y0, x1, y1, wanted)
+    return _to_wire(scores, class_idx, x0, y0, x1, y1, wanted, vocabulary)
 
 
 def _to_wire(
@@ -172,14 +152,17 @@ def _to_wire(
     x1: np.ndarray,
     y1: np.ndarray,
     wanted: "set[str] | None",
+    vocabulary: ModelVocabulary,
 ) -> DetectionBatch:
     """Assemble detections, dropping only what CANNOT be put on the wire.
 
     Two drops, and each is counted rather than swallowed:
 
-    * an UNNAMED CLASS SLOT. Eleven of the ninety-one slots are COCO id gaps
-      with no name. `docs/runbooks/cctv-detector-tier.md` §5 rule 2 forbids
-      guessing; a detection with no nameable class is dropped.
+    * an UNNAMED CLASS SLOT. For COCO-91, eleven of the ninety-one slots are
+      category-id gaps with no name; a specialist may have its own. The name
+      comes from THIS MODEL's committed vocabulary and from nowhere else.
+      `docs/runbooks/cctv-detector-tier.md` §5 rule 2 forbids guessing; a
+      detection with no nameable class is dropped.
     * a ZERO-EXTENT BOX. A box clamped flush against a frame edge can have zero
       width or height, and `LocalDetectorClient` REJECTS THE ENTIRE PAYLOAD on
       one — correctly, since it cannot tell a schema-drifted service from a
@@ -197,8 +180,9 @@ def _to_wire(
     degenerate = 0
     unnamed = 0
 
+    slot_names = vocabulary.slot_names
     for i in range(scores.shape[0]):
-        name = COCO91_CLASS_NAMES.get(int(class_idx[i]))
+        name = slot_names.get(int(class_idx[i]))
         if name is None:
             unnamed += 1
             continue
@@ -221,7 +205,12 @@ def _to_wire(
         # sigmoid is (0,1); clamp only guards float64 round-trip at the edges.
         out.append(Detection(name, min(1.0, max(0.0, conf)), left, top, width, height))
 
-    return DetectionBatch(out, degenerate_dropped=degenerate, unnamed_class_dropped=unnamed)
+    return DetectionBatch(
+        out,
+        degenerate_dropped=degenerate,
+        unnamed_class_dropped=unnamed,
+        models=[vocabulary.model_name],
+    )
 
 
 def _sigmoid(x: np.ndarray) -> np.ndarray:
@@ -250,21 +239,30 @@ class OnnxDetector:
     overrides them. Pinning them is the mistake the same section names.
     """
 
-    def __init__(self, model_path: Path, model_name: str, intra_op_threads: "int | None" = None):
+    def __init__(
+        self,
+        model_path: Path,
+        vocabulary: ModelVocabulary,
+        intra_op_threads: "int | None" = None,
+    ):
         self.model_path = model_path
-        self.model_name = model_name
+        self.vocabulary = vocabulary
+        self.model_name = vocabulary.model_name
         self._lock = threading.Lock()
 
         opts = ort.SessionOptions()
         if intra_op_threads is not None:
             opts.intra_op_num_threads = intra_op_threads
-        # Loopback service, one process, one model: log only what a fault needs.
+        # Loopback service, one process: log only what a fault needs. Several
+        # sessions may be resident at once now (`registry.py`), which is exactly
+        # why the thread counts below stay at ORT's default — pinning them would
+        # multiply an already non-monotonic pool by the number of models.
         opts.log_severity_level = 3
 
         self._session = ort.InferenceSession(
             str(model_path), sess_options=opts, providers=["CPUExecutionProvider"]
         )
-        self.spec = _read_graph_spec(self._session)
+        self.spec = _read_graph_spec(self._session, vocabulary)
 
     def detect(
         self,
@@ -282,21 +280,38 @@ class OnnxDetector:
             )
             infer_ms = (time.perf_counter() - infer_started) * 1000.0
 
-        batch = postprocess(outputs[0], outputs[1], frame_w, frame_h, min_confidence, wanted)
+        batch = postprocess(
+            outputs[0],
+            outputs[1],
+            frame_w,
+            frame_h,
+            min_confidence,
+            wanted,
+            vocabulary=self.vocabulary,
+        )
         batch.inference_ms = infer_ms
         batch.total_ms = (time.perf_counter() - started) * 1000.0
         return batch
 
 
-def _read_graph_spec(session: "ort.InferenceSession") -> GraphSpec:
+def _read_graph_spec(
+    session: "ort.InferenceSession",
+    vocabulary: ModelVocabulary,
+) -> GraphSpec:
     """Read the contract off the loaded graph, and REFUSE a graph we cannot label.
 
-    The exported artifact carries no class metadata, so the label map in
-    `labels.py` is the only thing naming its 91 slots. If the graph's class axis
-    is not 91 wide, that map does not describe it — and applying it anyway
-    renames every object in the venue while every number stays plausible. That
-    is the `yolov8_nano` failure with the sign flipped: instead of a model
-    offered and never loadable, a model loaded and never right.
+    The exported artifact carries no class metadata, so the committed
+    vocabulary in `labels.py` is the only thing naming its slots. If the graph's
+    class axis is not the width that vocabulary declares, it does not describe
+    this artifact — and applying it anyway renames every object in the venue
+    while every number stays plausible. That is the `yolov8_nano` failure with
+    the sign flipped: instead of a model offered and never loadable, a model
+    loaded and never right.
+
+    THE CHECK IS PER MODEL, NOT PER SERVICE. With a library, "91 slots" is one
+    model's fact rather than the box's, so the width is read off the vocabulary
+    being loaded. A specialist with a 4-wide axis loads happily against ITS OWN
+    vocabulary and is still refused against anyone else's.
 
     So a mismatch raises, the service goes UNHEALTHY with the reason, and
     nothing is emitted. The 2.1%-of-events figure the placement decision rests
@@ -335,11 +350,11 @@ def _read_graph_spec(session: "ort.InferenceSession") -> GraphSpec:
         raise ModelContractError(f"`labels` is not (N, Q, C): {logit_shape}")
 
     num_classes = logit_shape[2]
-    if num_classes != EXPECTED_LOGIT_SLOTS:
+    if num_classes != vocabulary.logit_slots:
         raise ModelContractError(
-            f"model has {num_classes} class slots; the committed label map describes "
-            f"{EXPECTED_LOGIT_SLOTS}. Refusing rather than labelling boxes by an "
-            "index this map does not name — see labels.py."
+            f"model has {num_classes} class slots; the committed vocabulary for "
+            f"{vocabulary.model_name} describes {vocabulary.logit_slots}. Refusing rather "
+            "than labelling boxes by an index that vocabulary does not name — see labels.py."
         )
 
     return GraphSpec(
@@ -352,3 +367,17 @@ def _read_graph_spec(session: "ort.InferenceSession") -> GraphSpec:
         num_classes=int(num_classes),
         providers=list(session.get_providers()),
     )
+
+
+#: Re-exported so `from .session import DetectionBatch` keeps working. ONE
+#: definition, in `detections.py`, which is stdlib-only so `registry.py` can
+#: merge two models' answers on a runner that has no onnxruntime.
+__all__ = [
+    "Detection",
+    "DetectionBatch",
+    "GraphSpec",
+    "ModelContractError",
+    "OnnxDetector",
+    "postprocess",
+    "preprocess",
+]

package/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.81';
+const SDK_VERSION = '0.2.82';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();

package/dist/diagnose.d.ts

@@ -31,7 +31,7 @@ export interface DiagnosticReport {
         skipped: number;
     };
 }
-declare const SDK_VERSION = "0.2.81";
+declare const SDK_VERSION = "0.2.82";
 declare function checkNodeVersion(): CheckResult;
 declare function checkPlatform(): CheckResult;
 declare function checkMemory(): CheckResult;

package/dist/diagnose.js

@@ -63,7 +63,7 @@ const localNetworkAccess_1 = require("./localNetworkAccess");
 // ---------------------------------------------------------------------------
 // SDK version — mirrors package.json; kept in sync by CI
 // ---------------------------------------------------------------------------
-const SDK_VERSION = '0.2.81';
+const SDK_VERSION = '0.2.82';
 exports._SDK_VERSION = SDK_VERSION;
 // ---------------------------------------------------------------------------
 // ANSI helpers (no external deps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-sdk",
-  "version": "0.2.81",
+  "version": "0.2.82",
   "description": "Composable cross-platform Edge AI SDK for audience sensing on DOOH/CTV devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",