reactor-runtime 3.2.2__tar.gz → 3.2.4__tar.gz

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.2.2
+Version: 3.2.4
 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://deploy-docs.reactor.inc) · [🚀 Quickstart](https://deploy-docs.reactor.inc/development/quickstart) · [🌐 Reactor](https://reactor.inc)
+[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/overview) · [🌐 Reactor](https://reactor.inc)
 
 </div>
 
@@ -95,19 +95,19 @@ reactor run
 
 ## Install
 
-Everything runs through the [`reactor` CLI](https://deploy-docs.reactor.inc/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.
+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://deploy-docs.reactor.inc/platform/installation).
+Not on macOS, or pinning a release in CI? See [Install the CLI](https://docs.reactor.inc/deploy/platform/installation).
 
 ## Learn more
 
-- [Quickstart](https://deploy-docs.reactor.inc/development/quickstart): from zero to a streaming model in 2 minutes
-- [Model anatomy](https://deploy-docs.reactor.inc/development/reactor-model/model-anatomy): every piece of a Reactor model, line by line
-- [The run loop](https://deploy-docs.reactor.inc/development/reactor-model/run-loop): emitting frames, batches, and frame rates
+- [Quickstart](https://docs.reactor.inc/deploy/development/overview): from zero to a streaming model in 2 minutes
+- [Model anatomy](https://docs.reactor.inc/deploy/development/reactor-model/model-anatomy): every piece of a Reactor model, line by line
+- [The run loop](https://docs.reactor.inc/deploy/development/reactor-model/run-loop): emitting frames, batches, and frame rates
 
 ## Development
 

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/README.md

@@ -4,7 +4,7 @@
 
 **Build real-time AI models in Python.**
 
-[📖 Documentation](https://deploy-docs.reactor.inc) · [🚀 Quickstart](https://deploy-docs.reactor.inc/development/quickstart) · [🌐 Reactor](https://reactor.inc)
+[📖 Documentation](https://docs.reactor.inc/deploy/overview) · [🚀 Quickstart](https://docs.reactor.inc/deploy/development/overview) · [🌐 Reactor](https://reactor.inc)
 
 </div>
 
@@ -69,19 +69,19 @@ reactor run
 
 ## Install
 
-Everything runs through the [`reactor` CLI](https://deploy-docs.reactor.inc/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.
+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://deploy-docs.reactor.inc/platform/installation).
+Not on macOS, or pinning a release in CI? See [Install the CLI](https://docs.reactor.inc/deploy/platform/installation).
 
 ## Learn more
 
-- [Quickstart](https://deploy-docs.reactor.inc/development/quickstart): from zero to a streaming model in 2 minutes
-- [Model anatomy](https://deploy-docs.reactor.inc/development/reactor-model/model-anatomy): every piece of a Reactor model, line by line
-- [The run loop](https://deploy-docs.reactor.inc/development/reactor-model/run-loop): emitting frames, batches, and frame rates
+- [Quickstart](https://docs.reactor.inc/deploy/development/overview): from zero to a streaming model in 2 minutes
+- [Model anatomy](https://docs.reactor.inc/deploy/development/reactor-model/model-anatomy): every piece of a Reactor model, line by line
+- [The run loop](https://docs.reactor.inc/deploy/development/reactor-model/run-loop): emitting frames, batches, and frame rates
 
 ## Development
 

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/pyproject.toml

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

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/pyproject.toml.orig

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

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/src/reactor_runtime/manifest.py

@@ -2,8 +2,8 @@
 
 The ``reactor.yaml`` manifest is the runtime's one configuration file:
 ``runtime.import`` names the model as a ``"module:Class"`` reference,
-``runtime.config`` points at the model's own config file, and the top-level
-``recording:`` block configures the recorder. This module turns that file into
+``runtime.config`` points at the model's own config file, and the
+``runtime.recording`` block configures the recorder. This module turns that file into
 a :class:`~reactor_runtime.core.RuntimeConfig` and the reference into the model
 class — and it is the only code that does either, so every entry point resolves
 the same model from the same directory.
@@ -32,8 +32,8 @@ def load_config(manifest: Path) -> RuntimeConfig:
 
     ``runtime.import`` — the ``"module:Class"`` model reference — and
     ``runtime.config`` — the path to the model's own config file — name the
-    model, ``model.name`` is the name it is published under, and the top-level
-    ``recording:`` block configures the recorder; the rest of the manifest
+    model, ``model.name`` is the name it is published under, and the
+    ``runtime.recording`` block configures the recorder; the rest of the manifest
     describes the model to the platform and is not the runtime's concern. The
     config path is passed to the model verbatim (resolved to an absolute path);
     the runtime never parses its contents.
@@ -65,7 +65,7 @@ def load_config(manifest: Path) -> RuntimeConfig:
         model_ref=model_ref,
         model_name=_model_name(document.get("model")),
         config_path=_resolve_config_path(runtime, manifest),
-        recording=_recording_from_manifest(document.get("recording")),
+        recording=_recording_from_manifest(runtime, document),
     )
 
 
@@ -110,19 +110,25 @@ def import_model_class(model_ref: str) -> type[ReactorCore]:
     return model_cls
 
 
-def _recording_from_manifest(block: Any) -> RecordingConfig:
+def _recording_from_manifest(runtime: dict[str, Any], document: dict[str, Any]) -> RecordingConfig:
     """Parse the manifest's ``recording:`` block into a :class:`RecordingConfig`.
 
-    A missing or non-mapping block leaves recording disabled at its defaults.
-    Unknown keys are ignored so a manifest can carry forward-looking settings
-    without breaking an older runtime.
+    The block nests under ``runtime:``. A top-level ``recording:`` block is
+    still honored for older manifests, and the nested block wins when both are
+    present. A missing or non-mapping block leaves recording disabled at its
+    defaults. Unknown keys are ignored so a manifest can carry forward-looking
+    settings without breaking an older runtime.
 
     Args:
-        block: The raw ``recording:`` value from the manifest, if any.
+        runtime: The manifest's ``runtime`` section.
+        document: The whole manifest document, for the legacy top-level block.
 
     Returns:
         The parsed recorder configuration.
     """
+    block = runtime.get("recording")
+    if not isinstance(block, dict):
+        block = document.get("recording")
     if not isinstance(block, dict):
         return RecordingConfig()
     raw_video = block.get("video")

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/src/reactor_runtime/recording/recorder.py

@@ -15,7 +15,6 @@ director learns a clip is genuinely fetchable rather than merely requested.
 
 from __future__ import annotations
 
-import contextlib
 import math
 import queue
 import re
@@ -25,6 +24,7 @@ import threading
 import time
 from collections.abc import Callable
 from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlencode
@@ -45,6 +45,21 @@ logger = get_logger(__name__)
 # model that runs slower or faster than real time still records at true duration.
 RECORDING_FPS = 30
 
+# How many grid frames may sit queued between the model thread and the encoder.
+# Never applied below one emission's worth, so a model that batches always fits
+# a whole emission: the queue absorbs a burst and drains it between emissions,
+# rather than gating the burst at its own depth.
+_FEED_DEPTH = 4
+# How long one emission may wait, in total, for the encoder to make room. Bounds
+# the producer's exposure to a wedged encoder: past the deadline the rest of the
+# emission is counted and abandoned, so a stalled recording costs the recording
+# rather than the session.
+_FEED_WAIT_SECONDS = 1.0
+# How often the feed reports dropped frames. An encoder that stays behind loses
+# frames on every emission, so the count is carried on every recording's summary
+# and only the periodic warning is rate-limited.
+_DROP_LOG_INTERVAL_SECONDS = 5.0
+
 _INIT_FILENAME = "init.mp4"
 # Written into a recording's directory once it is finished, so its final segment
 # (which has no successor to prove it closed) is recognised as fetchable.
@@ -72,6 +87,23 @@ _AudioArray = npt.NDArray[Any]
 _FeedItem = tuple[npt.NDArray[Any], _AudioArray | None]
 
 
+class _Slot(Enum):
+    """The answer to asking the feed queue for room for one grid frame.
+
+    Separates the two reasons room is refused, because only one of them is a
+    fact about the recording's health: frames abandoned because the encoder is
+    behind are the recording losing media, while frames abandoned because the
+    recording is stopping are teardown and say nothing about the encoder.
+    """
+
+    TAKEN = "taken"
+    """There is room; the frame can be queued."""
+    FULL = "full"
+    """The encoder is behind, and any wait the chunk asked for has run out."""
+    WINDING_DOWN = "winding_down"
+    """The recording is stopping, so the rest of the emission is moot."""
+
+
 class RecorderError(Exception):
     """Base for a clip request the recorder cannot serve."""
 
@@ -205,7 +237,13 @@ class Recorder:
         self._started = False
         self._disabled = False
 
-        self._feed_queue: queue.Queue[_FeedItem | None] = queue.Queue(maxsize=4)
+        # The queue is unbounded in itself; the depth is the bound, checked as
+        # each frame is queued. The effective capacity never sits below one
+        # emission, so a batching model always fits a whole emission.
+        self._feed_queue: queue.Queue[_FeedItem | None] = queue.Queue()
+        # Signalled by the feed worker after each dequeue so a producer waiting
+        # for room sleeps until the encoder takes a frame instead of polling.
+        self._feed_room = threading.Condition()
         self._feed_thread: threading.Thread | None = None
         self._feed_stop = threading.Event()
         self._watch_thread: threading.Thread | None = None
@@ -227,6 +265,9 @@ class Recorder:
         self._chunk_lock = threading.Lock()
 
         self._dropped_frames = 0
+        # When the feed last warned about dropped frames. Zero until it has, so
+        # the first loss of a session is always reported.
+        self._dropped_logged_at = 0.0
         # Fractional grid frames carried between chunks so resampling a chunk's
         # own rate onto the fixed recording grid accumulates no rounding drift.
         self._grid_debt = 0.0
@@ -311,8 +352,11 @@ class Recorder:
             return
         self._disabled = True
         self._feed_stop.set()
-        with contextlib.suppress(queue.Full):
-            self._feed_queue.put_nowait(None)
+        self._feed_queue.put_nowait(None)
+        # Release a producer parked on a full queue, so teardown cannot wait
+        # behind an encoder that has already stopped draining.
+        with self._feed_room:
+            self._feed_room.notify_all()
         feed_thread = self._feed_thread
         self._feed_thread = None
         if self._encoder is not None:
@@ -410,6 +454,7 @@ class Recorder:
         self._audio_sample_rate = 48_000
         self._has_audio = False
         self._dropped_frames = 0
+        self._dropped_logged_at = 0.0
         self._grid_debt = 0.0
         self._audio_jitter_buf = []
         self._audio_buffered_samples = 0
@@ -423,7 +468,7 @@ class Recorder:
     # -- media fan-out tap ----------------------------------------------------
 
     def on_chunk(self, chunk: MediaChunk) -> None:
-        """Feed one emitted media chunk to the recording; non-blocking.
+        """Feed one emitted media chunk to the recording.
 
         Called on the model thread by the runner's media fan-out. The chunk's
         frames are resampled from the chunk's own rate onto the fixed recording
@@ -433,8 +478,17 @@ class Recorder:
         duration. Fractional grid frames carry across chunks so the resampling
         accumulates no drift. The timeline advances by the media actually fed,
         not by wall-clock, so a pause simply stops advancing rather than
-        recording dead air. A frame that does not fit the feed queue is dropped
-        to keep the model thread unblocked.
+        recording dead air.
+
+        The feed queue holds at least a whole emission, so handing a batch over
+        costs the model thread nothing while the encoder keeps up. Once the
+        queue is full the chunk decides, exactly as it does at the wire: a chunk
+        that asks for backpressure (``chunk.wait``) makes this call wait for
+        room, bounded by :data:`_FEED_WAIT_SECONDS` across the emission, and one
+        that prefers skipping has its overflow dropped and counted. Only the
+        encoder falling behind is counted: an emission cut short because the
+        recording is stopping is teardown, and reporting it would put phantom
+        losses on the summary :meth:`stop` logs.
         """
         if self.disabled:
             return
@@ -456,24 +510,69 @@ class Recorder:
         grid_frames = int(self._grid_debt)
         self._grid_debt -= grid_frames
         audio_target = round(self._audio_sample_rate / RECORDING_FPS) if self._has_audio else 0
+        # One authoritative bound, never below the emission being queued, so the
+        # burst a batching model hands over always fits.
+        capacity = max(_FEED_DEPTH, grid_frames)
+        deadline = time.monotonic() + _FEED_WAIT_SECONDS
         fed = 0
+        outcome = _Slot.TAKEN
         for i in range(grid_frames):
+            outcome = self._claim_slot(capacity, wait=chunk.wait, deadline=deadline)
+            if outcome is not _Slot.TAKEN:
+                break
             video_data = frames[i * len(frames) // grid_frames]
             audio_data = self._take_audio(audio_target) if self._has_audio else None
-            try:
-                self._feed_queue.put_nowait((video_data, audio_data))
-            except queue.Full:
-                self._dropped_frames += 1
-                if self._dropped_frames == 1 or self._dropped_frames % 300 == 0:
-                    logger.warning(
-                        "recorder feed queue full; dropping a frame to keep the model unblocked",
-                        dropped_total=self._dropped_frames,
-                    )
-                break
+            self._feed_queue.put_nowait((video_data, audio_data))
             fed += 1
+        if outcome is _Slot.FULL:
+            self._count_dropped(grid_frames - fed, grid_frames)
         if fed:
             markers.advance(fed / RECORDING_FPS)
 
+    def _claim_slot(self, capacity: int, *, wait: bool, deadline: float) -> _Slot:
+        """Ask the feed queue for room for one more grid frame.
+
+        A chunk that asks for backpressure waits for the encoder to take a
+        frame, until *deadline* passes; one that does not reports the full queue
+        immediately so its caller can drop. A recording that is stopping answers
+        :attr:`_Slot.WINDING_DOWN` on either path, so teardown is never counted
+        against the encoder.
+        """
+        if self._feed_queue.qsize() < capacity:
+            return _Slot.TAKEN
+        if self._feed_stop.is_set() or self._disabled:
+            return _Slot.WINDING_DOWN
+        if not wait:
+            return _Slot.FULL
+        with self._feed_room:
+            while self._feed_queue.qsize() >= capacity:
+                if self._feed_stop.is_set() or self._disabled:
+                    return _Slot.WINDING_DOWN
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return _Slot.FULL
+                self._feed_room.wait(timeout=min(remaining, 0.1))
+        return _Slot.TAKEN
+
+    def _count_dropped(self, dropped: int, offered: int) -> None:
+        """Record the frames an emission could not hand over, and say so.
+
+        Every dropped frame reaches the count, which the recording reports when
+        it stops; the warning itself is rate-limited so an encoder that stays
+        behind reports the loss periodically rather than once per emission.
+        """
+        self._dropped_frames += dropped
+        now = time.monotonic()
+        if now - self._dropped_logged_at < _DROP_LOG_INTERVAL_SECONDS:
+            return
+        self._dropped_logged_at = now
+        logger.warning(
+            "recorder feed queue full; dropping frames from an emission",
+            dropped=dropped,
+            offered=offered,
+            dropped_total=self._dropped_frames,
+        )
+
     def _video_frames(self, bundle: MediaBundle) -> list[npt.NDArray[Any]]:
         """Split the recorded video track into single ``(H, W, 3)`` frames.
 
@@ -537,6 +636,10 @@ class Recorder:
                 item = self._feed_queue.get(timeout=0.1)
             except queue.Empty:
                 continue
+            # Room opened the moment the frame left the queue, so a producer
+            # waiting on capacity is released before the encode, not after it.
+            with self._feed_room:
+                self._feed_room.notify_all()
             if item is None:
                 return
             encoder = self._encoder
@@ -598,12 +701,14 @@ class Recorder:
         return out.reshape(1, -1)
 
     def _drain_feed_queue(self) -> None:
-        """Discard every queued feed item."""
+        """Discard every queued feed item, releasing anyone waiting for room."""
         while True:
             try:
                 self._feed_queue.get_nowait()
             except queue.Empty:
-                return
+                break
+        with self._feed_room:
+            self._feed_room.notify_all()
 
     # -- clip / recording requests --------------------------------------------
 

{reactor_runtime-3.2.2 → reactor_runtime-3.2.4}/src/reactor_runtime/runner/runner.py

@@ -888,17 +888,27 @@ class Runner(ServiceComponent, ConnectionSink):
     def _emit_media(self, chunk: MediaChunk) -> None:
         """Fan one emitted media chunk out to the recorder and the connections.
 
-        Called off the model loop (emit dispatches to a worker thread). The
-        recorder is fed first and always queues without blocking, so a
-        backpressure wait in a connection's pacer (``chunk.wait``) delays the
-        producer, never the recording. A chunk emitted with ``drop=True``
-        keeps every consumer non-blocking.
+        Called off the model loop (emit dispatches to a worker thread). Both
+        consumers bound their queue the same way — never below the emission
+        being handed over — so a whole chunk fits each of them and the fan-out
+        costs the producer nothing while they keep up. A consumer that falls
+        behind honours ``chunk.wait``, and a chunk emitted with ``drop=True``
+        leaves every consumer non-blocking.
+
+        The connections are served first so the archive is never in front of
+        the session. A pacer that makes the producer wait is throttling it to
+        the playout rate it asked for, and drains on its own thread meanwhile;
+        the recorder's wait is bounded instead, because an encoder can stall
+        outright. Feeding the recorder second keeps that bounded stall off the
+        live path, and leaves its queue the whole broadcast to drain into.
         """
         for track in chunk.bundle.tracks:
             self._model_metrics.emitted(track, chunk.n_frames)
-        self._recorder.on_chunk(chunk)
         generation = self._media_generation
         self._connections.broadcast_media(chunk, abort=lambda: self._media_generation != generation)
+        # The archive takes the whole chunk even when a flush cut the broadcast
+        # short: a playout cut is not an archive boundary.
+        self._recorder.on_chunk(chunk)
 
     def _flush_media(self) -> None:
         """Drop queued media in every connection and cut playout to black.