feat: 实现 Brain 区域与方向越线判定 (#15)

合入 dev，#14 保持待验收。

Brain/src/yovision_brain/decode/__init__.py

@@ -0,0 +1,16 @@
+"""Replaceable Brain-internal video decode pipeline."""
+
+from .models import DecodedFrame, DecoderBackend, DecoderError
+from .pipeline import DecoderPipeline, decode_packets
+from .raw_rgb import RawRGBDecoder
+from .y4m import Y4MDecoder
+
+__all__ = [
+    "DecodedFrame",
+    "DecoderBackend",
+    "DecoderError",
+    "DecoderPipeline",
+    "RawRGBDecoder",
+    "Y4MDecoder",
+    "decode_packets",
+]

Brain/src/yovision_brain/decode/models.py

@@ -0,0 +1,35 @@
+"""Decode-layer ports and frame model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Protocol
+
+from yovision_brain.input import CancellationToken, InputPacket
+
+
+class DecoderError(RuntimeError):
+    """A safe and actionable decode failure."""
+
+
+@dataclass(frozen=True, slots=True)
+class DecodedFrame:
+    sequence: int
+    timestamp_ns: int
+    logical_device_id: str
+    profile_id: str
+    width: int
+    height: int
+    pixel_format: str
+    payload: bytes
+    dimensions_changed: bool = False
+
+
+class DecoderBackend(Protocol):
+    media_formats: frozenset[str]
+
+    def decode(
+        self,
+        packets: Iterable[InputPacket],
+        cancellation: CancellationToken | None = None,
+    ) -> Iterator[DecodedFrame]: ...

Brain/src/yovision_brain/decode/pipeline.py

@@ -0,0 +1,47 @@
+"""Decoder selection independent of concrete codec libraries."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from itertools import chain
+
+from yovision_brain.input import CancellationToken, InputPacket
+
+from .models import DecodedFrame, DecoderBackend, DecoderError
+from .raw_rgb import RawRGBDecoder
+from .y4m import Y4MDecoder
+
+
+class DecoderPipeline:
+    def __init__(self, backends: Iterable[DecoderBackend] | None = None) -> None:
+        selected = tuple(backends) if backends is not None else (RawRGBDecoder(), Y4MDecoder())
+        self._backends: dict[str, DecoderBackend] = {}
+        for backend in selected:
+            for media_format in backend.media_formats:
+                if media_format in self._backends:
+                    raise ValueError(f"duplicate decoder for media format {media_format!r}")
+                self._backends[media_format] = backend
+
+    def decode(
+        self,
+        packets: Iterable[InputPacket],
+        cancellation: CancellationToken | None = None,
+    ) -> Iterator[DecodedFrame]:
+        iterator = iter(packets)
+        if cancellation is not None and cancellation.cancelled:
+            return
+        try:
+            first = next(iterator)
+        except StopIteration:
+            return
+        backend = self._backends.get(first.media_format)
+        if backend is None:
+            raise DecoderError(f"no decoder registered for media format {first.media_format!r}")
+        yield from backend.decode(chain((first,), iterator), cancellation)
+
+
+def decode_packets(
+    packets: Iterable[InputPacket],
+    cancellation: CancellationToken | None = None,
+) -> Iterator[DecodedFrame]:
+    return DecoderPipeline().decode(packets, cancellation)

Brain/src/yovision_brain/decode/raw_rgb.py

@@ -0,0 +1,45 @@
+"""Pass-through decoder for deterministic RGB24 synthetic frames."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+
+from yovision_brain.input import CancellationToken, InputPacket
+
+from .models import DecodedFrame, DecoderError
+
+
+class RawRGBDecoder:
+    media_formats = frozenset({"rgb24"})
+
+    def decode(
+        self,
+        packets: Iterable[InputPacket],
+        cancellation: CancellationToken | None = None,
+    ) -> Iterator[DecodedFrame]:
+        previous_dimensions: tuple[int, int] | None = None
+        for packet in packets:
+            if cancellation is not None and cancellation.cancelled:
+                return
+            if packet.media_format != "rgb24":
+                raise DecoderError(f"raw RGB decoder does not support {packet.media_format!r}")
+            expected = packet.width * packet.height * 3
+            if len(packet.payload) != expected:
+                raise DecoderError(
+                    f"RGB24 frame {packet.sequence} has {len(packet.payload)} bytes; expected {expected}"
+                )
+            if packet.timestamp_ns is None:
+                raise DecoderError(f"RGB24 frame {packet.sequence} has no source timestamp")
+            dimensions = (packet.width, packet.height)
+            yield DecodedFrame(
+                sequence=packet.sequence,
+                timestamp_ns=packet.timestamp_ns,
+                logical_device_id=packet.logical_device_id,
+                profile_id=packet.profile_id,
+                width=packet.width,
+                height=packet.height,
+                pixel_format="rgb24",
+                payload=packet.payload,
+                dimensions_changed=previous_dimensions is not None and dimensions != previous_dimensions,
+            )
+            previous_dimensions = dimensions

Brain/src/yovision_brain/decode/y4m.py

@@ -0,0 +1,167 @@
+"""Minimal streaming YUV4MPEG2 decoder for anonymous local fixtures.
+
+The backend intentionally supports only uncompressed C444 streams. Production
+codecs and RTSP belong behind the same decoder port in later tasks.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+
+from yovision_brain.input import CancellationToken, InputPacket
+
+from .models import DecodedFrame, DecoderError
+
+_MAX_HEADER_BYTES = 4096
+_MAX_FRAME_BYTES = 256 * 1024 * 1024
+
+
+class _Cancelled(Exception):
+    pass
+
+
+class _PacketReader:
+    def __init__(
+        self,
+        packets: Iterable[InputPacket],
+        cancellation: CancellationToken | None,
+    ) -> None:
+        self._packets = iter(packets)
+        self._cancellation = cancellation
+        self._buffer = bytearray()
+        self._ended = False
+        self.first_packet: InputPacket | None = None
+
+    def _fill(self) -> bool:
+        if self._cancellation is not None and self._cancellation.cancelled:
+            raise _Cancelled
+        if self._ended:
+            return False
+        try:
+            packet = next(self._packets)
+        except StopIteration:
+            self._ended = True
+            return False
+        if packet.media_format != "container-bytes":
+            raise DecoderError(f"Y4M decoder does not support {packet.media_format!r}")
+        if self.first_packet is None:
+            self.first_packet = packet
+        else:
+            first = self.first_packet
+            if (packet.logical_device_id, packet.profile_id) != (
+                first.logical_device_id,
+                first.profile_id,
+            ):
+                raise DecoderError("input identity changed inside one local video stream")
+        self._buffer.extend(packet.payload)
+        return True
+
+    def line(self, *, allow_clean_eof: bool = False) -> bytes | None:
+        while True:
+            newline = self._buffer.find(b"\n")
+            if newline >= 0:
+                result = bytes(self._buffer[:newline])
+                del self._buffer[: newline + 1]
+                return result
+            if len(self._buffer) > _MAX_HEADER_BYTES:
+                raise DecoderError("Y4M header exceeds the safe size limit")
+            if not self._fill():
+                if not self._buffer and allow_clean_eof:
+                    return None
+                raise DecoderError("truncated Y4M header")
+
+    def exact(self, size: int) -> bytes:
+        while len(self._buffer) < size:
+            if not self._fill():
+                raise DecoderError("truncated Y4M frame payload")
+        result = bytes(self._buffer[:size])
+        del self._buffer[:size]
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class _Header:
+    width: int
+    height: int
+    fps_numerator: int
+    fps_denominator: int
+
+
+def _positive_int(value: bytes, field: str) -> int:
+    try:
+        result = int(value)
+    except ValueError as exc:
+        raise DecoderError(f"invalid Y4M {field}") from exc
+    if result <= 0:
+        raise DecoderError(f"invalid Y4M {field}")
+    return result
+
+
+def _parse_header(line: bytes) -> _Header:
+    parts = line.split()
+    if not parts or parts[0] != b"YUV4MPEG2":
+        raise DecoderError("unsupported local video format; expected YUV4MPEG2")
+    fields = {part[:1]: part[1:] for part in parts[1:] if len(part) > 1}
+    if fields.get(b"C", b"444") not in {b"444", b"444jpeg"}:
+        raise DecoderError("unsupported Y4M chroma; only C444 is supported")
+    width = _positive_int(fields.get(b"W", b""), "width")
+    height = _positive_int(fields.get(b"H", b""), "height")
+    fps_parts = fields.get(b"F", b"").split(b":", 1)
+    if len(fps_parts) != 2:
+        raise DecoderError("invalid Y4M frame rate")
+    header = _Header(
+        width=width,
+        height=height,
+        fps_numerator=_positive_int(fps_parts[0], "frame rate numerator"),
+        fps_denominator=_positive_int(fps_parts[1], "frame rate denominator"),
+    )
+    if header.width * header.height * 3 > _MAX_FRAME_BYTES:
+        raise DecoderError("Y4M frame exceeds the safe size limit")
+    return header
+
+
+class Y4MDecoder:
+    media_formats = frozenset({"container-bytes"})
+
+    def decode(
+        self,
+        packets: Iterable[InputPacket],
+        cancellation: CancellationToken | None = None,
+    ) -> Iterator[DecodedFrame]:
+        reader = _PacketReader(packets, cancellation)
+        try:
+            header_line = reader.line()
+            assert header_line is not None
+            header = _parse_header(header_line)
+            first = reader.first_packet
+            if first is None:
+                raise DecoderError("local video input is empty")
+            if (first.width, first.height) != (header.width, header.height):
+                raise DecoderError(
+                    "Y4M dimensions do not match the configured input profile "
+                    f"({header.width}x{header.height} != {first.width}x{first.height})"
+                )
+            interval_ns = round(1_000_000_000 * header.fps_denominator / header.fps_numerator)
+            frame_size = header.width * header.height * 3
+            sequence = 0
+            while True:
+                frame_header = reader.line(allow_clean_eof=True)
+                if frame_header is None:
+                    return
+                if frame_header != b"FRAME":
+                    raise DecoderError(f"invalid Y4M frame header at frame {sequence}")
+                payload = reader.exact(frame_size)
+                yield DecodedFrame(
+                    sequence=sequence,
+                    timestamp_ns=sequence * interval_ns,
+                    logical_device_id=first.logical_device_id,
+                    profile_id=first.profile_id,
+                    width=header.width,
+                    height=header.height,
+                    pixel_format="yuv444p",
+                    payload=payload,
+                )
+                sequence += 1
+        except _Cancelled:
+            return

Brain/src/yovision_brain/rules/__init__.py

@@ -0,0 +1,21 @@
+"""Brain-internal anonymous area and directional-line rules."""
+
+from .engine import RuleEngine
+from .models import (
+    AreaDefinition,
+    DirectionalLineDefinition,
+    NormalizedPoint,
+    RuleConfigError,
+    RuleDecision,
+    RuleSet,
+)
+
+__all__ = [
+    "AreaDefinition",
+    "DirectionalLineDefinition",
+    "NormalizedPoint",
+    "RuleConfigError",
+    "RuleDecision",
+    "RuleEngine",
+    "RuleSet",
+]

Brain/src/yovision_brain/rules/engine.py

@@ -0,0 +1,112 @@
+"""Stateful, explainable area and directional-line evaluation."""
+
+from __future__ import annotations
+
+from yovision_brain.vision import TrackedObject
+
+from .models import NormalizedPoint, RuleConfigError, RuleDecision, RuleSet
+
+_EPSILON = 1e-9
+
+
+def _anchor(track: TrackedObject, width: int, height: int) -> NormalizedPoint:
+    x = (track.box.left + track.box.right) / (2.0 * width)
+    y = track.box.bottom / height
+    try:
+        return NormalizedPoint(x, y)
+    except RuleConfigError as exc:
+        raise RuleConfigError(f"track {track.track_id!r} anchor is outside the configured frame") from exc
+
+
+def _on_segment(point: NormalizedPoint, first: NormalizedPoint, second: NormalizedPoint) -> bool:
+    cross = (second.x - first.x) * (point.y - first.y) - (second.y - first.y) * (point.x - first.x)
+    return abs(cross) <= _EPSILON and min(first.x, second.x) - _EPSILON <= point.x <= max(first.x, second.x) + _EPSILON and min(first.y, second.y) - _EPSILON <= point.y <= max(first.y, second.y) + _EPSILON
+
+
+def _inside(point: NormalizedPoint, polygon: tuple[NormalizedPoint, ...]) -> bool:
+    inside = False
+    previous = polygon[-1]
+    for current in polygon:
+        if _on_segment(point, previous, current):
+            return True
+        if (current.y > point.y) != (previous.y > point.y):
+            crossing_x = (previous.x - current.x) * (point.y - current.y) / (previous.y - current.y) + current.x
+            if point.x < crossing_x:
+                inside = not inside
+        previous = current
+    return inside
+
+
+def _side(point: NormalizedPoint, start: NormalizedPoint, end: NormalizedPoint) -> float:
+    return (end.x - start.x) * (point.y - start.y) - (end.y - start.y) * (point.x - start.x)
+
+
+class RuleEngine:
+    """Evaluates one versioned rule set against one stream session."""
+
+    def __init__(self, rules: RuleSet) -> None:
+        self._rules = rules
+        self._area_inside: dict[tuple[str, str], bool] = {}
+        self._line_side: dict[tuple[str, str], int] = {}
+
+    def evaluate(
+        self,
+        tracks: tuple[TrackedObject, ...],
+        *,
+        profile_id: str,
+        width: int,
+        height: int,
+    ) -> tuple[RuleDecision, ...]:
+        if (profile_id, width, height) != (self._rules.profile_id, self._rules.width, self._rules.height):
+            raise RuleConfigError("track Profile/resolution does not match the versioned rule configuration")
+        decisions: list[RuleDecision] = []
+        for track in tracks:
+            anchor = _anchor(track, width, height)
+            common = dict(
+                track_id=track.track_id,
+                config_version=self._rules.version,
+                profile_id=profile_id,
+                width=width,
+                height=height,
+                anchor=anchor,
+                timestamp_ns=track.timestamp_ns,
+            )
+            for area in self._rules.areas:
+                key = (track.track_id, area.rule_id)
+                current = _inside(anchor, area.points)
+                previous = self._area_inside.get(key, False)
+                state = "entered" if current and not previous else "inside" if current else "outside"
+                self._area_inside[key] = current
+                decisions.append(RuleDecision(
+                    rule_id=area.rule_id,
+                    rule_type="danger_area",
+                    state=state,
+                    triggered=state == "entered",
+                    reason=f"bottom-center anchor is {state} the configured polygon",
+                    **common,
+                ))
+            for line in self._rules.directional_lines:
+                key = (track.track_id, line.rule_id)
+                value = _side(anchor, line.start, line.end)
+                if abs(value) <= line.deadband:
+                    decisions.append(RuleDecision(
+                        rule_id=line.rule_id, rule_type="directional_line", state="on_line",
+                        triggered=False, reason="anchor is inside the line deadband; previous significant side is retained",
+                        **common,
+                    ))
+                    continue
+                current_side = 1 if value > 0 else -1
+                previous_side = self._line_side.get(key)
+                self._line_side[key] = current_side
+                wanted = (previous_side, current_side) == ((1, -1) if line.trigger_direction == "left_to_right" else (-1, 1))
+                crossed = previous_side is not None and previous_side != current_side
+                state = "triggered" if wanted else "reverse_crossing" if crossed else "same_side"
+                decisions.append(RuleDecision(
+                    rule_id=line.rule_id,
+                    rule_type="directional_line",
+                    state=state,
+                    triggered=wanted,
+                    reason=f"directed side transition {previous_side!r}->{current_side}; expected {line.trigger_direction}",
+                    **common,
+                ))
+        return tuple(decisions)

Brain/src/yovision_brain/rules/models.py

@@ -0,0 +1,84 @@
+"""Versioned Brain-internal rule configuration and decisions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class RuleConfigError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class NormalizedPoint:
+    x: float
+    y: float
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.x <= 1.0 or not 0.0 <= self.y <= 1.0:
+            raise RuleConfigError("rule coordinates must be normalized to 0..1")
+
+
+@dataclass(frozen=True, slots=True)
+class AreaDefinition:
+    rule_id: str
+    points: tuple[NormalizedPoint, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DirectionalLineDefinition:
+    rule_id: str
+    start: NormalizedPoint
+    end: NormalizedPoint
+    trigger_direction: str
+    deadband: float = 0.005
+
+
+@dataclass(frozen=True, slots=True)
+class RuleSet:
+    version: str
+    profile_id: str
+    width: int
+    height: int
+    areas: tuple[AreaDefinition, ...] = ()
+    directional_lines: tuple[DirectionalLineDefinition, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.version or not self.profile_id or self.width <= 0 or self.height <= 0:
+            raise RuleConfigError("rule version, profile and dimensions are required")
+        identifiers = [rule.rule_id for rule in self.areas] + [rule.rule_id for rule in self.directional_lines]
+        if any(not identifier for identifier in identifiers) or len(set(identifiers)) != len(identifiers):
+            raise RuleConfigError("rule ids must be non-empty and unique")
+        for area in self.areas:
+            if len(area.points) < 3 or abs(_polygon_area(area.points)) < 1e-9:
+                raise RuleConfigError(f"area {area.rule_id!r} must be a non-degenerate polygon")
+        for line in self.directional_lines:
+            if line.start == line.end:
+                raise RuleConfigError(f"line {line.rule_id!r} must have distinct endpoints")
+            if line.trigger_direction not in {"left_to_right", "right_to_left"}:
+                raise RuleConfigError(f"line {line.rule_id!r} has invalid trigger direction")
+            if not 0.0 <= line.deadband < 0.5:
+                raise RuleConfigError(f"line {line.rule_id!r} has invalid deadband")
+
+
+def _polygon_area(points: tuple[NormalizedPoint, ...]) -> float:
+    return sum(
+        first.x * second.y - second.x * first.y
+        for first, second in zip(points, points[1:] + points[:1])
+    ) / 2.0
+
+
+@dataclass(frozen=True, slots=True)
+class RuleDecision:
+    rule_id: str
+    rule_type: str
+    track_id: str
+    state: str
+    triggered: bool
+    reason: str
+    config_version: str
+    profile_id: str
+    width: int
+    height: int
+    anchor: NormalizedPoint
+    timestamp_ns: int

Brain/src/yovision_brain/vision/__init__.py

@@ -0,0 +1,16 @@
+"""Anonymous detection and single-stream tracking."""
+
+from .detector import LumaBlobDetector, TorchLumaBlobDetector
+from .models import BoundingBox, Detection, Detector, DetectorMetadata, TrackedObject
+from .tracker import SingleStreamTracker
+
+__all__ = [
+    "BoundingBox",
+    "Detection",
+    "Detector",
+    "DetectorMetadata",
+    "LumaBlobDetector",
+    "SingleStreamTracker",
+    "TorchLumaBlobDetector",
+    "TrackedObject",
+]

Brain/src/yovision_brain/vision/detector.py

@@ -0,0 +1,120 @@
+"""Deterministic anonymous blob detectors with no biometric semantics."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from yovision_brain.decode import DecodedFrame, DecoderError
+
+from .models import BoundingBox, Detection, DetectorMetadata
+
+_METADATA = DetectorMetadata(
+    name="yovision-luma-blob",
+    version="1.0.0",
+    source="YoVision Brain first-party deterministic algorithm",
+    license="No external model license; no learned weights are distributed",
+    weights="none",
+)
+
+
+def _components(mask: Sequence[Sequence[bool]], minimum_area: int) -> tuple[BoundingBox, ...]:
+    height = len(mask)
+    width = len(mask[0]) if height else 0
+    visited: set[tuple[int, int]] = set()
+    boxes: list[BoundingBox] = []
+    for y in range(height):
+        for x in range(width):
+            if not mask[y][x] or (x, y) in visited:
+                continue
+            pending = [(x, y)]
+            visited.add((x, y))
+            points: list[tuple[int, int]] = []
+            while pending:
+                current_x, current_y = pending.pop()
+                points.append((current_x, current_y))
+                for neighbor in (
+                    (current_x - 1, current_y),
+                    (current_x + 1, current_y),
+                    (current_x, current_y - 1),
+                    (current_x, current_y + 1),
+                ):
+                    nx, ny = neighbor
+                    if 0 <= nx < width and 0 <= ny < height and mask[ny][nx] and neighbor not in visited:
+                        visited.add(neighbor)
+                        pending.append(neighbor)
+            if len(points) >= minimum_area:
+                xs, ys = zip(*points)
+                boxes.append(BoundingBox(min(xs), min(ys), max(xs) + 1, max(ys) + 1))
+    return tuple(sorted(boxes, key=lambda box: (box.top, box.left, box.bottom, box.right)))
+
+
+def _validate_frame(frame: DecodedFrame) -> None:
+    if frame.pixel_format not in {"rgb24", "yuv444p"}:
+        raise DecoderError(f"anonymous detector does not support pixel format {frame.pixel_format!r}")
+    expected = frame.width * frame.height * 3
+    if len(frame.payload) != expected:
+        raise DecoderError(f"vision frame has {len(frame.payload)} bytes; expected {expected}")
+
+
+class LumaBlobDetector:
+    """Small CPU reference detector used for deterministic integration tests."""
+
+    metadata = _METADATA
+
+    def __init__(self, *, threshold: int = 200, minimum_area: int = 1) -> None:
+        if not 0 <= threshold <= 255 or minimum_area < 1:
+            raise ValueError("invalid luma detector threshold or minimum area")
+        self._threshold = threshold
+        self._minimum_area = minimum_area
+
+    def detect(self, frame: DecodedFrame) -> tuple[Detection, ...]:
+        _validate_frame(frame)
+        if frame.pixel_format == "rgb24":
+            pixels = [
+                max(frame.payload[index : index + 3])
+                for index in range(0, len(frame.payload), 3)
+            ]
+        else:
+            pixels = list(frame.payload[: frame.width * frame.height])
+        mask = [
+            [pixels[y * frame.width + x] >= self._threshold for x in range(frame.width)]
+            for y in range(frame.height)
+        ]
+        return tuple(
+            Detection(box=box, category="anonymous_target", confidence=1.0)
+            for box in _components(mask, self._minimum_area)
+        )
+
+
+class TorchLumaBlobDetector:
+    """PyTorch CPU/GPU smoke backend; it contains no external model weights."""
+
+    metadata = DetectorMetadata(
+        name="yovision-torch-luma-blob",
+        version="1.0.0",
+        source="YoVision Brain first-party PyTorch tensor implementation",
+        license="PyTorch BSD-3-Clause; no external model weights",
+        weights="none",
+    )
+
+    def __init__(self, *, threshold: int = 200, minimum_area: int = 1, device: str = "cpu") -> None:
+        self._threshold = threshold
+        self._minimum_area = minimum_area
+        self._device = device
+
+    def detect(self, frame: DecodedFrame) -> tuple[Detection, ...]:
+        _validate_frame(frame)
+        try:
+            import torch
+        except ImportError as exc:
+            raise RuntimeError("PyTorch runtime is required for TorchLumaBlobDetector") from exc
+        values = torch.tensor(list(frame.payload), dtype=torch.uint8, device=self._device)
+        if frame.pixel_format == "rgb24":
+            luma = values.reshape(frame.height, frame.width, 3).amax(dim=2)
+        else:
+            luma = values[: frame.width * frame.height].reshape(frame.height, frame.width)
+        mask = (luma >= self._threshold).cpu().tolist()
+        return tuple(
+            Detection(box=box, category="anonymous_target", confidence=1.0)
+            for box in _components(mask, self._minimum_area)
+        )

Brain/src/yovision_brain/vision/models.py

@@ -0,0 +1,52 @@
+"""Privacy-preserving vision ports and observations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from yovision_brain.decode import DecodedFrame
+
+
+@dataclass(frozen=True, slots=True)
+class DetectorMetadata:
+    name: str
+    version: str
+    source: str
+    license: str
+    weights: str
+
+
+@dataclass(frozen=True, slots=True)
+class BoundingBox:
+    left: int
+    top: int
+    right: int
+    bottom: int
+
+    @property
+    def area(self) -> int:
+        return max(0, self.right - self.left) * max(0, self.bottom - self.top)
+
+
+@dataclass(frozen=True, slots=True)
+class Detection:
+    box: BoundingBox
+    category: str
+    confidence: float
+
+
+@dataclass(frozen=True, slots=True)
+class TrackedObject:
+    track_id: str
+    box: BoundingBox
+    category: str
+    confidence: float
+    frame_sequence: int
+    timestamp_ns: int
+
+
+class Detector(Protocol):
+    metadata: DetectorMetadata
+
+    def detect(self, frame: DecodedFrame) -> tuple[Detection, ...]: ...

Brain/src/yovision_brain/vision/tracker.py

@@ -0,0 +1,83 @@
+"""Session-local single-stream IoU tracker."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import BoundingBox, Detection, TrackedObject
+
+
+def _iou(first: BoundingBox, second: BoundingBox) -> float:
+    intersection = BoundingBox(
+        max(first.left, second.left),
+        max(first.top, second.top),
+        min(first.right, second.right),
+        min(first.bottom, second.bottom),
+    ).area
+    union = first.area + second.area - intersection
+    return intersection / union if union else 0.0
+
+
+@dataclass(slots=True)
+class _Track:
+    track_id: str
+    detection: Detection
+    missed: int = 0
+
+
+class SingleStreamTracker:
+    """Tracks anonymous boxes only within one process session and one stream."""
+
+    def __init__(self, *, iou_threshold: float = 0.2, max_missed: int = 2) -> None:
+        if not 0.0 <= iou_threshold <= 1.0 or max_missed < 0:
+            raise ValueError("invalid tracker threshold or missed-frame limit")
+        self._iou_threshold = iou_threshold
+        self._max_missed = max_missed
+        self._tracks: dict[str, _Track] = {}
+        self._next_id = 1
+
+    def update(
+        self,
+        detections: tuple[Detection, ...],
+        *,
+        frame_sequence: int,
+        timestamp_ns: int,
+    ) -> tuple[TrackedObject, ...]:
+        unmatched_tracks = set(self._tracks)
+        results: list[TrackedObject] = []
+        for detection in detections:
+            candidates = [
+                (track_id, _iou(self._tracks[track_id].detection.box, detection.box))
+                for track_id in unmatched_tracks
+                if self._tracks[track_id].detection.category == detection.category
+            ]
+            track_id, score = max(candidates, key=lambda item: item[1], default=("", -1.0))
+            if score < self._iou_threshold:
+                track_id = f"track-{self._next_id:06d}"
+                self._next_id += 1
+                self._tracks[track_id] = _Track(track_id, detection)
+            else:
+                unmatched_tracks.remove(track_id)
+                self._tracks[track_id].detection = detection
+                self._tracks[track_id].missed = 0
+            results.append(
+                TrackedObject(
+                    track_id=track_id,
+                    box=detection.box,
+                    category=detection.category,
+                    confidence=detection.confidence,
+                    frame_sequence=frame_sequence,
+                    timestamp_ns=timestamp_ns,
+                )
+            )
+        for track_id in unmatched_tracks:
+            track = self._tracks[track_id]
+            track.missed += 1
+            if track.missed > self._max_missed:
+                del self._tracks[track_id]
+        return tuple(results)
+
+    def finish(self) -> tuple[str, ...]:
+        ended = tuple(sorted(self._tracks))
+        self._tracks.clear()
+        return ended

Brain/tests/decode/test_pipeline.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from yovision_brain.config import parse_input_config
+from yovision_brain.decode import DecoderError, DecoderPipeline, decode_packets
+from yovision_brain.input import CancellationToken, InputPacket, LocalFileInput, SyntheticInput
+
+
+def synthetic_packets():
+    config = parse_input_config(
+        {
+            "schema": "brain.internal.input/v1",
+            "logical_device_id": "synthetic-01",
+            "profile": {"id": "main", "width": 2, "height": 1, "fps": 5},
+            "source": {"kind": "synthetic", "seed": 3, "frame_count": 2},
+        }
+    )
+    return SyntheticInput(config).packets()
+
+
+def local_packets(path: Path, *, width: int = 2, height: int = 1, chunk_size: int = 5):
+    config = parse_input_config(
+        {
+            "schema": "brain.internal.input/v1",
+            "logical_device_id": "local-01",
+            "profile": {"id": "archive", "width": width, "height": height, "fps": 25},
+            "source": {"kind": "local_file", "path": str(path), "chunk_size": chunk_size},
+        }
+    )
+    return LocalFileInput(config).packets()
+
+
+def test_rgb24_pipeline_preserves_order_timestamps_and_metadata() -> None:
+    frames = list(decode_packets(synthetic_packets()))
+    assert [frame.sequence for frame in frames] == [0, 1]
+    assert [frame.timestamp_ns for frame in frames] == [0, 200_000_000]
+    assert all(frame.logical_device_id == "synthetic-01" for frame in frames)
+    assert all(frame.profile_id == "main" for frame in frames)
+    assert all((frame.width, frame.height, frame.pixel_format) == (2, 1, "rgb24") for frame in frames)
+
+
+def test_rgb24_dimension_change_is_explicit() -> None:
+    packets = [
+        InputPacket(0, 0, "camera", "main", 1, 1, "rgb24", b"abc"),
+        InputPacket(1, 1, "camera", "main", 2, 1, "rgb24", b"abcdef"),
+    ]
+    frames = list(decode_packets(packets))
+    assert [frame.dimensions_changed for frame in frames] == [False, True]
+
+
+def test_invalid_rgb_payload_and_unsupported_format_are_clear() -> None:
+    bad = [InputPacket(0, 0, "camera", "main", 2, 2, "rgb24", b"short")]
+    with pytest.raises(DecoderError, match="expected 12"):
+        list(decode_packets(bad))
+    unknown = [InputPacket(0, 0, "camera", "main", 1, 1, "opaque", b"data")]
+    with pytest.raises(DecoderError, match="no decoder registered"):
+        list(DecoderPipeline().decode(unknown))
+
+
+def test_y4m_local_video_decodes_across_input_chunks(tmp_path: Path) -> None:
+    video = tmp_path / "anonymous.y4m"
+    first, second = b"abcdef", b"ghijkl"
+    video.write_bytes(b"YUV4MPEG2 W2 H1 F25:1 C444\nFRAME\n" + first + b"FRAME\n" + second)
+    frames = list(decode_packets(local_packets(video)))
+    assert [frame.payload for frame in frames] == [first, second]
+    assert [frame.timestamp_ns for frame in frames] == [0, 40_000_000]
+    assert all(frame.pixel_format == "yuv444p" for frame in frames)
+    assert all((frame.width, frame.height) == (2, 1) for frame in frames)
+    assert all(frame.profile_id == "archive" for frame in frames)
+
+
+def test_y4m_clean_eof_and_cancellation_are_normal(tmp_path: Path) -> None:
+    video = tmp_path / "empty.y4m"
+    video.write_bytes(b"YUV4MPEG2 W2 H1 F25:1 C444\n")
+    assert list(decode_packets(local_packets(video))) == []
+
+    token = CancellationToken()
+    token.cancel()
+    assert list(decode_packets(local_packets(video), token)) == []
+
+
+@pytest.mark.parametrize(
+    ("payload", "message"),
+    [
+        (b"not-video\n", "expected YUV4MPEG2"),
+        (b"YUV4MPEG2 W2 H1 F25:1 C420\n", "only C444"),
+        (b"YUV4MPEG2 W2 H1 F25:1 C444\nFRAME\nabc", "truncated Y4M frame"),
+    ],
+)
+def test_y4m_damage_and_unsupported_content_are_clear(tmp_path: Path, payload: bytes, message: str) -> None:
+    video = tmp_path / "broken.y4m"
+    video.write_bytes(payload)
+    with pytest.raises(DecoderError, match=message):
+        list(decode_packets(local_packets(video)))
+
+
+def test_y4m_profile_dimension_mismatch_is_rejected(tmp_path: Path) -> None:
+    video = tmp_path / "mismatch.y4m"
+    video.write_bytes(b"YUV4MPEG2 W2 H1 F25:1 C444\n")
+    with pytest.raises(DecoderError, match="do not match"):
+        list(decode_packets(local_packets(video, width=3)))

Brain/tests/fixtures/decode/README.md

@@ -0,0 +1,5 @@
+# Brain decode fixtures
+
+Decode tests generate tiny anonymous YUV4MPEG2 streams at runtime. Do not add
+customer recordings, camera credentials, machine-specific codec paths, or
+large model/media artifacts to this directory.

Brain/tests/fixtures/rules/README.md

@@ -0,0 +1,5 @@
+# Brain rule fixtures
+
+Rule tests use normalized synthetic geometry and anonymous track IDs only. Do
+not add customer site layouts, camera paths, identities, credentials, or a
+copy of a future cross-project contract.

Brain/tests/fixtures/vision/README.md

@@ -0,0 +1,5 @@
+# Brain vision fixtures
+
+Vision tests create anonymous geometric RGB frames in memory. Never add faces,
+customer recordings, biometric templates, camera credentials, or unreviewed
+model weights to this directory.

Brain/tests/rules/test_engine.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import pytest
+
+from yovision_brain.rules import (
+    AreaDefinition,
+    DirectionalLineDefinition,
+    NormalizedPoint,
+    RuleConfigError,
+    RuleEngine,
+    RuleSet,
+)
+from yovision_brain.vision import BoundingBox, TrackedObject
+
+
+def point(x: float, y: float) -> NormalizedPoint:
+    return NormalizedPoint(x, y)
+
+
+def rules() -> RuleSet:
+    return RuleSet(
+        version="rules-v7",
+        profile_id="main",
+        width=100,
+        height=100,
+        areas=(AreaDefinition("yard", (point(0.2, 0.2), point(0.8, 0.2), point(0.8, 0.8), point(0.2, 0.8))),),
+        directional_lines=(DirectionalLineDefinition("gate", point(0.5, 0.1), point(0.5, 0.9), "left_to_right", 0.01),),
+    )
+
+
+def track(track_id: str, anchor_x: int, anchor_y: int, sequence: int = 0) -> TrackedObject:
+    return TrackedObject(track_id, BoundingBox(anchor_x - 1, anchor_y - 2, anchor_x + 1, anchor_y), "anonymous_target", 1.0, sequence, sequence)
+
+
+def decisions(engine: RuleEngine, item: TrackedObject):
+    return engine.evaluate((item,), profile_id="main", width=100, height=100)
+
+
+def test_area_outside_entered_inside_and_boundary() -> None:
+    engine = RuleEngine(rules())
+    assert decisions(engine, track("one", 10, 50))[0].state == "outside"
+    entered = decisions(engine, track("one", 20, 50, 1))[0]
+    assert (entered.state, entered.triggered) == ("entered", True)
+    inside = decisions(engine, track("one", 50, 50, 2))[0]
+    assert (inside.state, inside.triggered) == ("inside", False)
+    assert inside.config_version == "rules-v7"
+
+
+def test_direction_and_reverse_crossing_are_distinct() -> None:
+    engine = RuleEngine(rules())
+    decisions(engine, track("one", 40, 50))
+    forward = decisions(engine, track("one", 60, 50, 1))[1]
+    assert (forward.state, forward.triggered) == ("triggered", True)
+
+    reverse_engine = RuleEngine(rules())
+    decisions(reverse_engine, track("two", 60, 50))
+    reverse = decisions(reverse_engine, track("two", 40, 50, 1))[1]
+    assert (reverse.state, reverse.triggered) == ("reverse_crossing", False)
+
+
+def test_line_deadband_prevents_jitter_trigger() -> None:
+    engine = RuleEngine(rules())
+    decisions(engine, track("one", 40, 50))
+    on_line = decisions(engine, track("one", 50, 50, 1))[1]
+    assert (on_line.state, on_line.triggered) == ("on_line", False)
+    triggered = decisions(engine, track("one", 60, 50, 2))[1]
+    assert triggered.triggered is True
+
+
+def test_profile_resolution_mismatch_is_rejected() -> None:
+    with pytest.raises(RuleConfigError, match="Profile/resolution"):
+        RuleEngine(rules()).evaluate((track("one", 20, 20),), profile_id="sub", width=100, height=100)
+
+
+def test_invalid_polygon_line_and_duplicate_ids_are_rejected() -> None:
+    with pytest.raises(RuleConfigError, match="non-degenerate"):
+        RuleSet("v", "main", 10, 10, areas=(AreaDefinition("bad", (point(0, 0), point(0.5, 0.5), point(1, 1))),))
+    with pytest.raises(RuleConfigError, match="distinct endpoints"):
+        RuleSet("v", "main", 10, 10, directional_lines=(DirectionalLineDefinition("bad", point(0, 0), point(0, 0), "left_to_right"),))
+    with pytest.raises(RuleConfigError, match="unique"):
+        RuleSet("v", "main", 10, 10, areas=(AreaDefinition("same", (point(0, 0), point(1, 0), point(0, 1))),), directional_lines=(DirectionalLineDefinition("same", point(0, 0), point(1, 1), "left_to_right"),))

Brain/tests/vision/test_detection_tracking.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import pytest
+
+from yovision_brain.decode import DecodedFrame
+from yovision_brain.vision import (
+    BoundingBox,
+    Detection,
+    LumaBlobDetector,
+    SingleStreamTracker,
+    TorchLumaBlobDetector,
+)
+
+
+def frame(payload: bytes, *, sequence: int = 0, width: int = 4, height: int = 3) -> DecodedFrame:
+    return DecodedFrame(sequence, sequence * 40_000_000, "camera", "main", width, height, "rgb24", payload)
+
+
+def rgb(values: list[int]) -> bytes:
+    return b"".join(bytes((value, value, value)) for value in values)
+
+
+def detection(left: int, top: int, right: int, bottom: int) -> Detection:
+    return Detection(BoundingBox(left, top, right, bottom), "anonymous_target", 0.9)
+
+
+def test_detector_emits_only_anonymous_observations() -> None:
+    payload = rgb([0, 255, 255, 0, 0, 255, 255, 0, 0, 0, 0, 0])
+    result = LumaBlobDetector(minimum_area=2).detect(frame(payload))
+    assert result == (Detection(BoundingBox(1, 0, 3, 2), "anonymous_target", 1.0),)
+    assert LumaBlobDetector.metadata.weights == "none"
+    assert "external model license" in LumaBlobDetector.metadata.license
+
+
+def test_empty_frame_has_no_detection() -> None:
+    assert LumaBlobDetector().detect(frame(rgb([0] * 12))) == ()
+
+
+def test_tracker_keeps_session_id_across_motion_and_short_occlusion() -> None:
+    tracker = SingleStreamTracker(iou_threshold=0.1, max_missed=2)
+    first = tracker.update((detection(0, 0, 3, 3),), frame_sequence=0, timestamp_ns=0)
+    assert first[0].track_id == "track-000001"
+    assert tracker.update((), frame_sequence=1, timestamp_ns=1) == ()
+    resumed = tracker.update((detection(1, 0, 4, 3),), frame_sequence=2, timestamp_ns=2)
+    assert resumed[0].track_id == "track-000001"
+    assert tracker.finish() == ("track-000001",)
+
+
+def test_disappeared_track_ends_and_new_target_gets_new_id() -> None:
+    tracker = SingleStreamTracker(max_missed=1)
+    first = tracker.update((detection(0, 0, 2, 2),), frame_sequence=0, timestamp_ns=0)
+    tracker.update((), frame_sequence=1, timestamp_ns=1)
+    tracker.update((), frame_sequence=2, timestamp_ns=2)
+    second = tracker.update((detection(0, 0, 2, 2),), frame_sequence=3, timestamp_ns=3)
+    assert first[0].track_id == "track-000001"
+    assert second[0].track_id == "track-000002"
+
+
+def test_track_ids_are_session_local() -> None:
+    one = SingleStreamTracker().update((detection(0, 0, 1, 1),), frame_sequence=0, timestamp_ns=0)
+    two = SingleStreamTracker().update((detection(0, 0, 1, 1),), frame_sequence=0, timestamp_ns=0)
+    assert one[0].track_id == two[0].track_id == "track-000001"
+
+
+def test_torch_backend_cpu_smoke_uses_no_external_weights() -> None:
+    pytest.importorskip("torch")
+    result = TorchLumaBlobDetector().detect(frame(rgb([0, 255] + [0] * 10)))
+    assert result[0].category == "anonymous_target"
+    assert TorchLumaBlobDetector.metadata.weights == "none"