converse-sdk 0.1.0__py3-none-any.whl

converse_sdk/__init__.py

@@ -0,0 +1,37 @@
+from .audio import (
+    chunk_audio,
+    f32le_to_float32,
+    float32_to_pcm16,
+    pcm16_to_float32,
+    to_ws_url,
+)
+from .recorder import TurnRecorder
+from .session import (
+    DEFAULT_CHUNK_MS,
+    DEFAULT_SR,
+    OUTPUT_SR,
+    ConverseError,
+    ConverseMode,
+    RelayMode,
+    SessionMode,
+    ConverseSession,
+    SessionEvent,
+)
+
+__all__ = [
+    "ConverseError",
+    "ConverseMode",
+    "RelayMode",
+    "SessionMode",
+    "ConverseSession",
+    "SessionEvent",
+    "TurnRecorder",
+    "DEFAULT_CHUNK_MS",
+    "DEFAULT_SR",
+    "OUTPUT_SR",
+    "chunk_audio",
+    "f32le_to_float32",
+    "float32_to_pcm16",
+    "pcm16_to_float32",
+    "to_ws_url",
+]

converse_sdk/audio.py

@@ -0,0 +1,50 @@
+"""Audio codecs for the Converse wire protocol.
+
+Uplink is PCM16 little-endian mono; downlink assistant audio is float32 little-endian mono.
+WAV loading/resampling is deliberately out of scope — callers own file I/O.
+"""
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import numpy as np
+
+
+def float32_to_pcm16(audio: np.ndarray) -> bytes:
+    clipped = np.clip(audio, -1.0, 1.0)
+    return (clipped * 32767.0).astype("<i2").tobytes()
+
+
+def pcm16_to_float32(data: bytes) -> np.ndarray:
+    if not data:
+        return np.zeros(0, dtype=np.float32)
+    return (np.frombuffer(data, dtype="<i2").astype(np.float32)) / 32768.0
+
+
+def f32le_to_float32(data: bytes) -> np.ndarray:
+    if not data:
+        return np.zeros(0, dtype=np.float32)
+    return np.frombuffer(data, dtype="<f4").astype(np.float32)
+
+
+def chunk_audio(audio: np.ndarray, sr: int, chunk_ms: int) -> list[np.ndarray]:
+    """Slice a float32 waveform into fixed-size frames, zero-padding the tail."""
+    n = max(1, int(sr * chunk_ms / 1000))
+    chunks = []
+    for i in range(0, len(audio), n):
+        chunk = audio[i:i + n]
+        if len(chunk) < n:
+            padded = np.zeros(n, dtype=np.float32)
+            padded[: len(chunk)] = chunk
+            chunk = padded
+        chunks.append(chunk.astype(np.float32, copy=False))
+    return chunks
+
+
+def to_ws_url(value: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme in {"ws", "wss"}:
+        return value
+    if parsed.scheme in {"http", "https"}:
+        return ("wss://" if parsed.scheme == "https" else "ws://") + value.split("://", 1)[1]
+    return value

converse_sdk/py.typed

@@ -0,0 +1 @@
+

converse_sdk/recorder.py

@@ -0,0 +1,89 @@
+"""Canonical assistant-audio bookkeeping over a ConverseSession event stream.
+
+Encodes the two Converse-specific capture rules the eval runner established:
+- `canceled` is a pre-audible rescind — the rescinded reply was never heard, so its audio must be
+  dropped and first-audio must re-latch on the reply the user actually hears.
+- `interrupted` is a barge — the user heard the fragment, so captured audio keeps it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .session import OUTPUT_SR, SessionEvent
+
+
+@dataclass
+class TurnRecorder:
+    sr: int = OUTPUT_SR
+    audio_parts: list[np.ndarray] = field(default_factory=list)
+    # (arrival_ms, cumulative_samples) per audio frame, for mapping samples back to wall clock.
+    arrivals: list[tuple[float, int]] = field(default_factory=list)
+    first_audio_ms: float | None = None
+    turn_started_ms: float | None = None
+    done_ms: float | None = None
+    canceled_count: int = 0
+    interrupted_count: int = 0
+    _turn_audio_start: int = 0
+    _turn_arrival_start: int = 0
+
+    def feed(self, ev: SessionEvent) -> None:
+        if ev.type == "audio" and ev.audio is not None and len(ev.audio):
+            if self.first_audio_ms is None:
+                self.first_audio_ms = ev.t_ms
+            self.audio_parts.append(ev.audio)
+            total = (self.arrivals[-1][1] if self.arrivals else 0) + len(ev.audio)
+            self.arrivals.append((ev.t_ms, total))
+        elif ev.type == "turn":
+            self.turn_started_ms = ev.t_ms
+        elif ev.type == "done":
+            self.done_ms = ev.t_ms
+        elif ev.type == "canceled":
+            self.canceled_count += 1
+            # Hard clear of the CURRENT turn's audio only: rescinded pre-audible reply.
+            del self.audio_parts[self._turn_audio_start:]
+            del self.arrivals[self._turn_arrival_start:]
+            self.first_audio_ms = None
+            self.turn_started_ms = None
+        elif ev.type == "interrupted":
+            self.interrupted_count += 1  # keep audio: the user heard the fragment
+
+    def mark_turn_boundary(self) -> None:
+        """Call after a completed turn so a later `canceled` only clears the new turn's audio."""
+        self._turn_audio_start = len(self.audio_parts)
+        self._turn_arrival_start = len(self.arrivals)
+        self.first_audio_ms = None
+        self.turn_started_ms = None
+        self.done_ms = None
+
+    def waveform(self) -> np.ndarray:
+        """Captured assistant audio, gaplessly concatenated."""
+        if not self.audio_parts:
+            return np.zeros(0, dtype=np.float32)
+        return np.concatenate(self.audio_parts)
+
+    def aligned_waveform(self, *, end_ms: float | None = None) -> np.ndarray:
+        """Assistant audio placed on a wall-clock silence timeline.
+
+        Frames arrive in bursts ahead of playback, so each frame is placed at its arrival time or
+        immediately after the previous frame, whichever is later — the earliest moment it could
+        have been audible. This is the layout full-duplex benchmarks score against.
+
+        `end_ms` is a FLOOR, not a ceiling: audio already placed past it is never truncated
+        (captured audio the user heard must not be discarded), it only pads shorter timelines.
+        """
+        if not self.audio_parts:
+            n = int((end_ms or 0) / 1000 * self.sr)
+            return np.zeros(n, dtype=np.float32)
+        placements = []
+        cursor = 0
+        for (arrival_ms, _cum), part in zip(self.arrivals, self.audio_parts):
+            start = max(int(arrival_ms / 1000 * self.sr), cursor)
+            placements.append((start, part))
+            cursor = start + len(part)
+        end = max(cursor, int(end_ms / 1000 * self.sr) if end_ms is not None else 0)
+        timeline = np.zeros(end, dtype=np.float32)
+        for start, part in placements:
+            timeline[start:start + len(part)] = part
+        return timeline

converse_sdk/session.py

@@ -0,0 +1,306 @@
+"""Headless duplex client for the Converse broker websocket protocol.
+
+Mirrors the browser SDK's event vocabulary (sdk/browser/src/index.js): `ready`, `turn`, `asr`,
+`utterance`, `done`, `interrupted`, `canceled`, `error`, `ack`, `playback_pause`,
+`playback_resume`, `tool_call`, plus a synthetic `audio` event per binary frame. Every event is
+stamped with `t_ms` — milliseconds since `connect()` began — so callers can reconstruct a
+wall-clock-aligned view of the conversation without their own clock plumbing.
+
+The client is a thin wire terminal: it does not decide turn boundaries, pacing policy, or what
+`canceled`/`interrupted` mean for captured audio. `TurnRecorder` (recorder.py) implements the
+canonical bookkeeping for callers that assemble waveforms.
+
+Callers that perform REAL playback (telephony bridges, apps with a speaker) own the playback
+clock and must report discards themselves: after an `interrupted` event, send
+`send_client_event("playback_stopped", discarded_ms=<unplayed ms>, barge_seq=<from the event>)`
+so the broker re-truncates its committed text to what the user actually heard (see
+https://converse.trelis.com/docs/api/reference/#playback-contract). Without that report the broker assumes every
+delivered fragment was heard — correct for headless recording/eval use, wrong for live playback.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+import numpy as np
+
+from .audio import chunk_audio, f32le_to_float32, float32_to_pcm16, to_ws_url
+
+DEFAULT_SR = 16_000
+OUTPUT_SR = 16_000
+DEFAULT_CHUNK_MS = 100
+
+
+@dataclass(frozen=True)
+class ConverseMode:
+    """Converse-cascade capabilities. Relay-only fields cannot be expressed here."""
+
+    voice: str | None = None
+    instructions: str | None = None
+    tools: list[dict[str, Any]] | None = None
+    web_search: bool = False
+    flow: bool = False
+    greeting: str | bool | None = None  # None=server default, False=disabled, str=custom opener
+
+    def __post_init__(self) -> None:
+        if self.voice is not None and not isinstance(self.voice, str):
+            raise TypeError("ConverseMode voice must be a string or None")
+        if self.instructions is not None and not isinstance(self.instructions, str):
+            raise TypeError("ConverseMode instructions must be a string or None")
+        if self.tools is not None and not isinstance(self.tools, list):
+            raise TypeError("ConverseMode tools must be a list or None")
+        if type(self.web_search) is not bool:
+            raise TypeError("ConverseMode web_search must be a boolean")
+        if type(self.flow) is not bool:
+            raise TypeError("ConverseMode flow must be a boolean")
+        if self.greeting is not None and self.greeting is not False \
+                and not isinstance(self.greeting, str):
+            raise ValueError("ConverseMode greeting must be a string, False, or None")
+
+    def to_wire(self) -> dict[str, Any]:
+        mode: dict[str, Any] = {"kind": "converse", "web_search": self.web_search}
+        for key, value in (("voice", self.voice), ("instructions", self.instructions),
+                           ("tools", self.tools), ("greeting", self.greeting)):
+            if value is not None:
+                mode[key] = value
+        if self.flow:
+            mode["flow"] = True
+        return mode
+
+
+@dataclass(frozen=True)
+class RelayMode:
+    """External speech-to-speech relay capabilities; no Converse instructions or tools."""
+
+    provider: str
+    model: str | None = None
+    voice: str | None = None
+    web_search: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.provider, str) or not self.provider.strip():
+            raise ValueError("RelayMode provider is required")
+        if self.model is not None and not isinstance(self.model, str):
+            raise TypeError("RelayMode model must be a string or None")
+        if self.voice is not None and not isinstance(self.voice, str):
+            raise TypeError("RelayMode voice must be a string or None")
+        if type(self.web_search) is not bool:
+            raise TypeError("RelayMode web_search must be a boolean")
+
+    def to_wire(self) -> dict[str, Any]:
+        mode: dict[str, Any] = {
+            "kind": "relay", "provider": self.provider, "web_search": self.web_search,
+        }
+        if self.model is not None:
+            mode["model"] = self.model
+        if self.voice is not None:
+            mode["voice"] = self.voice
+        return mode
+
+
+SessionMode = ConverseMode | RelayMode
+
+
+@dataclass
+class SessionEvent:
+    type: str
+    t_ms: float
+    data: dict[str, Any] = field(default_factory=dict)
+    audio: np.ndarray | None = None  # float32 mono at OUTPUT_SR, only for type == "audio"
+
+
+class ConverseError(RuntimeError):
+    """Raised when the broker reports {"type": "error"} during connect."""
+
+
+class ConverseSession:
+    """One duplex broker session. Use `ConverseSession.connect(...)` to open.
+
+    Reading and writing are independent: `send_audio`/`stream_audio` feed the mic uplink while
+    `events()` yields broker events — full duplex, no phasing. The receive loop runs as a
+    background task from connect until the socket closes; events buffer in an unbounded queue.
+    """
+
+    def __init__(self, ws: Any, start_t: float) -> None:
+        self._ws = ws
+        self._start_t = start_t
+        self._queue: asyncio.Queue[SessionEvent | None] = asyncio.Queue()
+        self._reader: asyncio.Task | None = None
+        self._closed = False
+
+    # -- lifecycle -----------------------------------------------------------------
+
+    @classmethod
+    async def connect(
+        cls,
+        url: str,
+        *,
+        session_id: str | None = None,
+        sr: int = DEFAULT_SR,
+        api_key: str | None = None,
+        mode: SessionMode | None = None,
+        user: str | None = None,
+        timezone: str | None = None,
+        capabilities: list[str] | None = None,
+        connect_timeout_s: float = 15.0,
+    ) -> "ConverseSession":
+        import websockets
+
+        selected_mode = mode or ConverseMode()
+        if not isinstance(selected_mode, (ConverseMode, RelayMode)):
+            raise TypeError("mode must be ConverseMode or RelayMode")
+        start: dict[str, Any] = {
+            "type": "start",
+            "session_id": session_id or f"sdk-{int(time.time() * 1000)}",
+            "audio": {"sr": sr},
+            "mode": selected_mode.to_wire(),
+        }
+        if api_key is not None:
+            start["api_key"] = api_key
+        client = {key: value for key, value in (
+            ("user", user), ("timezone", timezone), ("capabilities", capabilities),
+        ) if value is not None}
+        if client:
+            start["client"] = client
+        start_json = json.dumps(start)
+        start_t = time.perf_counter()
+        ws = await websockets.connect(to_ws_url(url), max_size=None)
+        await ws.send(start_json)
+
+        session = cls(ws, start_t)
+        session._reader = asyncio.create_task(session._read_loop())
+        # Surface `ready` (or a pre-ready error) before returning, mirroring the browser client;
+        # the event is also re-queued so `events()` consumers see the full stream.
+        try:
+            async with asyncio.timeout(connect_timeout_s):
+                while True:
+                    ev = await session._queue.get()
+                    if ev is None:
+                        raise ConverseError("connection closed before ready")
+                    session._queue.put_nowait(ev)
+                    if ev.type == "ready":
+                        return session
+                    if ev.type == "error":
+                        raise ConverseError(ev.data.get("detail") or "broker error before ready")
+        except (ConverseError, TimeoutError):
+            await session.close()
+            raise
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            await self._ws.close()
+        finally:
+            if self._reader is not None:
+                self._reader.cancel()
+                try:
+                    await self._reader
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                    pass
+            self._queue.put_nowait(None)
+
+    async def __aenter__(self) -> "ConverseSession":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # -- clock ---------------------------------------------------------------------
+
+    @property
+    def start_t(self) -> float:
+        """perf_counter anchor taken as connect() began; all t_ms values are relative to it."""
+        return self._start_t
+
+    def now_ms(self) -> float:
+        return round((time.perf_counter() - self._start_t) * 1000, 1)
+
+    # -- uplink --------------------------------------------------------------------
+
+    async def send_audio(self, chunk: np.ndarray | bytes) -> None:
+        """Send one mic frame. float32 arrays are encoded to PCM16; bytes pass through."""
+        data = chunk if isinstance(chunk, (bytes, bytearray)) else float32_to_pcm16(chunk)
+        await self._ws.send(data)
+
+    async def stream_audio(
+        self,
+        audio: np.ndarray,
+        *,
+        sr: int = DEFAULT_SR,
+        chunk_ms: int = DEFAULT_CHUNK_MS,
+        realtime: bool = True,
+        on_sent: Any | None = None,
+    ) -> list[float]:
+        """Stream a waveform as paced mic frames; returns the actual send time (ms) per chunk.
+
+        asyncio pacing drifts under load, so callers anchoring timing on the input must use the
+        returned actual send times, never `i * chunk_ms`.
+        """
+        send_times: list[float] = []
+        for chunk in chunk_audio(audio, sr, chunk_ms):
+            now = self.now_ms()
+            send_times.append(now)
+            await self.send_audio(chunk)
+            if on_sent is not None:
+                on_sent(now, chunk)
+            if realtime:
+                await asyncio.sleep(chunk_ms / 1000)
+        return send_times
+
+    # -- control messages ----------------------------------------------------------
+
+    async def _send_json(self, payload: dict[str, Any]) -> None:
+        await self._ws.send(json.dumps(payload))
+
+    async def reset(self) -> None:
+        await self._send_json({"type": "reset"})
+
+    async def send_tool_result(self, tool_id: str, content: Any) -> None:
+        """Resolve a call with JSON content.
+
+        Keep results compact: the server enforces its configured UTF-8 JSON byte ceiling and
+        replaces oversized content with a bounded truncation marker and preview.
+        """
+        await self._send_json({"type": "tool_result", "id": tool_id, "content": content})
+
+    async def send_tool_cancel(self, tool_id: str) -> None:
+        await self._send_json({"type": "tool_cancel", "id": tool_id})
+
+    async def send_tool_progress(self, tool_id: str, note: str) -> None:
+        """Report progress on an in-flight tool call (docs/client-tool-protocol.md §3): appends to the brain's
+        context so the next turn can speak to it; never resolves the call."""
+        await self._send_json({"type": "tool_progress", "id": tool_id, "note": note})
+
+    async def send_client_event(self, event: str, **fields: Any) -> None:
+        await self._send_json({"type": "client_event", "event": event, **fields})
+
+    # -- downlink ------------------------------------------------------------------
+
+    async def events(self) -> AsyncIterator[SessionEvent]:
+        """Yield broker events until the connection closes. Safe to consume from one task only."""
+        while True:
+            ev = await self._queue.get()
+            if ev is None:
+                return
+            yield ev
+
+    async def _read_loop(self) -> None:
+        try:
+            async for raw in self._ws:
+                if isinstance(raw, (bytes, bytearray)):
+                    self._queue.put_nowait(SessionEvent(
+                        type="audio", t_ms=self.now_ms(), audio=f32le_to_float32(bytes(raw))))
+                    continue
+                msg = json.loads(raw)
+                typ = msg.get("type", "")
+                data = {k: v for k, v in msg.items() if k != "type"}
+                self._queue.put_nowait(SessionEvent(type=typ, t_ms=self.now_ms(), data=data))
+        except Exception:  # noqa: BLE001 — closure (normal or abnormal) ends the stream
+            pass
+        finally:
+            self._queue.put_nowait(None)

converse_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: converse-sdk
+Version: 0.1.0
+Summary: Headless Python SDK for the Trelis Converse realtime voice API.
+Project-URL: Documentation, https://converse.trelis.com/docs/api/
+Project-URL: Homepage, https://converse.trelis.com/
+Author: Trelis Research
+License-Expression: LicenseRef-Proprietary
+Keywords: converse,realtime,speech,voice,voice-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# converse-sdk
+
+The headless Python SDK for the
+[Trelis Converse realtime voice API](https://converse.trelis.com/docs/api/).
+Use it for telephony bridges, services, evaluations and custom devices.
+
+```sh
+uv add converse-sdk
+```
+
+The session-loop fragment below assumes your media layer supplies `mic_frame` and `play_audio`,
+and your application supplies `run_tool`:
+
+```python
+import os
+
+from converse_sdk import ConverseMode, ConverseSession
+
+session = await ConverseSession.connect(
+    "wss://converse.trelis.com/ws",
+    api_key=os.environ["CONVERSE_API_KEY"],
+    mode=ConverseMode(
+        instructions="Help callers with their orders.",
+        greeting="Hello, how can I help?",
+    ),
+)
+
+async with session:
+    await session.send_audio(mic_frame)  # PCM16 little-endian mono at 16 kHz
+
+    async for event in session.events():
+        if event.type == "audio":
+            play_audio(event.audio)  # Float32 mono at 16 kHz
+        elif event.type == "tool_call":
+            result = await run_tool(event.data["name"], event.data["args"])
+            await session.send_tool_result(event.data["id"], result)
+```
+
+The SDK deliberately does not own capture, playback, pacing or echo cancellation. Live playback
+integrations must implement the
+[playback contract](https://converse.trelis.com/docs/api/reference/#playback-contract).
+
+See the [complete Python reference](https://converse.trelis.com/docs/api/reference/#python-sdk)
+and the [Twilio bridge quickstart](https://converse.trelis.com/docs/api/reference/#twilio).
+
+Proprietary software. All rights reserved.

converse_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+converse_sdk/__init__.py,sha256=dAfTd2nlRmBS6Zu1JOFM6a65XF06MIM3Rp7n73Vm5TU,664
+converse_sdk/audio.py,sha256=HJUr8VetVoSx5UNnmdOGY2KrbG8OzMq9NMh8V-_A_7E,1618
+converse_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+converse_sdk/recorder.py,sha256=342EVHZ7kC5Ag7iqSYsx4pmnxMzzuD6OmgRufsjJgXU,3968
+converse_sdk/session.py,sha256=Q6TRiTI37R-lVlmMQ0XNdCAeoFoBiF17ebFcWua_lps,12572
+converse_sdk-0.1.0.dist-info/METADATA,sha256=nK6j2P3DkpFFJLMjL-rKdTIBAHNZwHbEz4qa6U44uBo,2378
+converse_sdk-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+converse_sdk-0.1.0.dist-info/RECORD,,

converse_sdk-0.1.0.dist-info/WHEEL

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