reactor-runtime 2.9.0__tar.gz → 2.9.2__tar.gz

{reactor_runtime-2.9.0 → reactor_runtime-2.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.9.0
+Version: 2.9.2
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9

{reactor_runtime-2.9.0 → reactor_runtime-2.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reactor_runtime"
-version = "2.9.0"
+version = "2.9.2"
 description = "Reactor runtime with public model API"
 authors = [
 	{ name = "Reactor", email = "team@reactor.inc" }

reactor_runtime-2.9.2/src/reactor_runtime/realtime/__init__.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Reactor Technologies, Inc. All rights reserved.
+"""
+Runtime ↔ engine bridge.
+
+The realtime inference engine lives in its own standalone package
+(``realtime_engine``) with **zero** ``reactor_runtime`` dependency — it is
+driven entirely through inbox/outbox queues. This module is the runtime-side
+caller: :class:`RealtimePipeline` pumps the engine's queues from inside a
+``ReactorPipeline`` so a client connected over the real transport drives the
+engine and receives its chunks.
+
+Only the bridge lives here; the engine itself is never imported into the
+runtime tree beyond this thin seam.
+"""
+
+from __future__ import annotations
+
+from reactor_runtime.realtime.pipeline import RealtimePipeline
+
+__all__ = ["RealtimePipeline"]

reactor_runtime-2.9.2/src/reactor_runtime/realtime/pipeline.py

@@ -0,0 +1,304 @@
+# Copyright (c) 2026 Reactor Technologies, Inc. All rights reserved.
+"""
+:class:`RealtimePipeline` — the thin runtime bridge to a standalone engine.
+
+The engine (the ``realtime_engine`` package) owns the scheduling loop and all
+ML. It is driven only through inbox/outbox queues and has **zero**
+``reactor_runtime`` dependency. This bridge is the runtime-side caller: it
+inherits everything from :class:`ReactorPipeline` — typed :class:`InputState`,
+auto ``set_<field>`` events, :class:`Output` wrapping, ``emit`` / FPS pacing,
+and the connection lifecycle — and adds only the queue plumbing::
+
+    connect      ->  Attach(session_id, attach_context)
+    set_<field>  ->  Action(session_id, conditioning)     (on change)
+    Chunk        ->  _wrap_output  ->  emit
+
+The bridge owns **no** scheduling, **no** ML, and **no** state machine; if it
+grows logic, that logic belongs in the engine (its ``serve`` loop) or in a
+hook, not here.
+
+Subclasses declare a typed ``state: MyState`` and an :class:`Output` subclass,
+then override the four small hooks: :meth:`build_engine`,
+:meth:`_attach_context`, :meth:`state_to_conditioning`, :meth:`_wrap_output`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import itertools
+from collections.abc import Mapping
+from typing import Any, Callable, Optional
+
+import numpy as np
+
+from reactor_runtime.interface.pipeline.reactor_pipeline import ReactorPipeline
+from reactor_runtime.interface.tracks.output import Output
+from reactor_runtime.utils.log import get_logger
+
+# Optional dependency: the runtime does NOT depend on the engine/contract. This
+# guarded import lets a plain ``reactor_runtime`` install (and non-engine models)
+# work without it — importing this module never fails. Only engine-backed models
+# need the contract, and ``RealtimePipeline.__init__`` fails clearly (below) if
+# it's absent, instead of a bare ``ModuleNotFoundError``.
+try:
+    from realtime_engine import (
+        Action,
+        Attach,
+        Detach,
+        Inbox,
+        Outbox,
+        RealtimeInterface,
+        run_engine,
+    )
+
+    HAS_REALTIME_ENGINE = True
+except ImportError:
+    HAS_REALTIME_ENGINE = False
+
+logger = get_logger(__name__)
+
+
+class RealtimePipeline(ReactorPipeline):
+    """Drive a queue/``serve`` :class:`RealtimeInterface` engine from the runtime.
+
+    Override :meth:`run` is **not** needed — this class provides the queue
+    loop. Subclasses provide the model surface (state + output track) and the
+    four hooks. ``inference()`` is intentionally unused: the engine, not a
+    generator, produces frames.
+    """
+
+    # Session-liveness poll interval. This only governs how quickly the bridge
+    # notices connect/disconnect transitions to issue Attach/Detach — it is NOT
+    # on the frame path (chunks flow through an independent drain task + the
+    # engine's own loop), so a coarse interval is fine.
+    _lifecycle_poll_s: float = 0.02
+
+    def __init__(self) -> None:
+        if not HAS_REALTIME_ENGINE:
+            raise ImportError(
+                "RealtimePipeline (engine-backed models) requires the realtime "
+                "contract package. Install it with "
+                "`pip install reactor-realtime-engine`."
+            )
+        super().__init__()
+        self._engine: Optional[RealtimeInterface] = None
+        self._inbox: Optional[Inbox] = None
+        self._sid: Optional[str] = None
+        self._last_cond: Optional[dict] = None
+        self._sid_counter = itertools.count(1)
+
+    # ------------------------------------------------------------------
+    # load() — build the engine (no event-loop primitives here)
+    # ------------------------------------------------------------------
+
+    def load(self, config: dict[str, Any]) -> None:
+        """Build the engine once, before any client connects.
+
+        Queues / events are created in :meth:`run` instead — ``load()`` runs
+        before the event loop exists.
+        """
+        self._engine = self.build_engine(config)
+
+    # ------------------------------------------------------------------
+    # run() — the queue-plumbing loop (replaces the generator loop)
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        engine = self._engine
+        if engine is None:
+            raise RuntimeError(
+                f"{type(self).__name__}.load() must build an engine before run()"
+            )
+
+        inbox, outbox, stop = Inbox(), Outbox(), asyncio.Event()
+        self._inbox = inbox
+
+        # Pace emission to the engine's declared chunk cadence — NOT to its
+        # per-step compute time. The engine's serve loop already ticks at
+        # rate_hz; deriving fps from step_ms (tiny on a fast engine) would tell
+        # the output buffer to drain far faster than chunks actually arrive.
+        # frames_per_chunk is declared by the manifest (not inferred from
+        # chunk_shape, which is an opaque output shape).
+        manifest = engine.manifest()
+        self.output_buffer.set_fps(
+            max(1.0, manifest.rate_hz * manifest.frames_per_chunk)
+        )
+
+        lock = self._gen_lock
+        if lock is None:
+            raise RuntimeError(
+                f"{type(self).__name__}.run() called before _init_async()"
+            )
+
+        engine_task = asyncio.create_task(run_engine(engine, inbox, outbox, stop=stop))
+        try:
+            while True:
+                # Fresh state per connection (mirrors ReactorPipeline.run()).
+                self.state = self._state_cls()
+                self._sid = None
+                self._last_cond = None
+                await self.connected.wait()
+
+                # Attach only after the @connected handler has initialized state.
+                # That handler runs under _gen_lock (ReactorPipeline._invoke), and
+                # the dispatcher acquires the lock before it yields, so taking the
+                # lock here orders us strictly after it — otherwise a model that
+                # sets seed/prompt/image in @connected would attach with defaults.
+                async with lock:
+                    sid = f"s{next(self._sid_counter)}"
+                    self._sid = sid
+                    # deepcopy: the inbox payload must be a self-contained
+                    # snapshot — a nested ndarray/list in the context stays a
+                    # live alias of self.state under a shallow dict() copy, so a
+                    # later in-place mutation could change an already-enqueued msg.
+                    inbox.put_nowait(
+                        Attach(sid, copy.deepcopy(dict(self._attach_context())))
+                    )
+                    self._push_action_if_changed()  # seed the initial conditioning
+
+                # One loop both drains chunks -> emit and notices disconnect.
+                # wait_for bounds get() so a paused engine (no chunks) still
+                # detaches promptly instead of blocking here forever; a timed-out
+                # get() leaves any in-flight chunk on the queue (get is
+                # cancellation-safe), so the next iteration picks it up.
+                try:
+                    while self.connected.is_set():
+                        try:
+                            chunk = await asyncio.wait_for(
+                                outbox.get(), self._lifecycle_poll_s
+                            )
+                        except asyncio.TimeoutError:
+                            continue  # no chunk this interval — re-check liveness
+                        if chunk.session_id != sid:
+                            continue  # a chunk for a previous/other session — drop it
+                        out = self._wrap_output(chunk.output)
+                        if not isinstance(out, Output):
+                            out = self._resolve_output(out)
+                        await self.emit(out)
+                finally:
+                    # Clear identity BEFORE enqueuing Detach: a set_<field> event
+                    # racing teardown then sees no session and won't enqueue an
+                    # Action after the Detach (the local sid stays valid here).
+                    self._sid = None
+                    self.state = None
+                    inbox.put_nowait(Detach(sid))
+                    for buf in self._input_buffers.values():
+                        buf.reset()
+                    self.output_buffer.flush()
+        finally:
+            stop.set()
+            self._inbox = None
+            await _await_quietly(engine_task)
+
+    # ------------------------------------------------------------------
+    # Conditioning — client→action, event-driven
+    # ------------------------------------------------------------------
+
+    async def _invoke(
+        self,
+        handler: Callable,
+        is_async: bool,
+        *,
+        _event: Any = None,
+        reserved: tuple = (),
+        ctx: Any = None,
+        **kw: Any,
+    ) -> None:
+        """Run the handler (under ``_gen_lock``), then refresh conditioning.
+
+        Any ``set_<field>`` auto-setter or custom ``@event`` handler may have
+        mutated ``self.state``; afterwards we recompute conditioning and push a
+        single :class:`Action` only when it actually changed. ``default_serve``
+        keeps the last conditioning between ticks, so unchanged state needs no
+        message.
+        """
+        await super()._invoke(
+            handler, is_async, _event=_event, reserved=reserved, ctx=ctx, **kw
+        )
+        self._push_action_if_changed()
+
+    def _push_action_if_changed(self) -> None:
+        if self._inbox is None or self._sid is None or self.state is None:
+            return
+        # deepcopy so the enqueued Action is a self-contained snapshot: a nested
+        # ndarray/list would otherwise alias self.state and could be mutated in
+        # place after enqueue (also keeps _last_cond a stable comparison base).
+        cond = copy.deepcopy(dict(self.state_to_conditioning()))
+        if _conds_equal(cond, self._last_cond):
+            return
+        self._last_cond = cond
+        self._inbox.put_nowait(Action(self._sid, cond))
+
+    # ------------------------------------------------------------------
+    # Hooks — subclasses override these
+    # ------------------------------------------------------------------
+
+    def build_engine(self, config: dict[str, Any]) -> RealtimeInterface:
+        """Construct the engine. Required override."""
+        raise NotImplementedError(
+            f"{type(self).__name__} must implement build_engine()"
+        )
+
+    def _state_snapshot(self) -> dict[str, Any]:
+        """Public state fields as a plain dict (the default hook payload)."""
+        if self.state is None:
+            return {}
+        return {
+            name: getattr(self.state, name) for name in type(self.state)._public_fields
+        }
+
+    def _attach_context(self) -> Mapping[str, Any]:
+        """Seed context for :class:`Attach` (image / scene / prompt / seed).
+
+        Defaults to a snapshot of public state at connect time; override to
+        narrow it (e.g. only the seed).
+        """
+        return self._state_snapshot()
+
+    def state_to_conditioning(self) -> Mapping[str, Any]:
+        """Adapter from ``self.state`` to the engine's action-class conditioning.
+
+        This is the State -> ``dict[str, Any]`` seam for :class:`Action`.
+        Override it to decouple your state shape from the engine's conditioning
+        vocabulary — rename fields, drop internal-only fields, or derive values
+        the engine wants but you don't expose in state. Defaults to a snapshot
+        of public state.
+
+        Note: change-detection between ticks compares the returned dict; array
+        values are handled with :func:`numpy.array_equal`, but prefer
+        scalars/strings for high-frequency ``Action`` conditioning.
+        """
+        return self._state_snapshot()
+
+    def _wrap_output(self, output: Any) -> Any:
+        """Turn one engine chunk into an :class:`Output` (or a raw frame).
+
+        Returning a raw ``np.ndarray`` falls back to ``ReactorPipeline``'s
+        single-track shorthand. Default: pass through.
+        """
+        return output
+
+
+def _conds_equal(a: Optional[dict], b: Optional[dict]) -> bool:
+    """Dict equality that tolerates ndarray values (plain ``==`` on arrays
+    yields an array, and ``bool()`` of that raises ``ValueError``)."""
+    if a is None or b is None:
+        return a is b
+    if a.keys() != b.keys():
+        return False
+    for key in a:
+        av, bv = a[key], b[key]
+        if isinstance(av, np.ndarray) or isinstance(bv, np.ndarray):
+            if not np.array_equal(av, bv):
+                return False
+        elif av != bv:
+            return False
+    return True
+
+
+async def _await_quietly(task: asyncio.Task) -> None:
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass

{reactor_runtime-2.9.0 → reactor_runtime-2.9.2}/src/reactor_runtime/transports/gstreamer/client.py

@@ -71,6 +71,7 @@ from reactor_runtime.transports.gstreamer.signals import SignalManager
 from reactor_runtime.transports.gstreamer.sender import AudioSender, VideoSender
 from reactor_runtime.transports.gstreamer.receiver import VideoReceiver, AudioReceiver
 from reactor_runtime.transports.gstreamer.quality import aggregate_qos_score
+from reactor_runtime.utils.messages import advance_media_stats_report
 from reactor_runtime.transports.gstreamer.settings import (
     SUPPORTED_RTP_HEADER_EXTENSION_URIS,
     VIDEO_BWE_MIN_BITRATE_KBPS,
@@ -108,6 +109,9 @@ FRAME_Q_DRAIN_TIMEOUT_MS = 10
 # Quality score measurement interval
 QUALITY_METER_INTERVAL_MS = 1000
 
+# Quality-meter ticks between mediaStats pushes to the client (5 s at 1 s/tick).
+CLIENT_SEND_STATS_INTERVAL = 5
+
 # =============================================================================
 # Helpers for converting transport-agnostic types to GStreamer expected ones
 # =============================================================================
@@ -244,6 +248,8 @@ class GStreamerTransport(WebRTCTransport):
         self._incoming_width = 0
         self._incoming_height = 0
 
+        self._stats_interval_tick = 0
+
     # =========================================================================
     # Factory (implements the ABC hook)
     # =========================================================================
@@ -508,18 +514,24 @@ class GStreamerTransport(WebRTCTransport):
             scores = [
                 s
                 for sender in self._senders.values()
-                if isinstance(sender, VideoSender)
-                for s in [sender.qos()]
-                if s is not None
+                if isinstance(sender, VideoSender) and (s := sender.qos()) is not None
             ]
             score = aggregate_qos_score(scores)
             if score is not None:
-                logger.info(
+                logger.debug(
                     "video quality score",
                     score=score,
                     senders=len(scores),
                 )
 
+                self._stats_interval_tick, wrapped = advance_media_stats_report(
+                    self._stats_interval_tick,
+                    CLIENT_SEND_STATS_INTERVAL,
+                    video_aggregate_qos=score,
+                )
+                if wrapped is not None:
+                    self._gst_send_datachannel_msg(json.dumps(wrapped))
+
             return GLib.SOURCE_CONTINUE
 
         src.set_callback(_tick)

{reactor_runtime-2.9.0 → reactor_runtime-2.9.2}/src/reactor_runtime/utils/messages.py

@@ -39,6 +39,47 @@ class RuntimeMessageType(str, Enum):
     # when a moderatable input is flagged. Carries the action tier,
     # categories, and a short human-readable message.
     MODERATION = "moderation"
+    # Periodic media statistics exchanged with the client.
+    MEDIA_STATS = "mediaStats"
+
+
+def build_media_stats_message(*, video_aggregate_qos: int | float) -> dict:
+    """Build a runtime-channel ``mediaStats`` message."""
+    vqos_scaled = max(0, min(10, round(video_aggregate_qos)))
+    return RuntimeMessage(
+        data={
+            "type": RuntimeMessageType.MEDIA_STATS,
+            "data": {"video": {"aggregateQos": vqos_scaled}},
+        }
+    ).model_dump()
+
+
+def advance_media_stats_report(
+    tick: int,
+    send_interval: int,
+    *,
+    video_aggregate_qos: int | float,
+) -> tuple[int, dict | None]:
+    """Advance the quality-meter tick counter and maybe emit ``mediaStats``.
+
+    Called once per quality-meter tick (typically every 1 s). When
+    ``send_interval`` consecutive ticks have elapsed — e.g. ``5`` for a
+    5 s client push cadence — returns a freshly built message and resets
+    the counter to ``0``. When ``send_interval <= 0``, reporting is
+    disabled and ``(tick, None)`` is returned unchanged.
+
+    Returns:
+        ``(new_tick, message_or_none)`` — ``message_or_none`` is a
+        serialized ``RuntimeMessage`` envelope when the interval elapses.
+    """
+    if send_interval <= 0:
+        return tick, None
+
+    tick += 1
+    if tick != send_interval:
+        return tick, None
+
+    return 0, build_media_stats_message(video_aggregate_qos=video_aggregate_qos)
 
 
 class ApplicationMessage(BaseModel):

{reactor_runtime-2.9.0 → reactor_runtime-2.9.2}/src/reactor_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor_runtime
-Version: 2.9.0
+Version: 2.9.2
 Summary: Reactor runtime with public model API
 Author-email: Reactor <team@reactor.inc>
 Requires-Python: >=3.9

{reactor_runtime-2.9.0 → reactor_runtime-2.9.2}/src/reactor_runtime.egg-info/SOURCES.txt

@@ -54,6 +54,8 @@ src/reactor_runtime/profiling/backends/file.py
 src/reactor_runtime/profiling/backends/otlp.py
 src/reactor_runtime/profiling/plotting/__init__.py
 src/reactor_runtime/profiling/plotting/plot_profiling.py
+src/reactor_runtime/realtime/__init__.py
+src/reactor_runtime/realtime/pipeline.py
 src/reactor_runtime/recording/__init__.py
 src/reactor_runtime/recording/chunk_encoder.py
 src/reactor_runtime/recording/chunk_uploader.py