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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.6.0
+Version: 3.7.0
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>
@@ -11,6 +11,7 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Dist: av>=18.0.0
 Requires-Dist: fastapi>=0.139.0
@@ -18,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
@@ -78,6 +79,8 @@ class MyModel(ReactorApp):
 
 That is a complete application. The runtime calls `generate()` in a loop for as long as someone is watching and emits what it returns. Every public field on `MyState` is a command the client can send: here `set_prompt` and `set_paused`, validated from the fields, and the next step reads the new values.
 
+State and message classes can be subclassed. A subclass keeps every field of its parents and adds its own, so `class SeededState(MyState): seed: int = InputField(default=0)` exposes `set_prompt`, `set_paused`, and `set_seed`. A field declared again in the subclass replaces the parent's, default and constraints included. The fields a subclass adds are keyword-only in its constructor, which lets a required field follow an inherited one that has a default. A private field (leading underscore) always needs a default, because the state is built from defaults when a session starts.
+
 A step is three calls, and `generate()` is the one you must write. `process_input()` runs before it, reading `self.state` and the media tracks, and decides whether a step can happen: return the input `generate()` gets, or raise `ApplicationError("reason")` to skip the step without touching the model. `process_output(outcome)` runs after it, with the result or the error, and returns the media to emit; send a message from there with `await self.send()` and it reaches the client before the step's frames. Both have defaults, so the model above writes neither.
 
 ```python
@@ -119,7 +122,24 @@ class MyModel(ReactorApp):
         return outcome.to_output()
 ```
 
-Command handlers and lifecycle hooks run between steps, never during one. The default `run()` is the loop that drives the three hooks. Override it to write your own loop against `emit()`, `send()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called. Do that for a loop that is not one step per emit, such as a renderer that emits several times per step or a model that must block on an input.
+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.0 → reactor_runtime-3.7.0}/README.md

@@ -52,6 +52,8 @@ class MyModel(ReactorApp):
 
 That is a complete application. The runtime calls `generate()` in a loop for as long as someone is watching and emits what it returns. Every public field on `MyState` is a command the client can send: here `set_prompt` and `set_paused`, validated from the fields, and the next step reads the new values.
 
+State and message classes can be subclassed. A subclass keeps every field of its parents and adds its own, so `class SeededState(MyState): seed: int = InputField(default=0)` exposes `set_prompt`, `set_paused`, and `set_seed`. A field declared again in the subclass replaces the parent's, default and constraints included. The fields a subclass adds are keyword-only in its constructor, which lets a required field follow an inherited one that has a default. A private field (leading underscore) always needs a default, because the state is built from defaults when a session starts.
+
 A step is three calls, and `generate()` is the one you must write. `process_input()` runs before it, reading `self.state` and the media tracks, and decides whether a step can happen: return the input `generate()` gets, or raise `ApplicationError("reason")` to skip the step without touching the model. `process_output(outcome)` runs after it, with the result or the error, and returns the media to emit; send a message from there with `await self.send()` and it reaches the client before the step's frames. Both have defaults, so the model above writes neither.
 
 ```python
@@ -93,7 +95,24 @@ class MyModel(ReactorApp):
         return outcome.to_output()
 ```
 
-Command handlers and lifecycle hooks run between steps, never during one. The default `run()` is the loop that drives the three hooks. Override it to write your own loop against `emit()`, `send()`, `@event`, `self.connected`, and the tracks; `process_input()`, `generate()`, and `process_output()` are then not called. Do that for a loop that is not one step per emit, such as a renderer that emits several times per step or a model that must block on an input.
+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.0 → reactor_runtime-3.7.0}/pyproject.toml

@@ -10,7 +10,7 @@ module-name = [
 namespace = true
 
 [tool.reactor-wire]
-version = "1.20260814.7"
+version = "1.20260929.8"
 
 [tool.ruff]
 line-length = 100
@@ -95,7 +95,7 @@ pythonpath = ["."]
 
 [project]
 name = "reactor-runtime"
-version = "3.6.0"
+version = "3.7.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -109,6 +109,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Typing :: Typed",
 ]
 dependencies = [
@@ -118,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.0 → reactor_runtime-3.7.0}/pyproject.toml.orig

@@ -16,11 +16,11 @@ namespace = true
 # gates the pin against proto/, so a release cannot ship a schema older than the
 # sources it was built from.
 [tool.reactor-wire]
-version = "1.20260814.7"
+version = "1.20260929.8"
 
 [project]
 name = "reactor-runtime"
-version = "3.6.0"
+version = "3.7.0"
 description = "A Python framework for building real-time, interactive video models"
 readme = "README.md"
 license = "Apache-2.0"
@@ -32,6 +32,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Typing :: Typed",
 ]
 dependencies = [
@@ -41,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.0 → 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.0 → 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.0 → reactor_runtime-3.7.0}/src/reactor_runtime/core/fields.py

@@ -13,6 +13,8 @@ graph alongside the neutral value vocabulary.
 
 from __future__ import annotations
 
+import dataclasses
+import inspect
 from dataclasses import dataclass
 from typing import Any, Final
 
@@ -121,6 +123,74 @@ def InputField(  # noqa: N802 — a capitalised factory reads as a type in field
     )
 
 
+def own_annotations(cls: type) -> dict[str, Any]:
+    """Return the annotations *cls* declares itself, none from its bases.
+
+    Goes through :func:`inspect.get_annotations` rather than the class
+    ``__dict__``. From Python 3.14 (PEP 649) a class stores its annotations
+    lazily, behind ``__annotate__``, and a direct dict read finds nothing; the
+    accessor materialises them on every version. Inherited annotations are
+    read from the bases' cached field records, never re-resolved.
+    """
+    return inspect.get_annotations(cls)
+
+
+def inherited_record(cls: type, attribute: str) -> dict[str, Any]:
+    """Merge the field records the bases of *cls* store on themselves.
+
+    A declaration base (``InputState``, ``ModelMessage``, ``Command``) caches
+    the fields each subclass declares in a class-level dict. A subclass starts
+    from this merge, so the fields it inherits are part of its own record. Bases
+    are read from the most distant to the closest, so a nearer base wins a name
+    both declare, and a re-declared name keeps the position the first base gave
+    it, which is the order a dataclass lays inherited fields out in.
+
+    Args:
+        cls: The class being declared.
+        attribute: The name of the record attribute on each base.
+
+    Returns:
+        A new dict; the bases' records are not modified.
+    """
+    merged: dict[str, Any] = {}
+    for base in reversed(cls.__mro__[1:]):
+        merged.update(base.__dict__.get(attribute, {}))
+    return merged
+
+
+def apply_dataclass(cls: type, *, required: list[str], inherits: bool) -> None:
+    """Turn a freshly declared subclass into a dataclass, once.
+
+    A class whose parent is already a dataclass is still converted, so the
+    fields it declares become fields of its own. Its fields are keyword-only
+    when it inherits any, because a dataclass refuses a required field placed
+    after an inherited field with a default, and keyword-only fields have no
+    such order.
+
+    A required field hides any class attribute a parent holds under the same
+    name for the duration of the conversion. The dataclass reads a field's
+    default with ``getattr``, so without this a field declared required again
+    would silently inherit the parent's default. Once the placeholder is
+    removed the parent's attribute is reachable through the subclass again, so
+    ``Child.x`` reads the parent's value while ``dataclasses.fields(Child)``
+    and the field record both say required. The runtime reads defaults from
+    the record, never from the class attribute.
+
+    Args:
+        cls: The class to convert. A class that already carries its own
+            ``__dataclass_fields__`` is left alone.
+        required: The names of the fields *cls* declares without a default.
+        inherits: Whether *cls* inherits fields from a declared base.
+    """
+    if "__dataclass_fields__" in cls.__dict__:
+        return
+    for name in required:
+        setattr(cls, name, dataclasses.MISSING)
+    dataclasses.dataclass(cls, kw_only=inherits)
+    for name in required:
+        delattr(cls, name)
+
+
 def raise_if_default_not_static(owner: str, field_name: str, default: Any) -> None:
     """Raise ``TypeError`` when *default* is a mutable container.
 

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

@@ -20,6 +20,9 @@ from reactor_runtime.core.fields import (
     NO_DEFAULT,
     FieldInfo,
     InputField,
+    apply_dataclass,
+    inherited_record,
+    own_annotations,
     raise_if_default_invalid,
     raise_if_default_not_static,
 )
@@ -62,6 +65,10 @@ class Command:
     invalid defaults at import), turns the class into a dataclass, and caches the
     resolved fields on the class. There is no global registry — each command
     carries its own contract.
+
+    A subclass of a command inherits every field of its parents, and a field it
+    declares again replaces the parent's. The fields a subclass adds are
+    keyword-only in its constructor.
     """
 
     name: ClassVar[str]
@@ -71,8 +78,6 @@ class Command:
     def __init_subclass__(cls, **kwargs: object) -> None:
         super().__init_subclass__(**kwargs)
         _build_command(cls)
-        if not dataclasses.is_dataclass(cls):
-            dataclasses.dataclass(cls)
         if "name" not in cls.__dict__:
             cls.name = pascal_to_snake(cls.__name__)
 
@@ -83,9 +88,9 @@ def _is_classvar(annotation: Any) -> bool:
 
 
 def _build_command(cls: type[Command]) -> None:
-    """Resolve a command class's fields and cache them on it.
+    """Resolve a command class's fields, cache them on it, and make it a dataclass.
 
-    Runs once per subclass, before ``@dataclass`` is applied. Unwraps
+    Runs once per subclass. Starts from the fields the parents declared, unwraps
     ``InputField`` defaults so the dataclass sees plain values, resolves each
     field's :class:`TypeSpec` (the support check), records which fields are
     uploads, and reorders so fields without a default come first — the order a
@@ -103,10 +108,18 @@ def _build_command(cls: type[Command]) -> None:
     # deferring the import until a command is actually declared.
     from reactor_runtime.core.typespec import OptionalSpec, TypeSpec, UploadSpec
 
-    annotations: dict[str, Any] = getattr(cls, "__annotations__", {})
+    def is_upload(spec: TypeSpec) -> bool:
+        resolved = spec.inner if isinstance(spec, OptionalSpec) else spec
+        return isinstance(resolved, UploadSpec)
+
+    fields = inherited_record(cls, "__command_fields__")
+    inherits = bool(fields)
+
+    annotations = own_annotations(cls)
     if not annotations:
-        cls.__command_fields__ = {}
-        cls.__upload_fields__ = frozenset()
+        cls.__command_fields__ = fields
+        cls.__upload_fields__ = frozenset(n for n, f in fields.items() if is_upload(f.spec))
+        apply_dataclass(cls, required=[], inherits=inherits)
         return
 
     try:
@@ -115,14 +128,17 @@ def _build_command(cls: type[Command]) -> None:
         hints = {}
 
     owner = cls.__qualname__
-    fields: dict[str, CommandField] = {}
-    uploads: set[str] = set()
     no_default: list[str] = []
     has_default: list[str] = []
+    class_vars: list[str] = []
 
     for name in list(annotations):
         annotation = hints.get(name, annotations[name])
         if _is_classvar(annotation):
+            # A ClassVar is not a field. Redeclaring an inherited field as one
+            # takes it out of the dataclass, so it leaves the record too.
+            fields.pop(name, None)
+            class_vars.append(name)
             continue
 
         raw = cls.__dict__.get(name, NO_DEFAULT)
@@ -138,8 +154,6 @@ def _build_command(cls: type[Command]) -> None:
             info = raw
             raise_if_default_invalid(owner, name, info.default, info)
             if info.default is NO_DEFAULT:
-                if hasattr(cls, name):
-                    delattr(cls, name)
                 no_default.append(name)
             else:
                 setattr(cls, name, info.default)
@@ -160,15 +174,18 @@ def _build_command(cls: type[Command]) -> None:
                 )
 
         fields[name] = CommandField(spec=spec, info=info)
-        resolved = spec.inner if isinstance(spec, OptionalSpec) else spec
-        if isinstance(resolved, UploadSpec):
-            uploads.add(name)
 
     if no_default and has_default:
-        cls.__annotations__ = {key: annotations[key] for key in no_default + has_default}
+        cls.__annotations__ = {
+            key: annotations[key] for key in no_default + has_default + class_vars
+        }
 
     cls.__command_fields__ = fields
-    cls.__upload_fields__ = frozenset(uploads)
+    # Read off the winning definition of every field, so a name one base
+    # declares as an upload and a nearer base as something else follows the
+    # nearer base.
+    cls.__upload_fields__ = frozenset(n for n, f in fields.items() if is_upload(f.spec))
+    apply_dataclass(cls, required=no_default, inherits=inherits)
 
 
 class EndReason(StrEnum):
@@ -226,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)
@@ -257,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.0 → 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``.
@@ -112,8 +142,11 @@ class RuntimeConfig:
         host: Address the HTTP ingress binds.
         port: Port the HTTP ingress binds.
         grace_period: Seconds a draining session is given to end before stop.
+        exit_timeout: Seconds the orderly shutdown may take, on top of any
+            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
@@ -122,5 +155,7 @@ class RuntimeConfig:
     host: str = "0.0.0.0"
     port: int = 8080
     grace_period: float = 30.0
+    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.0 → 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.0 → 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.