reactor-runtime 3.5.0__tar.gz → 3.6.0__tar.gz

{reactor_runtime-3.5.0 → reactor_runtime-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.5.0
+Version: 3.6.0
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 **Build real-time AI models in Python.**
 
-[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/overview) · [🌐 Reactor](https://reactor.inc)
+[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/quickstart) · [🌐 Reactor](https://reactor.inc)
 
 </div>
 
@@ -129,7 +129,7 @@ cd my-model
 reactor run
 ```
 
-`reactor run` builds a container with the runtime inside and serves WebRTC signaling on port 8080. Point a browser at it with the [JS SDK](https://docs.reactor.inc), or connect from the [Reactor Sandbox](https://reactor-sandbox.vercel.app/) and watch frames stream immediately.
+`reactor run` builds a container with the runtime inside and serves WebRTC signaling on port 8080. Point a browser at it with the [JS SDK](https://docs.reactor.inc/sdk-reference/using-the-sdk), or connect from the [Reactor Sandbox](https://reactor-sandbox.vercel.app/) and watch frames stream immediately.
 
 Log from the same import, passing context as keyword arguments:
 
@@ -155,7 +155,8 @@ Not on macOS, or pinning a release in CI? See [Install the CLI](https://docs.rea
 
 ## Learn more
 
-- [Quickstart](https://docs.reactor.inc/deploy/development/overview): from zero to a streaming model in 2 minutes
+- [Quickstart](https://docs.reactor.inc/deploy/development/quickstart): from zero to a model deployed on Reactor's GPUs
+- [Runtime overview](https://docs.reactor.inc/deploy/development/overview): what the runtime handles, and the outline of a model
 - [Model anatomy](https://docs.reactor.inc/deploy/development/reactor-app/model-anatomy): every member of a `ReactorApp`, line by line
 - [The step loop](https://docs.reactor.inc/deploy/development/reactor-app/step-loop): `process_input()`, `generate()`, `process_output()`, and the frame rate
 - [Starter example](./examples/starter/README.md): the model `reactor init` scaffolds: one class, `generate()` alone, the smallest complete `ReactorApp`

{reactor_runtime-3.5.0 → reactor_runtime-3.6.0}/README.md

@@ -4,7 +4,7 @@
 
 **Build real-time AI models in Python.**
 
-[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/overview) · [🌐 Reactor](https://reactor.inc)
+[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/quickstart) · [🌐 Reactor](https://reactor.inc)
 
 </div>
 
@@ -103,7 +103,7 @@ cd my-model
 reactor run
 ```
 
-`reactor run` builds a container with the runtime inside and serves WebRTC signaling on port 8080. Point a browser at it with the [JS SDK](https://docs.reactor.inc), or connect from the [Reactor Sandbox](https://reactor-sandbox.vercel.app/) and watch frames stream immediately.
+`reactor run` builds a container with the runtime inside and serves WebRTC signaling on port 8080. Point a browser at it with the [JS SDK](https://docs.reactor.inc/sdk-reference/using-the-sdk), or connect from the [Reactor Sandbox](https://reactor-sandbox.vercel.app/) and watch frames stream immediately.
 
 Log from the same import, passing context as keyword arguments:
 
@@ -129,7 +129,8 @@ Not on macOS, or pinning a release in CI? See [Install the CLI](https://docs.rea
 
 ## Learn more
 
-- [Quickstart](https://docs.reactor.inc/deploy/development/overview): from zero to a streaming model in 2 minutes
+- [Quickstart](https://docs.reactor.inc/deploy/development/quickstart): from zero to a model deployed on Reactor's GPUs
+- [Runtime overview](https://docs.reactor.inc/deploy/development/overview): what the runtime handles, and the outline of a model
 - [Model anatomy](https://docs.reactor.inc/deploy/development/reactor-app/model-anatomy): every member of a `ReactorApp`, line by line
 - [The step loop](https://docs.reactor.inc/deploy/development/reactor-app/step-loop): `process_input()`, `generate()`, `process_output()`, and the frame rate
 - [Starter example](./examples/starter/README.md): the model `reactor init` scaffolds: one class, `generate()` alone, the smallest complete `ReactorApp`

{reactor_runtime-3.5.0 → reactor_runtime-3.6.0}/pyproject.toml

@@ -95,7 +95,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.5.0"
+version = "3.6.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"

{reactor_runtime-3.5.0 → reactor_runtime-3.6.0}/pyproject.toml.orig

@@ -20,7 +20,7 @@ version = "1.20260814.7"
 
 [project]
 name = "reactor-runtime"
-version = "3.5.0"
+version = "3.6.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"

reactor_runtime-3.6.0/src/reactor_runtime/distributed/__init__.py

@@ -0,0 +1,34 @@
+"""Run a model in its own process, or in one process per GPU, behind one object.
+
+A worker is a class with ``load()``, ``generate()``, and ``reset()``. A
+:class:`DistributedRunner` starts N of them, one per GPU, and lets the caller
+drive all of them with one call. The caller writes no process, queue,
+shared-memory, or NCCL code::
+
+    runner = DistributedRunner(MyModel, load_kwargs={"config_path": path})
+    runner.start()
+    result = runner.generate(MyInput(...))
+    runner.reset()
+    runner.shutdown()
+
+This package is standalone. Nothing else in the runtime depends on it, and it
+reads no manifest and no environment variable of its own.
+"""
+
+from reactor_runtime.distributed.errors import (
+    RankDesync,
+    SharedSlotAllocationFailed,
+    WorkerCrashed,
+    WorkerTimeout,
+)
+from reactor_runtime.distributed.runner import DistributedRunner
+from reactor_runtime.distributed.worker import DistributedWorker
+
+__all__ = [
+    "DistributedRunner",
+    "DistributedWorker",
+    "RankDesync",
+    "SharedSlotAllocationFailed",
+    "WorkerCrashed",
+    "WorkerTimeout",
+]

reactor_runtime-3.6.0/src/reactor_runtime/distributed/errors.py

@@ -0,0 +1,43 @@
+"""Failures a :class:`~reactor_runtime.distributed.DistributedRunner` raises to its caller.
+
+A worker's own exception is never wrapped: when every rank raises the same
+error, the caller receives rank 0's instance unchanged. The types here cover
+what the runner itself detects.
+"""
+
+from __future__ import annotations
+
+
+class WorkerCrashed(RuntimeError):  # noqa: N818 (named for the event a caller catches)
+    """A worker process died without answering.
+
+    The message names the rank and its exit code. The group is unusable after
+    this; ``shutdown()`` ends it.
+    """
+
+
+class WorkerTimeout(TimeoutError):  # noqa: N818 (named for the event a caller catches)
+    """A call did not get an answer from every rank within its timeout.
+
+    The processes are alive but one of them is stuck, usually inside a
+    collective a peer abandoned. The group is unusable after this.
+    """
+
+
+class RankDesync(RuntimeError):  # noqa: N818 (named for the state a caller catches)
+    """Some ranks raised and others did not, or ranks raised different types of error.
+
+    The message names the first failing rank and carries its exception as
+    ``__cause__``. Rank 0's result, if any, came out of a collective a failing
+    rank was meant to contribute to, so it is not returned. The group refuses
+    further calls.
+    """
+
+
+class SharedSlotAllocationFailed(MemoryError):  # noqa: N818 (named for the event a caller catches)
+    """A shared-memory block could not be created or grown.
+
+    The message states the size that was asked for and, where the host exposes
+    it, the size of ``/dev/shm``. Docker's default is 64 MB; ``--shm-size`` on
+    ``docker run`` and a ``medium: Memory`` ``emptyDir`` on a pod raise it.
+    """

reactor_runtime-3.6.0/src/reactor_runtime/distributed/ipc.py

@@ -0,0 +1,227 @@
+"""Carry an author's object across a process boundary without copying it twice.
+
+:func:`pack` pickles an object with protocol 5. Every flat buffer the object
+holds, a contiguous numpy array above all, is handed to the writer's
+:class:`SharedSlot` instead of being written into the pickle. The pickle
+stays small and travels on a queue; the bytes sit in shared memory. The
+header names the block, so the reader attaches to whatever it is told and
+the block can grow without a protocol of its own.
+
+Every block a slot creates is named from the slot's prefix and a generation
+number. A process that knows the prefix can unlink what a writer left behind
+when the writer was terminated before it could close its slot.
+
+A torch tensor and a non-contiguous array do not expose a flat buffer and
+pickle inline. That still works, only slower, and is reported once per
+process when the header passes about one megabyte.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import pickle
+import secrets
+import shutil
+from multiprocessing import shared_memory
+from pathlib import Path
+from typing import Any
+
+from reactor_runtime.distributed.errors import SharedSlotAllocationFailed
+from reactor_runtime.log import get_logger
+
+logger = get_logger(__name__)
+
+_INITIAL_BYTES = 1 << 20
+_INLINE_WARN_BYTES = 1 << 20
+_SHM_DIR = Path("/dev/shm")
+# Growth at least doubles a block, so no slot reaches this many generations.
+_MAX_GENERATIONS = 64
+
+_inline_reported = False
+
+
+def new_prefix() -> str:
+    """Return a block-name prefix for one slot. Short enough for macOS's 31-character limit."""
+    return f"rr{secrets.token_hex(4)}_"
+
+
+class SharedSlot:
+    """One shared-memory block a writer fills, one call at a time.
+
+    A call starts with :meth:`begin`, appends buffers with :meth:`write`, and
+    hands the returned spans to the reader inside the header. When a call's
+    buffers do not fit, the block is replaced by a larger one and the bytes
+    already written move with it. Steady state is one block at the writer's
+    high-water mark.
+
+    Args:
+        prefix: Names every block this slot creates, as ``<prefix><generation>``.
+            A process that holds the prefix can reclaim the blocks with
+            :func:`unlink_blocks` if the writer dies without :meth:`close`.
+            A fresh one from :func:`new_prefix` when omitted.
+        initial_bytes: The size of the first block.
+    """
+
+    def __init__(self, *, prefix: str | None = None, initial_bytes: int = _INITIAL_BYTES) -> None:
+        self._prefix = prefix or new_prefix()
+        self._generation = 0
+        self._shm = _allocate(f"{self._prefix}0", initial_bytes)
+        self._cursor = 0
+
+    @property
+    def name(self) -> str:
+        """The name a reader attaches to. Changes when the block grows."""
+        return self._shm.name
+
+    @property
+    def capacity(self) -> int:
+        """Bytes the current block holds."""
+        return self._shm.size
+
+    @property
+    def _buf(self) -> memoryview:
+        return _buffer_of(self._shm)
+
+    def begin(self) -> None:
+        """Start a new call; the next write lands at offset zero."""
+        self._cursor = 0
+
+    def write(self, buffer: Any) -> tuple[int, int]:
+        """Append one flat buffer and return its ``(offset, length)`` span."""
+        if isinstance(buffer, pickle.PickleBuffer):
+            raw = buffer.raw()
+        else:
+            raw = memoryview(buffer).cast("B")
+        length = raw.nbytes
+        end = self._cursor + length
+        if end > self.capacity:
+            self._grow(end)
+        self._buf[self._cursor : end] = raw
+        span = (self._cursor, length)
+        self._cursor = end
+        return span
+
+    def close(self) -> None:
+        """Detach and unlink the block."""
+        with contextlib.suppress(Exception):
+            self._shm.close()
+        with contextlib.suppress(Exception):
+            self._shm.unlink()
+
+    def _grow(self, needed: int) -> None:
+        self._generation += 1
+        replacement = _allocate(f"{self._prefix}{self._generation}", max(needed, 2 * self.capacity))
+        _buffer_of(replacement)[: self._cursor] = self._buf[: self._cursor]
+        logger.info("shared block grown", from_bytes=self.capacity, to_bytes=replacement.size)
+        self.close()
+        self._shm = replacement
+
+
+class SlotReader:
+    """The reading side: attaches to the block a header names and keeps the mapping."""
+
+    def __init__(self) -> None:
+        self._shm: shared_memory.SharedMemory | None = None
+
+    def attach(self, name: str) -> None:
+        """Map the block called *name*, replacing the previous mapping if it differs."""
+        if self._shm is not None and self._shm.name == name:
+            return
+        self.close()
+        self._shm = shared_memory.SharedMemory(name=name)
+
+    def copy(self, offset: int, length: int) -> bytearray:
+        """Copy one span out. A copy, so the writer may reuse the block at once."""
+        if self._shm is None:
+            raise RuntimeError("attach() has not run")
+        return bytearray(_buffer_of(self._shm)[offset : offset + length])
+
+    def close(self) -> None:
+        """Drop the mapping. The writer owns the block and unlinks it."""
+        if self._shm is not None:
+            with contextlib.suppress(Exception):
+                self._shm.close()
+            self._shm = None
+
+
+def pack(obj: Any, slot: SharedSlot) -> bytes:
+    """Pickle *obj* with its flat buffers written into *slot*.
+
+    Returns:
+        A header for the queue: the pickle bytes, the block's name, and the
+        span of each out-of-band buffer, pickled together.
+    """
+    slot.begin()
+    spans: list[tuple[int, int]] = []
+
+    def out_of_band(buffer: pickle.PickleBuffer) -> None:
+        spans.append(slot.write(buffer))
+
+    blob = pickle.dumps(obj, protocol=5, buffer_callback=out_of_band)
+    if len(blob) > _INLINE_WARN_BYTES:
+        _report_inline(len(blob))
+    return pickle.dumps((blob, slot.name, spans), protocol=5)
+
+
+def unpack(header: bytes, reader: SlotReader) -> Any:
+    """Rebuild the object a :func:`pack` header describes."""
+    blob, name, spans = pickle.loads(header)
+    reader.attach(name)
+    return pickle.loads(blob, buffers=[reader.copy(offset, length) for offset, length in spans])
+
+
+def unlink_blocks(prefix: str) -> None:
+    """Unlink every block a :class:`SharedSlot` with *prefix* left behind.
+
+    For a writer that ended without closing its slot, such as a terminated or
+    killed process. Every generation the slot could have reached is tried, so
+    a block that grew after its last header was read is reclaimed too. Call it
+    only once the writer is dead: a live writer's block would go with the rest.
+    """
+    for generation in range(_MAX_GENERATIONS):
+        try:
+            shm = shared_memory.SharedMemory(name=f"{prefix}{generation}")
+        except FileNotFoundError:
+            continue
+        with contextlib.suppress(Exception):
+            shm.close()
+        with contextlib.suppress(Exception):
+            shm.unlink()
+
+
+def _allocate(name: str, size: int) -> shared_memory.SharedMemory:
+    if _SHM_DIR.exists():
+        usage = shutil.disk_usage(_SHM_DIR)
+        if size > usage.free:
+            raise SharedSlotAllocationFailed(
+                f"could not grow the shared buffer to {size / 2**20:.1f} MB. /dev/shm has "
+                f"{usage.total / 2**20:.1f} MB total and {usage.free / 2**20:.1f} MB free. "
+                "Run with a larger --shm-size, or size /dev/shm in the deployment."
+            )
+    try:
+        return shared_memory.SharedMemory(name=name, create=True, size=size)
+    except OSError as exc:
+        raise SharedSlotAllocationFailed(
+            f"could not allocate a shared buffer of {size / 2**20:.1f} MB: {exc}. "
+            "Run with a larger --shm-size, or size /dev/shm in the deployment."
+        ) from exc
+
+
+def _buffer_of(shm: shared_memory.SharedMemory) -> memoryview:
+    buf = shm.buf
+    if buf is None:
+        raise RuntimeError(f"shared block {shm.name} is closed")
+    return buf
+
+
+def _report_inline(size: int) -> None:
+    global _inline_reported
+    if _inline_reported:
+        return
+    _inline_reported = True
+    logger.warning(
+        "a call's header is large; some payload pickled inline instead of through shared memory. "
+        "A torch tensor or a non-contiguous array does that: pass np.ascontiguousarray(x) or "
+        "np.asarray(tensor.cpu())",
+        header_bytes=size,
+    )

reactor_runtime-3.6.0/src/reactor_runtime/distributed/protocol.py

@@ -0,0 +1,66 @@
+"""The messages between a runner and its ranks.
+
+Requests go from the runner to every rank, in the same order on every rank's
+queue. Every rank answers every request. A large payload never rides on a
+queue: :class:`Generate` and :class:`Answer` carry a header from
+:func:`~reactor_runtime.distributed.ipc.pack`, and the bytes sit in a shared
+block the header names.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Generate:
+    """Run one ``generate()`` on every rank with the input the header describes."""
+
+    header: bytes
+
+
+@dataclass(frozen=True)
+class Reset:
+    """Call ``reset()`` on every rank."""
+
+
+@dataclass(frozen=True)
+class Shutdown:
+    """Leave the request loop, run the exit barrier, and end the process."""
+
+
+@dataclass(frozen=True)
+class Rendezvous:
+    """Rank 0 listens for the process group on this port, which it bound itself."""
+
+    port: int
+
+
+@dataclass(frozen=True)
+class Join:
+    """Join the process group on the port rank 0 reported. Sent to every other rank."""
+
+    port: int
+
+
+@dataclass(frozen=True)
+class Loaded:
+    """A rank finished ``load()`` and is ready for requests."""
+
+    rank: int
+
+
+@dataclass(frozen=True)
+class Answer:
+    """One rank's reply to a :class:`Generate` or :class:`Reset`.
+
+    Attributes:
+        rank: The answering rank.
+        header: Rank 0's packed result on a successful ``Generate``. Other
+            ranks and every ``Reset`` send ``None``.
+        error: What the worker raised, or ``None`` on success.
+    """
+
+    rank: int
+    header: bytes | None = None
+    error: Exception | None = None