openrtc 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrtc
-Version: 0.2.2
+Version: 0.2.3
 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.

{openrtc-0.2.2 → openrtc-0.2.3}/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.

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

@@ -147,12 +147,27 @@ contributor onboarding matches what's in the repo.
 
 <!-- releases -->
 
+## [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
 
 ---

{openrtc-0.2.2 → openrtc-0.2.3}/src/openrtc/execution/prewarm.py

@@ -10,13 +10,21 @@ Adding a new shared resource means adding it to ``_prewarm_worker``.
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING, Any
 
 from livekit.agents import JobProcess
 
+from openrtc.observability.metrics import (
+    format_prewarm_savings,
+    process_resident_set_bytes,
+)
+
 if TYPE_CHECKING:
     from openrtc.core.pool import _PoolRuntimeState
 
+logger = logging.getLogger("openrtc.execution.prewarm")
+
 
 def _prewarm_worker(
     runtime_state: _PoolRuntimeState,
@@ -29,6 +37,16 @@ def _prewarm_worker(
     proc.userdata["vad"] = silero_module.VAD.load()
     proc.userdata["turn_detection_factory"] = turn_detector_model
 
+    # Day-one payoff: surface the fleet-collapse idle-baseline saving once per
+    # worker, post-prewarm (RSS is now the per-worker baseline), so existing
+    # livekit-agents users see the win on first run without --dashboard.
+    logger.info(
+        format_prewarm_savings(
+            agent_count=len(runtime_state.agents),
+            shared_worker_bytes=process_resident_set_bytes(),
+        )
+    )
+
 
 def _load_shared_runtime_dependencies() -> tuple[Any, type[Any]]:
     """Load the optional LiveKit runtime dependencies used during prewarm."""

{openrtc-0.2.2 → openrtc-0.2.3}/src/openrtc/observability/metrics.py

@@ -352,6 +352,43 @@ def estimate_shared_worker_savings(
     )
 
 
+def format_prewarm_savings(*, agent_count: int, shared_worker_bytes: int | None) -> str:
+    """One honest, human-readable line about the shared-worker idle-baseline win.
+
+    Emitted once per worker at prewarm so the fleet-collapse saving is visible on
+    first run. It claims only idle-baseline memory saved by hosting N per-agent
+    workers as one shared worker; it never implies per-session density or a speed
+    multiple, and it names its equal-baseline assumption whenever it shows a
+    number. Stays graceful when RSS is unavailable (e.g. Windows).
+    """
+    estimate = estimate_shared_worker_savings(
+        agent_count=agent_count, shared_worker_bytes=shared_worker_bytes
+    )
+    agents = "1 agent" if agent_count == 1 else f"{agent_count} agents"
+
+    if estimate.shared_worker_bytes is None or estimate.estimated_saved_bytes is None:
+        return (
+            f"OpenRTC: {agents} in 1 worker; per-worker memory estimate "
+            "unavailable on this platform."
+        )
+
+    baseline_mb = estimate.shared_worker_bytes / (1024 * 1024)
+    if agent_count <= 1:
+        return (
+            f"OpenRTC: {agents} in this worker (baseline ~{baseline_mb:.0f} MB). "
+            "Register more agents on the pool to amortize the shared prewarm."
+        )
+
+    separate_mb = (estimate.estimated_separate_workers_bytes or 0) / (1024 * 1024)
+    saved_mb = estimate.estimated_saved_bytes / (1024 * 1024)
+    return (
+        f"OpenRTC: {agents} in 1 worker (baseline ~{baseline_mb:.0f} MB). "
+        f"{agent_count} separate livekit-agents workers would cost "
+        f"~{separate_mb:.0f} MB; sharing one worker saves ~{saved_mb:.0f} MB "
+        "of idle baseline (assumes equal per-worker baselines)."
+    )
+
+
 def _linux_rss_bytes() -> int | None:
     """Read VmRSS (kiB in procfs) and convert to bytes."""
     try:

openrtc-0.2.3/tests/test_savings_readout.py

@@ -0,0 +1,76 @@
+"""Day-one savings readout: the format_prewarm_savings line and its prewarm emit.
+
+The readout makes the fleet-collapse idle-baseline win visible on first run. It
+claims only idle-baseline memory saved (never per-session density or a speed
+multiple) and stays graceful when RSS is unavailable.
+"""
+
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+
+import pytest
+
+from openrtc.execution import prewarm as prewarm_module
+from openrtc.execution.prewarm import _prewarm_worker
+from openrtc.observability.metrics import format_prewarm_savings
+
+_MB = 1024 * 1024
+
+
+def test_savings_line_for_multiple_agents() -> None:
+    line = format_prewarm_savings(agent_count=3, shared_worker_bytes=400 * _MB)
+    assert "3 agents" in line
+    assert "400 MB" in line  # shared baseline
+    assert "1200 MB" in line  # 3 separate workers
+    assert "800 MB" in line  # idle baseline saved: (3 - 1) * 400
+    assert "assumes" in line.lower()
+    assert "saves" in line.lower()
+
+
+def test_neutral_line_for_single_agent() -> None:
+    line = format_prewarm_savings(agent_count=1, shared_worker_bytes=400 * _MB)
+    assert "1 agent" in line
+    assert "saves" not in line.lower()  # no boast for a single agent
+    assert "amortize" in line.lower()
+
+
+def test_graceful_when_rss_unavailable() -> None:
+    line = format_prewarm_savings(agent_count=3, shared_worker_bytes=None)
+    assert "3 agents" in line
+    assert "unavailable" in line.lower()
+    assert "MB" not in line  # no fabricated number
+
+
+def test_prewarm_emits_one_savings_line(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    class _FakeVAD:
+        @staticmethod
+        def load() -> str:
+            return "vad"
+
+    class _FakeSilero:
+        VAD = _FakeVAD
+
+    class _FakeTurnDetector:
+        pass
+
+    monkeypatch.setattr(
+        prewarm_module,
+        "_load_shared_runtime_dependencies",
+        lambda: (_FakeSilero, _FakeTurnDetector),
+    )
+    runtime_state = SimpleNamespace(agents={"a": object(), "b": object()})
+    proc = SimpleNamespace(userdata={}, inference_executor=None)
+
+    with caplog.at_level(logging.INFO, logger="openrtc.execution.prewarm"):
+        _prewarm_worker(runtime_state, proc)  # type: ignore[arg-type]
+
+    records = [r for r in caplog.records if r.name == "openrtc.execution.prewarm"]
+    assert len(records) == 1
+    message = records[0].getMessage()
+    assert message.startswith("OpenRTC:")
+    assert "2 agents" in message
+    assert "saves" in message.lower()  # RSS is available in-process, so a number