braidpipe 0.3.0__tar.gz

braidpipe-0.3.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: braidpipe
+Version: 0.3.0
+Summary: Worker SDK for braidpipe, the never-dark AI video middleware: write a function that mutates a frame, the SDK runs the IPC loop.
+Author: braidpipe contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/emdiple/braidpipe
+Keywords: video,streaming,gstreamer,computer-vision,shared-memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Provides-Extra: examples
+Requires-Dist: opencv-python; extra == "examples"
+
+# braidpipe (worker SDK)
+
+The Python worker SDK for [braidpipe](https://github.com/emdiple/braidpipe), the
+never-dark AI video middleware. The Rust daemon owns the media path; this
+package is how a Python process receives its frames — as zero-copy NumPy views
+over shared memory locally, or over the tcp-raw transport from another machine —
+and hands them back.
+
+A complete worker:
+
+```python
+import braidpipe
+
+def process(frame):          # (H, W, 3) uint8, RGB — mutate it in place
+    frame[:, :, 0] //= 2     # your inference here
+
+if __name__ == "__main__":
+    braidpipe.run(process)
+```
+
+`run()` owns everything else: the handshake, the per-frame notification loop,
+freeing the shared-memory slot, acking (including `"success": false` when your
+code raises, so the stream falls back to passthrough instead of going dark),
+and the transport switch — set `BRAIDPIPE_DAEMON=host:port` and the same worker
+attaches over the network instead.
+
+This package does not contain the daemon. Build it from the
+[repository](https://github.com/emdiple/braidpipe), which also has the full
+worker contract, examples, and deadline rules in `docs/workers.md`.

braidpipe-0.3.0/README.md

@@ -0,0 +1,29 @@
+# braidpipe (worker SDK)
+
+The Python worker SDK for [braidpipe](https://github.com/emdiple/braidpipe), the
+never-dark AI video middleware. The Rust daemon owns the media path; this
+package is how a Python process receives its frames — as zero-copy NumPy views
+over shared memory locally, or over the tcp-raw transport from another machine —
+and hands them back.
+
+A complete worker:
+
+```python
+import braidpipe
+
+def process(frame):          # (H, W, 3) uint8, RGB — mutate it in place
+    frame[:, :, 0] //= 2     # your inference here
+
+if __name__ == "__main__":
+    braidpipe.run(process)
+```
+
+`run()` owns everything else: the handshake, the per-frame notification loop,
+freeing the shared-memory slot, acking (including `"success": false` when your
+code raises, so the stream falls back to passthrough instead of going dark),
+and the transport switch — set `BRAIDPIPE_DAEMON=host:port` and the same worker
+attaches over the network instead.
+
+This package does not contain the daemon. Build it from the
+[repository](https://github.com/emdiple/braidpipe), which also has the full
+worker contract, examples, and deadline rules in `docs/workers.md`.

braidpipe-0.3.0/braidpipe/__init__.py

@@ -0,0 +1,44 @@
+"""The braidpipe worker SDK: your function, our loop.
+
+A complete worker is a processing function handed to `run()`:
+
+    import braidpipe
+
+    def process(frame):          # (H, W, 3) uint8, RGB — mutate it in place
+        frame[:, :, 0] //= 2     # your inference here
+
+    if __name__ == "__main__":
+        braidpipe.run(process)
+
+`run()` owns the handshake, the per-frame loop, slot release, acking (including
+`"success": false` when the handler raises, so the stream falls back to
+passthrough instead of going dark) and the transport: shared memory next to a
+local daemon, tcp-raw when `BRAIDPIPE_DAEMON=host:port` is set. Take a second
+`ctx` parameter for frame ids and timestamps, and use `BackgroundModel` for
+models too slow for the 1.5-frame-period deadline.
+
+The transports underneath (`attach`/`SharedMemoryManager` for shared memory,
+`connect`/`RemoteWorkerLink` for tcp-raw) stay importable for workers that need
+the loop itself.
+"""
+
+from .background import BackgroundModel
+from .contract import CONTRACT_VERSION
+from .remote import RemoteWorkerLink, connect
+from .runner import FrameContext, run, worker
+from .shm import SharedMemoryManager, attach
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "BackgroundModel",
+    "CONTRACT_VERSION",
+    "FrameContext",
+    "RemoteWorkerLink",
+    "SharedMemoryManager",
+    "attach",
+    "connect",
+    "run",
+    "worker",
+    "__version__",
+]

braidpipe-0.3.0/braidpipe/__main__.py

@@ -0,0 +1,16 @@
+"""`python3 -m braidpipe`: the raw worker with no processing at all.
+
+Attaches, acks every frame untouched, and proves the AI loop is closed — the
+same thing python/braidpipe/worker.py does, without needing a path to a script.
+"""
+
+import numpy as np
+
+from .runner import run
+
+
+def process(frame: np.ndarray) -> None:
+    """Deliberately empty: every frame passes through the loop unmodified."""
+
+
+run(process, name="braidpipe")

braidpipe-0.3.0/braidpipe/background.py

@@ -0,0 +1,78 @@
+"""Off-hot-path inference: run a slow model on a thread, read cached results.
+
+The relay gives a worker 1.5 frame periods, and most real models do not fit in
+that. The trade that works is to decouple "what is in the frame" (slow, cached)
+from "draw it" (fast, every frame): submit an occasional frame to the model,
+annotate every frame with the most recent answer. Results lag the picture by a
+frame or two; no frame ever misses its deadline.
+
+`BackgroundModel` is that pattern with the threading taken out of your hands:
+
+    model = braidpipe.BackgroundModel(infer, initial=[])
+
+    def process(frame, ctx):
+        if ctx.frame_id % 3 == 0:
+            model.submit(frame)
+        draw(frame, model.latest())
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, Generic, TypeVar
+
+import numpy as np
+
+T = TypeVar("T")
+
+
+class BackgroundModel(Generic[T]):
+    """Runs `infer(frame) -> result` on a daemon thread, one frame at a time.
+
+    `submit()` copies the frame — the shared-memory slot is recycled the moment
+    the handler returns — and is dropped, not queued, while a previous frame is
+    still being inferred, so the model always works on the newest picture it
+    can get. `latest()` returns the most recent result, or `initial` until the
+    first inference completes. An exception in `infer` is logged and the result
+    left unchanged; the thread never dies.
+    """
+
+    def __init__(self, infer: Callable[[np.ndarray], T], initial: T = None):
+        self._infer = infer
+        self._pending: np.ndarray | None = None
+        self._latest: T = initial
+        self._lock = threading.Lock()
+        self._wake = threading.Event()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+
+    def submit(self, frame: np.ndarray) -> None:
+        """Offer a frame for inference; skipped if one is already waiting."""
+        with self._lock:
+            if self._pending is not None:
+                return
+            self._pending = frame.copy()
+        self._wake.set()
+
+    def latest(self) -> T:
+        with self._lock:
+            return self._latest
+
+    def _loop(self) -> None:
+        while True:
+            self._wake.wait()
+            self._wake.clear()
+
+            with self._lock:
+                frame, self._pending = self._pending, None
+            if frame is None:
+                continue
+
+            try:
+                result = self._infer(frame)
+            except Exception as exc:  # a bad frame must not kill the thread
+                print(f"[background] inference error: {exc}", flush=True)
+                continue
+
+            with self._lock:
+                self._latest = result

braidpipe-0.3.0/braidpipe/contract.py

@@ -0,0 +1,32 @@
+"""The IPC contract version this SDK speaks, and the check against the daemon.
+
+The contract is everything both sides must agree on: the shm/slot layouts, the
+control-packet fields, and the tcp-raw wire format. The daemon stamps its
+version into every config packet it answers a hello with; a mismatch here must
+fail at attach time, loudly, because the alternative is silently misreading
+shared memory.
+
+A config with no version at all comes from a daemon older than versioning
+(braidpipe <= 0.2.0). Those daemons speak contract 1, so attaching proceeds
+with a warning rather than refusing streams that would work.
+"""
+
+CONTRACT_VERSION = 1
+
+
+def check_contract(config: dict, transport: str) -> None:
+    """Raises RuntimeError if the daemon's config names a different contract."""
+    theirs = config.get("contract")
+    if theirs is None:
+        print(
+            f"[braidpipe] warning: daemon sent no contract version over {transport} "
+            f"(daemon <= 0.2.0); assuming contract {CONTRACT_VERSION}",
+            flush=True,
+        )
+        return
+    if theirs != CONTRACT_VERSION:
+        raise RuntimeError(
+            f"daemon speaks IPC contract {theirs}, this SDK speaks {CONTRACT_VERSION} "
+            f"(over {transport}); upgrade whichever side is older instead of attaching "
+            "and misreading frames"
+        )

braidpipe-0.3.0/braidpipe/remote.py

@@ -0,0 +1,137 @@
+"""The tcp-raw transport: attach to a braidpipe daemon on another machine.
+
+Mirrors the shm handshake in shape: say hello, get a config packet back.
+Here the hello goes over UDP to the daemon's --worker-listen address, the
+config carries a TCP port instead of a file descriptor, and frames flow both
+ways on one TCP connection as a fixed 24-byte header plus raw pixel bytes.
+
+The frames are uncompressed, so this needs a fast link: 720p RGB at 30 fps is
+~660 Mbit/s each way. Use it on a 10 GbE LAN (or 720p on a quiet gigabit
+link), not across the internet.
+"""
+
+import json
+import socket
+import struct
+import time
+
+import numpy as np
+
+from .contract import check_contract
+
+# Wire header matching Rust net.rs, 24 bytes little-endian:
+# frame_id u64, time_us u64, payload_len u32, slot u8, flags u8, 2 pad.
+# time_us carries the capture timestamp daemon -> worker and this worker's
+# processing time on the way back. Bit 0 of flags is "success" on results.
+WIRE_HEADER_FMT = "<QQIBB2x"
+WIRE_HEADER_SIZE = struct.calcsize(WIRE_HEADER_FMT)
+assert WIRE_HEADER_SIZE == 24
+
+HELLO = b'{"type":"hello","transports":["tcp-raw"]}'
+
+
+def connect(daemon: str, retry_interval: float = 1.0) -> "RemoteWorkerLink":
+    """Negotiates with the daemon at "host:port" until a data connection is up.
+
+    Retries forever, so a worker may start before the daemon and simply wait
+    for it -- the same contract the shm attach gives a local worker.
+    """
+    host, _, port_text = daemon.rpartition(":")
+    address = (host, int(port_text))
+
+    udp = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    udp.settimeout(retry_interval)
+    try:
+        while True:
+            try:
+                udp.sendto(HELLO, address)
+                reply, _ = udp.recvfrom(512)
+            except (TimeoutError, OSError):
+                time.sleep(retry_interval)
+                continue
+            config = json.loads(reply)
+            if config.get("type") == "config" and config.get("transport") == "tcp-raw":
+                check_contract(config, "tcp-raw")
+                break
+            raise RuntimeError(f"daemon refused tcp-raw: {config}")
+    finally:
+        udp.close()
+
+    tcp = socket.create_connection((host, config["data_port"]))
+    tcp.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+    return RemoteWorkerLink(tcp, config)
+
+
+class RemoteWorkerLink:
+    def __init__(self, sock: socket.socket, config: dict):
+        self.sock = sock
+        self.width = config["width"]
+        self.height = config["height"]
+        self.channels = config["channels"]
+        self._payload_len = self.width * self.height * self.channels
+        # One reusable buffer: frames are processed in place and sent back
+        # from the same bytes, so no per-frame allocation happens.
+        self._buf = bytearray(self._payload_len)
+        self._frame_view = np.frombuffer(self._buf, dtype=np.uint8).reshape(
+            self.height, self.width, self.channels
+        )
+
+    def frames(self):
+        """Yields (frame_id, slot, timestamp_us, frame) until the daemon hangs up.
+
+        `frame` is a NumPy view over an internal buffer that is reused for the
+        next frame -- process it (in place is fine) and call `send_processed`
+        before advancing the loop; copy it if you need to keep it longer.
+        """
+        header_buf = bytearray(WIRE_HEADER_SIZE)
+        frame = self._frame_view
+        while True:
+            if not self._recv_exact(header_buf):
+                return
+            frame_id, timestamp_us, payload_len, slot, _flags = struct.unpack(
+                WIRE_HEADER_FMT, header_buf
+            )
+            if payload_len != self._payload_len:
+                raise RuntimeError(
+                    f"daemon sent {payload_len} payload bytes, expected {self._payload_len}"
+                )
+            if not self._recv_exact(self._buf):
+                return
+            yield frame_id, slot, timestamp_us, frame
+
+    def send_processed(
+        self,
+        frame_id: int,
+        slot: int,
+        frame: np.ndarray,
+        processing_time_us: int,
+        success: bool = True,
+    ) -> None:
+        """Returns a result to the daemon; this doubles as the frame's ack."""
+        header = struct.pack(
+            WIRE_HEADER_FMT,
+            frame_id,
+            processing_time_us,
+            self._payload_len,
+            slot,
+            1 if success else 0,
+        )
+        self.sock.sendall(header)
+        if np.shares_memory(frame, self._frame_view):
+            # The frame is (a view of) the internal buffer; send it as-is.
+            self.sock.sendall(self._buf)
+        else:
+            self.sock.sendall(np.ascontiguousarray(frame).tobytes())
+
+    def _recv_exact(self, buf) -> bool:
+        """Fills `buf` completely, or returns False on a closed connection."""
+        view = memoryview(buf)
+        while view:
+            received = self.sock.recv_into(view, len(view))
+            if received == 0:
+                return False
+            view = view[received:]
+        return True
+
+    def close(self):
+        self.sock.close()

braidpipe-0.3.0/braidpipe/runner.py

@@ -0,0 +1,245 @@
+"""The worker loop as a library: write `process(frame)`, call `run(process)`.
+
+Every worker has the same four obligations — attach, receive a notification per
+frame, free the slot, ack — and the same failure contract: report an exception
+with `"success": false` instead of dying, so the daemon passes the original
+frame through and the stream never goes dark. This module owns all of that,
+for both transports:
+
+- shared memory + Unix datagrams when launched by (or next to) a local daemon,
+- tcp-raw when `BRAIDPIPE_DAEMON=host:port` points at a remote one.
+
+The processing callback is the only thing a worker author writes. It takes the
+frame — an (H, W, 3) uint8 RGB array to mutate in place — and optionally a
+`FrameContext`; raising is safe and costs one passthrough frame, but the
+callback must finish inside 1.5 frame periods (50 ms at 30 fps) or the daemon
+falls back to passthrough. Anything slower belongs off the hot path — see
+`braidpipe.BackgroundModel`.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import socket
+import time
+from dataclasses import dataclass
+from typing import Callable
+
+import numpy as np
+
+from .remote import connect
+from .shm import attach
+
+DEFAULT_RUST_SOCK = "/tmp/braidpipe_rust.sock"
+DEFAULT_PYTHON_SOCK = "/tmp/braidpipe_python.sock"
+
+ProcessFn = Callable[..., None]
+
+
+@dataclass(frozen=True)
+class FrameContext:
+    """Everything known about the frame besides its pixels.
+
+    `timestamp_us` is the wall clock the daemon recorded as it handed the frame
+    over (written into the slot header locally, carried on the wire remotely),
+    so `time.time_ns() // 1000 - ctx.timestamp_us` is the one-way IPC delay.
+    """
+
+    frame_id: int
+    slot: int
+    timestamp_us: int
+    width: int
+    height: int
+    channels: int
+    transport: str  # "shm" or "tcp-raw"
+
+
+_registered: ProcessFn | None = None
+
+
+def worker(process: ProcessFn) -> ProcessFn:
+    """Marks `process` as this script's frame handler, so `run()` finds it
+    without being passed anything. Sugar only: `run(process)` is the same."""
+    global _registered
+    _registered = process
+    return process
+
+
+def _wants_context(process: ProcessFn) -> bool:
+    """Whether to call `process(frame, ctx)` or just `process(frame)`.
+
+    Decided once from the signature, not per frame; anything uninspectable is
+    given both arguments.
+    """
+    try:
+        parameters = inspect.signature(process).parameters.values()
+    except (TypeError, ValueError):
+        return True
+    positional = [
+        p
+        for p in parameters
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    return len(positional) >= 2 or any(p.kind == p.VAR_POSITIONAL for p in parameters)
+
+
+def run(
+    process: ProcessFn | None = None,
+    *,
+    daemon: str | None = None,
+    rust_sock: str | None = None,
+    python_sock: str | None = None,
+    name: str = "worker",
+) -> None:
+    """Runs the worker loop until the daemon hangs up or Ctrl-C.
+
+    Arguments not given fall back to the environment: `BRAIDPIPE_DAEMON`
+    selects the tcp-raw transport, otherwise `BRAIDPIPE_RUST_SOCK` and
+    `BRAIDPIPE_PYTHON_SOCK` name the local sockets. `name` is only the log
+    prefix. Returns normally on shutdown, so final reporting can follow it.
+    """
+    if process is None:
+        process = _registered
+    if process is None:
+        raise TypeError(
+            "no frame handler: pass one to run() or decorate it with @braidpipe.worker"
+        )
+    wants_ctx = _wants_context(process)
+
+    if daemon is None:
+        daemon = os.environ.get("BRAIDPIPE_DAEMON")
+    if daemon:
+        _run_remote(process, wants_ctx, daemon, name)
+    else:
+        _run_shm(
+            process,
+            wants_ctx,
+            rust_sock or os.environ.get("BRAIDPIPE_RUST_SOCK", DEFAULT_RUST_SOCK),
+            python_sock or os.environ.get("BRAIDPIPE_PYTHON_SOCK", DEFAULT_PYTHON_SOCK),
+            name,
+        )
+
+
+def _invoke(
+    process: ProcessFn,
+    wants_ctx: bool,
+    frame: np.ndarray,
+    ctx: FrameContext,
+    name: str,
+) -> bool:
+    """Calls the handler; an exception becomes a failed (passthrough) frame."""
+    try:
+        if wants_ctx:
+            process(frame, ctx)
+        else:
+            process(frame)
+        return True
+    except Exception as exc:
+        print(f"[{name}] frame {ctx.frame_id} failed: {exc}", flush=True)
+        return False
+
+
+def _run_shm(
+    process: ProcessFn,
+    wants_ctx: bool,
+    rust_sock_path: str,
+    python_sock_path: str,
+    name: str,
+) -> None:
+    if os.path.exists(python_sock_path):
+        os.remove(python_sock_path)
+
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+    sock.bind(python_sock_path)
+
+    # Handshake: the daemon answers our hello with the shared-memory fd.
+    shm = attach(sock, rust_sock_path)
+    print(
+        f"[{name}] attached to SHM ({shm.width}x{shm.height} @ {shm.channels}ch)",
+        flush=True,
+    )
+
+    try:
+        while True:
+            packet = json.loads(sock.recvfrom(512)[0])
+            if "frame_id" not in packet:
+                continue  # a control packet, e.g. a duplicate handshake reply
+            frame_id = packet["frame_id"]
+            slot_idx = packet["slot_index"]
+            started = time.perf_counter_ns()
+
+            # The daemon's write time must be read before the slot is freed,
+            # or the next frame may already have overwritten the header.
+            _, _, written_us = shm.read_slot_header(slot_idx)
+            ctx = FrameContext(
+                frame_id=frame_id,
+                slot=slot_idx,
+                timestamp_us=written_us,
+                width=shm.width,
+                height=shm.height,
+                channels=shm.channels,
+                transport="shm",
+            )
+
+            frame = shm.get_slot_numpy_array(slot_idx)
+            success = _invoke(process, wants_ctx, frame, ctx, name)
+
+            # The slot is recycled the moment it is freed: the handler must
+            # have copied any pixels it wants to keep.
+            shm.mark_slot_free(slot_idx)
+
+            ack = {
+                "frame_id": frame_id,
+                "slot_index": slot_idx,
+                "processing_time_us": (time.perf_counter_ns() - started) // 1000,
+                "success": success,
+            }
+            try:
+                sock.sendto(json.dumps(ack).encode("utf-8"), rust_sock_path)
+            except OSError as exc:
+                # A full datagram buffer is backpressure, not a fatal error.
+                print(f"[{name}] dropped ack for frame {frame_id}: {exc}", flush=True)
+
+    except KeyboardInterrupt:
+        print(f"[{name}] shutting down cleanly...", flush=True)
+    finally:
+        sock.close()
+        shm.close()
+        if os.path.exists(python_sock_path):
+            os.remove(python_sock_path)
+
+
+def _run_remote(process: ProcessFn, wants_ctx: bool, daemon: str, name: str) -> None:
+    link = connect(daemon)
+    print(
+        f"[{name}] connected to daemon at {daemon} "
+        f"({link.width}x{link.height} @ {link.channels}ch)",
+        flush=True,
+    )
+    try:
+        for frame_id, slot_idx, timestamp_us, frame in link.frames():
+            started = time.perf_counter_ns()
+            ctx = FrameContext(
+                frame_id=frame_id,
+                slot=slot_idx,
+                timestamp_us=timestamp_us,
+                width=link.width,
+                height=link.height,
+                channels=link.channels,
+                transport="tcp-raw",
+            )
+            success = _invoke(process, wants_ctx, frame, ctx, name)
+            link.send_processed(
+                frame_id,
+                slot_idx,
+                frame,
+                (time.perf_counter_ns() - started) // 1000,
+                success,
+            )
+        print(f"[{name}] daemon hung up", flush=True)
+    except KeyboardInterrupt:
+        print(f"[{name}] shutting down cleanly...", flush=True)
+    finally:
+        link.close()

braidpipe-0.3.0/braidpipe/shm.py

@@ -0,0 +1,126 @@
+import json
+import mmap
+import os
+import socket as socket_module
+import struct
+import time
+import numpy as np
+
+from .contract import check_contract
+
+# Slot State Constants matching Rust shm.rs
+SLOT_FREE = 0
+SLOT_READY_FOR_AI = 1
+SLOT_PROCESSING = 2
+
+# Struct layouts matching the explicit #[repr(C)] layouts in Rust shm.rs:
+# ShmHeader: width u32, height u32, channels u8, slot_count u8, 2 pad bytes,
+#            slot_size u32, 16 reserved bytes -> 32 bytes total
+HEADER_FMT = "<IIBB2xI16s"
+HEADER_SIZE = struct.calcsize(HEADER_FMT)
+assert HEADER_SIZE == 32
+
+# SlotHeader: state u8, 7 pad bytes, frame_id u64, timestamp_us u64 -> 24 bytes
+SLOT_HEADER_FMT = "<B7xQQ"
+SLOT_HEADER_SIZE = struct.calcsize(SLOT_HEADER_FMT)
+assert SLOT_HEADER_SIZE == 24
+
+# The handshake: a worker announces itself with HELLO on the daemon's socket
+# and receives a datagram carrying the shared segment's fd as SCM_RIGHTS
+# ancillary data. The segment is anonymous -- the fd is the only way in.
+HELLO = b'{"type":"hello"}'
+
+
+def attach(sock: socket_module.socket, rust_sock_path: str, retry_interval: float = 1.0):
+    """Says hello to the daemon until it answers with the shared-memory fd.
+
+    `sock` must already be bound to this worker's own socket path, because the
+    daemon addresses its reply there. Retries forever, so a worker may start
+    before the daemon and simply wait for it.
+    """
+    previous_timeout = sock.gettimeout()
+    sock.settimeout(retry_interval)
+    try:
+        while True:
+            try:
+                sock.sendto(HELLO, rust_sock_path)
+            except OSError:
+                # The daemon is not up (no socket file yet); try again.
+                time.sleep(retry_interval)
+                continue
+            try:
+                msg, fds, _flags, _addr = socket_module.recv_fds(sock, 512, 1)
+            except TimeoutError:
+                continue
+            except OSError:
+                time.sleep(retry_interval)
+                continue
+            if fds:
+                # The config body riding beside the fd names the daemon's
+                # contract version; refuse the fd rather than misread it.
+                try:
+                    config = json.loads(msg)
+                except ValueError:
+                    config = {}
+                try:
+                    check_contract(config, "shm")
+                except Exception:
+                    os.close(fds[0])
+                    raise
+                return SharedMemoryManager(fds[0])
+            # A frame notification that raced the handshake; ignore it. The
+            # daemon passes those frames through unchanged.
+    finally:
+        sock.settimeout(previous_timeout)
+
+
+class SharedMemoryManager:
+    def __init__(self, fd: int):
+        # The fd received from the daemon describes the whole segment; its
+        # size comes from the fd itself, and everything else from the header.
+        size = os.fstat(fd).st_size
+        self.shm = mmap.mmap(fd, size)
+        os.close(fd)  # the mapping keeps the segment alive on its own
+
+        # Unpack header metadata
+        header_bytes = bytes(self.shm[:HEADER_SIZE])
+        (
+            self.width,
+            self.height,
+            self.channels,
+            self.slot_count,
+            self.slot_size,
+            _,
+        ) = struct.unpack(HEADER_FMT, header_bytes)
+
+    def get_slot_numpy_array(self, slot_idx: int) -> np.ndarray:
+        """Returns a zero-copy NumPy view over a specific SHM slot's pixel buffer."""
+        slot_offset = HEADER_SIZE + (slot_idx * self.slot_size)
+        payload_offset = slot_offset + SLOT_HEADER_SIZE
+        payload_bytes = self.width * self.height * self.channels
+
+        # Point NumPy directly to the shared memory buffer slice
+        return np.ndarray(
+            shape=(self.height, self.width, self.channels),
+            dtype=np.uint8,
+            buffer=self.shm,
+            offset=payload_offset,
+        )
+
+    def read_slot_header(self, slot_idx: int) -> tuple[int, int, int]:
+        """Returns (state, frame_id, timestamp_us) for a slot.
+
+        `timestamp_us` is the wall clock the daemon recorded as it wrote the
+        frame, so subtracting `time.time()` here gives the one-way IPC delay.
+        """
+        slot_offset = HEADER_SIZE + (slot_idx * self.slot_size)
+        raw = bytes(self.shm[slot_offset : slot_offset + SLOT_HEADER_SIZE])
+        return struct.unpack(SLOT_HEADER_FMT, raw)
+
+    def mark_slot_free(self, slot_idx: int):
+        """Resets the slot state back to FREE so Rust can write the next frame."""
+        slot_offset = HEADER_SIZE + (slot_idx * self.slot_size)
+        self.shm[slot_offset] = SLOT_FREE
+
+    def close(self):
+        self.shm.close()

braidpipe-0.3.0/braidpipe/worker.py

@@ -0,0 +1,47 @@
+"""The raw worker template: your code in `process()`, the SDK does the rest.
+
+This is the file to copy when writing your own worker. The braidpipe package
+owns the whole IPC contract — attach, one datagram per frame, a zero-copy NumPy
+view of the slot, slot release, the ack — and an exception in `process()` costs
+one passthrough frame, never the stream. The one thing this template does not
+do is touch the pixels.
+
+Demonstration workers live in examples/ — an edge transform, threaded YOLO
+detection, and latency stamping.
+
+Usage:
+    cargo run -p braidpipe --release -- --python-script python/braidpipe/worker.py
+
+Environment:
+    BRAIDPIPE_DAEMON        a daemon's --worker-listen address; switches the
+                            worker to the tcp-raw transport   (default: unset)
+    BRAIDPIPE_RUST_SOCK     daemon's ack socket       (default: /tmp/braidpipe_rust.sock)
+    BRAIDPIPE_PYTHON_SOCK   this worker's socket      (default: /tmp/braidpipe_python.sock)
+"""
+
+import numpy as np
+
+try:
+    import braidpipe
+except ModuleNotFoundError:  # run from a source checkout, package not installed
+    import os
+    import sys
+
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    import braidpipe
+
+
+def process(frame: np.ndarray) -> None:
+    """Your code goes here. Modify `frame` in place; writing to the view *is*
+    writing the output.
+
+    Frames are RGB, not BGR. Finish inside 1.5 frame periods (50 ms at 30 fps)
+    or the daemon falls back to passthrough; anything slower than that belongs
+    on a thread with cached results — see braidpipe.BackgroundModel and
+    examples/worker_detect.py. Take a second `ctx` parameter if you need frame
+    ids or timestamps.
+    """
+
+
+if __name__ == "__main__":
+    braidpipe.run(process)

braidpipe-0.3.0/braidpipe.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: braidpipe
+Version: 0.3.0
+Summary: Worker SDK for braidpipe, the never-dark AI video middleware: write a function that mutates a frame, the SDK runs the IPC loop.
+Author: braidpipe contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/emdiple/braidpipe
+Keywords: video,streaming,gstreamer,computer-vision,shared-memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Provides-Extra: examples
+Requires-Dist: opencv-python; extra == "examples"
+
+# braidpipe (worker SDK)
+
+The Python worker SDK for [braidpipe](https://github.com/emdiple/braidpipe), the
+never-dark AI video middleware. The Rust daemon owns the media path; this
+package is how a Python process receives its frames — as zero-copy NumPy views
+over shared memory locally, or over the tcp-raw transport from another machine —
+and hands them back.
+
+A complete worker:
+
+```python
+import braidpipe
+
+def process(frame):          # (H, W, 3) uint8, RGB — mutate it in place
+    frame[:, :, 0] //= 2     # your inference here
+
+if __name__ == "__main__":
+    braidpipe.run(process)
+```
+
+`run()` owns everything else: the handshake, the per-frame notification loop,
+freeing the shared-memory slot, acking (including `"success": false` when your
+code raises, so the stream falls back to passthrough instead of going dark),
+and the transport switch — set `BRAIDPIPE_DAEMON=host:port` and the same worker
+attaches over the network instead.
+
+This package does not contain the daemon. Build it from the
+[repository](https://github.com/emdiple/braidpipe), which also has the full
+worker contract, examples, and deadline rules in `docs/workers.md`.

braidpipe-0.3.0/braidpipe.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+braidpipe/__init__.py
+braidpipe/__main__.py
+braidpipe/background.py
+braidpipe/contract.py
+braidpipe/py.typed
+braidpipe/remote.py
+braidpipe/runner.py
+braidpipe/shm.py
+braidpipe/worker.py
+braidpipe.egg-info/PKG-INFO
+braidpipe.egg-info/SOURCES.txt
+braidpipe.egg-info/dependency_links.txt
+braidpipe.egg-info/requires.txt
+braidpipe.egg-info/top_level.txt
+tests/test_runner.py

braidpipe-0.3.0/braidpipe.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

braidpipe-0.3.0/braidpipe.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=1.24
+
+[examples]
+opencv-python

braidpipe-0.3.0/braidpipe.egg-info/top_level.txt

@@ -0,0 +1 @@
+braidpipe

braidpipe-0.3.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "braidpipe"
+version = "0.3.0"
+description = "Worker SDK for braidpipe, the never-dark AI video middleware: write a function that mutates a frame, the SDK runs the IPC loop."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "braidpipe contributors" }]
+keywords = ["video", "streaming", "gstreamer", "computer-vision", "shared-memory"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+examples = ["opencv-python"]
+
+[project.urls]
+Homepage = "https://github.com/emdiple/braidpipe"
+
+[tool.setuptools.packages.find]
+include = ["braidpipe*"]
+
+[tool.setuptools.package-data]
+braidpipe = ["py.typed"]

braidpipe-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

braidpipe-0.3.0/tests/test_runner.py

@@ -0,0 +1,249 @@
+"""SDK tests against a fake daemon: pure Python, no Rust or GStreamer needed.
+
+Each test stands up the daemon side of one transport — the UDS handshake with a
+real fd for shared memory, a UDP-hello/TCP-data pair for tcp-raw — and runs
+`braidpipe.run()` against it, asserting the contract the Rust daemon relies on:
+pixels mutated in place, slots freed, every frame acked, and an exception in
+the handler reported as `"success": false` rather than a dead worker.
+
+Run with:  python3 -m unittest discover python/tests
+"""
+
+import array
+import json
+import os
+import socket
+import struct
+import sys
+import tempfile
+import threading
+import time
+import unittest
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import braidpipe
+from braidpipe.runner import _wants_context
+from braidpipe.shm import HEADER_FMT, HEADER_SIZE, SLOT_HEADER_FMT, SLOT_HEADER_SIZE
+
+WIDTH, HEIGHT, CHANNELS, SLOT_COUNT = 8, 4, 3, 2
+PAYLOAD = WIDTH * HEIGHT * CHANNELS
+SLOT_SIZE = SLOT_HEADER_SIZE + PAYLOAD
+
+TIMEOUT = 5.0
+
+
+def make_segment():
+    """A real mmap-able fd laid out exactly like the Rust daemon's segment."""
+    f = tempfile.TemporaryFile()
+    f.truncate(HEADER_SIZE + SLOT_COUNT * SLOT_SIZE)
+    f.seek(0)
+    f.write(struct.pack(HEADER_FMT, WIDTH, HEIGHT, CHANNELS, SLOT_COUNT, SLOT_SIZE, b""))
+    f.flush()
+    return f
+
+
+class ShmTransportTest(unittest.TestCase):
+    def test_frames_processed_freed_and_acked(self):
+        tmp = tempfile.mkdtemp()
+        rust_sock_path = os.path.join(tmp, "rust.sock")
+        python_sock_path = os.path.join(tmp, "python.sock")
+
+        daemon = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        daemon.bind(rust_sock_path)
+        daemon.settimeout(TIMEOUT)
+        self.addCleanup(daemon.close)
+
+        segment = make_segment()
+        self.addCleanup(segment.close)
+        view = np.memmap(segment, dtype=np.uint8, mode="r+")
+
+        seen = []
+
+        def process(frame, ctx):
+            seen.append((ctx.frame_id, ctx.timestamp_us, ctx.transport))
+            if ctx.frame_id == 2:
+                raise RuntimeError("deliberate failure")
+            frame += 1
+
+        worker = threading.Thread(
+            target=braidpipe.run,
+            kwargs=dict(
+                process=process,
+                rust_sock=rust_sock_path,
+                python_sock=python_sock_path,
+                name="test",
+            ),
+            daemon=True,  # left blocked in recvfrom once the test is over
+        )
+        worker.start()
+
+        # Handshake: the worker's hello is answered with the segment's fd.
+        # (sendmsg directly: socket.send_fds does not forward `address`.)
+        _, worker_addr = daemon.recvfrom(512)
+        daemon.sendmsg(
+            [b'{"type":"config","transport":"shm","contract":1}'],
+            [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", [segment.fileno()]))],
+            0,
+            worker_addr,
+        )
+
+        def send_frame(frame_id, slot, fill):
+            offset = HEADER_SIZE + slot * SLOT_SIZE
+            view[offset : offset + SLOT_HEADER_SIZE] = np.frombuffer(
+                struct.pack(SLOT_HEADER_FMT, 1, frame_id, 1_000_000 + frame_id),
+                dtype=np.uint8,
+            )
+            view[offset + SLOT_HEADER_SIZE : offset + SLOT_SIZE] = fill
+            daemon.sendto(
+                json.dumps({"frame_id": frame_id, "slot_index": slot}).encode(),
+                python_sock_path,
+            )
+            ack = json.loads(daemon.recvfrom(512)[0])
+            return offset, ack
+
+        # A control packet with no frame_id must be skipped, not crash the loop.
+        daemon.sendto(b'{"type":"noise"}', python_sock_path)
+
+        offset, ack = send_frame(1, 0, fill=10)
+        self.assertEqual(ack["frame_id"], 1)
+        self.assertTrue(ack["success"])
+        self.assertEqual(view[offset], 0)  # slot freed
+        self.assertTrue((view[offset + SLOT_HEADER_SIZE : offset + SLOT_SIZE] == 11).all())
+
+        # A raising handler acks success=false and leaves the loop alive.
+        offset, ack = send_frame(2, 1, fill=20)
+        self.assertFalse(ack["success"])
+        self.assertEqual(view[offset], 0)
+        self.assertTrue((view[offset + SLOT_HEADER_SIZE : offset + SLOT_SIZE] == 20).all())
+
+        _, ack = send_frame(3, 0, fill=30)
+        self.assertTrue(ack["success"])
+
+        self.assertEqual(
+            seen,
+            [(1, 1_000_001, "shm"), (2, 1_000_002, "shm"), (3, 1_000_003, "shm")],
+        )
+
+
+class TcpRawTransportTest(unittest.TestCase):
+    def test_frames_round_trip_and_clean_shutdown(self):
+        from braidpipe.remote import WIRE_HEADER_FMT, WIRE_HEADER_SIZE
+
+        udp = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        udp.bind(("127.0.0.1", 0))
+        udp.settimeout(TIMEOUT)
+        self.addCleanup(udp.close)
+
+        tcp = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        tcp.bind(("127.0.0.1", 0))
+        tcp.listen(1)
+        tcp.settimeout(TIMEOUT)
+        self.addCleanup(tcp.close)
+
+        def process(frame):
+            frame += 1
+
+        worker = threading.Thread(
+            target=braidpipe.run,
+            kwargs=dict(
+                process=process,
+                daemon=f"127.0.0.1:{udp.getsockname()[1]}",
+                name="test",
+            ),
+            daemon=True,  # a failed test must not hang the runner at exit
+        )
+        worker.start()
+
+        hello, worker_addr = udp.recvfrom(512)
+        self.assertIn("tcp-raw", json.loads(hello)["transports"])
+        udp.sendto(
+            json.dumps(
+                {
+                    "type": "config",
+                    "transport": "tcp-raw",
+                    "contract": 1,
+                    "data_port": tcp.getsockname()[1],
+                    "width": WIDTH,
+                    "height": HEIGHT,
+                    "channels": CHANNELS,
+                }
+            ).encode(),
+            worker_addr,
+        )
+
+        conn, _ = tcp.accept()
+        conn.settimeout(TIMEOUT)
+        for frame_id in (1, 2):
+            conn.sendall(
+                struct.pack(WIRE_HEADER_FMT, frame_id, 5_000, PAYLOAD, 0, 0)
+                + bytes([frame_id * 10]) * PAYLOAD
+            )
+            reply = b""
+            while len(reply) < WIRE_HEADER_SIZE + PAYLOAD:
+                reply += conn.recv(4096)
+            reply_id, _, _, _, flags = struct.unpack(
+                WIRE_HEADER_FMT, reply[:WIRE_HEADER_SIZE]
+            )
+            self.assertEqual(reply_id, frame_id)
+            self.assertEqual(flags & 1, 1)
+            self.assertEqual(set(reply[WIRE_HEADER_SIZE:]), {frame_id * 10 + 1})
+
+        # Hanging up must end run() rather than strand the worker.
+        conn.close()
+        worker.join(TIMEOUT)
+        self.assertFalse(worker.is_alive())
+
+
+class ContractTest(unittest.TestCase):
+    def test_matching_and_missing_versions_attach(self):
+        from braidpipe.contract import CONTRACT_VERSION, check_contract
+
+        check_contract({"contract": CONTRACT_VERSION}, "shm")  # must not raise
+        check_contract({}, "shm")  # pre-versioning daemon: warn, not refuse
+
+    def test_mismatch_refuses_loudly(self):
+        from braidpipe.contract import check_contract
+
+        with self.assertRaises(RuntimeError):
+            check_contract({"contract": 999}, "shm")
+
+    def test_remote_connect_refuses_mismatched_daemon(self):
+        udp = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        udp.bind(("127.0.0.1", 0))
+        udp.settimeout(TIMEOUT)
+        self.addCleanup(udp.close)
+
+        def answer_hello():
+            _, addr = udp.recvfrom(512)
+            udp.sendto(
+                b'{"type":"config","transport":"tcp-raw","data_port":1,'
+                b'"width":8,"height":4,"channels":3,"contract":999}',
+                addr,
+            )
+
+        threading.Thread(target=answer_hello, daemon=True).start()
+        with self.assertRaises(RuntimeError):
+            braidpipe.connect(f"127.0.0.1:{udp.getsockname()[1]}")
+
+
+class SignatureTest(unittest.TestCase):
+    def test_handler_arity_detection(self):
+        self.assertFalse(_wants_context(lambda frame: None))
+        self.assertTrue(_wants_context(lambda frame, ctx: None))
+        self.assertTrue(_wants_context(lambda *args: None))
+
+    def test_worker_decorator_registers_handler(self):
+        @braidpipe.worker
+        def handler(frame):
+            pass
+
+        from braidpipe import runner
+
+        self.assertIs(runner._registered, handler)
+
+
+if __name__ == "__main__":
+    unittest.main()