openrtc 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrtc
-Version: 0.2.2
+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
@@ -203,6 +203,76 @@ If a module has no `@agent_config`, the agent name defaults to the filename stem
 
 Discovered agents work with `livekit dev` and spawn-based workers on macOS. For `add()`, define agent classes at module scope so worker reload can import them.
 
+## Migrating from livekit-agents
+
+Already running one or more `livekit-agents` workers? Each is its own process that
+loads the same VAD and turn-detector models. Collapse them into one `AgentPool`
+worker without changing your agents.
+
+**Before** (one worker per agent, N processes):
+
+```python
+# restaurant_worker.py  (plus a near-identical dental_worker.py, support_worker.py, ...)
+from livekit import agents
+from livekit.agents import Agent, AgentSession
+from livekit.plugins import openai, silero
+
+
+class RestaurantAgent(Agent):
+    def __init__(self) -> None:
+        super().__init__(instructions="You help callers book tables.")
+
+
+async def entrypoint(ctx: agents.JobContext) -> None:
+    session = AgentSession(
+        stt=openai.STT(), llm=openai.LLM(), tts=openai.TTS(), vad=silero.VAD.load()
+    )
+    await session.start(agent=RestaurantAgent(), room=ctx.room)
+    await ctx.connect()
+
+
+if __name__ == "__main__":
+    agents.cli.run_app(agents.WorkerOptions(entrypoint_fnc=entrypoint))
+```
+
+**After** (one worker, N agents, one shared prewarm):
+
+```python
+# worker.py
+from livekit.agents import Agent
+from livekit.plugins import openai
+from openrtc import AgentPool
+
+
+class RestaurantAgent(Agent):  # unchanged
+    def __init__(self) -> None:
+        super().__init__(instructions="You help callers book tables.")
+
+
+class DentalAgent(Agent):  # unchanged
+    def __init__(self) -> None:
+        super().__init__(instructions="You help callers manage appointments.")
+
+
+pool = AgentPool(default_stt=openai.STT(), default_llm=openai.LLM(), default_tts=openai.TTS())
+pool.add("restaurant", RestaurantAgent)
+pool.add("dental", DentalAgent)
+pool.run()
+```
+
+Your `Agent` subclasses, tools, and provider objects are unchanged. You delete the
+per-worker boilerplate (`entrypoint`, `AgentSession` wiring, `cli.run_app`) and
+register the agents on one pool; OpenRTC owns prewarm, routing, and per-call
+session construction. On the first run the worker logs the win, for example:
+
+```text
+OpenRTC: 2 agents in 1 worker (baseline ~410 MB). 2 separate livekit-agents
+workers would cost ~820 MB; sharing one worker saves ~410 MB of idle baseline
+(assumes equal per-worker baselines).
+```
+
+See [Routing](#routing) for how each incoming call resolves to one registered agent.
+
 ## Memory: before and after
 
 Assume an illustrative **~400 MB** idle baseline per worker for the shared stack (VAD, turn detector, and similar). Your measured RSS will differ by provider, model, and OS.
@@ -373,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.2 → openrtc-0.3.0}/README.md

@@ -171,6 +171,76 @@ If a module has no `@agent_config`, the agent name defaults to the filename stem
 
 Discovered agents work with `livekit dev` and spawn-based workers on macOS. For `add()`, define agent classes at module scope so worker reload can import them.
 
+## Migrating from livekit-agents
+
+Already running one or more `livekit-agents` workers? Each is its own process that
+loads the same VAD and turn-detector models. Collapse them into one `AgentPool`
+worker without changing your agents.
+
+**Before** (one worker per agent, N processes):
+
+```python
+# restaurant_worker.py  (plus a near-identical dental_worker.py, support_worker.py, ...)
+from livekit import agents
+from livekit.agents import Agent, AgentSession
+from livekit.plugins import openai, silero
+
+
+class RestaurantAgent(Agent):
+    def __init__(self) -> None:
+        super().__init__(instructions="You help callers book tables.")
+
+
+async def entrypoint(ctx: agents.JobContext) -> None:
+    session = AgentSession(
+        stt=openai.STT(), llm=openai.LLM(), tts=openai.TTS(), vad=silero.VAD.load()
+    )
+    await session.start(agent=RestaurantAgent(), room=ctx.room)
+    await ctx.connect()
+
+
+if __name__ == "__main__":
+    agents.cli.run_app(agents.WorkerOptions(entrypoint_fnc=entrypoint))
+```
+
+**After** (one worker, N agents, one shared prewarm):
+
+```python
+# worker.py
+from livekit.agents import Agent
+from livekit.plugins import openai
+from openrtc import AgentPool
+
+
+class RestaurantAgent(Agent):  # unchanged
+    def __init__(self) -> None:
+        super().__init__(instructions="You help callers book tables.")
+
+
+class DentalAgent(Agent):  # unchanged
+    def __init__(self) -> None:
+        super().__init__(instructions="You help callers manage appointments.")
+
+
+pool = AgentPool(default_stt=openai.STT(), default_llm=openai.LLM(), default_tts=openai.TTS())
+pool.add("restaurant", RestaurantAgent)
+pool.add("dental", DentalAgent)
+pool.run()
+```
+
+Your `Agent` subclasses, tools, and provider objects are unchanged. You delete the
+per-worker boilerplate (`entrypoint`, `AgentSession` wiring, `cli.run_app`) and
+register the agents on one pool; OpenRTC owns prewarm, routing, and per-call
+session construction. On the first run the worker logs the win, for example:
+
+```text
+OpenRTC: 2 agents in 1 worker (baseline ~410 MB). 2 separate livekit-agents
+workers would cost ~820 MB; sharing one worker saves ~410 MB of idle baseline
+(assumes equal per-worker baselines).
+```
+
+See [Routing](#routing) for how each incoming call resolves to one registered agent.
+
 ## Memory: before and after
 
 Assume an illustrative **~400 MB** idle baseline per worker for the shared stack (VAD, turn detector, and similar). Your measured RSS will differ by provider, model, and OS.
@@ -341,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.2 → 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,12 +155,35 @@ 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
+- Coroutine mode now establishes the LiveKit job context for the session duration, so `get_job_context()` works inside agents and sessions and shutdown callbacks run (MAH-158).
+- Coroutine sessions are held open until the call ends (room disconnect or `ctx.shutdown()`) instead of being marked SUCCESS when the entrypoint returns, so `max_concurrent_sessions` backpressure and runtime session counts are accurate (MAH-160).
+
+### Added
+- Real-audio throughput benchmark (`tests/benchmarks/throughput.py`) reporting steady-state event-loop p99 vs session count, separating startup from steady state (MAH-163).
+- `examples/density_demo.py`: a no-server demo comparing process-per-session vs coroutine-pool resident memory.
+
+### Changed
+- The coroutine real-room integration test is now a correctness gate (job context plus no-failure); throughput moved to the dedicated benchmark.
+
+---
+
 ## [0.2.1] - 2026-05-06
 
-## What's Changed
-* [v0.2.1] File watcher infrastructure for agent code (MAH-80) by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/39
-
-
+## What's Changed
+* [v0.2.1] File watcher infrastructure for agent code (MAH-80) by @mahimairaja in https://github.com/mahimailabs/openrtc-runtime/pull/39
+
+
 **Full Changelog**: https://github.com/mahimailabs/openrtc-runtime/compare/v0.1.0...v0.2.1
 
 ---
@@ -162,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