vox-rtc-server 0.1.1__py3-none-any.whl

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/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/py.typed

@@ -0,0 +1 @@
+

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+vox_rtc_server/__init__.py,sha256=bUpCrq4dkT_V9gkkFPgsujgvTzUny9pjTxrrVkxw3ig,585
+vox_rtc_server/client.py,sha256=O3tw5ixLge0ru8ajpEkKJ4k9EHyMvPLNhyNcZ7DwQ7I,6219
+vox_rtc_server/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+vox_rtc_server/session.py,sha256=fQasNrcuLzpizdVJTwiigou9D4LSr6tx9KE7mq8n_fA,5087
+vox_rtc_server/types.py,sha256=36J5U8NMFSMjWjR4K6gbOC2fz4bKe-CE3ES18oJACxI,2675
+vox_rtc_server-0.1.1.dist-info/METADATA,sha256=It5BLjSMa1GUqjDWexaYP1CzJLUScSU05SggLZ1ZG-0,1953
+vox_rtc_server-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+vox_rtc_server-0.1.1.dist-info/RECORD,,

vox_rtc_server-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any