@trillboards/edge-sdk 0.2.74 → 0.2.76

package/deploy/detector/tests/test_session.py

@@ -0,0 +1,242 @@
+"""Post-processing, against hand-built tensors. No model, no ORT session.
+
+These are the arithmetic the measured 98.8/98.8 depends on: the top-k selection
+rule, the cxcywh -> pixel conversion, the class-slot lookup. A transcription bug
+in any of them produces detections that are entirely plausible and entirely
+wrong — the shape `docs/runbooks/cctv-detector-tier.md` §5 rule 2 records, where
+a class-index fallback scored BUSES as people for a whole run.
+
+Skipped rather than failed without numpy: the wire contract in `test_server.py`
+needs no third-party package at all and is the half that must always run.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+try:
+    import numpy as np
+
+    from trillboards_detector.session import (
+        ModelContractError,
+        _read_graph_spec,
+        _sigmoid,
+        postprocess,
+    )
+
+    HAVE_NUMPY = True
+except ImportError:  # pragma: no cover - exercised only on a bare interpreter
+    HAVE_NUMPY = False
+
+
+def _logits(pairs, num_queries=3, num_classes=91):
+    """Build a logit tensor whose sigmoid gives EXACTLY the requested scores."""
+    out = np.full((1, num_queries, num_classes), -30.0, dtype=np.float32)
+    for (q, c), score in pairs.items():
+        out[0, q, c] = np.log(score / (1.0 - score))
+    return out
+
+
+def _boxes(rows, num_queries=3):
+    out = np.zeros((1, num_queries, 4), dtype=np.float32)
+    for q, box in rows.items():
+        out[0, q] = box
+    return out
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestPostprocess(unittest.TestCase):
+    def test_cxcywh_normalised_becomes_pixels_of_the_submitted_frame(self):
+        # Centre of a 640x480 frame, half its width and height.
+        batch = postprocess(
+            _boxes({0: (0.5, 0.5, 0.5, 0.5)}),
+            _logits({(0, 1): 0.9}),
+            frame_w=640,
+            frame_h=480,
+            min_confidence=0.25,
+        )
+        self.assertEqual(len(batch.detections), 1)
+        d = batch.detections[0]
+        self.assertEqual(d.label, "person")
+        self.assertAlmostEqual(d.confidence, 0.9, places=5)
+        self.assertAlmostEqual(d.x, 160.0, places=3)
+        self.assertAlmostEqual(d.y, 120.0, places=3)
+        self.assertAlmostEqual(d.width, 320.0, places=3)
+        self.assertAlmostEqual(d.height, 240.0, places=3)
+
+    def test_a_box_running_off_the_frame_is_clamped_to_it(self):
+        batch = postprocess(
+            _boxes({0: (0.0, 0.0, 0.5, 0.5)}),  # centred on the top-left corner
+            _logits({(0, 1): 0.9}),
+            frame_w=100,
+            frame_h=100,
+            min_confidence=0.25,
+        )
+        d = batch.detections[0]
+        self.assertEqual((d.x, d.y), (0.0, 0.0))
+        self.assertAlmostEqual(d.width, 25.0, places=3)
+        self.assertAlmostEqual(d.height, 25.0, places=3)
+
+    def test_class_slot_1_is_person_and_slot_3_is_car(self):
+        batch = postprocess(
+            _boxes({0: (0.5, 0.5, 0.2, 0.2), 1: (0.3, 0.3, 0.2, 0.2)}),
+            _logits({(0, 1): 0.9, (1, 3): 0.8}),
+            frame_w=200,
+            frame_h=200,
+            min_confidence=0.25,
+        )
+        self.assertEqual(sorted(d.label for d in batch.detections), ["car", "person"])
+
+    def test_below_threshold_is_dropped_strictly_greater_than(self):
+        """`PostProcess` filters `scores > threshold`. Exactly on the threshold
+        is OUT, and that has to match: the operating point in the runbook was
+        chosen against this comparison, not a >=."""
+        args = (_boxes({0: (0.5, 0.5, 0.2, 0.2)}), _logits({(0, 1): 0.5}), 100, 100)
+        self.assertEqual(len(postprocess(*args, min_confidence=0.4).detections), 1)
+        self.assertEqual(len(postprocess(*args, min_confidence=0.5).detections), 0)
+
+    def test_an_unnamed_class_slot_is_dropped_and_counted_never_labelled(self):
+        """Eleven of the ninety-one slots are COCO id gaps. Slot 12 is one.
+
+        Naming it anything would be exactly the fabrication the runbook forbids,
+        and dropping it silently is the failure this whole stack keeps hitting.
+        So: dropped, and counted where `/health` publishes it.
+        """
+        batch = postprocess(
+            _boxes({0: (0.5, 0.5, 0.2, 0.2)}),
+            _logits({(0, 12): 0.9}),
+            frame_w=100,
+            frame_h=100,
+            min_confidence=0.25,
+        )
+        self.assertEqual(batch.detections, [])
+        self.assertEqual(batch.unnamed_class_dropped, 1)
+
+    def test_a_zero_extent_box_is_dropped_and_counted(self):
+        """A box with no width covers no pixels and would make the CLIENT reject
+        the entire frame's result. Dropping it costs one artifact; emitting it
+        costs every other detection in the frame."""
+        batch = postprocess(
+            _boxes({0: (0.5, 0.5, 0.0, 0.4), 1: (0.5, 0.5, 0.4, 0.4)}),
+            _logits({(0, 1): 0.9, (1, 1): 0.8}),
+            frame_w=100,
+            frame_h=100,
+            min_confidence=0.25,
+        )
+        self.assertEqual(len(batch.detections), 1)
+        self.assertEqual(batch.degenerate_dropped, 1)
+
+    def test_the_class_filter_runs_at_the_service(self):
+        args = (
+            _boxes({0: (0.5, 0.5, 0.2, 0.2), 1: (0.3, 0.3, 0.2, 0.2)}),
+            _logits({(0, 1): 0.9, (1, 3): 0.8}),
+            100,
+            100,
+            0.25,
+        )
+        self.assertEqual([d.label for d in postprocess(*args, wanted={"car"}).detections], ["car"])
+        self.assertEqual(len(postprocess(*args, wanted=None).detections), 2)
+
+    def test_selection_keeps_the_top_300_pairs_before_thresholding(self):
+        """`num_select=300` is applied FIRST, exactly as upstream does.
+
+        Thresholding first would return rows the measured arm never saw on a
+        busy frame — a difference invisible on an empty one and decisive on a
+        crowded one.
+        """
+        # 400 queries each with one class above the threshold: only 300 survive.
+        scores = {(q, 1): 0.9 for q in range(400)}
+        batch = postprocess(
+            _boxes({q: (0.5, 0.5, 0.2, 0.2) for q in range(400)}, num_queries=400),
+            _logits(scores, num_queries=400),
+            frame_w=100,
+            frame_h=100,
+            min_confidence=0.25,
+        )
+        self.assertEqual(len(batch.detections), 300)
+
+    def test_confidences_are_always_inside_the_unit_interval(self):
+        rng = np.random.default_rng(7)
+        logits = rng.normal(0.0, 40.0, size=(1, 300, 91)).astype(np.float32)
+        boxes = np.abs(rng.normal(0.4, 0.2, size=(1, 300, 4))).astype(np.float32)
+        batch = postprocess(boxes, logits, 640, 480, 0.0)
+        for d in batch.detections:
+            self.assertGreaterEqual(d.confidence, 0.0)
+            self.assertLessEqual(d.confidence, 1.0)
+
+    def test_sigmoid_does_not_overflow_on_a_large_negative_logit(self):
+        out = _sigmoid(np.array([-800.0, 800.0, 0.0], dtype=np.float32))
+        self.assertTrue(np.all(np.isfinite(out)))
+        self.assertAlmostEqual(float(out[2]), 0.5, places=6)
+
+
+class _FakeIo:
+    def __init__(self, name, shape):
+        self.name = name
+        self.shape = shape
+
+
+class _FakeSession:
+    def __init__(self, inputs, outputs):
+        self._inputs = inputs
+        self._outputs = outputs
+
+    def get_inputs(self):
+        return self._inputs
+
+    def get_outputs(self):
+        return self._outputs
+
+    def get_providers(self):
+        return ["CPUExecutionProvider"]
+
+
+@unittest.skipUnless(HAVE_NUMPY, "numpy is not installed")
+class TestGraphContract(unittest.TestCase):
+    """A graph we cannot label must take the service UNHEALTHY, not relabel boxes.
+
+    An off-by-one on the class axis renames every object in the venue and every
+    number stays plausible — the `yolov8_nano` failure with the sign flipped:
+    instead of a model offered and never loadable, a model loaded and never
+    right.
+    """
+
+    GOOD_IN = [_FakeIo("input", [1, 3, 576, 576])]
+    GOOD_OUT = [_FakeIo("dets", [1, 300, 4]), _FakeIo("labels", [1, 300, 91])]
+
+    def test_accepts_the_shipped_graph(self):
+        spec = _read_graph_spec(_FakeSession(self.GOOD_IN, self.GOOD_OUT))
+        self.assertEqual((spec.width, spec.height), (576, 576))
+        self.assertEqual(spec.num_classes, 91)
+        self.assertEqual(spec.input_name, "input")
+
+    def test_refuses_a_class_axis_the_label_map_does_not_describe(self):
+        out = [_FakeIo("dets", [1, 300, 4]), _FakeIo("labels", [1, 300, 80])]
+        with self.assertRaisesRegex(ModelContractError, "80 class slots"):
+            _read_graph_spec(_FakeSession(self.GOOD_IN, out))
+
+    def test_refuses_a_dynamic_resolution(self):
+        """imgsz is one of the two numbers a detector arm is meaningless
+        without (§5 rule 1). A dynamic axis means it is not recoverable from
+        the artifact at all."""
+        dyn = [_FakeIo("input", [1, 3, "height", "width"])]
+        with self.assertRaisesRegex(ModelContractError, "fixed input resolution"):
+            _read_graph_spec(_FakeSession(dyn, self.GOOD_OUT))
+
+    def test_refuses_unexpected_output_names(self):
+        out = [_FakeIo("boxes", [1, 300, 4]), _FakeIo("scores", [1, 300, 91])]
+        with self.assertRaisesRegex(ModelContractError, "dets"):
+            _read_graph_spec(_FakeSession(self.GOOD_IN, out))
+
+    def test_refuses_a_multi_input_graph(self):
+        """An open-vocabulary model would carry a text input. Per the runbook
+        those do not survive ONNX export at all — one exported artifact is one
+        class list, permanently — so a second input means this is not the model
+        the label map belongs to."""
+        two = [_FakeIo("images", [1, 3, 576, 576]), _FakeIo("text", [1, 512])]
+        with self.assertRaisesRegex(ModelContractError, "one graph input"):
+            _read_graph_spec(_FakeSession(two, self.GOOD_OUT))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/deploy/detector/trillboards_detector/__init__.py

@@ -0,0 +1,8 @@
+"""On-device object detector for the Trillboards BYO-CCTV connector.
+
+Its own uv tool, its own venv, its own OS-supervised loopback service on
+127.0.0.1:9380 — see `LocalDetectorClient.ts` for why all three, and
+`docs/runbooks/cctv-detector-tier.md` for what it runs and why that model.
+"""
+
+__version__ = "0.1.0"

package/deploy/detector/trillboards_detector/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/deploy/detector/trillboards_detector/cli.py

@@ -0,0 +1,141 @@
+"""`trillboards-detector serve` — the entrypoint the OS supervisors run.
+
+NOTHING SPAWNS THIS FROM NODE. `LocalDetectorClient` is an HTTP client and
+nothing else: a launchd LaunchAgent, a systemd unit and a Windows Scheduled Task
+own the process, exactly as they do for `litert-lm serve`. That is deliberate —
+the connector must be able to come back from a crash without also being
+responsible for a Python runtime it did not install.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import logging.handlers
+import signal
+import sys
+import threading
+from pathlib import Path
+
+from .loader import DEFAULT_POLL_INTERVAL_S, DetectorLoader
+from .modelpath import DEFAULT_MODEL_NAME, resolve_model_path
+from .server import DEFAULT_HOST, DEFAULT_PORT, serve
+
+LOG = logging.getLogger("trillboards_detector")
+
+
+def _configure_logging(log_file: "str | None", verbose: bool) -> None:
+    """stderr always; a file only when asked.
+
+    THE FILE OPTION EXISTS FOR WINDOWS AND ONLY FOR WINDOWS. A Windows Scheduled
+    Task has no stdout, so `litert-lm serve`'s own log is discarded on that
+    platform and nowhere else — which is why the 2026-08-19 windows-latest
+    failure is STILL undiagnosed (`docs/runbooks/cctv-local-inference-hardware-floor.md`
+    §Windows: "the one process that knows why wrote its explanation to a handle
+    nobody was holding"). litert-lm cannot be fixed from here — it takes no
+    --log-file and wrapping it in cmd.exe breaks the stop path's image-name
+    filter. This service is OURS, so it simply writes the file itself.
+
+    ROTATED, because macOS has no log rotation for this connector at all
+    (`docs/runbooks/cctv-connector-runtime-edge-cases.md`) and an always-on
+    service on a box nobody visits must not be able to fill a disk that has no
+    space preflight anywhere on the model path.
+    """
+    LOG.setLevel(logging.DEBUG if verbose else logging.INFO)
+    fmt = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
+
+    stream = logging.StreamHandler(sys.stderr)
+    stream.setFormatter(fmt)
+    LOG.addHandler(stream)
+
+    if log_file:
+        path = Path(log_file)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        rotating = logging.handlers.RotatingFileHandler(
+            path, maxBytes=8 * 1024 * 1024, backupCount=2, encoding="utf-8"
+        )
+        rotating.setFormatter(fmt)
+        LOG.addHandler(rotating)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="trillboards-detector")
+    sub = p.add_subparsers(dest="command")
+    s = sub.add_parser("serve", help="run the loopback detector service")
+    s.add_argument("--host", default=DEFAULT_HOST)
+    s.add_argument("--port", type=int, default=DEFAULT_PORT)
+    s.add_argument("--model", default=None, help="path to the ONNX artifact (overrides the default location)")
+    s.add_argument("--model-name", default=DEFAULT_MODEL_NAME)
+    s.add_argument(
+        "--threads",
+        type=int,
+        default=None,
+        help=(
+            "ORT intra-op threads. LEAVE UNSET. cctv-detector-tier.md §2 measured "
+            "threads as non-monotonic — 16 (99.9 ms) is slower than 6 (78-83) and "
+            "slower than ORT's own auto heuristic (63.9) — so 'use all cores' is "
+            "wrong and this exists only to reproduce a bench arm."
+        ),
+    )
+    s.add_argument("--poll-interval", type=float, default=DEFAULT_POLL_INTERVAL_S)
+    s.add_argument("--log-file", default=None, help="also write to this file (Windows has no task stdout)")
+    s.add_argument("--verbose", action="store_true")
+    return p
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command != "serve":
+        build_parser().print_help()
+        return 2
+
+    _configure_logging(args.log_file, args.verbose)
+
+    model_path = Path(args.model) if args.model else resolve_model_path(args.model_name)
+    LOG.info("[detector] starting on %s:%s, model %s", args.host, args.port, model_path)
+
+    loader = DetectorLoader(
+        model_path=model_path,
+        model_name=args.model_name,
+        intra_op_threads=args.threads,
+        poll_interval_s=args.poll_interval,
+        log=LOG.info,
+    )
+    loader.start()
+
+    try:
+        server = serve(loader, args.host, args.port, LOG.info)
+    except OSError as err:
+        # A bind failure is FATAL and must stay fatal. `register-litertlm-task.ps1`
+        # has the incident this mirrors: a serve left alive keeps ANSWERING, so an
+        # upgrade installs the new binary, fails to bind, and leaves the OLD one
+        # serving while every health probe passes. Exiting lets the supervisor's
+        # restart policy do its job instead of running two half-services.
+        LOG.error("[detector] could not bind %s:%s — %s", args.host, args.port, err)
+        loader.stop()
+        return 1
+
+    stop = threading.Event()
+
+    def _shutdown(signum, _frame):
+        LOG.info("[detector] signal %s — shutting down", signum)
+        stop.set()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            signal.signal(sig, _shutdown)
+        except (ValueError, OSError):  # not available on every platform/thread
+            pass
+
+    LOG.info("[detector] listening on http://%s:%s", args.host, args.port)
+    try:
+        stop.wait()
+    except KeyboardInterrupt:
+        pass
+    server.shutdown()
+    loader.stop()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

package/deploy/detector/trillboards_detector/errors.py

@@ -0,0 +1,16 @@
+"""Errors shared by the wire layer and the model layer.
+
+Its own module, with NO third-party imports, so `server.py` stays importable —
+and therefore unit-testable against a stub — on a machine with no onnxruntime,
+no numpy and no Pillow. The wire contract is the load-bearing half of this
+service; it must not need a 128 MiB model or a 50 MB runtime to be tested.
+"""
+
+
+class DetectorNotReady(RuntimeError):
+    """No usable session. The server turns this into a 503, never into `[]`.
+
+    The distinction is the entire reason `LocalDetectorClient` exists: a cascade
+    that reads "detector down" as "nobody there" suppresses every alert while
+    every health surface stays green.
+    """

package/deploy/detector/trillboards_detector/labels.py

@@ -0,0 +1,107 @@
+"""The class vocabulary — COMMITTED, never inferred from the artifact.
+
+WHY THIS FILE IS A CONSTANT AND NOT A LOOKUP
+--------------------------------------------
+The exported RF-DETR graph carries NO class metadata: its
+``custom_metadata_map`` is empty and its only outputs are ``dets`` and
+``labels``. So there is nothing on disk to read the names from, and the
+alternative to committing them is guessing an index — which
+``docs/runbooks/cctv-detector-tier.md`` §5 rule 2 forbids by name, because a
+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`::
+
+    _class_id_to_name = {coco_id: model_class_names[i]
+                         for i, coco_id in enumerate(COCO_CLASSES) if i < n}
+
+`COCO_CLASSES` is the SPARSE list of 80 COCO category ids and
+`COCO_CLASS_NAMES` the 80 flat names. The logit axis is 91 wide because COCO's
+category ids run 1..90 WITH GAPS — so eleven of the ninety-one slots name
+nothing at all, and slot 0 is background.
+
+THE ELEVEN UNNAMED SLOTS ARE DROPPED, NOT LABELLED.
+A detection whose argmax lands on an unnamed slot cannot be given a name
+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.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+
+# 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.
+COCO91_CLASS_NAMES: "MappingProxyType[int, str]" = MappingProxyType({
+    1: "person", 2: "bicycle", 3: "car", 4: "motorcycle", 5: "airplane",
+    6: "bus", 7: "train", 8: "truck", 9: "boat", 10: "traffic light",
+    11: "fire hydrant", 13: "stop sign", 14: "parking meter", 15: "bench",
+    16: "bird", 17: "cat", 18: "dog", 19: "horse", 20: "sheep", 21: "cow",
+    22: "elephant", 23: "bear", 24: "zebra", 25: "giraffe", 27: "backpack",
+    28: "umbrella", 31: "handbag", 32: "tie", 33: "suitcase", 34: "frisbee",
+    35: "skis", 36: "snowboard", 37: "sports ball", 38: "kite",
+    39: "baseball bat", 40: "baseball glove", 41: "skateboard",
+    42: "surfboard", 43: "tennis racket", 44: "bottle", 46: "wine glass",
+    47: "cup", 48: "fork", 49: "knife", 50: "spoon", 51: "bowl", 52: "banana",
+    53: "apple", 54: "sandwich", 55: "orange", 56: "broccoli", 57: "carrot",
+    58: "hot dog", 59: "pizza", 60: "donut", 61: "cake", 62: "chair",
+    63: "couch", 64: "potted plant", 65: "bed", 67: "dining table",
+    70: "toilet", 72: "tv", 73: "laptop", 74: "mouse", 75: "remote",
+    76: "keyboard", 77: "cell phone", 78: "microwave", 79: "oven",
+    80: "toaster", 81: "sink", 82: "refrigerator", 84: "book", 85: "clock",
+    86: "vase", 87: "scissors", 88: "teddy bear", 89: "hair drier",
+    90: "toothbrush",
+})
+
+# 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
+# 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.
+EXPECTED_LOGIT_SLOTS = 91
+
+# The one label the cascade actually gates on. Asserted at import so a careless
+# edit to the map above fails at start rather than at the first empty venue.
+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.
+
+    `sensing_profiles.classes` is written by an LLM from a COCO vocabulary, so
+    it arrives as prose-ish text: 'Person', 'cell_phone', 'dining-table'. The
+    canonical name is what goes back on the wire regardless, so the connector
+    and the eval harness always see one spelling.
+    """
+    return name.strip().lower().replace("_", " ").replace("-", " ")
+
+
+_CANONICAL_BY_NORMALIZED = {normalize_class_name(v): v for v in COCO91_CLASS_NAMES.values()}
+
+
+def resolve_requested_classes(requested: list[str]) -> tuple[set[str], list[str]]:
+    """Map caller-supplied class names onto canonical ones.
+
+    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.
+    """
+    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