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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reactor-runtime
-Version: 3.7.0
+Version: 3.8.0
 Summary: A Python framework for building real-time, interactive video models
 Author: Reactor
 Author-email: Reactor <team@reactor.inc>

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

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

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

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

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

@@ -33,7 +33,8 @@ from reactor_runtime.core.session import (
     SessionState,
     Transition,
 )
-from reactor_runtime.core.transport import Connection, ConnectionSink
+from reactor_runtime.core.stats import TransportReading, TransportTrackReading
+from reactor_runtime.core.transport import Connection, ConnectionSink, TransportStatsSource
 from reactor_runtime.core.typespec import TypeSpec
 from reactor_runtime.core.values import (
     ClientConnectionStat,
@@ -98,6 +99,9 @@ __all__ = [
     "TrackKind",
     "Transition",
     "TransitionEvent",
+    "TransportReading",
+    "TransportStatsSource",
+    "TransportTrackReading",
     "TypeSpec",
     "UploadedFile",
 ]

reactor_runtime-3.8.0/src/reactor_runtime/core/stats.py

@@ -0,0 +1,55 @@
+"""Readings a transport takes of its own wire.
+
+A transport that measures its wire describes what it measured in these types,
+which follow a client's own stats reading (:class:`~reactor_runtime.core.ClientTrackStat`):
+what is fixed about a track stays a field, and the measurements go in an open
+``metrics`` mapping. Each transport names what it measures, so a new transport
+reports its own measurements without a change here, and a reader holds the same
+shape whichever transport took the reading.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from reactor_runtime.core.values import ClientTrackDirection, TrackKind
+
+
+@dataclass(frozen=True)
+class TransportTrackReading:
+    """What a transport measured of one track on one connection.
+
+    Attributes:
+        track_name: The track the reading is for.
+        kind: The track's kind; ``None`` when the transport does not know it.
+        direction: The track's direction as the client sees it: a model
+            output track is one the client receives.
+        codec: The negotiated codec, e.g. ``"VP9"``, ``"opus"``; empty when
+            the transport has not reported one.
+        metrics: The measurements, by name. Names match a client reading's
+            where both measure the same thing (``"bitrate_bps"``,
+            ``"packets_lost"``, ``"frames_per_second"``), and a measurement the
+            transport has no value for is left out rather than reported as
+            zero.
+    """
+
+    track_name: str
+    kind: TrackKind | None
+    direction: ClientTrackDirection
+    codec: str = ""
+    metrics: Mapping[str, float] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TransportReading:
+    """What a transport measured of one connection's wire at one moment.
+
+    Attributes:
+        metrics: Measurements of the connection as a whole, by name, e.g.
+            ``"connection_rtt_ms"`` or ``"available_outgoing_bitrate_bps"``.
+        tracks: One reading per track the transport measured.
+    """
+
+    metrics: Mapping[str, float] = field(default_factory=dict)
+    tracks: tuple[TransportTrackReading, ...] = ()

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

@@ -4,7 +4,8 @@ The two structural protocols that form the seam between a transport and the
 runner, pointing opposite ways. ``Connection`` carries commands down to one
 client; ``ConnectionSink`` carries facts up from the transport. Both are
 ``Protocol``s, so a transport author or a test fake conforms by shape and
-signaling never reaches the runner.
+signaling never reaches the runner. ``TransportStatsSource`` is an optional
+capability a connection adds when its transport measures its wire.
 """
 
 from __future__ import annotations
@@ -12,6 +13,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Protocol, runtime_checkable
 
+from reactor_runtime.core.stats import TransportReading
 from reactor_runtime.core.values import (
     ClientStatsBatch,
     ConnectionCapabilities,
@@ -95,6 +97,27 @@ class Connection(Protocol):
         """Tear the connection down."""
 
 
+@runtime_checkable
+class TransportStatsSource(Protocol):
+    """A connection whose transport samples statistics about its own wire.
+
+    Optional, beside :class:`Connection`: a transport that measures its wire
+    implements it on its connections, and a reader checks for it with
+    ``isinstance`` before reading. A connection without it is a connection
+    with nothing to report, not an error, so a transport that predates it
+    keeps working unchanged.
+    """
+
+    @property
+    def latest_reading(self) -> TransportReading | None:
+        """The most recent reading of this connection's wire.
+
+        ``None`` before the transport has taken its first. The reading is
+        replaced as the transport takes new ones, so reading it never waits on
+        the wire.
+        """
+
+
 @runtime_checkable
 class ConnectionSink(Protocol):
     """The transport-to-runner upward channel — the facts-up half.

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

@@ -410,12 +410,17 @@ class MediaChunk:
         wait: Whether a consumer with a bounded queue should make the producer
             wait for room (backpressure, throttling the model to the playout
             rate) instead of dropping the overflow.
+        session: The number of the session the model was in when it emitted
+            the chunk, counted on the model's side, or ``None`` when the
+            emitter does not count sessions. A consumer compares it with its
+            own count to tell a late chunk of an earlier session apart.
     """
 
     bundle: MediaBundle
     fps: float
     n_frames: int = 1
     wait: bool = False
+    session: int | None = None
 
     def frames(self) -> list[MediaBundle]:
         """Split the chunk into one single-frame bundle per carried frame."""

{reactor_runtime-3.7.0 → reactor_runtime-3.8.0}/src/reactor_runtime/interface/app/reactor_app.py

@@ -74,6 +74,7 @@ from reactor_runtime.interface.events.decorators import (
 from reactor_runtime.interface.events.errors import ApplicationError, CommandError
 from reactor_runtime.interface.events.messages import ModelMessage
 from reactor_runtime.interface.internal.reactor_core import (
+    STEP_SESSION,
     CommandEnvelope,
     ReactorCore,
     RequestId,
@@ -353,7 +354,13 @@ class ReactorApp(ReactorCore):
                         rate = None
                         if report.output is not None:
                             pace = None if fps_pinned else outcome.elapsed
-                            await self.emit(report.output, compute_time=pace)
+                            # The media is the step's, so it carries the
+                            # session the step began in, as the report does.
+                            token = STEP_SESSION.set(session)
+                            try:
+                                await self.emit(report.output, compute_time=pace)
+                            finally:
+                                STEP_SESSION.reset(token)
                             frames = self._to_bundle(report.output).frame_count
                             rate = self._playout_rate(frames, pace)
                         self._report_step(report, session, rate)

{reactor_runtime-3.7.0 → reactor_runtime-3.8.0}/src/reactor_runtime/interface/internal/reactor_core.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import contextvars
 import json
 import logging
 import threading
@@ -50,6 +51,17 @@ RequestId = str
 
 _Holder = TypeVar("_Holder")
 
+STEP_SESSION: contextvars.ContextVar[int | None] = contextvars.ContextVar(
+    "reactor_step_session", default=None
+)
+"""The session the step being emitted began in, set by the step loop around its emit.
+
+A step reports the session it began in, and its media is stamped with the
+same number, so both count toward one session even when the session changes
+while the step emits. An emit made outside a step leaves it unset and is
+stamped with the session the model is in when it emits.
+"""
+
 BroadcastSink = Callable[[ModelMessage], None]
 
 AddressedSink = Callable[[ConnId, "ModelMessage | CommandFailure | None", RequestId | None], None]
@@ -167,7 +179,14 @@ class OutputStream:
         fps = core._playout_rate(n_frames, compute_time)
         core._last_emit_fps = fps
         if core._out_media is not None:
-            chunk = MediaChunk(bundle=bundle, fps=fps, n_frames=n_frames, wait=not drop)
+            session = STEP_SESSION.get()
+            chunk = MediaChunk(
+                bundle=bundle,
+                fps=fps,
+                n_frames=n_frames,
+                wait=not drop,
+                session=core._sessions_started if session is None else session,
+            )
             await asyncio.to_thread(core._out_media, chunk)
         await asyncio.sleep(0)
 

{reactor_runtime-3.7.0 → reactor_runtime-3.8.0}/src/reactor_runtime/runner/connection_manager.py

@@ -48,6 +48,8 @@ from reactor_runtime.core import (
     ConnId,
     MediaChunk,
     SessionEvent,
+    TransportReading,
+    TransportStatsSource,
 )
 from reactor_runtime.log import get_logger
 from reactor_runtime.protocol import Channel, ProtocolVersion
@@ -139,6 +141,20 @@ class ConnectionManager:
         """The number of connections currently registered."""
         return len(self._by_id)
 
+    def transport_readings(self) -> list[tuple[ConnId, TransportReading]]:
+        """The latest transport reading of every connection that has one.
+
+        A connection whose transport has not taken a reading yet, or does not
+        measure its wire (it is not a :class:`TransportStatsSource`), is left
+        out.
+        """
+        return [
+            (cid, reading)
+            for cid, conn in self._by_id.items()
+            if isinstance(conn, TransportStatsSource)
+            and (reading := conn.latest_reading) is not None
+        ]
+
     def new_conn_id(self) -> ConnId:
         """Mint a fresh random connection id, unique within the session.
 

{reactor_runtime-3.7.0 → reactor_runtime-3.8.0}/src/reactor_runtime/runner/runner.py

@@ -51,6 +51,7 @@ from reactor_runtime.core import (
     SessionState,
     StartingInputApplied,
     TrackDirection,
+    TrackKind,
     Transition,
     TransitionEvent,
     TypeSpec,
@@ -73,10 +74,11 @@ from reactor_runtime.metrics import (
 )
 from reactor_runtime.protocol import Channel, Codec, ProtocolVersion, select
 from reactor_runtime.recording import ClipResult, Recorder, RecorderError
-from reactor_runtime.runner import client_stats
+from reactor_runtime.runner import client_stats, runtime_stats
 from reactor_runtime.runner.client_stats import ClientStatsGate
 from reactor_runtime.runner.connection_manager import ConnectionManager
 from reactor_runtime.runner.offer_epochs import OfferEpochs
+from reactor_runtime.runner.runtime_stats import ModelOutput
 from reactor_runtime.runner.session_start import (
     InvalidSessionStartError,
     SessionStart,
@@ -241,6 +243,11 @@ class Runner(ServiceComponent, ConnectionSink):
         self._sm.on_transition(self._metrics_recorder.observe)
         self._command_metrics = CommandMetrics(self._metrics)
         self._model_metrics = ModelMetrics(self._metrics)
+        # The same emissions, counted per session for the runtime's own stats.
+        self._model_output = ModelOutput()
+        self._output_kinds: dict[str, TrackKind] = {}
+        self._runtime_stats_interval = runtime_stats.INTERVAL_SECONDS
+        self._runtime_stats_task: asyncio.Task[None] | None = None
         self._events = EventStream()
         self._uploads = UploadStore()
         self._recorder = Recorder(
@@ -377,9 +384,13 @@ class Runner(ServiceComponent, ConnectionSink):
         self._model_metrics.loaded(since=started_at)
         self._bridge = bridge
         self._command_metrics.declare(contract.commands)
-        self._model_metrics.declare(
-            name for name, info in contract.tracks.items() if info.direction is TrackDirection.OUT
-        )
+        self._output_kinds = {
+            name: info.kind
+            for name, info in contract.tracks.items()
+            if info.direction is TrackDirection.OUT
+        }
+        self._model_metrics.declare(self._output_kinds.keys())
+        self._model_output.declare(self._output_kinds.keys())
         self._sm.send(SessionEvent.INITIALIZATION_SUCCESS)
         logger.info(
             "model loaded; session ready",
@@ -414,6 +425,11 @@ class Runner(ServiceComponent, ConnectionSink):
         thing released even when ``stop`` races a session that is still closing.
         """
         self._cancel_orphan_timeout()
+        task = self._cancel_runtime_stats()
+        if task is not None:
+            # Waits for the reporter to finish without raising its
+            # cancellation, which it never caught if it had not started yet.
+            await asyncio.wait([task])
         await self._drain_teardown()
         await asyncio.to_thread(self._recorder.close)
         if self._step_store is not None:
@@ -1295,6 +1311,10 @@ class Runner(ServiceComponent, ConnectionSink):
         """
         for track in chunk.bundle.tracks:
             self._model_metrics.emitted(track, chunk.n_frames)
+            # A chunk the model emitted for an earlier session (from its
+            # session-end hook, say, after the next session started) still
+            # plays out, but it is not this session's output.
+            self._model_output.emitted(track, chunk.n_frames, chunk.session)
         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
@@ -1522,6 +1542,7 @@ class Runner(ServiceComponent, ConnectionSink):
         entered = transition.from_state is not transition.to_state
         if entered:
             self._reset_orphan_timeout(transition.to_state)
+            self._sync_runtime_stats(transition.to_state)
         if entered and transition.to_state is SessionState.CLOSING and self._loop is not None:
             reason = transition.detail.get("reason", EndReason.STOPPED)
             close_reason = transition.detail.get("close_reason", "")
@@ -1654,6 +1675,9 @@ class Runner(ServiceComponent, ConnectionSink):
         """
         if transition.is_session_start:
             self._sessions_posted += 1
+            # Before the model hears of the session: from then on its thread
+            # can emit, and every frame it emits for this session counts.
+            self._model_output.reset(self._sessions_posted)
             bridge.dispatch_reactor_event(
                 SessionStarted(
                     self._session_id,
@@ -1714,6 +1738,63 @@ class Runner(ServiceComponent, ConnectionSink):
             return
         self._sm.send(SessionEvent.TIMEOUT, reason=EndReason.TIMED_OUT)
 
+    # -- runtime stats --------------------------------------------------------
+
+    def _sync_runtime_stats(self, state: SessionState) -> None:
+        """Run the runtime stats reporter while a session runs, and only then."""
+        if state in _RUNNING_STATES:
+            if self._runtime_stats_task is None and self._loop is not None:
+                self._runtime_stats_task = self._loop.create_task(self._report_runtime_stats())
+        else:
+            self._cancel_runtime_stats()
+
+    def _cancel_runtime_stats(self) -> asyncio.Task[None] | None:
+        """Cancel the runtime stats reporter, returning its task to await, if one ran."""
+        task, self._runtime_stats_task = self._runtime_stats_task, None
+        if task is not None:
+            task.cancel()
+        return task
+
+    async def _report_runtime_stats(self) -> None:
+        """Journal a ``runtime_stats`` reading on a fixed cadence until cancelled.
+
+        A reading that fails to build is logged and skipped rather than ending
+        the reporter: stats are best-effort, so one bad sample must not stop
+        them for the rest of the session.
+        """
+        try:
+            while True:
+                await asyncio.sleep(self._runtime_stats_interval)
+                try:
+                    self._journal_runtime_stats()
+                except Exception:
+                    logger.warning("runtime stats reading failed", exc_info=True)
+        except asyncio.CancelledError:
+            return
+
+    def _journal_runtime_stats(self) -> None:
+        """Journal the runtime's own view of the session as one ``metric`` fact.
+
+        The fact is a self-loop named ``runtime_stats``, the runtime's
+        counterpart to a client's ``client_stats``: what the model emitted on
+        each output track over the last window, and each connection's latest
+        transport reading, in the metrics its transport names. Shaped by
+        :func:`runtime_stats.to_detail`.
+        """
+        if self._sm.current_state not in _RUNNING_STATES:
+            return
+        self._sm.send(
+            SessionEvent.METRIC,
+            name="runtime_stats",
+            session_id=self._recording_id,
+            **runtime_stats.to_detail(
+                observed_at_ms=int(time.time() * 1000),
+                model_output=self._model_output.take(),
+                output_kinds=self._output_kinds,
+                readings=self._connections.transport_readings(),
+            ),
+        )
+
     async def _close_session(self, reason: EndReason) -> None:
         """Close the session's connections, then mark cleanup complete.
 

reactor_runtime-3.8.0/src/reactor_runtime/runner/runtime_stats.py

@@ -0,0 +1,204 @@
+"""Count what the model emits during a session, for the runtime's own stats.
+
+The runtime reports its own view of a session alongside what clients report
+about theirs. The model's output is the part of that view no transport sees:
+how many frames it produced on each output track and how evenly it produced
+them. :class:`ModelOutput` keeps those counts for the session that is running.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+from reactor_runtime.core import (
+    ClientTrackDirection,
+    ConnId,
+    TrackKind,
+    TransportReading,
+    TransportTrackReading,
+)
+
+
+class ModelOutput:
+    """Per-session counts of the frames the model emitted, by output track.
+
+    Emissions are counted from the thread the model emits on, and a reading is
+    taken from the runtime's loop, so every access holds a lock. A reading
+    covers the window since the previous one: the frame rate and the longest
+    gap are what that window saw, while the frame total runs for the whole
+    session. :meth:`reset` starts a new session from zero, and an emission
+    stamped with another session's number is left out of its count.
+    """
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._tracks: tuple[str, ...] = ()
+        self._frames: dict[str, int] = {}
+        self._window_frames: dict[str, int] = {}
+        self._last_emit: dict[str, float] = {}
+        self._longest_gap: dict[str, float] = {}
+        self._window_start = clock()
+        self._session: int | None = None
+
+    def declare(self, tracks: Iterable[str]) -> None:
+        """Name the output tracks the model declares.
+
+        A declared track the model has emitted nothing on reads zero frames
+        rather than being absent, which tells a silent track apart from a
+        track this model does not have.
+        """
+        with self._lock:
+            self._tracks = tuple(tracks)
+
+    def reset(self, session: int | None = None) -> None:
+        """Start counting *session* from zero.
+
+        The gap between the last frame of one session and the first of the
+        next is the model waiting for a client, so no gap crosses the reset.
+
+        Args:
+            session: The number of the session that starts, as the model counts
+                them. From here on, an emission stamped with any other number
+                belongs to another session and is not counted.
+        """
+        with self._lock:
+            self._session = session
+            self._frames.clear()
+            self._window_frames.clear()
+            self._last_emit.clear()
+            self._longest_gap.clear()
+            self._window_start = self._clock()
+
+    def emitted(self, track: str, frames: int, session: int | None = None) -> None:
+        """Count one emission of *frames* frames on *track*.
+
+        Counted in frames because one emission can carry a batch of them. The
+        gap is measured between emissions, undivided by the batch, so a model
+        that emits a batch at a time has the play-out length of a batch as its
+        normal gap and a stall shows above it.
+
+        Args:
+            track: The output track the frames were emitted on.
+            frames: How many frames the emission carried.
+            session: The number of the session the model emitted them in, or
+                ``None`` when the emitter does not count sessions. An emission
+                of a session other than the one :meth:`reset` started is not
+                counted. The check runs under the same lock as the reset, so
+                an emission is counted for the session that is current when
+                it lands.
+        """
+        with self._lock:
+            if session is not None and self._session is not None and session != self._session:
+                return
+            # Read under the lock, so concurrent emissions store their times
+            # in the order they were taken.
+            now = self._clock()
+            previous = self._last_emit.get(track)
+            if previous is not None:
+                gap = now - previous
+                if gap > self._longest_gap.get(track, 0.0):
+                    self._longest_gap[track] = gap
+            self._last_emit[track] = now
+            self._frames[track] = self._frames.get(track, 0) + frames
+            self._window_frames[track] = self._window_frames.get(track, 0) + frames
+
+    def take(self) -> dict[str, dict[str, float]]:
+        """Read every output track's counts and start the next window.
+
+        Returns:
+            Per track name, its metrics: ``frames_emitted`` (the session's
+            total), ``frames_per_second`` (over the window), and, once the track
+            has emitted, ``max_emit_interval_ms`` (the longest gap the window
+            saw, when it saw two emissions) and ``ms_since_last_emit``, which
+            shows a stall that is still going before the next emission ends it.
+        """
+        with self._lock:
+            now = self._clock()
+            elapsed = now - self._window_start
+            names = dict.fromkeys((*self._tracks, *self._frames))
+            readings: dict[str, dict[str, float]] = {}
+            for name in names:
+                metrics: dict[str, float] = {
+                    "frames_emitted": float(self._frames.get(name, 0)),
+                }
+                if elapsed > 0:
+                    metrics["frames_per_second"] = self._window_frames.get(name, 0) / elapsed
+                if name in self._longest_gap:
+                    metrics["max_emit_interval_ms"] = self._longest_gap[name] * 1000.0
+                last = self._last_emit.get(name)
+                if last is not None:
+                    metrics["ms_since_last_emit"] = (now - last) * 1000.0
+                readings[name] = metrics
+            self._window_frames.clear()
+            self._longest_gap.clear()
+            self._window_start = now
+            return readings
+
+
+INTERVAL_SECONDS = 5.0
+"""How often the runner journals a ``runtime_stats`` reading during a session."""
+
+
+def to_detail(
+    *,
+    observed_at_ms: int,
+    model_output: Mapping[str, Mapping[str, float]],
+    output_kinds: Mapping[str, TrackKind],
+    readings: Iterable[tuple[ConnId, TransportReading]],
+) -> dict[str, Any]:
+    """Shape one ``runtime_stats`` reading as a ``metric`` fact's detail.
+
+    The shape follows a ``client_stats`` reading's, so a consumer reads both
+    the same way: tracks carry ``track_name``, ``kind``, ``direction`` (as the
+    client sees the track) and ``codec``, beside their ``metrics``. A metric
+    value that isn't a finite number is left out, since JSON has no way to
+    carry it.
+
+    Args:
+        observed_at_ms: When the reading was taken, in Unix milliseconds.
+        model_output: Per output track, the metrics :meth:`ModelOutput.take`
+            returned.
+        output_kinds: The kind of each output track the model declares.
+        readings: Each connection's latest transport reading.
+    """
+    return {
+        "observed_at": observed_at_ms,
+        "model_output": [
+            {
+                "track_name": name,
+                "kind": str(output_kinds[name]) if name in output_kinds else "",
+                # What the model sends, the client receives.
+                "direction": str(ClientTrackDirection.RECVONLY),
+                "metrics": _finite(metrics),
+            }
+            for name, metrics in model_output.items()
+        ],
+        "connection_stats": [
+            {
+                "conn_id": int(cid),
+                "metrics": _finite(reading.metrics),
+                "track_stats": [_track(track) for track in reading.tracks],
+            }
+            for cid, reading in readings
+        ],
+    }
+
+
+def _track(track: TransportTrackReading) -> dict[str, Any]:
+    return {
+        "track_name": track.track_name,
+        "kind": str(track.kind) if track.kind is not None else "",
+        "direction": str(track.direction),
+        "codec": track.codec,
+        "metrics": _finite(track.metrics),
+    }
+
+
+def _finite(metrics: Mapping[str, float]) -> dict[str, float]:
+    """Keep the values JSON can carry: finite numbers."""
+    return {name: float(value) for name, value in metrics.items() if math.isfinite(value)}

{reactor_runtime-3.7.0 → reactor_runtime-3.8.0}/src/reactor_runtime/transport/webrtc/connection.py

@@ -25,12 +25,14 @@ from reactor_runtime.core import (
     TrackDirection,
     TrackInfo,
     TrackKind,
+    TransportReading,
 )
 from reactor_runtime.protocol import Channel, ProtocolVersion
 from reactor_runtime.transport.webrtc.client_stats import read_client_stats
 from reactor_runtime.transport.webrtc.config import WebRtcConfig
 from reactor_runtime.transport.webrtc.pacer import MediaPacer
 from reactor_runtime.transport.webrtc.peer import WebRTCPeer, WebRtcPeerFactory
+from reactor_runtime.transport.webrtc.reading import transport_reading
 from reactor_runtime.transport.webrtc.signaling import IceCandidate, SdpAnswer, SdpOffer, TrackMap
 from reactor_runtime.transport.webrtc.stats import OutboundMediaHealth, PeerStats
 
@@ -105,6 +107,8 @@ class WebRTCConnection:
         self._watchdog_task: asyncio.Task[None] | None = None
         self._stats_task: asyncio.Task[None] | None = None
         self._latest_stats: PeerStats | None = None
+        self._latest_reading: TransportReading | None = None
+        self._sampled_at: float | None = None
         # The counters as of the previous sample, so each report is what the
         # window cost rather than what the connection has cost since it opened.
         self._reported_media = OutboundMediaHealth()
@@ -152,6 +156,15 @@ class WebRTCConnection:
         """The most recent stats sample, or ``None`` before the first cycle."""
         return self._latest_stats
 
+    @property
+    def latest_reading(self) -> TransportReading | None:
+        """The most recent stats sample as a neutral reading, or ``None`` before the first.
+
+        Each track's bitrate is measured between this sample and the one before
+        it, so the reading of a connection's first sample has none.
+        """
+        return self._latest_reading
+
     @property
     def protocol_version(self) -> ProtocolVersion:
         """The wire codec the connection negotiated, held by its peer."""
@@ -365,7 +378,11 @@ class WebRTCConnection:
                     media=replace(stats.media, dropped_frames=self._pacer.dropped_frames),
                 )
                 self._report_media_health(stats.media)
+                now = time.monotonic()
+                elapsed = now - self._sampled_at if self._sampled_at is not None else None
+                self._latest_reading = transport_reading(stats, self._latest_stats, elapsed)
                 self._latest_stats = stats
+                self._sampled_at = now
                 if self._on_stats is not None:
                     self._on_stats(stats)
         except asyncio.CancelledError: