openrtc 0.2.3__tar.gz → 0.3.0__tar.gz

{openrtc-0.2.3 → openrtc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrtc
-Version: 0.2.3
+Version: 0.3.0
 Summary: Run multiple LiveKit voice agents in a single shared worker process.
 Project-URL: Homepage, https://github.com/mahimailabs/openrtc
 Project-URL: Repository, https://github.com/mahimailabs/openrtc
@@ -443,6 +443,27 @@ Pass instantiated provider objects through to `livekit-agents` unchanged, for ex
 
 If you pass strings such as `openai/gpt-4.1-mini`, OpenRTC leaves them as-is and the LiveKit runtime interprets them for your deployment.
 
+## Session observers
+
+Attach external telemetry to every session without subclassing or touching OpenRTC internals. Any object with two async methods is a `SessionObserver` (structural typing, no base class):
+
+```python
+from openrtc import AgentPool, SessionInfo, SessionOutcome
+
+
+class LoggingObserver:
+    async def on_session_start(self, info: SessionInfo, session: object) -> None:
+        print(f"live: {info.agent_name} in {info.room_name}")
+
+    async def on_session_end(self, info: SessionInfo, outcome: SessionOutcome) -> None:
+        print(f"done: {info.agent_name} -> {outcome.status.value}")
+
+
+pool = AgentPool(observers=[LoggingObserver()])  # or pool.add_observer(...)
+```
+
+`on_session_start` receives the live `AgentSession`, which is where you subscribe to its metrics. `on_session_end` receives the terminal outcome (`SUCCESS`, `FAILED`, or `CANCELLED`). Observer calls are isolated: a raising or slow observer is logged and skipped, never crashing the session. In `process` isolation mode an observer must be picklable, so build live resources lazily on the first `on_session_start`.
+
 ## CLI and TUI
 
 Install `openrtc[cli]` to get `openrtc` on your PATH. Subcommands follow the LiveKit Agents CLI shape (`dev`, `start`, `console`, `connect`, `download-files`), plus `list` and `tui`. For most commands you can pass the agents directory (or, for `tui`, the metrics JSONL file) as the first path argument instead of `--agents-dir` / `--watch`.

{openrtc-0.2.3 → openrtc-0.3.0}/README.md

@@ -411,6 +411,27 @@ Pass instantiated provider objects through to `livekit-agents` unchanged, for ex
 
 If you pass strings such as `openai/gpt-4.1-mini`, OpenRTC leaves them as-is and the LiveKit runtime interprets them for your deployment.
 
+## Session observers
+
+Attach external telemetry to every session without subclassing or touching OpenRTC internals. Any object with two async methods is a `SessionObserver` (structural typing, no base class):
+
+```python
+from openrtc import AgentPool, SessionInfo, SessionOutcome
+
+
+class LoggingObserver:
+    async def on_session_start(self, info: SessionInfo, session: object) -> None:
+        print(f"live: {info.agent_name} in {info.room_name}")
+
+    async def on_session_end(self, info: SessionInfo, outcome: SessionOutcome) -> None:
+        print(f"done: {info.agent_name} -> {outcome.status.value}")
+
+
+pool = AgentPool(observers=[LoggingObserver()])  # or pool.add_observer(...)
+```
+
+`on_session_start` receives the live `AgentSession`, which is where you subscribe to its metrics. `on_session_end` receives the terminal outcome (`SUCCESS`, `FAILED`, or `CANCELLED`). Observer calls are isolated: a raising or slow observer is logged and skipped, never crashing the session. In `process` isolation mode an observer must be picklable, so build live resources lazily on the first `on_session_start`.
+
 ## CLI and TUI
 
 Install `openrtc[cli]` to get `openrtc` on your PATH. Subcommands follow the LiveKit Agents CLI shape (`dev`, `start`, `console`, `connect`, `download-files`), plus `list` and `tui`. For most commands you can pass the agents directory (or, for `tui`, the metrics JSONL file) as the first path argument instead of `--agents-dir` / `--watch`.

{openrtc-0.2.3 → openrtc-0.3.0}/docs/changelog.md

@@ -59,6 +59,14 @@ Changes that have landed on `main` but have not yet been tagged for release.
   `livekit-agents` and is allowed to fail.
 - New `docker-compose.test.yml` + `tests/integration/conftest.py`
   fixture harness for local and CI integration runs.
+- Public `SessionObserver` protocol (`openrtc.SessionObserver`,
+  `SessionInfo`, `SessionOutcome`, `SessionStatus`) plus
+  `AgentPool(observers=[...])` and `AgentPool.add_observer(...)`. External
+  telemetry attaches to each live session through the pool:
+  `on_session_start` hands the live `AgentSession`, `on_session_end` the
+  terminal outcome. Observer faults are isolated (logged and skipped,
+  bounded by a timeout) and never crash the session. Additive and backward
+  compatible; the built-in metrics store is unchanged.
 
 **Changed**
 
@@ -147,6 +155,14 @@ contributor onboarding matches what's in the repo.
 
 <!-- releases -->
 
+## [0.2.3] - 2026-05-30
+
+### Added
+- Day-one savings readout: each worker logs the fleet-collapse idle-baseline memory saved (N agents in one shared-prewarm worker vs N separate livekit-agents workers) once at startup, for both `pool.run()` and `openrtc dev/start`, with no `--dashboard` flag. The line claims only idle baseline saved (not per-session density), stays neutral for a single agent, degrades gracefully when RSS is unavailable, and names its equal-baseline assumption.
+- README: a one-screen "Migrating from livekit-agents" recipe (N per-agent workers to one AgentPool).
+
+---
+
 ## [0.2.2] - 2026-05-30
 
 ### Fixed
@@ -177,7 +193,7 @@ contributor onboarding matches what's in the repo.
 ## What's Changed
 * Feat: light websocket by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/30
 * docs: bring docs/ in sync with v0.1 surface by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/35
-* Feat: struc refac by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/36
+* Feat: structural refactor by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/36
 * Feat/coroutine pool by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/37
 * Feat/coroutine pool prod by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/38