@camstack/addon-pipeline 1.2.327 → 1.2.329

package/python/inference_pool.py

@@ -321,26 +321,11 @@ def _ov_request_count(optimal: int) -> int:
 # entirely. We resolve an ordered candidate list (NPU > GPU > CPU) and compile the
 # first that succeeds, with CPU as the guaranteed floor.
 #
-# OpenVINO async execution (CAMSTACK_OV_ASYNC, default OFF / "0"). When ON, the
-# OpenVINO runtime drives an ov.AsyncInferQueue sized to
-# OPTIMAL_NUMBER_OF_INFER_REQUESTS instead of the synchronous InferRequest pool +
-# req.infer(). This mirrors how the reference Intel-iGPU async pipeline saturates
-# the GPU: keep N inferences in flight, collect each in the queue's callback.
-# start_async() BLOCKS once all N jobs are busy, so in-flight work is bounded to N
-# with NO extra buffer (respects the "never buffer frames at frame-rate" rule).
-# OFF is byte-for-byte the historical synchronous path — the ship-dark default.
-_OV_ASYNC_ENABLED: bool = os.environ.get("CAMSTACK_OV_ASYNC", "0") not in (
-    "0", "false", "no",
-)
-# OpenVINO PERFORMANCE_HINT (CAMSTACK_OV_HINT, default "LATENCY"). THROUGHPUT
-# raises OPTIMAL_NUMBER_OF_INFER_REQUESTS (a larger async queue → more device
-# saturation) but spins up multiple internal streams that multiply memory and
-# lengthen tail latency — a known N100 OOM-freeze factor (see the ov_config note
-# in _load_model). Kept at LATENCY by default; only flip to THROUGHPUT on a node
-# with headroom. Any unrecognised value falls back to LATENCY.
-_OV_PERF_HINT: str = os.environ.get("CAMSTACK_OV_HINT", "LATENCY").upper()
-if _OV_PERF_HINT not in ("LATENCY", "THROUGHPUT"):
-    _OV_PERF_HINT = "LATENCY"
+# OpenVINO PERFORMANCE_HINT is LATENCY: one deterministic execution stream. The
+# THROUGHPUT hint multiplied memory and lengthened tail latency (an N100
+# OOM-freeze factor, see the ov_config note in _load_model); its env switch and
+# the never-enabled AsyncInferQueue path were removed on 2026-10-06.
+_OV_PERF_HINT: str = "LATENCY"
 
 # OpenVINO COMPILATION thread pool (CAMSTACK_OV_COMPILATION_THREADS, default 4).
 #
@@ -1087,15 +1072,14 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
             candidates = [ov_device_req]  # operator pin — compiled directly
             sys.stderr.write(f"OpenVINO: operator-pinned device {ov_device_req}\n")
             sys.stderr.flush()
-        # PERFORMANCE_HINT defaults to LATENCY (CAMSTACK_OV_HINT): one
+        # PERFORMANCE_HINT is LATENCY: one
         # deterministic execution stream instead of N. THROUGHPUT spins up
         # multiple internal streams whose lazy request creation historically
         # collided with the AUTO handover AND multiplied memory (a factor in the
         # N100 OOM-freeze); it also RAISES OPTIMAL_NUMBER_OF_INFER_REQUESTS, which
-        # enlarges the async queue built below at a memory / tail-latency cost.
+        # enlarges the request pool at a memory / tail-latency cost.
         # LATENCY keeps a single stream; camera-level concurrency comes from the
-        # fixed InferRequest pool / async queue built below. Operators can opt into
-        # THROUGHPUT on a node with headroom via CAMSTACK_OV_HINT=THROUGHPUT.
+        # fixed InferRequest pool built below.
         ov_config = {"PERFORMANCE_HINT": _OV_PERF_HINT}
         # Persist compiled GPU/NPU kernels so the multi-second JIT compile is paid
         # once (first boot) instead of on every pool spawn. The cold compile storm
@@ -1111,7 +1095,7 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
         # graph via PrePostProcessor. When it succeeds we compile the PPP model
         # object (fed uint8 NHWC at inference time); on ANY failure we fall back
         # to compiling the plain `path` (byte-identical to the historical float
-        # preprocess). Default on for OpenVINO — CAMSTACK_OV_PPP=0 disables.
+        # preprocess). Always on for OpenVINO (tests flip `_OV_PPP_ENABLED`).
         ppp_meta: Optional[dict] = None
         compile_source: Any = path
         if _OV_PPP_ENABLED:
@@ -1222,9 +1206,8 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
 
         # Size N ONCE from the device's optimal infer-request count (falling back
         # to OV_DEFAULT_CONCURRENCY only when the property is missing/zero) so it
-        # matches the predict-pool worker count sized in _run(). Both the sync
-        # request-pool and the async queue below are sized to this same N, and
-        # both go through `_ov_request_count` so they cannot drift apart.
+        # matches the predict-pool worker count sized in _run(); `_ov_request_count`
+        # is the one place it is computed.
         import queue as _queue
 
         try:
@@ -1233,97 +1216,31 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
             _n_req = 0
         _n_req = _ov_request_count(_n_req)
 
-        if _OV_ASYNC_ENABLED:
-            # Async pipelining path (CAMSTACK_OV_ASYNC=1). An ov.AsyncInferQueue of
-            # N jobs keeps up to N inferences in flight on the device at once — the
-            # way the Intel-iGPU reference path saturates the GPU. Each completion
-            # fires the queue callback; start_async() BLOCKS when all N jobs are
-            # busy, so in-flight submissions are bounded to N with NO extra buffer
-            # (repo rule: never buffer frames at frame-rate). The RuntimeDispatcher
-            # still calls a BLOCKING predict_fn(input)->dict, so we bridge async->
-            # sync per call with a threading.Event + a 1-slot result holder passed
-            # as the submission's userdata; the callback fills it and wakes us.
-            import threading as _threading
-            try:
-                from openvino import AsyncInferQueue as _AsyncInferQueue
-            except Exception:
-                from openvino.runtime import AsyncInferQueue as _AsyncInferQueue
-
-            _infer_queue = _AsyncInferQueue(compiled, _n_req)
-
-            # Callback runs on an OpenVINO worker thread when a job finishes. Fetch
-            # outputs POSITIONALLY (get_output_tensor(i)) so an UNNAMED IR output
-            # tensor is tolerated (same reason the sync path indexes by position —
-            # see the output_names note above), and .copy() detaches the result
-            # from the request's reusable output buffer before the job is freed
-            # back into the queue and possibly overwritten by the next inference.
-            def _on_done(_request, _userdata, _names=output_names) -> None:
-                _event, _holder = _userdata
-                try:
-                    _holder[0] = {
-                        name: _request.get_output_tensor(i).data.copy()
-                        for i, name in enumerate(_names)
-                    }
-                except BaseException as _exc:  # surface to the waiting caller
-                    _holder[1] = _exc
-                finally:
-                    _event.set()
-
-            _infer_queue.set_callback(_on_done)
-            # Serialise only the (cheap) hand-off. start_async internally waits for
-            # an idle request; guarding it means two dispatcher threads can never
-            # claim the same idle slot. The inference itself stays fully async —
-            # N requests keep running on the device concurrently — so this lock
-            # does not reduce pipelining, it only makes concurrent submit safe.
-            _submit_lock = _threading.Lock()
-            sys.stderr.write(
-                f"OpenVINO: AsyncInferQueue with {_n_req} job(s) on {ov_device} "
-                f"(CAMSTACK_OV_ASYNC=1, hint={_OV_PERF_HINT})\n"
-            )
-            sys.stderr.flush()
-
-            def predict(inp_dict: dict, _q=_infer_queue, _lock=_submit_lock) -> dict:
-                inp = list(inp_dict.values())[0]
-                done = _threading.Event()
-                holder: list = [None, None]  # [result_dict, exception]
-                with _lock:
-                    # Blocks here when all N jobs are busy -> bounded in-flight.
-                    _q.start_async(inp, (done, holder))
-                done.wait()
-                if holder[1] is not None:
-                    raise holder[1]
-                return holder[0]
-
-            slot.model = compiled
-            slot.predict_fn = predict
-        else:
-            # Synchronous path (default, CAMSTACK_OV_ASYNC=0) — byte-for-byte the
-            # historical behaviour. Create ALL InferRequests ONCE, now, post-
-            # compile. With AUTO gone there is no CPU->GPU handover, so no request
-            # can be born mid-handover and bind to stale ports — the score_8 race
-            # is structurally removed. Requests are handed out through a thread-
-            # safe queue: an InferRequest is never touched by two threads at once
-            # (checkout/return), so sharing a fixed pool is safe and avoids the old
-            # thread-local lazy creation.
-            _req_pool: "_queue.Queue" = _queue.Queue()
-            for _ in range(_n_req):
-                _req_pool.put(compiled.create_infer_request())
-            sys.stderr.write(f"OpenVINO: created {_n_req} InferRequest(s) up-front on {ov_device}\n")
-            sys.stderr.flush()
+        # Create ALL InferRequests ONCE, now, post-compile. With AUTO gone there is no CPU->GPU handover, so no request
+        # can be born mid-handover and bind to stale ports — the score_8 race
+        # is structurally removed. Requests are handed out through a thread-
+        # safe queue: an InferRequest is never touched by two threads at once
+        # (checkout/return), so sharing a fixed pool is safe and avoids the old
+        # thread-local lazy creation.
+        _req_pool: "_queue.Queue" = _queue.Queue()
+        for _ in range(_n_req):
+            _req_pool.put(compiled.create_infer_request())
+        sys.stderr.write(f"OpenVINO: created {_n_req} InferRequest(s) up-front on {ov_device}\n")
+        sys.stderr.flush()
 
-            def predict(inp_dict: dict, _names=output_names, _pool=_req_pool) -> dict:
-                inp = list(inp_dict.values())[0]
-                req = _pool.get()
-                try:
-                    result = req.infer(inp)
-                finally:
-                    _pool.put(req)
-                # Output fetch by positional index — stable and harmless now that
-                # the ports no longer diverge (single explicit device, no handover).
-                return {name: result[i] for i, name in enumerate(_names)}
-
-            slot.model = compiled
-            slot.predict_fn = predict
+        def predict(inp_dict: dict, _names=output_names, _pool=_req_pool) -> dict:
+            inp = list(inp_dict.values())[0]
+            req = _pool.get()
+            try:
+                result = req.infer(inp)
+            finally:
+                _pool.put(req)
+            # Output fetch by positional index — stable and harmless now that
+            # the ports no longer diverge (single explicit device, no handover).
+            return {name: result[i] for i, name in enumerate(_names)}
+
+        slot.model = compiled
+        slot.predict_fn = predict
         # When the PPP preprocessor is folded in, `_preprocess` produces uint8
         # NHWC and short-circuits BEFORE the NHWC/NCHW float logic — so the
         # `_input_shape` heuristic below is irrelevant for PPP models. Record
@@ -1402,9 +1319,19 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
         slot.config["_edgetpu_in_dtype"] = in_dtype
         slot.config["inputWidth"] = in_w
         slot.config["inputHeight"] = in_h
-        slot.config.setdefault("inputSize", max(in_w, in_h))
+        # The FILE's input size is the truth for a compiled Edge TPU graph: a
+        # Coral build may be compiled at a smaller input than the catalog
+        # entry's other formats (activations share the 8 MB on-chip memory
+        # with the parameter cache, D710), and a decoder sized from the
+        # catalog would put every prior in the wrong cell.
+        slot.config["inputSize"] = max(in_w, in_h)
         in_index = int(in_det["index"])
         out_index = [int(o["index"]) for o in out_dets]
+        from edgetpu_dequant import edgetpu_output_keys
+
+        out_keys = edgetpu_output_keys(
+            [str(o.get("name") or "") for o in out_dets], slot.config.get("postprocessor")
+        )
         sys.stderr.write(
             f"EdgeTPU: loaded {os.path.basename(path)} in={in_w}x{in_h} "
             f"dtype={in_dtype} outputs={len(out_dets)}\n"
@@ -1414,6 +1341,7 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
         def predict(
             inp_dict: dict,
             _interp=interp, _lock=lock, _in=in_index, _outs=out_index, _details=out_dets,
+            _keys=out_keys,
         ) -> dict:
             from edgetpu_dequant import dequant_edgetpu_output
 
@@ -1421,22 +1349,25 @@ def _load_model(slot: ModelSlot, config: dict) -> None:
             with _lock:
                 _interp.set_tensor(_in, tensor)
                 _interp.invoke()
-                # Positional keys — ssd reads "0".."3"; yolo-split-dfl pairs by
-                # shape. Integer outputs are dequantised here so every
-                # postprocessor sees float32 (SSD Detection_PostProcess is
-                # already float and passes through).
-                result = {}
-                for i, idx in enumerate(_outs):
-                    raw = _interp.get_tensor(idx)
-                    detail = _details[i]
-                    q = detail.get("quantization") or (0.0, 0)
-                    scale = float(q[0]) if q else 0.0
-                    zp = int(q[1]) if q else 0
-                    dtype_name = str(np.dtype(detail["dtype"]).name)
-                    result[str(i)] = dequant_edgetpu_output(
-                        raw, dtype_name=dtype_name, scale=scale, zero_point=zp
-                    )
-                return result
+                # `get_tensor` returns a copy, so the Coral is released before
+                # the dequantisation below runs.
+                raws = [_interp.get_tensor(idx) for idx in _outs]
+            # Positional keys — ssd reads "0".."3"; yolo-split-dfl pairs by
+            # shape — except for a postprocessor that matches by name
+            # (`edgetpu_output_keys`). Integer outputs are dequantised here so
+            # every postprocessor sees float32 (SSD Detection_PostProcess is
+            # already float and passes through).
+            result = {}
+            for i, raw in enumerate(raws):
+                detail = _details[i]
+                q = detail.get("quantization") or (0.0, 0)
+                scale = float(q[0]) if q else 0.0
+                zp = int(q[1]) if q else 0
+                dtype_name = str(np.dtype(detail["dtype"]).name)
+                result[_keys[i]] = dequant_edgetpu_output(
+                    raw, dtype_name=dtype_name, scale=scale, zero_point=zp
+                )
+            return result
 
         slot.model = interp
         slot.predict_fn = predict
@@ -1613,9 +1544,9 @@ def _preprocess_ctc_gray(img: "Image.Image", input_w: int, input_h: int) -> "np.
 # Fix 2 — OpenVINO PrePostProcessor (preprocess folded into the compiled graph)
 # ---------------------------------------------------------------------------
 
-# Default ON for OpenVINO; set CAMSTACK_OV_PPP=0 to fall back to the pure-Python
-# float preprocess (the historical path) if a model/postprocessor misbehaves.
-_OV_PPP_ENABLED: bool = os.environ.get("CAMSTACK_OV_PPP", "1") not in ("0", "false", "no")
+# Always ON for OpenVINO; a module constant only so tests can exercise the
+# plain-path compile. A failed fold already falls back per model (above).
+_OV_PPP_ENABLED: bool = True
 
 
 def _ov_dim_to_int(dim: Any) -> "int | None":

package/python/postprocessors/test_bird_edgetpu.py

@@ -0,0 +1,124 @@
+"""Pins the bird-classifier Coral build on REAL output tensors (D710 enforcement).
+
+`bird-classifier` ships a `tflite` format compiled for the Edge TPU
+(`bird-classifier_edgetpu.tflite`). Its single output is `[1,965] uint8`,
+scale 1/256, zero point 0, with the softmax ALREADY in the graph. Two things
+must hold for the step to emit the species the ONNX survivor emits:
+
+- the edgetpu predict closure dequantises the tensor (`edgetpu_dequant`) —
+  read raw, the top-1 "probability" is a byte count in the hundreds and every
+  confidence gate passes everything;
+- the softmax postprocessor consumes it verbatim (`outputProbabilities`) —
+  re-softmaxing a 1/256-step distribution flattens it below the 0.6 gate.
+
+The fixture (`testdata/bird_classifier_int8_outputs.json`) holds the raw
+outputs of the integer graph the Edge TPU file is compiled from, on two bird
+crops (detector boxes) and one 48-px crop whose top-1 is `background`, next
+to the ONNX survivor's top-1 on the same crop. Produced by
+`scripts/build-bird-classifier-edgetpu.py`; its `producedBy` says how.
+
+`unittest.TestCase`: the dequant cases run on CI's bare interpreter (no
+numpy); the postprocessor cases need numpy (`softmax.py` imports it) and are
+skipped, by name, without it.
+"""
+import json
+import os
+import sys
+import unittest
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(_HERE))  # edgetpu_dequant lives one level up
+
+from edgetpu_dequant import dequant_edgetpu_output  # noqa: E402
+
+try:
+    import numpy as _numpy_probe
+except ImportError:
+    _numpy_probe = None
+_HAS_REAL_NUMPY = _numpy_probe is not None and hasattr(_numpy_probe, "ndarray")
+
+with open(os.path.join(_HERE, "testdata", "bird_classifier_int8_outputs.json"), encoding="utf-8") as _fh:
+    _FIXTURE = json.load(_fh)
+
+_OUT = _FIXTURE["output"]
+_BACKGROUND = _FIXTURE["backgroundIndex"]
+_STEP_GATE = 0.6  # STEP_BIRD_CLASSIFIER.defaultConfidence
+_SPECIES = [f for f in _FIXTURE["frames"] if f["onnxTop1Index"] != _BACKGROUND]
+_BACKGROUND_FRAMES = [f for f in _FIXTURE["frames"] if f["onnxTop1Index"] == _BACKGROUND]
+# One crop's ONNX vs int8 top-1 difference is quantisation noise, not a defect;
+# the parity pass of the build script measured p95 of max |dp| at 0.12.
+_SCORE_TOLERANCE = 0.05
+
+
+def _dequant(frame):
+    return dequant_edgetpu_output(
+        [frame["raw"]], dtype_name=_OUT["dtype"], scale=_OUT["scale"], zero_point=_OUT["zeroPoint"],
+    )
+
+
+class BirdEdgetpuDequant(unittest.TestCase):
+    def test_fixture_is_the_shipped_contract(self):
+        self.assertEqual(_OUT["shape"], [1, 965])
+        self.assertEqual(_OUT["dtype"], "uint8")
+        self.assertAlmostEqual(_OUT["scale"], 1.0 / 256.0, places=9)
+        self.assertEqual(_OUT["zeroPoint"], 0)
+        self.assertGreaterEqual(len(_SPECIES), 2)
+        self.assertEqual(len(_BACKGROUND_FRAMES), 1)
+
+    def test_raw_tensor_is_not_a_probability(self):
+        # The defect the dequant closes: read raw, the top-1 is far above 1.
+        for frame in _SPECIES:
+            self.assertGreater(max(frame["raw"]), 200)
+
+    def test_dequantised_tensor_is_the_in_graph_softmax(self):
+        for frame in _FIXTURE["frames"]:
+            probs = _dequant(frame)[0]
+            self.assertEqual(len(probs), 965)
+            # Mass below one step (1/256) quantises to 0, so the sum lands a
+            # little under 1 — the flatter the distribution, the more is lost
+            # (0.71 on the background crop, 0.92+ on the species) — never above.
+            self.assertGreater(sum(probs), 0.6)
+            self.assertLessEqual(sum(probs), 1.0 + 1e-6)
+            self.assertTrue(all(0.0 <= p <= 1.0 for p in probs))
+
+    def test_dequantised_top1_is_the_onnx_survivors(self):
+        for frame in _SPECIES:
+            probs = _dequant(frame)[0]
+            top = max(range(len(probs)), key=probs.__getitem__)
+            self.assertEqual(top, frame["onnxTop1Index"], frame["crop"])
+            self.assertAlmostEqual(probs[top], frame["onnxTop1Score"], delta=_SCORE_TOLERANCE)
+            self.assertGreaterEqual(probs[top], _STEP_GATE)
+
+
+@unittest.skipUnless(_HAS_REAL_NUMPY, "softmax.py needs numpy")
+class BirdEdgetpuSoftmax(unittest.TestCase):
+    def _classify(self, frame, output_probabilities=True):
+        import numpy as np
+        from softmax import postprocess_softmax
+
+        tensor = np.array(_dequant(frame), dtype=np.float32)
+        config = {"labels": [str(i) for i in range(965)], "outputProbabilities": output_probabilities}
+        return postprocess_softmax({"0": tensor}, config, 224, 224, 1.0, (0, 0))["classifications"]
+
+    def test_species_crop_emits_the_onnx_species_above_the_step_gate(self):
+        for frame in _SPECIES:
+            top = self._classify(frame)[0]
+            self.assertEqual(top["class"], str(frame["onnxTop1Index"]), frame["crop"])
+            self.assertGreaterEqual(top["score"], _STEP_GATE)
+
+    def test_background_crop_tops_out_as_background(self):
+        # The step rejects `background` downstream (rejectClasses); the
+        # postprocessor must still name it, not a species.
+        top = self._classify(_BACKGROUND_FRAMES[0])[0]
+        self.assertEqual(top["class"], str(_BACKGROUND))
+
+    def test_re_softmax_would_sink_every_species_below_the_gate(self):
+        # Why the catalog sets outputProbabilities on this entry.
+        for frame in _SPECIES:
+            # Flattened so far that nothing clears the postprocessor's 0.01 floor.
+            ranked = self._classify(frame, output_probabilities=False)
+            self.assertTrue(all(c["score"] < _STEP_GATE for c in ranked))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/postprocessors/test_yolox_plate_edgetpu.py

@@ -0,0 +1,126 @@
+"""Pins the YOLOX-tiny plate Coral build on REAL output tensors (D710 enforcement).
+
+`yolox-tiny-plate` ships a `tflite` format compiled for the Edge TPU
+(`camstack-yolox-tiny-plate_edgetpu.tflite`). Unlike its other builds — which
+bake YOLOX's grid decode into the graph and emit the YOLOv8 layout — the Coral
+graph stops at the raw head (an `Exp` and a coordinate Concat would share one
+int8 scale between pixels and probabilities): per stride, `reg_s` (dx, dy,
+log w, log h) and `score_s` (obj*cls), NHWC, int8. Three things must hold for
+the step to emit the box the ONNX build emits:
+
+- the edgetpu predict closure keys the `yolo` postprocessor's outputs by
+  tensor NAME (`edgetpu_output_keys`) — the head is found by its names;
+- every output is dequantised (`edgetpu_dequant`);
+- `yolo.py`'s `yolox_head_to_v8` decodes the head (row-major cells, centre =
+  (offset + cell) * stride, size = exp(log) * stride) into the layout the rest
+  of the postprocessor already reads.
+
+The fixture (`testdata/yolox_plate_int8_outputs.json`) holds the raw outputs of
+the int8 graph the Edge TPU file is compiled from, on the public
+`reference-images/1-car-plate.jpg` letterboxed to 640, and the published ONNX
+build's detections on the same frame. Produced by
+`scripts/build-yolox-plate-edgetpu.py`.
+
+`unittest.TestCase`: the key and dequant cases run on CI's bare interpreter;
+the decode cases need numpy and are skipped, by name, without it.
+"""
+import base64
+import json
+import os
+import sys
+import unittest
+import zlib
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(_HERE))  # edgetpu_dequant lives one level up
+
+from edgetpu_dequant import dequant_edgetpu_output, edgetpu_output_keys  # noqa: E402
+
+try:
+    import numpy as _numpy_probe
+except ImportError:
+    _numpy_probe = None
+_HAS_REAL_NUMPY = _numpy_probe is not None and hasattr(_numpy_probe, "ndarray")
+
+with open(os.path.join(_HERE, "testdata", "yolox_plate_int8_outputs.json"), encoding="utf-8") as _fh:
+    _FIXTURE = json.load(_fh)
+
+_OUTPUTS = _FIXTURE["outputs"]
+_FRAME = _FIXTURE["frame"]
+_STEP_GATE = 0.5  # plate-detection.defaultConfidence
+_HEAD = ["reg_8", "score_8", "reg_16", "score_16", "reg_32", "score_32"]
+
+
+def _raw(name):
+    data = zlib.decompress(base64.b64decode(_OUTPUTS[name]["zlibB64"]))
+    return [b - 256 if b > 127 else b for b in data]
+
+
+def _iou(a, b):
+    ix = max(0.0, min(a[2], b[2]) - max(a[0], b[0]))
+    iy = max(0.0, min(a[3], b[3]) - max(a[1], b[1]))
+    inter = ix * iy
+    union = (a[2] - a[0]) * (a[3] - a[1]) + (b[2] - b[0]) * (b[3] - b[1]) - inter
+    return inter / union if union > 0 else 0.0
+
+
+class YoloxPlateEdgetpuContract(unittest.TestCase):
+    def test_fixture_is_the_shipped_contract(self):
+        self.assertEqual(sorted(_OUTPUTS), sorted(_HEAD))
+        self.assertEqual(_OUTPUTS["reg_8"]["shape"], [1, 80, 80, 4])
+        self.assertEqual(_OUTPUTS["score_32"]["shape"], [1, 20, 20, 1])
+        for name, o in _OUTPUTS.items():
+            self.assertEqual(o["dtype"], "int8", name)
+        self.assertEqual(len(_FIXTURE["onnxDetections"]), 1)
+
+    def test_the_yolo_postprocessor_gets_named_outputs_on_the_coral(self):
+        listed = list(_OUTPUTS)
+        self.assertEqual(edgetpu_output_keys(listed, "yolo"), listed)
+
+    def test_dequantised_scores_are_probabilities(self):
+        for name in ("score_8", "score_16", "score_32"):
+            o = _OUTPUTS[name]
+            probs = dequant_edgetpu_output(_raw(name), dtype_name="int8", scale=o["scale"], zero_point=o["zeroPoint"])
+            self.assertTrue(all(-1e-6 <= p <= 1.0 + 1e-6 for p in probs), name)
+
+
+@unittest.skipUnless(_HAS_REAL_NUMPY, "yolo.py needs numpy")
+class YoloxPlateEdgetpuDecode(unittest.TestCase):
+    def _decode(self, keys):
+        import numpy as np
+        from yolo import postprocess_yolo
+
+        preds = {}
+        for key, name in zip(keys, _OUTPUTS):
+            o = _OUTPUTS[name]
+            raw = np.array(_raw(name), dtype=np.int8).reshape(o["shape"])
+            preds[key] = dequant_edgetpu_output(raw, dtype_name="int8", scale=o["scale"], zero_point=o["zeroPoint"])
+        config = {"confidence": _STEP_GATE, "labels": ["plate"], "numClasses": 1, "nmsIouThreshold": 0.45,
+                  "inputSize": 640}
+        return postprocess_yolo(preds, config, _FRAME["w"], _FRAME["h"], _FRAME["scale"],
+                                tuple(_FRAME["pad"]))["detections"]
+
+    def test_the_int8_head_decodes_to_the_onnx_plate(self):
+        got = self._decode(edgetpu_output_keys(list(_OUTPUTS), "yolo"))
+        ref = _FIXTURE["onnxDetections"]
+        self.assertEqual(len(got), len(ref))
+        self.assertEqual(got[0]["class"], "plate")
+        self.assertGreaterEqual(_iou(got[0]["bbox"], ref[0]["bbox"]), 0.9)
+        self.assertAlmostEqual(got[0]["score"], ref[0]["score"], delta=0.05)
+
+    def test_a_head_sized_for_another_input_is_refused(self):
+        import numpy as np
+        from yolo import yolox_head_to_v8
+
+        preds = {name: np.zeros(_OUTPUTS[name]["shape"], dtype=np.float32) for name in _OUTPUTS}
+        with self.assertRaises(ValueError):
+            yolox_head_to_v8(preds, 416)
+
+    def test_positional_keys_never_reach_the_head_decode(self):
+        from yolo import yolox_head_to_v8
+
+        self.assertIsNone(yolox_head_to_v8({str(i): None for i in range(6)}, 640))
+
+
+if __name__ == "__main__":
+    unittest.main()