reactor-runtime 2.3.2__tar.gz → 2.5.0__tar.gz

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.3.2
+Version: 2.5.0
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Requires-Dist: numpy<2.0
+Requires-Dist: numpy>=1.24.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: omegaconf>=2.3.0
 Requires-Dist: av>=14.0.0
@@ -68,4 +68,23 @@ Implement `inference()` as a generator that yields frames. Clients can update `s
 - **Real-time streaming** — frames delivered over WebRTC as they're generated
 - **Live interaction** — clients change inputs mid-generation via typed, validated state
 - **No transport code** — no WebRTC, WebSocket, or video encoding to manage
-- **Scaffold & run** — `reactor init` creates a project; `reactor run` starts it locally
+- **Scaffold & run** — the Go `reactor` CLI gives you `reactor init` / `reactor run`; the
+  Python runtime ships its own `reactor-runtime` script for standalone use
+
+## Standalone usage (no Go CLI)
+
+The runtime CLI is installed as `reactor-runtime` so it never shadows the Go
+`reactor` binary. If you only use the Python runtime:
+
+```bash
+pip install reactor-runtime
+reactor-runtime init my-model
+cd my-model
+python -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+reactor-runtime run
+```
+
+The Go `reactor` CLI delegates to this same `reactor-runtime` script under the
+hood; both `reactor run` (Go) and `reactor-runtime run` (standalone) execute the
+same Python entry point.

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/README.md

@@ -41,4 +41,23 @@ Implement `inference()` as a generator that yields frames. Clients can update `s
 - **Real-time streaming** — frames delivered over WebRTC as they're generated
 - **Live interaction** — clients change inputs mid-generation via typed, validated state
 - **No transport code** — no WebRTC, WebSocket, or video encoding to manage
-- **Scaffold & run** — `reactor init` creates a project; `reactor run` starts it locally
+- **Scaffold & run** — the Go `reactor` CLI gives you `reactor init` / `reactor run`; the
+  Python runtime ships its own `reactor-runtime` script for standalone use
+
+## Standalone usage (no Go CLI)
+
+The runtime CLI is installed as `reactor-runtime` so it never shadows the Go
+`reactor` binary. If you only use the Python runtime:
+
+```bash
+pip install reactor-runtime
+reactor-runtime init my-model
+cd my-model
+python -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+reactor-runtime run
+```
+
+The Go `reactor` CLI delegates to this same `reactor-runtime` script under the
+hood; both `reactor run` (Go) and `reactor-runtime run` (standalone) execute the
+same Python entry point.

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.3.2"
+version = "2.5.0"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }
@@ -13,7 +13,7 @@ readme = "README.md"
 requires-python = ">=3.9"
 
 dependencies = [
-	"numpy<2.0",
+	"numpy>=1.24.0",
 	"pydantic>=2.0.0",
 	"omegaconf>=2.3.0",
     "av>=14.0.0",
@@ -38,10 +38,15 @@ gst = [
 ]
 
 [project.scripts]
-reactor = "reactor_cli.main:main"
+# The runtime ships a CLI for standalone use (no Go reactor-cli required).
+# Named `reactor-runtime` so it never collides with the Go `reactor` binary,
+# which delegates to this script when both are installed.
+reactor-runtime = "reactor_cli.main:main"
 
 [tool.setuptools.package-data]
-template = ["*.yaml", "*.yml", "*.txt", "*.md"]
+# Dockerfile is included so the scaffolded workspace ships a partner-ready
+# image baseline. The literal name (no extension) requires an explicit entry.
+template = ["*.yaml", "*.yml", "*.txt", "*.md", "Dockerfile"]
 
 [tool.reactor-proto]
 # Proto dependency from reactor-team/reactor-proto

reactor_runtime-2.5.0/src/reactor_cli/commands/init.py

@@ -0,0 +1,155 @@
+# Copyright (c) 2026 Reactor Technologies, Inc. All rights reserved.
+"""Init command — scaffolds a new Reactor model workspace."""
+
+import pathlib
+import importlib.resources
+
+
+_TEMPLATE_FILES = {
+    "pipeline.py": "pipeline.py",
+    "model.py": "model.py",
+    "reactor.yaml": "reactor.yaml",
+    "config.yaml": "config.yaml",
+    "requirements.txt": "requirements.txt",
+    "README.md": "README.md",
+    # Partner-facing Dockerfile baseline (python:3.12-slim + GStreamer apt
+    # deps + reactor-runtime run). Listed last so the printed file order
+    # mirrors the order partners typically read them in.
+    "Dockerfile": "Dockerfile",
+}
+
+
+class InitCommand:
+    @staticmethod
+    def register_subcommand(subparsers):
+        """Register init command"""
+        init_parser = subparsers.add_parser(
+            "init", help="Initialize a new reactor model workspace"
+        )
+        init_parser.add_argument(
+            "name",
+            nargs="?",
+            default=None,
+            help=(
+                "Name of the model. When provided, a new directory with "
+                "this name is created in the current folder. When omitted, "
+                "the current folder is used (must be empty)."
+            ),
+        )
+        # --cli is set by the Go `reactor` CLI when it forwards to this
+        # Python init via `runtime.PythonRun`. The Go side then prints its
+        # own next-steps message tailored to the CLI workflow (workspace
+        # .venv was created, `reactor run` picks it up, etc.), so when
+        # this flag is present we suppress the standalone post-init
+        # message here to avoid duplicate / contradictory guidance.
+        # Behavior is otherwise identical — only the trailing print block
+        # is gated on this flag.
+        init_parser.add_argument(
+            "--cli",
+            action="store_true",
+            default=False,
+            help="Reserved for use by the reactor CLI; suppresses the standalone post-init message.",
+        )
+        init_parser.set_defaults(func=InitCommand)
+
+    def __init__(self, args):
+        self.args = args
+
+    def run(self):
+        """Initialize a Reactor model workspace.
+
+        Two modes:
+        * ``reactor-runtime init <name>``: create a new ``<name>`` directory
+          under the current folder and scaffold into it.
+        * ``reactor-runtime init`` (no arg): scaffold into the current
+          folder. The folder must be empty (modulo dotfiles) so we never
+          clobber anything by accident.
+        """
+        if self.args.name:
+            model_name = self.args.name
+            target_dir = pathlib.Path.cwd() / model_name
+            if target_dir.exists():
+                print(f"Error: Directory '{model_name}' already exists")
+                print("Please choose a different name or remove the existing directory")
+                return
+            try:
+                target_dir.mkdir()
+            except Exception as e:
+                print(f"Error creating directory '{model_name}': {e}")
+                return
+        else:
+            target_dir = pathlib.Path.cwd()
+            model_name = target_dir.name
+            visible = [p for p in target_dir.iterdir() if not p.name.startswith(".")]
+            if visible:
+                # The Go `reactor` CLI streams our stdout verbatim when it
+                # forwards via PythonRun (--cli), so the retry hint needs
+                # to use whichever entrypoint the user is actually driving:
+                # `reactor` for the Go-CLI flow (standalone `reactor-runtime`
+                # may not even be on PATH), `reactor-runtime` otherwise.
+                cli_name = "reactor" if self.args.cli else "reactor-runtime"
+                print(
+                    f"Error: current folder ({target_dir}) is not empty. "
+                    f"Pass a name (e.g. `{cli_name} init my-model`) or "
+                    "run from an empty folder."
+                )
+                return
+
+        try:
+            import template as template_package
+        except ImportError:
+            print(
+                "Error: template package not found. "
+                "Make sure reactor_runtime is properly installed."
+            )
+            if self.args.name:
+                target_dir.rmdir()
+            return
+
+        created = []
+        for dest_name, src_name in _TEMPLATE_FILES.items():
+            dest_path = target_dir / dest_name
+            try:
+                content = (
+                    importlib.resources.files(template_package)
+                    .joinpath(src_name)
+                    .read_text(encoding="utf-8")
+                )
+                if dest_name == "reactor.yaml":
+                    content = content.replace("name: my-model", f"name: {model_name}")
+                dest_path.write_text(content)
+                created.append(dest_name)
+            except FileNotFoundError:
+                print(f"Warning: template file {src_name} not found, skipping")
+
+        if not created:
+            print("Error: no template files were created")
+            if self.args.name:
+                target_dir.rmdir()
+            return
+
+        for name in created:
+            print(f"  {name}")
+
+        print(f"\nReactor workspace '{model_name}' created.")
+
+        # When invoked from the Go reactor CLI (--cli), the caller emits
+        # its own next-steps message that knows about the workspace .venv
+        # it just created and the `reactor run` / `reactor model register`
+        # commands. We stay silent here so the user only sees one
+        # consistent block of guidance.
+        if self.args.cli:
+            return
+
+        # Standalone path: partners using `pip install reactor-runtime`
+        # directly. They don't have a Go CLI to lean on, so spell out the
+        # full workspace-venv provisioning recipe.
+        if self.args.name:
+            print(f"\n  cd {model_name}")
+        print("  # With uv (https://docs.astral.sh/uv/ — recommended):")
+        print("  uv venv .venv && . .venv/bin/activate")
+        print("  uv pip install -r requirements.txt")
+        print("  # Or with plain pip:")
+        print("  python -m venv .venv && . .venv/bin/activate")
+        print("  pip install -r requirements.txt")
+        print("  reactor-runtime run\n")

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_cli/commands/run.py

@@ -20,6 +20,7 @@ from reactor_runtime.transports.config import (
 )
 from reactor_runtime.utils.launch import run_reactor_runtime
 from reactor_runtime.utils.log import get_logger
+from reactor_runtime.utils.paths import _set_configured_weights_path
 
 logger = get_logger(__name__)
 
@@ -102,22 +103,30 @@ class RunCommand:
         if not reactor_yaml_path.exists():
             print(
                 f"Error: {_REACTOR_YAML} not found in {model_path}.\n"
-                f"Create a {_REACTOR_YAML} with at least: model: module:ClassName"
+                f"Create a {_REACTOR_YAML} with at least:\n"
+                "  runtime:\n"
+                "    import: module:ClassName"
             )
             return
 
         raw_yaml = OmegaConf.to_container(
             OmegaConf.load(str(reactor_yaml_path)), resolve=True
         )
-        if not isinstance(raw_yaml, dict) or "model" not in raw_yaml:
+        if not isinstance(raw_yaml, dict):
+            print(f"Error: {_REACTOR_YAML} must be a YAML mapping")
+            return
+
+        try:
+            reactor_config = ReactorConfig.from_dict(raw_yaml)
+        except KeyError:
             print(
-                f"Error: {_REACTOR_YAML} must contain a 'model' field "
-                "(e.g. model: my_module:MyModel)"
+                f"Error: {_REACTOR_YAML} must declare a model entrypoint, "
+                "either as 'runtime.import' (e.g. 'runtime:\\n  import: "
+                "my_module:MyModel') or, for legacy configs, as a top-level "
+                "'model: my_module:MyModel' field."
             )
             return
 
-        reactor_config = ReactorConfig.from_dict(raw_yaml)
-
         # ---------------------------------------------------------
         # Model name (from YAML or env override)
         # ---------------------------------------------------------
@@ -148,7 +157,7 @@ class RunCommand:
         if model_overrides and not reactor_config.config:
             print(
                 "Error: --model.* overrides require a 'config' field in "
-                f"{_REACTOR_YAML} (e.g. config: config.yml)"
+                f"{_REACTOR_YAML} (e.g. config: config.yaml)"
             )
             return
 
@@ -157,6 +166,21 @@ class RunCommand:
                 reactor_config.config = str(model_path / reactor_config.config)
             reactor_config.config_overrides = model_overrides
 
+        # ---------------------------------------------------------
+        # Wire reactor.yaml's weights_path into the get_weights_path()
+        # helper so model code can call it with no arguments and still
+        # see the YAML override. Relative values are resolved against the
+        # model root, mirroring how `runtime.config` is resolved above —
+        # partners write `runtime.weights_path: ./weights` and have it
+        # work no matter which cwd `reactor-runtime run` is invoked from.
+        # ~ expansion happens lazily inside get_weights_path().
+        # ---------------------------------------------------------
+        if reactor_config.weights_path:
+            resolved = reactor_config.weights_path
+            if not resolved.startswith("~") and not Path(resolved).is_absolute():
+                resolved = str(model_path / resolved)
+            _set_configured_weights_path(resolved)
+
         # Handle --config-help
         if self.args.config_help:
             if reactor_config.config:
@@ -179,8 +203,11 @@ class RunCommand:
         runtime_parser = config_class.parser()
 
         if self.args.help:
+            # Show the standalone command name (`reactor-runtime run`) since
+            # `--help` is what partners not using the Go CLI most often hit;
+            # the Go `reactor run` passthrough delegates here transparently.
             print(
-                "Usage: reactor run [--path DIR] [--runtime NAME] [-v/--verbose] [--debug] [runtime options]"
+                "Usage: reactor-runtime run [--path DIR] [--runtime NAME] [-v/--verbose] [--debug] [runtime options]"
             )
             print("\nBase options:")
             print("  --path, -p DIR       Path to model directory (default: cwd)")

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_cli/commands/schema.py

@@ -96,14 +96,22 @@ class SchemaCommand:
         raw_yaml = OmegaConf.to_container(
             OmegaConf.load(str(reactor_yaml_path)), resolve=True
         )
-        if not isinstance(raw_yaml, dict) or "model" not in raw_yaml:
+        if not isinstance(raw_yaml, dict):
             print(
-                f"Error: {_REACTOR_YAML} must contain a 'model' field",
+                f"Error: {_REACTOR_YAML} must be a YAML mapping",
                 file=sys.stderr,
             )
             sys.exit(1)
 
-        reactor_config = ReactorConfig.from_dict(raw_yaml)
+        try:
+            reactor_config = ReactorConfig.from_dict(raw_yaml)
+        except KeyError:
+            print(
+                f"Error: {_REACTOR_YAML} must declare a model entrypoint via "
+                "'runtime.import' (or, for legacy configs, top-level 'model').",
+                file=sys.stderr,
+            )
+            sys.exit(1)
 
         add_import_paths([str(model_path)])
 

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_cli/main.py

@@ -4,7 +4,7 @@ import sys
 
 
 def main():
-    parser = argparse.ArgumentParser(prog="reactor")
+    parser = argparse.ArgumentParser(prog="reactor-runtime")
     subparsers = parser.add_subparsers(dest="command")
 
     from .commands import (

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_runtime/__init__.py

@@ -14,6 +14,7 @@ from reactor_runtime.interface import (
     MESSAGE_REGISTRY,
     FieldInfo,
     InputField,
+    InputFrame,
     Output,
     Input,
     Video,
@@ -27,6 +28,7 @@ from reactor_runtime.interface import (
     disconnected,
 )
 from reactor_runtime.profiling.singleton import get_profiler
+from reactor_runtime.utils.paths import get_weights_path
 
 try:
     __version__ = version("reactor_runtime")
@@ -45,6 +47,7 @@ __all__ = [
     "MESSAGE_REGISTRY",
     "FieldInfo",
     "InputField",
+    "InputFrame",
     "Output",
     "Input",
     "Video",
@@ -57,5 +60,6 @@ __all__ = [
     "connected",
     "disconnected",
     "get_profiler",
+    "get_weights_path",
     "__version__",
 ]

reactor_runtime-2.5.0/src/reactor_runtime/config.py

@@ -0,0 +1,170 @@
+# Copyright (c) 2026 Reactor Technologies, Inc. All rights reserved.
+"""
+Typed configuration parsed from ``reactor.yaml``.
+
+:class:`ReactorConfig` is the runtime-level configuration that identifies
+the model entry point and slug.  Track topology is inferred from the
+model class via the ``OUTPUT_REGISTRY`` / ``INPUT_REGISTRY``.
+
+Emission settings (``fps``, ``buffer_size``) are declared as class
+attributes on the model class, not in YAML.  Model-specific parameters
+(latent dims, learning rate, etc.) live in a separate config file
+pointed to by ``ReactorConfig.config``.
+
+Two YAML shapes are supported:
+
+* Modern (richer ``reactor.yaml`` shared with the ``reactor`` CLI)::
+
+      model:
+          name: my-model              # slug, optional
+          # ...other CLI-only fields are ignored here
+      runtime:
+          import: my_module:MyModel   # entrypoint, required
+          config: config.yaml         # optional model config
+          weights_path: ./weights     # optional weights root override
+
+* Legacy (top-level keys, kept for backwards compatibility)::
+
+      model: my_module:MyModel        # entrypoint
+      name: my-model                  # optional slug
+      config: config.yaml             # optional model config
+      weights_path: ./weights         # optional weights root override
+
+  Loading a legacy file emits a one-shot deprecation warning pointing
+  partners at the modern shape and the ``reactor`` Go CLI.
+
+The runtime only reads the few fields it needs; any additional keys —
+in particular the rich ``model.*`` metadata used by the ``reactor`` CLI
+(``display-name``, ``description``, ``gpu``, ``extra-args``, ...) —
+are deliberately ignored.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from reactor_runtime.utils.log import get_logger
+
+_logger = get_logger(__name__)
+
+# Multi-line WARNING surfaced once per process when ``from_dict`` is
+# invoked on a legacy (top-level ``model``/``name``/``config``) reactor.yaml.
+# The runtime keeps reading the legacy shape so partners aren't broken,
+# but we want them to migrate to the richer shape — either by hand or by
+# regenerating the file with the ``reactor`` Go CLI.
+_LEGACY_DEPRECATION_MSG = (
+    "reactor.yaml is using the legacy top-level shape "
+    "(model: / name: / config:); this is DEPRECATED and will be removed "
+    "in a future release. Please migrate to the modern shape:\n"
+    "  model:\n"
+    "    name: my-model\n"
+    "  runtime:\n"
+    "    import: my_module:MyModel\n"
+    "    config: config.yaml\n"
+    "The 'reactor' Go CLI generates this format automatically; install "
+    "with `brew install reactor-team/tools/reactor-cli` and run "
+    "`reactor init <name>` in a fresh workspace, or copy the new shape "
+    "by hand."
+)
+
+# Module-level guard so the warning fires once per process even if multiple
+# reactor.yaml files are loaded (e.g. from tests).  Reset by tests via
+# ``_reset_legacy_warning_for_tests``.
+_legacy_warned = False
+
+
+def _reset_legacy_warning_for_tests() -> None:
+    """Test helper: clear the once-per-process warning latch."""
+    global _legacy_warned
+    _legacy_warned = False
+
+
+@dataclass
+class ReactorConfig:
+    """Parsed ``reactor.yaml``.
+
+    Attributes:
+        model: The model entrypoint spec, ``module:ClassName``.  Sourced
+            from ``runtime.import`` (modern) or top-level ``model``
+            (legacy).
+        name: Model slug used on the wire (Redis streams, logs).
+            Sourced from ``model.name`` (modern) or top-level ``name``
+            (legacy).  Empty string when not set.
+        config: Optional path to a model-specific YAML config.  Sourced
+            from ``runtime.config`` (modern) or top-level ``config``
+            (legacy).  The caller is responsible for resolving relative
+            paths to absolute before passing to :func:`build_model`.
+        config_overrides: CLI dotlist overrides
+            (e.g. ``["lr=0.001", "batch=4"]``) merged on top of the
+            loaded config file.
+        weights_path: Optional override for the weights root consumed by
+            :func:`reactor_runtime.get_weights_path`.  Sourced from
+            ``runtime.weights_path`` (modern) or top-level ``weights_path``
+            (legacy). When set, takes precedence over the built-in default
+            but is itself overridden by ``$REACTOR_WEIGHTS_PATH``.  The
+            runtime CLI resolves relative paths against the model root
+            before registering this with the helper, so partners can
+            commit ``runtime.weights_path: ./weights`` and have it work
+            from any cwd.
+    """
+
+    model: str
+    name: str = ""
+    config: Optional[str] = None
+    config_overrides: List[str] = field(default_factory=list)
+    weights_path: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "ReactorConfig":
+        """Parse a raw YAML dict into a :class:`ReactorConfig`.
+
+        Accepts both the modern (``model:`` / ``runtime:`` sections) and
+        legacy (top-level ``model`` / ``name`` / ``config``) shapes.
+        Detection is based on whether ``runtime`` is a mapping or
+        ``model`` is a mapping (legacy ``model`` is always a string).
+
+        Raises:
+            KeyError: when neither schema provides a model entrypoint.
+        """
+        runtime_section = raw.get("runtime")
+        model_section = raw.get("model")
+
+        modern = isinstance(runtime_section, dict) or isinstance(model_section, dict)
+
+        if modern:
+            runtime_section = (
+                runtime_section if isinstance(runtime_section, dict) else {}
+            )
+            model_section = model_section if isinstance(model_section, dict) else {}
+
+            entrypoint = runtime_section.get("import")
+            if not entrypoint:
+                raise KeyError(
+                    "runtime.import is required in reactor.yaml "
+                    "(e.g. 'runtime:\\n  import: my_module:MyModel')"
+                )
+
+            slug = model_section.get("name") or ""
+
+            return cls(
+                model=str(entrypoint),
+                name=str(slug),
+                config=runtime_section.get("config"),
+                weights_path=runtime_section.get("weights_path") or None,
+            )
+
+        if "model" not in raw:
+            raise KeyError("model")
+
+        global _legacy_warned
+        if not _legacy_warned:
+            _legacy_warned = True
+            _logger.warning(_LEGACY_DEPRECATION_MSG)
+
+        return cls(
+            model=raw["model"],
+            name=raw.get("name", "") or "",
+            config=raw.get("config"),
+            weights_path=raw.get("weights_path") or None,
+        )

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_runtime/interface/__init__.py

@@ -54,6 +54,10 @@ from reactor_runtime.interface.internal.input_buffer import (
     ReadMode,
 )
 
+# Inbound frame with timing metadata (re-exported from transports so model
+# authors can ``from reactor_runtime.interface import InputFrame``).
+from reactor_runtime.transports.media import InputFrame
+
 __all__ = [
     # Tracks
     "Output",
@@ -95,4 +99,6 @@ __all__ = [
     "InputBuffer",
     "BufferClosed",
     "ReadMode",
+    # Inbound frame
+    "InputFrame",
 ]

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_runtime/interface/driver/pipeline_executor.py

@@ -6,7 +6,9 @@ from __future__ import annotations
 import asyncio
 import dataclasses
 import inspect
-from typing import Any, Dict, Iterator, List, Optional, Type
+from typing import Any, Dict, Iterator, List, Optional, Type, Union
+
+import numpy as np
 
 from reactor_runtime.interface.driver.step_result import StepResult
 from reactor_runtime.interface.events.messages import ModelMessage
@@ -17,6 +19,7 @@ from reactor_runtime.interface.pipeline.reactor_pipeline import (
     GeneratorEnded,
     ReactorPipeline,
 )
+from reactor_runtime.transports.media import InputFrame
 
 
 class PipelineExecutor(Iterator[StepResult]):
@@ -166,14 +169,29 @@ class PipelineExecutor(Iterator[StepResult]):
         }
         return self._run(self._send_event(entry, **handler_kwargs))
 
-    def push_media(self, track_name: str, data: Any) -> None:
+    def push_media(self, track_name: str, data: Union[np.ndarray, InputFrame]) -> None:
         """Push a media frame into an input buffer.
 
-        The frame becomes available to the model on the next
-        iteration when ``inference()`` calls ``try_read()`` or
-        ``read()``.
+        Accepts either a raw ``np.ndarray`` (auto-wrapped into an
+        :class:`~reactor_runtime.transports.media.InputFrame` with
+        ``pts=None``) or a prebuilt :class:`InputFrame` for callers
+        that want to stamp the frame with an explicit presentation
+        timestamp.
+
+        The frame becomes available to the model on the next iteration
+        when ``inference()`` calls ``try_read()`` / ``read()`` — both
+        of which now return ``List[InputFrame]``.
         """
-        self._model._push_media(track_name, data)
+        if isinstance(data, InputFrame):
+            frame = data
+        elif isinstance(data, np.ndarray):
+            frame = InputFrame(data=data)
+        else:
+            raise TypeError(
+                "push_media expects an np.ndarray or InputFrame, got "
+                f"{type(data).__name__}"
+            )
+        self._model._push_media(track_name, frame)
 
     def disconnect(self) -> List[ModelMessage]:
         """End the current session.

{reactor_runtime-2.3.2 → reactor_runtime-2.5.0}/src/reactor_runtime/interface/events/messages.py

@@ -93,10 +93,20 @@ class ModelMessage:
 
     name: ClassVar[str]
     _field_descriptions: ClassVar[Dict[str, str]]
+    _user_doc: ClassVar[Optional[str]]
 
     def __init_subclass__(cls, **kwargs: object) -> None:
         super().__init_subclass__(**kwargs)
 
+        # Snapshot the user-supplied docstring before any `@dataclass`
+        # decoration runs. ``dataclasses.dataclass`` rewrites
+        # ``__doc__`` to an auto-generated signature like
+        # ``"Foo(x: int)"`` whenever the class body has no explicit
+        # docstring, which would leak meaningless noise into the
+        # schema description. Reading ``cls.__dict__`` (not
+        # ``cls.__doc__``) avoids inheriting the parent's docstring.
+        cls._user_doc = cls.__dict__.get("__doc__", None)
+
         descriptions: Dict[str, str] = {}
         has_default: list[str] = []
         no_default: list[str] = []