@trillboards/edge-sdk 0.2.81 → 0.2.82

package/deploy/detector/trillboards_detector/labels.py

@@ -1,4 +1,4 @@
-"""The class vocabulary — COMMITTED, never inferred from the artifact.
+"""The class vocabularies — COMMITTED, never inferred from the artifact.
 
 WHY THIS FILE IS A CONSTANT AND NOT A LOOKUP
 --------------------------------------------
@@ -10,8 +10,8 @@ alternative to committing them is guessing an index — which
 fallback to index 0 once scored BUSES as people for an entire eval run and the
 resulting table looked entirely plausible.
 
-This map is not hand-typed. It is what the `rfdetr` package itself computes for
-a pretrained COCO checkpoint, at `rfdetr/detr.py`::
+The COCO map is not hand-typed. It is what the `rfdetr` package itself computes
+for a pretrained COCO checkpoint, at `rfdetr/detr.py`::
 
     _class_id_to_name = {coco_id: model_class_names[i]
                          for i, coco_id in enumerate(COCO_CLASSES) if i < n}
@@ -27,11 +27,37 @@ without inventing one, and inventing one is precisely the failure above. It is
 dropped and COUNTED (`unnamed_class_drops` on /health), because a drop nobody
 can see is the other failure this codebase keeps hitting — an operation that
 reports success while doing nothing.
+
+WHY THERE IS A `ModelVocabulary` AND NOT JUST A MAP
+--------------------------------------------------
+`docs/runbooks/sensing-model-library.md` §3: "`KNOWN_CLASS_NAMES` becomes the
+union of the loaded models' vocabularies rather than a fixed COCO list." A
+frozen COCO set is the reason the service could not express a specialist AT ALL
+— a PPE model's `glove` came back `unknown` and the request 400'd, so publishing
+one would have changed nothing here. The union has to be computed from whatever
+this box actually holds, which means one vocabulary object per model and an
+index over the set of them (`ClassIndex`).
+
+ADDING A SPECIALIST IS AN EDIT TO `BUILTIN_VOCABULARIES`, and §4 rule 1 —
+"read the class list, never the title" — is why. A "fine-tuned fisheye" model
+scored worse than raw COCO because its classes were `{bus,bike,car,pedestrian,
+truck}`: a traffic model. The class list IS the model's identity, so it is
+committed alongside the name rather than trusted from a filename, a registry row
+or the artifact.
+
+A COMMITTED VOCABULARY ADVERTISES NOTHING ON ITS OWN. `ClassIndex` is built by
+`registry.py` over the models whose ARTIFACT IS ON DISK, so a vocabulary added
+here before its ONNX has been OTA'd contributes no requestable class. That is
+§4 rule 5 ("the artifact, its checksum and its score land together, or it does
+not ship") enforced by construction rather than by remembering.
 """
 
 from __future__ import annotations
 
+import re
+from dataclasses import dataclass
 from types import MappingProxyType
+from typing import Mapping, Sequence
 
 # Slot index (the position on the model's 91-wide logit axis) -> class name.
 # Slot index IS the COCO category id here; the gaps are real and deliberate.
@@ -57,7 +83,7 @@ COCO91_CLASS_NAMES: "MappingProxyType[int, str]" = MappingProxyType({
 })
 
 # How wide the logit axis must be for the map above to mean anything. Checked
-# against the loaded graph at startup — a mismatch takes the service UNHEALTHY
+# against the loaded graph at startup — a mismatch takes THAT MODEL unavailable
 # rather than relabelling every box by a constant offset. That is the whole
 # point: an off-by-one on this axis is invisible downstream, it just renames
 # every object in the venue, and the resulting numbers stay plausible.
@@ -69,9 +95,6 @@ PERSON_SLOT = 1
 assert COCO91_CLASS_NAMES[PERSON_SLOT] == "person"
 assert max(COCO91_CLASS_NAMES) < EXPECTED_LOGIT_SLOTS
 
-#: Canonical names, for validating a caller's `classes` filter.
-KNOWN_CLASS_NAMES = frozenset(COCO91_CLASS_NAMES.values())
-
 
 def normalize_class_name(name: str) -> str:
     """Fold a requested class name to its canonical form.
@@ -84,24 +107,216 @@ def normalize_class_name(name: str) -> str:
     return name.strip().lower().replace("_", " ").replace("-", " ")
 
 
-_CANONICAL_BY_NORMALIZED = {normalize_class_name(v): v for v in COCO91_CLASS_NAMES.values()}
+#: A model name is a DIRECTORY name (`models/<name>/model.onnx`) on three
+#: platforms, so it is held to the intersection of what all three accept.
+_MODEL_NAME_RE = re.compile(r"[a-z0-9][a-z0-9._-]*")
 
 
-def resolve_requested_classes(requested: list[str]) -> tuple[set[str], list[str]]:
-    """Map caller-supplied class names onto canonical ones.
+@dataclass(frozen=True)
+class ModelVocabulary:
+    """What ONE model can be asked about, and what one resident copy costs.
 
-    Returns ``(canonical_names, unknown_inputs)``. The caller decides what an
-    unknown means; this function never silently discards one, because a profile
-    naming a class the model cannot emit is exactly the `yolov8_nano` shape —
-    offered to profile authors everywhere, loadable nowhere, and ~0% for six
-    months while every surface looked fine.
+    `approx_ram_bytes` is committed for the same reason the class list is: the
+    portfolio budget has to be decided BEFORE the allocation happens, and there
+    is no way to measure a session's footprint without first creating it. An
+    admission test that loads the model to find out whether the model fits is
+    not an admission test. So the figure is measured once, written down here
+    with its provenance, and re-measured when the artifact changes — never
+    inferred at runtime.
+
+    It is deliberately allowed to be wrong by a margin: `cctv-detector-tier.md`
+    §6 notes the detector is ~9% of the binding box's RAM, "so the conclusion
+    survives being wrong about the 632 MB by several times over".
+
+    THIS FIGURE IS AN INPUT TO A DECISION MADE ABOVE, NOT THE DECISION. The
+    ceiling it is checked against is injected (see `registry.py`) because the
+    allocation authority is server-side. What this column supplies is the
+    quantity that authority does not have: `min_ram_mb` is a GATE and
+    `model_size_mb` is a FILE SIZE, and neither is resident footprint —
+    `gemma_4_e2b` carries 8000 and 2580 against a measured working set of
+    3.31 GB. `rss_delta_bytes` on /health is the service measuring the same
+    quantity per load, so the committed figure can be checked against reality.
     """
-    canonical: set[str] = set()
-    unknown: list[str] = []
-    for raw in requested:
-        hit = _CANONICAL_BY_NORMALIZED.get(normalize_class_name(raw))
-        if hit is None:
-            unknown.append(raw)
-        else:
-            canonical.add(hit)
-    return canonical, unknown
+
+    model_name: str
+    #: Logit-axis slot -> class name. The slot index is the model's own, so a
+    #: sparse map (COCO's id gaps) and a dense one are both fine.
+    slot_names: "Mapping[int, str]"
+    #: How wide the class axis must be for `slot_names` to describe it.
+    logit_slots: int
+    #: Peak RSS of ONE resident session, in bytes.
+    approx_ram_bytes: int
+
+    def __post_init__(self) -> None:
+        # The model name IS A DIRECTORY NAME — `resolve_model_path` puts the
+        # artifact at `models/<model-name>/model.onnx` on every platform — so it
+        # is restricted to what is safe in a path on all three, and NOT folded
+        # by `normalize_class_name` (which turns `_` into a space; the shipped
+        # `rfdetr_medium` is a valid name and an invalid class).
+        if not self.model_name or not _MODEL_NAME_RE.fullmatch(self.model_name):
+            raise ValueError(
+                f"model name {self.model_name!r} must match {_MODEL_NAME_RE.pattern} — it is a "
+                "directory name on macOS, Linux and Windows"
+            )
+        if self.logit_slots <= 0:
+            raise ValueError(f"{self.model_name}: logit_slots must be positive, got {self.logit_slots}")
+        if self.approx_ram_bytes <= 0:
+            raise ValueError(f"{self.model_name}: approx_ram_bytes must be positive")
+        if not self.slot_names:
+            raise ValueError(f"{self.model_name}: a model with no named class can answer nothing")
+        for slot, name in self.slot_names.items():
+            if not isinstance(slot, int) or slot < 0 or slot >= self.logit_slots:
+                raise ValueError(
+                    f"{self.model_name}: slot {slot!r} is outside the declared {self.logit_slots}-wide axis"
+                )
+            # ALREADY-CANONICAL NAMES ONLY. `_to_wire` puts the DECLARED name on
+            # the wire and `postprocess` filters on the CANONICAL one, so a
+            # vocabulary declaring `cell_phone` would emit a label the caller's
+            # own request had just been folded away from — a class silently
+            # matching nothing, on a box where everything looks loaded. Checked
+            # at import, so a sloppy specialist fails at start rather than in a
+            # venue.
+            if not name or normalize_class_name(name) != name:
+                raise ValueError(
+                    f"{self.model_name}: class name {name!r} is not canonical "
+                    f"(expected {normalize_class_name(name)!r})"
+                )
+        if len(set(self.slot_names.values())) != len(self.slot_names):
+            raise ValueError(f"{self.model_name}: two slots share one class name, so a filter would be ambiguous")
+
+    @property
+    def class_names(self) -> "frozenset[str]":
+        return frozenset(self.slot_names.values())
+
+
+#: The artifact this service was built around and the ONLY one measured.
+#:
+#: 632 MB peak RSS — `docs/runbooks/cctv-detector-tier.md` §6, measured on
+#: macOS/arm64 against the shipped 135,146,350-byte fp32 export. Treated as MiB
+#: here, which over-reserves by ~4.9% against the runbook's decimal MB: the safe
+#: direction, since under-reserving is what the OOM killer resolves.
+RFDETR_MEDIUM = ModelVocabulary(
+    model_name="rfdetr_medium",
+    slot_names=COCO91_CLASS_NAMES,
+    logit_slots=EXPECTED_LOGIT_SLOTS,
+    approx_ram_bytes=632 * 1024 * 1024,
+)
+
+#: Every model this build knows how to label, IN PRIORITY ORDER.
+#:
+#: Order is load-bearing and it is the whole disambiguation rule: a class named
+#: by more than one vocabulary routes to the FIRST entry here that names it, so
+#: adding a specialist can never move an existing class off the model it was
+#: scored on. `person` stays on `rfdetr_medium` even after a PPE model that also
+#: emits `person` arrives, and that is correct rather than merely deterministic
+#: — the 98.8/98.8 pooled figure in `cctv-detector-tier.md` is a claim about THIS
+#: model's person, not about the concept.
+#:
+#: ONE ENTRY TODAY. That is not the multi-model machinery being unused; it is
+#: §4 rule 5 holding: a vocabulary here without a published artifact advertises
+#: nothing (see `ClassIndex`, built over models whose file is present), and
+#: publishing is a separate task. What changed is that the service can now
+#: EXPRESS a second entry, which before this it structurally could not.
+BUILTIN_VOCABULARIES: "tuple[ModelVocabulary, ...]" = (RFDETR_MEDIUM,)
+
+
+class ClassIndex:
+    """The union vocabulary of a SET of models, and who owns each class.
+
+    Built by `registry.py` over the models whose artifact is actually on the
+    box, so it answers two questions the old fixed `KNOWN_CLASS_NAMES` could
+    not: what may a caller ask for right now, and which model has to run to
+    answer it.
+    """
+
+    def __init__(self, vocabularies: "Sequence[ModelVocabulary]"):
+        self._vocabularies = tuple(vocabularies)
+        owner: "dict[str, str]" = {}
+        for vocabulary in self._vocabularies:
+            for name in sorted(vocabulary.class_names):
+                # First-in-catalogue-order wins. `setdefault`, not assignment:
+                # a later specialist must not capture a class an earlier model
+                # already owns.
+                owner.setdefault(name, vocabulary.model_name)
+        if len({v.model_name for v in self._vocabularies}) != len(self._vocabularies):
+            raise ValueError("two vocabularies share one model name")
+        self._owner = owner
+        self._class_names = frozenset(owner)
+
+    @property
+    def class_names(self) -> "frozenset[str]":
+        """The union. This is what a caller may ask for, and nothing else."""
+        return self._class_names
+
+    @property
+    def model_names(self) -> "tuple[str, ...]":
+        return tuple(v.model_name for v in self._vocabularies)
+
+    @property
+    def vocabularies(self) -> "tuple[ModelVocabulary, ...]":
+        return self._vocabularies
+
+    def owner_of(self, canonical_class: str) -> "str | None":
+        return self._owner.get(canonical_class)
+
+    def resolve(self, requested: "list[str]") -> "tuple[set[str], list[str]]":
+        """Map caller-supplied class names onto canonical ones.
+
+        Returns ``(canonical_names, unknown_inputs)``. Never silently discards
+        an unknown, because a profile naming a class no model on this box can
+        emit is exactly the `yolov8_nano` shape — offered to profile authors
+        everywhere, loadable nowhere, and ~0% for six months while every
+        surface looked fine. The caller turns a non-empty `unknown` into a 400.
+        """
+        canonical: "set[str]" = set()
+        unknown: "list[str]" = []
+        for raw in requested:
+            folded = normalize_class_name(raw)
+            if folded in self._class_names:
+                canonical.add(folded)
+            else:
+                unknown.append(raw)
+        return canonical, unknown
+
+    def assign(self, wanted: "set[str] | None") -> "list[tuple[ModelVocabulary, set[str] | None]]":
+        """Split a request across the models that have to run, in catalogue order.
+
+        `wanted=None` — the wire's "every class" — expands to the whole union
+        FIRST and is then routed like any other request. Running each model over
+        its own full vocabulary instead would double-report every class two
+        models share: one `person` box from the general detector and another
+        from a specialist, for the same person, with nothing downstream able to
+        tell that apart from two people. Expanding and routing means an
+        overlapping class is answered exactly once, by its owner.
+
+        A model whose assignment is its ENTIRE vocabulary gets `None`, which is
+        the same object the single-model service passed before this existed —
+        so the one-model box takes byte-identical code through `_to_wire`.
+        """
+        target = self._class_names if wanted is None else wanted
+        by_model: "dict[str, set[str]]" = {}
+        for name in target:
+            owner = self._owner.get(name)
+            if owner is None:
+                continue
+            by_model.setdefault(owner, set()).add(name)
+
+        plan: "list[tuple[ModelVocabulary, set[str] | None]]" = []
+        for vocabulary in self._vocabularies:
+            classes = by_model.get(vocabulary.model_name)
+            if not classes:
+                continue
+            plan.append((vocabulary, None if classes == set(vocabulary.class_names) else classes))
+        return plan
+
+
+__all__ = [
+    "BUILTIN_VOCABULARIES",
+    "COCO91_CLASS_NAMES",
+    "EXPECTED_LOGIT_SLOTS",
+    "PERSON_SLOT",
+    "RFDETR_MEDIUM",
+    "ClassIndex",
+    "ModelVocabulary",
+    "normalize_class_name",
+]