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

reactor_runtime-3.6.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: reactor-runtime
+Version: 3.6.0
+Summary: A Python framework for building real-time, interactive video models
+Author: Reactor
+Author-email: Reactor <team@reactor.inc>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: av>=18.0.0
+Requires-Dist: fastapi>=0.139.0
+Requires-Dist: numpy>=2.1
+Requires-Dist: prometheus-client>=0.26.0
+Requires-Dist: protobuf>=7.35.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: reactor-webrtc==0.18.0
+Requires-Dist: uvicorn>=0.49.0
+Requires-Python: >=3.12
+Project-URL: Source, https://github.com/reactor-team/reactor-runtime
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/banner.png" alt="Reactor Runtime" width="100%" />
+
+**Build real-time AI models in Python.**
+
+[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/quickstart) · [🌐 Reactor](https://reactor.inc)
+
+</div>
+
+---
+
+Reactor Runtime turns an inference pipeline into a real-time, interactive media and data stream. You write `load()` and `generate()`; the runtime drives them one step at a time and handles the session lifecycle, the WebRTC media transport, and the wire protocol that connects clients to your model. Viewers watch frames as they are generated and change what the model is doing mid-stream, with no restart and no re-queue.
+
+## Highlights
+
+- 📡 **Real-time streaming.** Frames reach clients over WebRTC as your model produces them, not after a whole video is done. The runtime paces playout from the time each step took, so a model needs no rate limiter of its own.
+- 🎮 **Live interaction.** Clients send commands mid-generation: change a prompt, move a camera, adjust a parameter. The next frame reflects it.
+- 🔌 **No transport code.** You never import a WebRTC library, manage a WebSocket, or encode video. The runtime ships its own media engine as a wheel, so a plain Python container is all a model needs.
+- ✅ **Typed, validated commands.** Declare the commands your model accepts with standard Python types and constraints. The runtime validates every payload before your handler runs and compiles the surface into an OpenAPI schema that drives typed client SDKs.
+- 🔎 **Traceable logs.** `get_logger()` writes structured records — readable `key=value` in a terminal, JSON for a log pipeline. Every record a session writes carries that session's id automatically, so one filter recovers everything a single run logged.
+- 📦 **One container, anywhere.** The `reactor` CLI scaffolds a workspace, builds a small image, and runs it locally. The same image deploys to [Reactor](https://reactor.inc)'s GPU cloud unchanged.
+
+## How it works
+
+You ship one `ReactorApp` subclass: the application the runtime drives and the client talks to. Declare the media it sends and the state a client can set, load your weights once, and write what one step of generation does:
+
+```python
+from pathlib import Path
+
+from reactor_runtime import InputField, InputState, Output, ReactorApp, Video
+
+
+class MyState(InputState):
+    prompt: str = InputField(default="a sunny meadow", moderate=True, description="Scene to render.")
+    paused: bool = InputField(default=False, description="Hold generation on the last frame.")
+
+
+class MyOutput(Output):
+    main_video: Video
+
+
+class MyModel(ReactorApp):
+    state: MyState
+
+    def load(self, config_path: Path | None) -> None:
+        self.pipe = load_my_pipeline()
+
+    def generate(self, input: MyState) -> MyOutput:
+        return MyOutput(main_video=self.pipe.forward(prompt=input.prompt))
+```
+
+That is a complete application. The runtime calls `generate()` in a loop for as long as someone is watching and emits what it returns. Every public field on `MyState` is a command the client can send: here `set_prompt` and `set_paused`, validated from the fields, and the next step reads the new values.
+
+A step is three calls, and `generate()` is the one you must write. `process_input()` runs before it, reading `self.state` and the media tracks, and decides whether a step can happen: return the input `generate()` gets, or raise `ApplicationError("reason")` to skip the step without touching the model. `process_output(outcome)` runs after it, with the result or the error, and returns the media to emit; send a message from there with `await self.send()` and it reaches the client before the step's frames. Both have defaults, so the model above writes neither.
+
+```python
+from reactor_runtime import ApplicationError, MessageField, ModelMessage, StepOutcome
+
+
+class FrameReady(ModelMessage):
+    prompt: str = MessageField(description="The prompt this frame was rendered from.")
+
+
+class MyModel(ReactorApp):
+    state: MyState
+
+    async def process_input(self) -> MyState:
+        if self.state.paused:
+            raise ApplicationError("paused")
+        return self.state
+
+    def generate(self, input: MyState) -> MyOutput: ...
+
+    async def process_output(self, outcome: StepOutcome) -> Output | None:
+        if outcome.error is not None:
+            raise outcome.error
+        await self.send(FrameReady(prompt=self.state.prompt))
+        return outcome.to_output()
+```
+
+`generate()` fails by raising, and the runtime hands the exception to `process_output()` as `outcome.error` rather than letting it escape. That is where you decide. Recover an error you expect from your model: reset it, send a message, return `None`, and the loop goes on to the next step. Re-raise anything else, as the example does: a raise out of `process_output()` is a crash of the model, not of the step. The runtime logs the traceback, stops dispatching commands, ends the session with an error the client sees, and does not restart the loop, which is what an uncaught exception in a hand-written `run()` does too. The default `process_output()` re-raises, so a failing model ends loudly instead of serving nothing in silence. A refusal from `process_input()` is not a failure and never reaches `process_output()`.
+
+```python
+    async def process_output(self, outcome: StepOutcome) -> Output | None:
+        if isinstance(outcome.error, RolloutExhausted):   # an error the model is known to raise
+            self.engine.reset()
+            self.output.flush()
+            await self.send(WorldRestarted(reason="rollout window reached"))
+            return None                                   # nothing to show; the next step starts over
+        if outcome.error is not None:
+            raise outcome.error                           # anything else is a bug: end the loop
+        return outcome.to_output()
+```
+
+Command handlers and lifecycle hooks run between steps, never during one. The default `run()` is the loop that drives the three hooks. Override it to write your own loop against `emit()`, `send()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called. Do that for a loop that is not one step per emit, such as a renderer that emits several times per step or a model that must block on an input.
+
+Scaffold, build, and run it with the CLI:
+
+```sh
+reactor init my-model
+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/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:
+
+```python
+from reactor_runtime import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("scene changed", prompt=self.prompt)
+```
+
+Records render as `key=value` text by default, or as one JSON object per line under `REACTOR_LOG_FORMAT=json`. While a session is live, its id is stamped on every record, so tracing one run's logs never requires threading an id through your call sites. Every record also carries the lifecycle phase it was written in, at both granularities: `state`, the session state machine's word, and `runtime_state`, the coarse word the health endpoint serves — so the logs of one phase — loading weights, a live session, teardown — are filterable by whichever vocabulary you are reading off another surface. The stamp is applied where records are written rather than where they are made, so a plain `logging.getLogger(__name__)` and the libraries your model imports are covered too.
+
+## Install
+
+Everything runs through the [`reactor` CLI](https://docs.reactor.inc/deploy/platform/installation). There is nothing to install on your host but the CLI and Docker; the runtime ships inside the image the CLI builds for your workspace.
+
+```sh
+brew install reactor-team/tools/reactor-cli
+```
+
+Not on macOS, or pinning a release in CI? See [Install the CLI](https://docs.reactor.inc/deploy/platform/installation).
+
+## Learn more
+
+- [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`
+- [Echo example](./examples/echo/README.md): the client's webcam and microphone in, an effect applied, both sent back, in batches
+- [Waypoint example](./examples/waypoint/README.md): a world model on a GPU, seeded from an upload and steered live
+
+## Development
+
+This repository holds the runtime package itself: the authoring interface, the session runner, the media transport, and the wire protocol. To work on it, use [mise](https://mise.jdx.dev/), which pins the toolchain and forwards every task through a thin `make` shim:
+
+```sh
+mise run install      # install deps, generate wire bindings, and git hooks
+mise run lint         # ruff check, ruff format --check, and mise.lock drift
+mise run format       # apply ruff formatting
+mise run typecheck    # ty (strict)
+mise run test         # unit tests on the floor Python
+mise run test-matrix  # unit tests on every supported Python
+```
+
+## License
+
+Licensed under the [Apache License, Version 2.0](./LICENSE).

reactor_runtime-3.6.0/README.md

@@ -0,0 +1,155 @@
+<div align="center">
+
+<img src="assets/banner.png" alt="Reactor Runtime" width="100%" />
+
+**Build real-time AI models in Python.**
+
+[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/quickstart) · [🌐 Reactor](https://reactor.inc)
+
+</div>
+
+---
+
+Reactor Runtime turns an inference pipeline into a real-time, interactive media and data stream. You write `load()` and `generate()`; the runtime drives them one step at a time and handles the session lifecycle, the WebRTC media transport, and the wire protocol that connects clients to your model. Viewers watch frames as they are generated and change what the model is doing mid-stream, with no restart and no re-queue.
+
+## Highlights
+
+- 📡 **Real-time streaming.** Frames reach clients over WebRTC as your model produces them, not after a whole video is done. The runtime paces playout from the time each step took, so a model needs no rate limiter of its own.
+- 🎮 **Live interaction.** Clients send commands mid-generation: change a prompt, move a camera, adjust a parameter. The next frame reflects it.
+- 🔌 **No transport code.** You never import a WebRTC library, manage a WebSocket, or encode video. The runtime ships its own media engine as a wheel, so a plain Python container is all a model needs.
+- ✅ **Typed, validated commands.** Declare the commands your model accepts with standard Python types and constraints. The runtime validates every payload before your handler runs and compiles the surface into an OpenAPI schema that drives typed client SDKs.
+- 🔎 **Traceable logs.** `get_logger()` writes structured records — readable `key=value` in a terminal, JSON for a log pipeline. Every record a session writes carries that session's id automatically, so one filter recovers everything a single run logged.
+- 📦 **One container, anywhere.** The `reactor` CLI scaffolds a workspace, builds a small image, and runs it locally. The same image deploys to [Reactor](https://reactor.inc)'s GPU cloud unchanged.
+
+## How it works
+
+You ship one `ReactorApp` subclass: the application the runtime drives and the client talks to. Declare the media it sends and the state a client can set, load your weights once, and write what one step of generation does:
+
+```python
+from pathlib import Path
+
+from reactor_runtime import InputField, InputState, Output, ReactorApp, Video
+
+
+class MyState(InputState):
+    prompt: str = InputField(default="a sunny meadow", moderate=True, description="Scene to render.")
+    paused: bool = InputField(default=False, description="Hold generation on the last frame.")
+
+
+class MyOutput(Output):
+    main_video: Video
+
+
+class MyModel(ReactorApp):
+    state: MyState
+
+    def load(self, config_path: Path | None) -> None:
+        self.pipe = load_my_pipeline()
+
+    def generate(self, input: MyState) -> MyOutput:
+        return MyOutput(main_video=self.pipe.forward(prompt=input.prompt))
+```
+
+That is a complete application. The runtime calls `generate()` in a loop for as long as someone is watching and emits what it returns. Every public field on `MyState` is a command the client can send: here `set_prompt` and `set_paused`, validated from the fields, and the next step reads the new values.
+
+A step is three calls, and `generate()` is the one you must write. `process_input()` runs before it, reading `self.state` and the media tracks, and decides whether a step can happen: return the input `generate()` gets, or raise `ApplicationError("reason")` to skip the step without touching the model. `process_output(outcome)` runs after it, with the result or the error, and returns the media to emit; send a message from there with `await self.send()` and it reaches the client before the step's frames. Both have defaults, so the model above writes neither.
+
+```python
+from reactor_runtime import ApplicationError, MessageField, ModelMessage, StepOutcome
+
+
+class FrameReady(ModelMessage):
+    prompt: str = MessageField(description="The prompt this frame was rendered from.")
+
+
+class MyModel(ReactorApp):
+    state: MyState
+
+    async def process_input(self) -> MyState:
+        if self.state.paused:
+            raise ApplicationError("paused")
+        return self.state
+
+    def generate(self, input: MyState) -> MyOutput: ...
+
+    async def process_output(self, outcome: StepOutcome) -> Output | None:
+        if outcome.error is not None:
+            raise outcome.error
+        await self.send(FrameReady(prompt=self.state.prompt))
+        return outcome.to_output()
+```
+
+`generate()` fails by raising, and the runtime hands the exception to `process_output()` as `outcome.error` rather than letting it escape. That is where you decide. Recover an error you expect from your model: reset it, send a message, return `None`, and the loop goes on to the next step. Re-raise anything else, as the example does: a raise out of `process_output()` is a crash of the model, not of the step. The runtime logs the traceback, stops dispatching commands, ends the session with an error the client sees, and does not restart the loop, which is what an uncaught exception in a hand-written `run()` does too. The default `process_output()` re-raises, so a failing model ends loudly instead of serving nothing in silence. A refusal from `process_input()` is not a failure and never reaches `process_output()`.
+
+```python
+    async def process_output(self, outcome: StepOutcome) -> Output | None:
+        if isinstance(outcome.error, RolloutExhausted):   # an error the model is known to raise
+            self.engine.reset()
+            self.output.flush()
+            await self.send(WorldRestarted(reason="rollout window reached"))
+            return None                                   # nothing to show; the next step starts over
+        if outcome.error is not None:
+            raise outcome.error                           # anything else is a bug: end the loop
+        return outcome.to_output()
+```
+
+Command handlers and lifecycle hooks run between steps, never during one. The default `run()` is the loop that drives the three hooks. Override it to write your own loop against `emit()`, `send()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called. Do that for a loop that is not one step per emit, such as a renderer that emits several times per step or a model that must block on an input.
+
+Scaffold, build, and run it with the CLI:
+
+```sh
+reactor init my-model
+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/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:
+
+```python
+from reactor_runtime import get_logger
+
+logger = get_logger(__name__)
+
+logger.info("scene changed", prompt=self.prompt)
+```
+
+Records render as `key=value` text by default, or as one JSON object per line under `REACTOR_LOG_FORMAT=json`. While a session is live, its id is stamped on every record, so tracing one run's logs never requires threading an id through your call sites. Every record also carries the lifecycle phase it was written in, at both granularities: `state`, the session state machine's word, and `runtime_state`, the coarse word the health endpoint serves — so the logs of one phase — loading weights, a live session, teardown — are filterable by whichever vocabulary you are reading off another surface. The stamp is applied where records are written rather than where they are made, so a plain `logging.getLogger(__name__)` and the libraries your model imports are covered too.
+
+## Install
+
+Everything runs through the [`reactor` CLI](https://docs.reactor.inc/deploy/platform/installation). There is nothing to install on your host but the CLI and Docker; the runtime ships inside the image the CLI builds for your workspace.
+
+```sh
+brew install reactor-team/tools/reactor-cli
+```
+
+Not on macOS, or pinning a release in CI? See [Install the CLI](https://docs.reactor.inc/deploy/platform/installation).
+
+## Learn more
+
+- [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`
+- [Echo example](./examples/echo/README.md): the client's webcam and microphone in, an effect applied, both sent back, in batches
+- [Waypoint example](./examples/waypoint/README.md): a world model on a GPU, seeded from an upload and steered live
+
+## Development
+
+This repository holds the runtime package itself: the authoring interface, the session runner, the media transport, and the wire protocol. To work on it, use [mise](https://mise.jdx.dev/), which pins the toolchain and forwards every task through a thin `make` shim:
+
+```sh
+mise run install      # install deps, generate wire bindings, and git hooks
+mise run lint         # ruff check, ruff format --check, and mise.lock drift
+mise run format       # apply ruff formatting
+mise run typecheck    # ty (strict)
+mise run test         # unit tests on the floor Python
+mise run test-matrix  # unit tests on every supported Python
+```
+
+## License
+
+Licensed under the [Apache License, Version 2.0](./LICENSE).

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

@@ -70,6 +70,9 @@ python = ".venv"
 python-version = "3.12"
 extra-paths = [
     ".",
+    "examples/starter",
+    "examples/echo",
+    "examples/waypoint",
     "tests/unit/transport/webrtc",
     "tests/contract",
 ]
@@ -92,7 +95,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.4.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.4.0 → reactor_runtime-3.6.0}/pyproject.toml.orig

@@ -20,7 +20,7 @@ version = "1.20260814.7"
 
 [project]
 name = "reactor-runtime"
-version = "3.4.0"
+version = "3.6.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -128,8 +128,17 @@ python-version = "3.12"
 # models (`examples`, first-party but outside the package) resolve the way
 # pytest's pythonpath makes them importable; the WebRTC test directory, so
 # its tests can import their sibling `conftest` for the shared peer fakes; and
-# the contract suite, so its tests can import their sibling `contract_helpers`.
-extra-paths = [".", "tests/unit/transport/webrtc", "tests/contract"]
+# the contract suite, so its tests can import their sibling `contract_helpers`;
+# and each example workspace, whose two modules import each other as top-level
+# names, the way the runtime imports a workspace.
+extra-paths = [
+    ".",
+    "examples/starter",
+    "examples/echo",
+    "examples/waypoint",
+    "tests/unit/transport/webrtc",
+    "tests/contract",
+]
 
 [tool.ty.src]
 # Check the package, its tests, and the example models; scripts/ ships developer

{reactor_runtime-3.4.0 → reactor_runtime-3.6.0}/src/reactor_runtime/__init__.py

@@ -3,39 +3,47 @@
 The authoring surface is re-exported here so a model author imports from one
 obvious place::
 
-    from reactor_runtime import ReactorModel, Output, Video, event
+    from reactor_runtime import ReactorApp, Output, Video, event
 
 The same names are available under :mod:`reactor_runtime.interface`; importing
 from the top-level package is the preferred path.
+
+Four names are deprecated and import with a :class:`DeprecationWarning`.
+``ReactorModel`` is :class:`ReactorApp` and ``Input`` is :class:`MediaInput`,
+renames that resolve to the new class. ``ReactorPipeline`` and ``Idle`` still
+resolve to themselves, so a model on the generator pattern keeps working, but
+the pattern is retired in favour of :class:`ReactorApp` and ``generate()``.
+All four are removed in the next major.
 """
 
 from importlib.metadata import version
+from typing import Any
 
 from reactor_runtime.interface import (
     EVENT_REGISTRY,
     INPUT_REGISTRY,
     MESSAGE_REGISTRY,
     OUTPUT_REGISTRY,
+    ApplicationError,
     Audio,
     BufferClosed,
     ClientInfo,
     Command,
     CommandError,
     FieldInfo,
-    Idle,
-    Input,
     InputBuffer,
     InputField,
     InputFrame,
     InputState,
+    MediaInput,
     MessageField,
     Metadata,
     ModelMessage,
     Output,
     OutputStream,
-    ReactorModel,
-    ReactorPipeline,
+    ReactorApp,
     ReadMode,
+    StepOutcome,
     Track,
     TrackPayload,
     UploadedFile,
@@ -49,6 +57,16 @@ from reactor_runtime.interface import (
     session_ended,
     session_started,
 )
+from reactor_runtime.interface.internal.aliases import (
+    IDLE_DEPRECATION,
+    PIPELINE_DEPRECATION,
+    deprecated_alias,
+)
+
+# Bound under private names so the public ones stay out of the module's
+# namespace and resolve through __getattr__, which is where the warning lives.
+from reactor_runtime.interface.pipeline import Idle as _Idle
+from reactor_runtime.interface.pipeline import ReactorPipeline as _ReactorPipeline
 from reactor_runtime.log import get_logger
 from reactor_runtime.paths import get_weights_path
 
@@ -59,26 +77,26 @@ __all__ = [
     "INPUT_REGISTRY",
     "MESSAGE_REGISTRY",
     "OUTPUT_REGISTRY",
+    "ApplicationError",
     "Audio",
     "BufferClosed",
     "ClientInfo",
     "Command",
     "CommandError",
     "FieldInfo",
-    "Idle",
-    "Input",
     "InputBuffer",
     "InputField",
     "InputFrame",
     "InputState",
+    "MediaInput",
     "MessageField",
     "Metadata",
     "ModelMessage",
     "Output",
     "OutputStream",
-    "ReactorModel",
-    "ReactorPipeline",
+    "ReactorApp",
     "ReadMode",
+    "StepOutcome",
     "Track",
     "TrackPayload",
     "UploadedFile",
@@ -95,3 +113,17 @@ __all__ = [
     "session_ended",
     "session_started",
 ]
+
+_DEPRECATED: dict[str, tuple[str, object, str | None]] = {
+    "ReactorModel": ("ReactorApp", ReactorApp, None),
+    "Input": ("MediaInput", MediaInput, None),
+    "ReactorPipeline": ("ReactorApp", _ReactorPipeline, PIPELINE_DEPRECATION),
+    "Idle": ("ApplicationError", _Idle, IDLE_DEPRECATION),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _DEPRECATED:
+        new, target, message = _DEPRECATED[name]
+        return deprecated_alias(name, new, target, message)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{reactor_runtime-3.4.0 → reactor_runtime-3.6.0}/src/reactor_runtime/core/transport.py

@@ -105,13 +105,15 @@ class ConnectionSink(Protocol):
     """
 
     def connection_opened(self, conn: Connection) -> None:
-        """Register a connection whose wire has reached its connected state.
+        """Register a connection whose wire can carry frames to the client.
 
         Fired when the transport is actually connected — for WebRTC, when the
-        peer connection reaches its connected state — never at handshake or
-        offer time. A transport that builds a connection during signaling holds
-        it itself until then, so a client that offers but never connects never
-        advances the session.
+        peer connection is connected and both data channels are open — never at
+        handshake or offer time. A transport that builds a connection during
+        signaling holds it itself until then, so a client that offers but never
+        connects never advances the session. Because the wire is open by the
+        time this fires, a message the model sends from its ``@connected`` hook
+        reaches the joining client.
         """
 
     def connection_closed(self, conn_id: ConnId) -> None:

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.
+    """