reactor-runtime 3.6.1__tar.gz → 3.7.0__tar.gz

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.6.1
+Version: 3.7.0
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -19,7 +19,7 @@ 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: reactor-webrtc==0.21.0
 Requires-Dist: uvicorn>=0.49.0
 Requires-Python: >=3.12
 Project-URL: Source, https://github.com/reactor-team/reactor-runtime
@@ -122,7 +122,24 @@ class MyModel(ReactorApp):
         return outcome.to_output()
 ```
 
-Command handlers and lifecycle hooks run between steps, never during one. A model has one method per lifecycle hook kind (`@session_started`, `@session_ended`, `@connected`, `@disconnected`, `@file_uploaded`). A subclass extends an inherited hook by overriding that method and calling `super()`; the override runs whether or not it repeats the decorator. Marking a second method with the same kind, in one class or in a subclass, fails when the class is defined, so a hook is never dropped in silence. 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.
+Command handlers and lifecycle hooks run between steps, never during one. A model has one method per lifecycle hook kind (`@session_started`, `@session_ended`, `@connected`, `@disconnected`, `@file_uploaded`). A subclass extends an inherited hook by overriding that method and calling `super()`; the override runs whether or not it repeats the decorator. Marking a second method with the same kind, in one class or in a subclass, fails when the class is defined, so a hook is never dropped in silence. The default `run()` is the loop that drives the three hooks, and it reports each step that runs with `complete_step()`, which is what the runtime counts a session's steps by. To write that report yourself, for example to keep extra files with the step, return a `StepCompleted(output=..., files=...)` from `process_output()` instead of the `Output`. Override `run()` to write your own loop against `emit()`, `send()`, `complete_step()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called, and your loop calls `complete_step(StepCompleted(output=...))` each time it finishes a unit of work. 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.
+
+A session can start with its setup already in hand: `POST /start_session` takes a `starting_input` of state values and commands, which the runtime applies on the normal command path before any client connects. A system client sends them, a connection the runtime opens itself, so a handler that takes `client` gets a `ClientInfo` whose `system` is true. The step loop takes its first step only once every starting command has landed, uploads included, so no step runs on the defaults the starting input replaces. In a live session the system client then leaves and the loop waits for a viewer, as it always does; a model with its own `run()` sees the system client connect like any client. A live session stays `waiting` while its starting input applies, because the system client does not occupy it, and `/events` journals the system client's `connection_opened` and `connection_closed` as `waiting -> waiting`. A session with `steps` is occupied by the system client until it ends, so it streams with no other client. The runtime ends it itself once the model has reported that many steps, with a normal stop whose close reason is "Session ended: the requested steps are complete."
+
+A model can keep each step it reports as a folder of files, turned on in `reactor.yaml`:
+
+```yaml
+runtime:
+  step_results:
+    enabled: true
+    video: {codec: h264, preset: veryfast, crf: 23}   # or codec: h265
+    audio: {codec: aac, bitrate_kbps: 128}
+    queue: 8
+```
+
+Every track of the step's output becomes its own stream in one `output.mp4`, beside the extra `files` the step carried and a `result.json` that lists them. `queue` bounds how many steps may wait to be saved; a step that finds it full is not saved, so saving never holds the model up. Each step is its own encode, so this suits a model that finishes a step every few seconds rather than every frame.
+
+When step results are on, `GET /sessions/{id}/steps` lists a session's saved folders by the session's own id; each stays readable for five minutes after it is written, after the session ends too.
 
 Scaffold, build, and run it with the CLI:
 

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/README.md

@@ -95,7 +95,24 @@ class MyModel(ReactorApp):
         return outcome.to_output()
 ```
 
-Command handlers and lifecycle hooks run between steps, never during one. A model has one method per lifecycle hook kind (`@session_started`, `@session_ended`, `@connected`, `@disconnected`, `@file_uploaded`). A subclass extends an inherited hook by overriding that method and calling `super()`; the override runs whether or not it repeats the decorator. Marking a second method with the same kind, in one class or in a subclass, fails when the class is defined, so a hook is never dropped in silence. 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.
+Command handlers and lifecycle hooks run between steps, never during one. A model has one method per lifecycle hook kind (`@session_started`, `@session_ended`, `@connected`, `@disconnected`, `@file_uploaded`). A subclass extends an inherited hook by overriding that method and calling `super()`; the override runs whether or not it repeats the decorator. Marking a second method with the same kind, in one class or in a subclass, fails when the class is defined, so a hook is never dropped in silence. The default `run()` is the loop that drives the three hooks, and it reports each step that runs with `complete_step()`, which is what the runtime counts a session's steps by. To write that report yourself, for example to keep extra files with the step, return a `StepCompleted(output=..., files=...)` from `process_output()` instead of the `Output`. Override `run()` to write your own loop against `emit()`, `send()`, `complete_step()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called, and your loop calls `complete_step(StepCompleted(output=...))` each time it finishes a unit of work. 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.
+
+A session can start with its setup already in hand: `POST /start_session` takes a `starting_input` of state values and commands, which the runtime applies on the normal command path before any client connects. A system client sends them, a connection the runtime opens itself, so a handler that takes `client` gets a `ClientInfo` whose `system` is true. The step loop takes its first step only once every starting command has landed, uploads included, so no step runs on the defaults the starting input replaces. In a live session the system client then leaves and the loop waits for a viewer, as it always does; a model with its own `run()` sees the system client connect like any client. A live session stays `waiting` while its starting input applies, because the system client does not occupy it, and `/events` journals the system client's `connection_opened` and `connection_closed` as `waiting -> waiting`. A session with `steps` is occupied by the system client until it ends, so it streams with no other client. The runtime ends it itself once the model has reported that many steps, with a normal stop whose close reason is "Session ended: the requested steps are complete."
+
+A model can keep each step it reports as a folder of files, turned on in `reactor.yaml`:
+
+```yaml
+runtime:
+  step_results:
+    enabled: true
+    video: {codec: h264, preset: veryfast, crf: 23}   # or codec: h265
+    audio: {codec: aac, bitrate_kbps: 128}
+    queue: 8
+```
+
+Every track of the step's output becomes its own stream in one `output.mp4`, beside the extra `files` the step carried and a `result.json` that lists them. `queue` bounds how many steps may wait to be saved; a step that finds it full is not saved, so saving never holds the model up. Each step is its own encode, so this suits a model that finishes a step every few seconds rather than every frame.
+
+When step results are on, `GET /sessions/{id}/steps` lists a session's saved folders by the session's own id; each stays readable for five minutes after it is written, after the session ends too.
 
 Scaffold, build, and run it with the CLI:
 

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/pyproject.toml

@@ -95,7 +95,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.6.1"
+version = "3.7.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -119,7 +119,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.18.0",
+    "reactor-webrtc==0.21.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/pyproject.toml.orig

@@ -20,7 +20,7 @@ version = "1.20260929.8"
 
 [project]
 name = "reactor-runtime"
-version = "3.6.1"
+version = "3.7.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -42,7 +42,7 @@ dependencies = [
     "prometheus-client>=0.26.0",
     "protobuf>=7.35.1",
     "pyyaml>=6.0.3",
-    "reactor-webrtc==0.18.0",
+    "reactor-webrtc==0.21.0",
     "uvicorn>=0.49.0",
 ]
 

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/__init__.py

@@ -43,6 +43,7 @@ from reactor_runtime.interface import (
     OutputStream,
     ReactorApp,
     ReadMode,
+    StepCompleted,
     StepOutcome,
     Track,
     TrackPayload,
@@ -96,6 +97,7 @@ __all__ = [
     "OutputStream",
     "ReactorApp",
     "ReadMode",
+    "StepCompleted",
     "StepOutcome",
     "Track",
     "TrackPayload",

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/core/__init__.py

@@ -17,10 +17,16 @@ from reactor_runtime.core.model import (
     ReactorEvent,
     SessionEnded,
     SessionStarted,
+    StartingInputApplied,
     TransitionEvent,
     UploadedFile,
 )
-from reactor_runtime.core.service import RecordingConfig, RuntimeConfig, ServiceComponent
+from reactor_runtime.core.service import (
+    RecordingConfig,
+    RuntimeConfig,
+    ServiceComponent,
+    StepResultsConfig,
+)
 from reactor_runtime.core.session import (
     JOURNAL_EVENTS,
     SessionEvent,
@@ -30,7 +36,12 @@ from reactor_runtime.core.session import (
 from reactor_runtime.core.transport import Connection, ConnectionSink
 from reactor_runtime.core.typespec import TypeSpec
 from reactor_runtime.core.values import (
+    ClientConnectionStat,
+    ClientStatsBatch,
+    ClientTrackDirection,
+    ClientTrackStat,
     CommandFailure,
+    CompletedStep,
     ConnectionCapabilities,
     ConnId,
     Health,
@@ -48,10 +59,15 @@ from reactor_runtime.core.values import (
 __all__ = [
     "JOURNAL_EVENTS",
     "ClientConnected",
+    "ClientConnectionStat",
     "ClientDisconnected",
+    "ClientStatsBatch",
+    "ClientTrackDirection",
+    "ClientTrackStat",
     "Command",
     "CommandFailure",
     "CommandField",
+    "CompletedStep",
     "ConnId",
     "Connection",
     "ConnectionCapabilities",
@@ -74,6 +90,8 @@ __all__ = [
     "SessionEvent",
     "SessionStarted",
     "SessionState",
+    "StartingInputApplied",
+    "StepResultsConfig",
     "TrackData",
     "TrackDirection",
     "TrackInfo",

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/core/model.py

@@ -243,9 +243,22 @@ class SessionStarted(ReactorEvent):
 
     Attributes:
         session_id: Identifier for the session that started.
+        starting_input: Whether a starting input follows. When one does, the
+            step loop takes no step until :class:`StartingInputApplied`
+            arrives, so its first step sees the state the starting input set.
     """
 
     session_id: str
+    starting_input: bool = False
+
+
+@dataclass(frozen=True)
+class StartingInputApplied(ReactorEvent):
+    """Every command of the session's starting input has been handed to the model.
+
+    It follows the last starting command on the same ordered queue, so every
+    starting handler has returned by the time the model handles it.
+    """
 
 
 @dataclass(frozen=True)
@@ -274,10 +287,12 @@ class ClientConnected(ReactorEvent):
     Attributes:
         conn_id: The connection that opened.
         total: Live connection count after the open.
+        system: Whether the connection is the runtime's own system client.
     """
 
     conn_id: ConnId
     total: int
+    system: bool = False
 
 
 @dataclass(frozen=True)

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/core/service.py

@@ -92,6 +92,36 @@ class RecordingConfig:
     recording_dir: str | None = None
 
 
+@dataclass(frozen=True)
+class StepResultsConfig:
+    """How each finished step is kept, drawn from the manifest's ``step_results:`` block.
+
+    A model with no ``step_results:`` block keeps nothing (``enabled`` is
+    ``False``). When enabled, every step the model reports is saved as a
+    folder: its output in one ``output.mp4``, with each track of the step's
+    ``Output`` as its own stream, beside any extra files and a ``result.json``.
+    Turning it on is the model's choice, not a session option.
+
+    Attributes:
+        enabled: Whether the runtime saves each finished step.
+        video_codec: ``"h264"`` or ``"h265"``.
+        video_preset: The libx264/libx265 preset.
+        video_crf: The constant-rate-factor quality target.
+        audio_codec: The audio codec, e.g. ``"aac"``.
+        audio_bitrate_kbps: The audio bitrate in kilobits per second.
+        queue: How many steps may wait to be saved. A step that finds the
+            queue full is not saved, so the model never waits on saving.
+    """
+
+    enabled: bool = False
+    video_codec: str = "h264"
+    video_preset: str = "veryfast"
+    video_crf: int = 23
+    audio_codec: str = "aac"
+    audio_bitrate_kbps: int = 128
+    queue: int = 8
+
+
 @dataclass(frozen=True)
 class RuntimeConfig:
     """The single configuration object threaded through ``serve``.
@@ -116,6 +146,7 @@ class RuntimeConfig:
             session drain it includes, before the process is forced to exit.
         orphan_timeout: Seconds a session may stay client-less before it closes.
         recording: The recorder's configuration; disabled by default.
+        step_results: How each finished step is saved; disabled by default.
     """
 
     model_ref: str
@@ -127,3 +158,4 @@ class RuntimeConfig:
     exit_timeout: float = 10.0
     orphan_timeout: float = 60.0
     recording: RecordingConfig = field(default_factory=RecordingConfig)
+    step_results: StepResultsConfig = field(default_factory=StepResultsConfig)

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/core/session.py

@@ -75,9 +75,10 @@ class SessionEvent(Enum):
     one phase otherwise silent, since the runner emits nothing until it leaves
     ``CREATED`` on ``INITIALIZATION_SUCCESS``.
 
-    ``CHUNK_READY``, ``CLIP_READY``, ``COMMAND``, ``ERROR``, and ``METRIC`` are
-    the journal-only events (:data:`JOURNAL_EVENTS`): facts recorded for an
-    external consumer rather than moves of the lifecycle. Each is a pure
+    ``CHUNK_READY``, ``CLIP_READY``, ``COMMAND``, ``ERROR``, ``METRIC``,
+    ``STEP_COMPLETED``, and ``STEP_RESULT_READY`` are the journal-only events
+    (:data:`JOURNAL_EVENTS`): facts recorded for an external consumer rather
+    than moves of the lifecycle. Each is a pure
     self-loop legal in **every** state — a journal fact must never be silently
     dropped by the transition table (the final ``CHUNK_READY`` fires during
     ``CLOSING``; an ``ERROR`` can fire while ``ORPHANED``) — that changes no
@@ -101,6 +102,8 @@ class SessionEvent(Enum):
     COMMAND = auto()
     ERROR = auto()
     METRIC = auto()
+    STEP_COMPLETED = auto()
+    STEP_RESULT_READY = auto()
 
 
 JOURNAL_EVENTS: frozenset[SessionEvent] = frozenset(
@@ -110,6 +113,8 @@ JOURNAL_EVENTS: frozenset[SessionEvent] = frozenset(
         SessionEvent.COMMAND,
         SessionEvent.ERROR,
         SessionEvent.METRIC,
+        SessionEvent.STEP_COMPLETED,
+        SessionEvent.STEP_RESULT_READY,
     }
 )
 """The journal-only events: pure self-loops in every state, payload in ``detail``."""

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/core/transport.py

@@ -13,6 +13,7 @@ from collections.abc import Mapping
 from typing import Protocol, runtime_checkable
 
 from reactor_runtime.core.values import (
+    ClientStatsBatch,
     ConnectionCapabilities,
     ConnId,
     InputFrame,
@@ -193,6 +194,16 @@ class ConnectionSink(Protocol):
         timeline, correlated by *request_id*.
         """
 
+    def client_stats_received(self, conn_id: ConnId, batch: ClientStatsBatch) -> None:
+        """Hand up a batch of client-observed quality samples for one connection.
+
+        The client is the only vantage point onto its own receive-side
+        quality, so a transport reports the batch as decoded rather than
+        validating it. The connection identity comes from *conn_id*, which the
+        transport already holds — never from anything the payload itself
+        might claim, because the payload carries none.
+        """
+
     def connection_answered(self, conn_id: ConnId, answer: Mapping[str, str]) -> None:
         """Relay the transport's negotiation answer for one connection.
 

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/core/values.py

@@ -9,7 +9,7 @@ the import graph.
 
 from __future__ import annotations
 
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass, field
 from enum import Enum, StrEnum
 from typing import Any, NewType
@@ -44,6 +44,95 @@ class CommandFailure:
     message: str
 
 
+@dataclass(frozen=True)
+class ClientTrackStat:
+    """One WebRTC quality reading a client took for one of its tracks.
+
+    Carries the client's own view of its receive-side quality — bitrate, frame
+    rate, packet loss, jitter, round-trip time — sourced from the browser's own
+    ``getStats()``, which is the only vantage point onto that side of the
+    connection. Values are taken as reported; the runtime attaches the
+    connection identity itself rather than trusting anything the payload might
+    claim, because the payload carries none.
+
+    ``kind``/``direction``/``codec`` are fixed, structural facts about the
+    track — never a new value at runtime — so they stay their own fields;
+    :attr:`metrics` is where the actual measurements live, because that set
+    grows as new stats become worth reporting, without a schema change.
+
+    Attributes:
+        timestamp: When the client took this reading, on its own clock, in
+            epoch milliseconds.
+        track_name: The track the reading is for.
+        kind: The track's kind; ``None`` when the client did not say.
+        direction: The track's direction from the client's own perspective;
+            ``None`` when the client did not say.
+        codec: The negotiated codec, e.g. ``"VP9"``, ``"opus"`` — empty when
+            the browser hasn't reported it yet.
+        paused: Whether the client has this track paused right now.
+        metrics: The reading's measurements, by name — e.g.
+            ``"bitrate_bps"``, ``"frames_per_second"``, ``"packets_lost"``,
+            ``"packets_received"``, ``"jitter_ms"``, ``"round_trip_time_ms"``,
+            ``"frames_decoded"``, ``"frames_dropped"``, ``"frame_width"``,
+            ``"frame_height"``, ``"nack_count"``, ``"keyframe_requests"``.
+            A cumulative counter (e.g. ``packets_lost``) rides here as a raw
+            count, not a ratio computed once elsewhere — a ratio from two
+            readings with different totals cannot be re-aggregated correctly
+            afterward; a raw count can always be summed and divided once, at
+            query time.
+    """
+
+    timestamp: int
+    track_name: str
+    kind: TrackKind | None
+    direction: ClientTrackDirection | None
+    codec: str
+    paused: bool
+    metrics: Mapping[str, float]
+
+
+@dataclass(frozen=True)
+class ClientConnectionStat:
+    """A connection-wide reading, not tied to any one track.
+
+    e.g. ``"available_outgoing_bitrate_bps"`` (the client engine's own
+    estimate of outgoing headroom — the encoder's own belief, not a
+    measurement of the user's internet) or ``"time_to_connect_ms"`` (how long
+    this connection waited to establish, start to "ready") — the latter a
+    one-time fact a client reports once rather than repeating on every batch,
+    which is why :class:`ClientStatsBatch` carries this as optional.
+
+    Attributes:
+        timestamp: When the client took this reading, on its own clock, in
+            epoch milliseconds.
+        metrics: The reading's measurements, by name.
+    """
+
+    timestamp: int
+    metrics: Mapping[str, float]
+
+
+@dataclass(frozen=True)
+class ClientStatsBatch:
+    """A batch of client-observed quality readings, plus connection-wide facts.
+
+    Mirrors the wire's ``ClientStats`` message: per-track readings alongside
+    a fact set that applies to the whole connection rather than any one
+    track. A client typically sends ``connection_stat`` once, on its first
+    batch after connecting, and omits it on every batch after — most batches
+    therefore carry ``track_stats`` only.
+
+    Attributes:
+        track_stats: One reading per track this batch reports on. Empty on a
+            batch that carries only ``connection_stat``.
+        connection_stat: This batch's connection-wide reading, or ``None`` on
+            a batch that doesn't carry one — the common case.
+    """
+
+    track_stats: Sequence[ClientTrackStat]
+    connection_stat: ClientConnectionStat | None
+
+
 @dataclass(frozen=True, eq=False)
 class InputFrame:
     """A single inbound media frame with its presentation timestamp.
@@ -103,6 +192,18 @@ class TrackDirection(StrEnum):
     OUT = "out"
 
 
+class ClientTrackDirection(StrEnum):
+    """Direction of flow for a track, from the client's perspective.
+
+    The opposite polarity of :class:`TrackDirection`: a model output track
+    (``OUT``) is one the client receives (``RECVONLY``), and a model input
+    track (``IN``) is one the client sends (``SENDONLY``).
+    """
+
+    RECVONLY = "recvonly"
+    SENDONLY = "sendonly"
+
+
 @dataclass(frozen=True)
 class TrackInfo:
     """Immutable metadata describing a single media track.
@@ -321,6 +422,36 @@ class MediaChunk:
         return split_batch(self.bundle)
 
 
+@dataclass(frozen=True)
+class CompletedStep:
+    """One finished step, as the model reports it to the runtime.
+
+    The neutral form of a model's step report: the media as a bundle rather
+    than the model's own output class, and the extra files as bytes, so the
+    runtime can count, journal, and save the step without touching model code.
+
+    Attributes:
+        bundle: The media the step produced, or ``None`` when it produced none.
+        files: Extra files the model keeps with the step, keyed by file name.
+        error: Why the step failed, or ``None`` when it worked.
+        elapsed: Wall-clock seconds the step took, when measured.
+        session: The session the step belongs to, as the number of session
+            starts the model had received when the step began. The runtime
+            counts the session starts it posts the same way, so it can tell a
+            late report from an earlier session apart from the current one.
+        fps: The rate the step's media was emitted at, which a saved step's
+            video plays at: the measured throughput for a model that does not
+            pin its rate.
+    """
+
+    bundle: MediaBundle | None
+    files: Mapping[str, bytes] = field(default_factory=dict)
+    error: str | None = None
+    elapsed: float | None = None
+    session: int = 0
+    fps: float = 30.0
+
+
 @dataclass(frozen=True)
 class ConnectionCapabilities:
     """What media a connection's wire can carry.

{reactor_runtime-3.6.1 → reactor_runtime-3.7.0}/src/reactor_runtime/http/__init__.py

@@ -11,6 +11,7 @@ from reactor_runtime.http.routes import (
     EgressRoutes,
     RecordingRoutes,
     SessionRoutes,
+    StepRoutes,
     UploadRoutes,
 )
 from reactor_runtime.http.server import HttpServer
@@ -20,5 +21,6 @@ __all__ = [
     "HttpServer",
     "RecordingRoutes",
     "SessionRoutes",
+    "StepRoutes",
     "UploadRoutes",
 ]