vox-rtc-server 0.1.1__tar.gz

vox_rtc_server-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+node_modules/
+dist/
+coverage/
+*.log
+.idea/
+.vscode/
+.cache/
+bin/
+__pycache__/
+*.pyc
+.venv/

vox_rtc_server-0.1.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: vox-rtc-server
+Version: 0.1.1
+Summary: Server-side Python SDK for Vox-hosted WebRTC sessions.
+Author: eleven-am
+License: GPL-3.0-or-later
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# `vox-rtc-server`
+
+Server-side Python SDK for Vox-hosted WebRTC sessions.
+
+This package is for backend applications that need to:
+
+- create RTC sessions over HTTP
+- attach to `/v1/socket`
+- join `/rtc/{session_id}`
+- send `session.update`, `response.*`, and `client.event`
+- observe RTC control events
+
+It is intentionally narrow. It is not the general STT/TTS/text SDK.
+
+## Install
+
+```bash
+pip install vox-rtc-server pondsocket-client
+```
+
+The SDK uses the PondSocket Python client for the control-plane socket.
+Until `pondsocket-client` is published, install it from your local checkout or git ref.
+Authentication can be passed explicitly with `api_key=...` or through `VOX_API_KEY`.
+
+## Example
+
+```python
+import asyncio
+import os
+
+from vox_rtc_server import (
+    ClientEventEnvelope,
+    SessionConfig,
+    VoxRtcServerClient,
+)
+
+
+async def main() -> None:
+    client = VoxRtcServerClient(
+        http_base="https://vox.example.com",
+        api_key=os.environ.get("VOX_API_KEY"),
+    )
+
+    bootstrap, session = await client.create_controlled_session()
+    print("session:", bootstrap.session_id)
+
+    session.on_event(lambda event: print(event.type, event.data))
+
+    session.configure(
+        SessionConfig(
+            stt_model="parakeet-stt-onnx:tdt-0.6b-v3",
+            tts_model="kokoro-tts-onnx:v1.0",
+            voice="af_heart",
+            turn_profile="browser_default",
+            vad_backend="silero",
+            turn_detector="livekit",
+        )
+    )
+
+    session.send_text_response("Hello from Python.")
+    session.send_client_event(
+        ClientEventEnvelope(
+            event="render.url",
+            payload={"url": "https://example.com"},
+        )
+    )
+
+
+asyncio.run(main())
+```

vox_rtc_server-0.1.1/README.md

@@ -0,0 +1,70 @@
+# `vox-rtc-server`
+
+Server-side Python SDK for Vox-hosted WebRTC sessions.
+
+This package is for backend applications that need to:
+
+- create RTC sessions over HTTP
+- attach to `/v1/socket`
+- join `/rtc/{session_id}`
+- send `session.update`, `response.*`, and `client.event`
+- observe RTC control events
+
+It is intentionally narrow. It is not the general STT/TTS/text SDK.
+
+## Install
+
+```bash
+pip install vox-rtc-server pondsocket-client
+```
+
+The SDK uses the PondSocket Python client for the control-plane socket.
+Until `pondsocket-client` is published, install it from your local checkout or git ref.
+Authentication can be passed explicitly with `api_key=...` or through `VOX_API_KEY`.
+
+## Example
+
+```python
+import asyncio
+import os
+
+from vox_rtc_server import (
+    ClientEventEnvelope,
+    SessionConfig,
+    VoxRtcServerClient,
+)
+
+
+async def main() -> None:
+    client = VoxRtcServerClient(
+        http_base="https://vox.example.com",
+        api_key=os.environ.get("VOX_API_KEY"),
+    )
+
+    bootstrap, session = await client.create_controlled_session()
+    print("session:", bootstrap.session_id)
+
+    session.on_event(lambda event: print(event.type, event.data))
+
+    session.configure(
+        SessionConfig(
+            stt_model="parakeet-stt-onnx:tdt-0.6b-v3",
+            tts_model="kokoro-tts-onnx:v1.0",
+            voice="af_heart",
+            turn_profile="browser_default",
+            vad_backend="silero",
+            turn_detector="livekit",
+        )
+    )
+
+    session.send_text_response("Hello from Python.")
+    session.send_client_event(
+        ClientEventEnvelope(
+            event="render.url",
+            payload={"url": "https://example.com"},
+        )
+    )
+
+
+asyncio.run(main())
+```

vox_rtc_server-0.1.1/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "vox-rtc-server"
+version = "0.1.1"
+description = "Server-side Python SDK for Vox-hosted WebRTC sessions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "eleven-am" }]
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vox_rtc_server"]

vox_rtc_server-0.1.1/src/vox_rtc_server/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .client import VoxRtcServerClient
+from .session import VoxRtcControlSession
+from .types import (
+    ChannelState,
+    ClientEventEnvelope,
+    ConnectionState,
+    RTCIceServer,
+    ResponseOptions,
+    SessionBootstrap,
+    SessionConfig,
+    WireEvent,
+)
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "ChannelState",
+    "ClientEventEnvelope",
+    "ConnectionState",
+    "RTCIceServer",
+    "ResponseOptions",
+    "SessionBootstrap",
+    "SessionConfig",
+    "VoxRtcControlSession",
+    "VoxRtcServerClient",
+    "WireEvent",
+    "__version__",
+]

vox_rtc_server-0.1.1/src/vox_rtc_server/client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import Mapping
+from typing import Any
+from urllib.request import Request, urlopen
+
+from .session import VoxRtcControlSession
+from .types import (
+    ConnectionState,
+    RTCIceServer,
+    SessionBootstrap,
+    SocketClientFactory,
+    SocketClientLike,
+)
+
+
+def _normalize_base(base: str) -> str:
+    return base.rstrip("/")
+
+
+def _default_socket_base(http_base: str) -> str:
+    return f"{_normalize_base(http_base)}/v1/socket"
+
+
+def _to_bootstrap(data: Mapping[str, Any]) -> SessionBootstrap:
+    ice_servers = [
+        RTCIceServer(
+            urls=entry.get("urls", []),
+            username=entry.get("username"),
+            credential=entry.get("credential"),
+        )
+        for entry in data.get("ice_servers", [])
+        if isinstance(entry, Mapping)
+    ]
+    return SessionBootstrap(
+        session_id=str(data["session_id"]),
+        client_token=str(data["client_token"]),
+        expires_at=str(data["expires_at"]),
+        join_token_ttl_seconds=int(data.get("join_token_ttl_seconds", 0)),
+        ice_servers=ice_servers,
+    )
+
+
+def _state_value(state: Any) -> str:
+    return str(getattr(state, "value", state))
+
+
+def _default_socket_factory(
+    endpoint: str,
+    params: Mapping[str, Any],
+    connection_timeout: float,
+    max_reconnect_delay: float,
+) -> SocketClientLike:
+    try:
+        from pondsocket_client import ClientOptions, PondClient
+    except ImportError as exc:
+        raise ImportError(
+            "pondsocket-client is required for the default Vox RTC socket transport"
+        ) from exc
+
+    options = ClientOptions(
+        connection_timeout=connection_timeout,
+        max_reconnect_delay=max_reconnect_delay,
+    )
+    return PondClient(endpoint, dict(params), options)
+
+
+class VoxRtcServerClient:
+    __slots__ = (
+        "_connection_timeout",
+        "_http_base",
+        "_api_key",
+        "_join_timeout",
+        "_max_reconnect_delay",
+        "_request_timeout",
+        "_socket",
+        "_socket_base",
+        "_socket_factory",
+        "_socket_params",
+        "_urlopen",
+    )
+
+    def __init__(
+        self,
+        *,
+        http_base: str,
+        api_key: str | None = None,
+        socket_base: str | None = None,
+        socket_params: Mapping[str, Any] | None = None,
+        connection_timeout: float = 10.0,
+        max_reconnect_delay: float = 30.0,
+        request_timeout: float = 15.0,
+        join_timeout: float = 10.0,
+        socket_factory: SocketClientFactory | None = None,
+        urlopen_impl: Any = urlopen,
+    ) -> None:
+        self._http_base = _normalize_base(http_base)
+        resolved_api_key = (api_key if api_key is not None else os.environ.get("VOX_API_KEY", "")).strip()
+        self._api_key = resolved_api_key or None
+        self._socket_base = (
+            _normalize_base(socket_base) if socket_base else _default_socket_base(http_base)
+        )
+        merged_socket_params = dict(socket_params or {})
+        if self._api_key:
+            merged_socket_params["api_key"] = self._api_key
+        self._socket_params = merged_socket_params
+        self._connection_timeout = connection_timeout
+        self._max_reconnect_delay = max_reconnect_delay
+        self._request_timeout = request_timeout
+        self._join_timeout = join_timeout
+        self._socket_factory = socket_factory or _default_socket_factory
+        self._socket: SocketClientLike | None = None
+        self._urlopen = urlopen_impl
+
+    @property
+    def http_base(self) -> str:
+        return self._http_base
+
+    @property
+    def socket_base(self) -> str:
+        return self._socket_base
+
+    @property
+    def connection_state(self) -> ConnectionState:
+        if self._socket is None:
+            return ConnectionState.DISCONNECTED
+        raw = _state_value(self._socket.get_state())
+        return ConnectionState(raw)
+
+    async def connect(self) -> None:
+        socket = self._ensure_socket()
+        if _state_value(socket.get_state()) == ConnectionState.CONNECTED.value:
+            return
+        await socket.connect()
+
+    async def disconnect(self) -> None:
+        socket = self._socket
+        if socket is None:
+            return
+        await socket.disconnect()
+        self._socket = None
+
+    async def create_session(self) -> SessionBootstrap:
+        return await asyncio.to_thread(self._create_session_blocking)
+
+    async def attach_session(self, session_id: str) -> VoxRtcControlSession:
+        await self.connect()
+        socket = self._ensure_socket()
+        channel = socket.create_channel(f"/rtc/{session_id}", {})
+        session = VoxRtcControlSession(
+            channel,
+            session_id,
+            join_timeout=self._join_timeout,
+        )
+        await session.join()
+        return session
+
+    async def create_controlled_session(
+        self,
+    ) -> tuple[SessionBootstrap, VoxRtcControlSession]:
+        bootstrap = await self.create_session()
+        session = await self.attach_session(bootstrap.session_id)
+        return bootstrap, session
+
+    def _ensure_socket(self) -> SocketClientLike:
+        if self._socket is None:
+            self._socket = self._socket_factory(
+                self._socket_base,
+                self._socket_params,
+                self._connection_timeout,
+                self._max_reconnect_delay,
+            )
+        return self._socket
+
+    def _create_session_blocking(self) -> SessionBootstrap:
+        request = Request(
+            f"{self._http_base}/v1/rtc/sessions",
+            data=json.dumps({}).encode("utf-8"),
+            headers={"content-type": "application/json"},
+            method="POST",
+        )
+        if self._api_key:
+            request.add_header("authorization", f"Bearer {self._api_key}")
+        with self._urlopen(request, timeout=self._request_timeout) as response:
+            status = int(response.status) if hasattr(response, "status") else int(response.getcode())
+            body = response.read().decode("utf-8")
+        if status < 200 or status >= 300:
+            raise RuntimeError(f"Failed to create Vox RTC session: {status} {body.strip()}")
+        return _to_bootstrap(json.loads(body))

vox_rtc_server-0.1.1/src/vox_rtc_server/py.typed

@@ -0,0 +1 @@
+

vox_rtc_server-0.1.1/src/vox_rtc_server/session.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from .types import (
+    ChannelState,
+    ClientEventEnvelope,
+    ResponseOptions,
+    SessionConfig,
+    SocketChannelLike,
+    Unsubscribe,
+    WireEvent,
+)
+
+
+def _state_value(state: Any) -> str:
+    return str(getattr(state, "value", state))
+
+
+def _payload_dict(payload: Any) -> dict[str, Any]:
+    if payload is None:
+        return {}
+    if isinstance(payload, dict):
+        return dict(payload)
+    if isinstance(payload, Mapping):
+        return dict(payload)
+    return {"payload": payload}
+
+
+def _response_options_payload(options: ResponseOptions | None) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    if options is not None and options.allow_interruptions is not None:
+        payload["allow_interruptions"] = options.allow_interruptions
+    return payload
+
+
+class VoxRtcControlSession:
+    __slots__ = ("_channel", "_channel_name", "_join_timeout", "_session_id")
+
+    def __init__(
+        self,
+        channel: SocketChannelLike,
+        session_id: str,
+        *,
+        join_timeout: float = 10.0,
+    ) -> None:
+        self._channel = channel
+        self._session_id = session_id
+        self._channel_name = f"/rtc/{session_id}"
+        self._join_timeout = join_timeout
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    @property
+    def channel_name(self) -> str:
+        return self._channel_name
+
+    async def join(self) -> None:
+        loop = asyncio.get_running_loop()
+        done: asyncio.Future[None] = loop.create_future()
+
+        def handle_state(state: Any) -> None:
+            value = _state_value(state)
+            if value == ChannelState.JOINED.value and not done.done():
+                done.set_result(None)
+            elif value in (ChannelState.DECLINED.value, ChannelState.CLOSED.value) and not done.done():
+                done.set_exception(
+                    RuntimeError(f"RTC channel join failed for {self._channel_name}: {value}")
+                )
+
+        unsubscribe = self._channel.on_channel_state_change(handle_state)
+        try:
+            self._channel.join()
+            await asyncio.wait_for(done, timeout=self._join_timeout)
+        finally:
+            unsubscribe()
+
+    def close(self) -> None:
+        self._channel.leave()
+
+    def on_event(self, handler: Callable[[WireEvent], None]) -> Unsubscribe:
+        def callback(message: Any) -> None:
+            handler(
+                WireEvent(
+                    type=str(getattr(message, "event", "")),
+                    data=_payload_dict(getattr(message, "payload", None)),
+                )
+            )
+
+        return self._channel.on_message(callback)
+
+    def on(self, event_name: str, handler: Callable[[dict[str, Any]], None]) -> Unsubscribe:
+        def callback(message: Any) -> None:
+            handler(_payload_dict(getattr(message, "payload", None)))
+
+        return self._channel.on_message_event(event_name, callback)
+
+    def send_control(self, event: str, payload: Mapping[str, Any] | None = None) -> None:
+        self._channel.send_message(event, dict(payload or {}))
+
+    def configure(self, config: SessionConfig) -> None:
+        session: dict[str, Any] = dict(config.extra)
+        if config.stt_model is not None:
+            session["stt_model"] = config.stt_model
+        if config.tts_model is not None:
+            session["tts_model"] = config.tts_model
+        if config.voice is not None:
+            session["voice"] = config.voice
+        if config.turn_profile is not None:
+            session["turn_profile"] = config.turn_profile
+        if config.vad_backend is not None:
+            session["vad_backend"] = config.vad_backend
+        if config.turn_detector is not None:
+            session["turn_detector"] = config.turn_detector
+        self.send_control("session.update", {"session": session})
+
+    def start_response(self, options: ResponseOptions | None = None) -> None:
+        self.send_control("response.start", _response_options_payload(options))
+
+    def append_response_text(
+        self,
+        delta: str,
+        options: ResponseOptions | None = None,
+    ) -> None:
+        payload = _response_options_payload(options)
+        payload["delta"] = delta
+        self.send_control("response.delta", payload)
+
+    def commit_response(self) -> None:
+        self.send_control("response.commit")
+
+    def cancel_response(self) -> None:
+        self.send_control("response.cancel")
+
+    def send_text_response(
+        self,
+        text: str,
+        options: ResponseOptions | None = None,
+        *,
+        cancel_first: bool = True,
+    ) -> None:
+        if cancel_first:
+            self.cancel_response()
+        self.start_response(options)
+        self.append_response_text(text, options)
+        self.commit_response()
+
+    def send_client_event(self, envelope: ClientEventEnvelope) -> None:
+        self.send_control(
+            "client.event",
+            {"event": envelope.event, "payload": envelope.payload},
+        )

vox_rtc_server-0.1.1/src/vox_rtc_server/types.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Protocol, TypeAlias
+
+
+class ConnectionState(StrEnum):
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+
+
+class ChannelState(StrEnum):
+    IDLE = "IDLE"
+    JOINING = "JOINING"
+    JOINED = "JOINED"
+    STALLED = "STALLED"
+    CLOSED = "CLOSED"
+    DECLINED = "DECLINED"
+
+
+@dataclass(slots=True)
+class RTCIceServer:
+    urls: str | list[str]
+    username: str | None = None
+    credential: str | None = None
+
+
+@dataclass(slots=True)
+class SessionBootstrap:
+    session_id: str
+    client_token: str
+    expires_at: str
+    join_token_ttl_seconds: int
+    ice_servers: list[RTCIceServer] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class SessionConfig:
+    stt_model: str | None = None
+    tts_model: str | None = None
+    voice: str | None = None
+    turn_profile: str | None = None
+    vad_backend: str | None = None
+    turn_detector: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class ResponseOptions:
+    allow_interruptions: bool | None = None
+
+
+@dataclass(slots=True)
+class ClientEventEnvelope:
+    event: str
+    payload: Any = None
+
+
+@dataclass(slots=True)
+class WireEvent:
+    type: str
+    data: dict[str, Any]
+
+
+Unsubscribe: TypeAlias = Callable[[], None]
+
+
+class ServerMessageLike(Protocol):
+    @property
+    def event(self) -> str: ...
+
+    @property
+    def payload(self) -> Any: ...
+
+
+class SocketChannelLike(Protocol):
+    def join(self) -> None: ...
+
+    def leave(self) -> None: ...
+
+    def send_message(self, event: str, payload: Mapping[str, Any] | None = None) -> None: ...
+
+    def on_message(self, callback: Callable[[ServerMessageLike], None]) -> Unsubscribe: ...
+
+    def on_message_event(
+        self, event_name: str, callback: Callable[[ServerMessageLike], None]
+    ) -> Unsubscribe: ...
+
+    def on_channel_state_change(
+        self, callback: Callable[[Any], None]
+    ) -> Unsubscribe: ...
+
+
+class SocketClientLike(Protocol):
+    async def connect(self) -> None: ...
+
+    async def disconnect(self) -> None: ...
+
+    def get_state(self) -> Any: ...
+
+    def create_channel(
+        self, name: str, params: Mapping[str, Any] | None = None
+    ) -> SocketChannelLike: ...
+
+    def on_connection_change(self, callback: Callable[[Any], None]) -> Unsubscribe: ...
+
+    def on_error(self, callback: Callable[[BaseException], None]) -> Unsubscribe: ...
+
+
+SocketClientFactory: TypeAlias = Callable[
+    [str, Mapping[str, Any], float, float],
+    SocketClientLike,
+]

vox_rtc_server-0.1.1/tests/test_client.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from vox_rtc_server import (
+    ChannelState,
+    ClientEventEnvelope,
+    ConnectionState,
+    SessionConfig,
+    VoxRtcServerClient,
+)
+
+
+@dataclass(slots=True)
+class FakeServerMessage:
+    event: str
+    payload: dict[str, Any]
+
+
+class FakeChannel:
+    def __init__(self) -> None:
+        self.sent: list[tuple[str, dict[str, Any]]] = []
+        self.state_handlers: list[Callable[[Any], None]] = []
+        self.message_handlers: list[Callable[[FakeServerMessage], None]] = []
+        self.message_event_handlers: dict[str, list[Callable[[FakeServerMessage], None]]] = {}
+
+    def join(self) -> None:
+        for handler in list(self.state_handlers):
+            handler(ChannelState.JOINED)
+
+    def leave(self) -> None:
+        return None
+
+    def send_message(self, event: str, payload: dict[str, Any] | None = None) -> None:
+        self.sent.append((event, dict(payload or {})))
+
+    def on_message(self, callback: Callable[[FakeServerMessage], None]) -> Callable[[], None]:
+        self.message_handlers.append(callback)
+        return lambda: self.message_handlers.remove(callback)
+
+    def on_message_event(
+        self, event_name: str, callback: Callable[[FakeServerMessage], None]
+    ) -> Callable[[], None]:
+        handlers = self.message_event_handlers.setdefault(event_name, [])
+        handlers.append(callback)
+        return lambda: handlers.remove(callback)
+
+    def on_channel_state_change(self, callback: Callable[[Any], None]) -> Callable[[], None]:
+        self.state_handlers.append(callback)
+        return lambda: self.state_handlers.remove(callback)
+
+    def emit(self, event: str, payload: dict[str, Any]) -> None:
+        message = FakeServerMessage(event=event, payload=payload)
+        for handler in list(self.message_handlers):
+            handler(message)
+        for handler in list(self.message_event_handlers.get(event, [])):
+            handler(message)
+
+
+class FakeSocket:
+    def __init__(self) -> None:
+        self.state = ConnectionState.DISCONNECTED
+        self.channel = FakeChannel()
+        self.connection_handlers: list[Callable[[Any], None]] = []
+        self.error_handlers: list[Callable[[BaseException], None]] = []
+
+    async def connect(self) -> None:
+        self.state = ConnectionState.CONNECTED
+        for handler in list(self.connection_handlers):
+            handler(self.state)
+
+    async def disconnect(self) -> None:
+        self.state = ConnectionState.DISCONNECTED
+        for handler in list(self.connection_handlers):
+            handler(self.state)
+
+    def get_state(self) -> ConnectionState:
+        return self.state
+
+    def create_channel(self, name: str, params: dict[str, Any] | None = None) -> FakeChannel:
+        assert name == "/rtc/rtc_123"
+        return self.channel
+
+    def on_connection_change(self, callback: Callable[[Any], None]) -> Callable[[], None]:
+        self.connection_handlers.append(callback)
+        return lambda: self.connection_handlers.remove(callback)
+
+    def on_error(self, callback: Callable[[BaseException], None]) -> Callable[[], None]:
+        self.error_handlers.append(callback)
+        return lambda: self.error_handlers.remove(callback)
+
+
+class FakeHTTPResponse:
+    def __init__(self, status: int, payload: dict[str, Any]) -> None:
+        self.status = status
+        self._body = json.dumps(payload).encode("utf-8")
+
+    def __enter__(self) -> FakeHTTPResponse:
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        return None
+
+    def read(self) -> bytes:
+        return self._body
+
+
+def test_create_session_parses_the_rtc_bootstrap_response(monkeypatch: Any) -> None:
+    monkeypatch.setenv("VOX_API_KEY", "secret")
+
+    def fake_urlopen(request: Any, timeout: float | None = None) -> FakeHTTPResponse:
+        assert request.full_url == "https://vox.example.com/v1/rtc/sessions"
+        assert request.method == "POST"
+        assert timeout == 15.0
+        assert json.loads(request.data.decode("utf-8")) == {}
+        assert request.get_header("Authorization") == "Bearer secret"
+        return FakeHTTPResponse(
+            200,
+            {
+                "session_id": "rtc_123",
+                "client_token": "tok_123",
+                "expires_at": "2026-01-01T00:00:00Z",
+                "join_token_ttl_seconds": 120,
+                "ice_servers": [{"urls": ["stun:turn.example.com:3478"]}],
+            },
+        )
+
+    client = VoxRtcServerClient(
+        http_base="https://vox.example.com/",
+        urlopen_impl=fake_urlopen,
+        socket_factory=lambda *args: FakeSocket(),
+    )
+
+    bootstrap = asyncio.run(client.create_session())
+
+    assert bootstrap.session_id == "rtc_123"
+    assert bootstrap.client_token == "tok_123"
+    assert bootstrap.join_token_ttl_seconds == 120
+    assert client.http_base == "https://vox.example.com"
+    assert client.socket_base == "https://vox.example.com/v1/socket"
+
+
+def test_attach_session_joins_and_sends_expected_control_messages() -> None:
+    fake_socket = FakeSocket()
+    captured_params: dict[str, Any] = {}
+    client = VoxRtcServerClient(
+        http_base="https://vox.example.com",
+        api_key="secret",
+        socket_factory=lambda _endpoint, params, *_args: captured_params.update(params) or fake_socket,
+    )
+
+    session = asyncio.run(client.attach_session("rtc_123"))
+    session.configure(
+        SessionConfig(
+            stt_model="stt",
+            tts_model="tts",
+            voice="voice",
+            turn_profile="browser_default",
+            vad_backend="silero",
+            turn_detector="livekit",
+        )
+    )
+    session.send_text_response("Hello")
+    session.send_client_event(
+        ClientEventEnvelope(
+            event="render.url",
+            payload={"url": "https://example.com"},
+        )
+    )
+
+    assert [event for event, _payload in fake_socket.channel.sent] == [
+        "session.update",
+        "response.cancel",
+        "response.start",
+        "response.delta",
+        "response.commit",
+        "client.event",
+    ]
+    assert fake_socket.channel.sent[0][1] == {
+        "session": {
+            "stt_model": "stt",
+            "tts_model": "tts",
+            "voice": "voice",
+            "turn_profile": "browser_default",
+            "vad_backend": "silero",
+            "turn_detector": "livekit",
+        }
+    }
+    assert captured_params == {"api_key": "secret"}
+
+
+def test_on_event_maps_socket_messages_into_wire_events() -> None:
+    fake_socket = FakeSocket()
+    client = VoxRtcServerClient(
+        http_base="https://vox.example.com",
+        socket_factory=lambda *args: fake_socket,
+    )
+
+    session = asyncio.run(client.attach_session("rtc_123"))
+    received: list[tuple[str, dict[str, Any]]] = []
+    unsubscribe = session.on_event(lambda event: received.append((event.type, event.data)))
+
+    fake_socket.channel.emit(
+        "turn.state_changed",
+        {"state": "speaking", "session_id": "rtc_123"},
+    )
+    unsubscribe()
+
+    assert received == [
+        ("turn.state_changed", {"state": "speaking", "session_id": "rtc_123"})
+    ]

vox_rtc_server-0.1.1/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.11"
+
+[[package]]
+name = "vox-rtc-server"
+version = "0.1.1"
+source = { editable = "." }