converse-sdk 0.1.0__tar.gz

converse_sdk-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+tmp/
+.venv/
+__pycache__/
+*.pyc
+MEMORY.md
+
+eval/out/
+eval/results/
+
+# Third-party / regenerable eval audio (fetch via eval/runners/*.py); manifests are tracked.
+# noise_beds/local/ is kept: locally-recorded beds (e.g. keyboard) cannot be regenerated.
+eval/datasets/noise_beds/demand_clean/
+eval/datasets/aec_challenge/real/
+eval/datasets/audio_frontend/fixtures/
+
+.env
+*.env
+!.env.example
+.runpod_endpoint
+eval/runners/aec_apm/target/
+turncast/checkpoints/
+turncast/data/synth/
+# turncast tooling defaults write repo-root checkpoints/ when run from the root (see vnext/train.py)
+/checkpoints/
+
+# pulled session captures (pull-sessions.sh default dest when run from repo root)
+live_sessions/
+
+# generated listen-QA page (rebuild: uv run eval/runners/review/span_review_page.py)
+eval/datasets/frontend_pairs/span_review.html
+eval/datasets/frontend_pairs/backchannel_onsets.html
+.claude/

converse_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,46 @@
+# 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/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-0.1.0/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-0.1.0/converse_sdk/py.typed

@@ -0,0 +1 @@
+

converse_sdk-0.1.0/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-0.1.0/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/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "converse-sdk"
+version = "0.1.0"
+description = "Headless Python SDK for the Trelis Converse realtime voice API."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [
+    { name = "Trelis Research" },
+]
+keywords = ["voice", "voice-ai", "realtime", "speech", "converse"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=1.26",
+    "websockets>=12.0",
+]
+
+[project.urls]
+Documentation = "https://converse.trelis.com/docs/api/"
+Homepage = "https://converse.trelis.com/"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["converse_sdk"]

converse_sdk-0.1.0/tests/test_session.py

@@ -0,0 +1,186 @@
+"""Offline ConverseSession tests against a scripted in-process websocket "broker".
+
+These pin the SDK's wire behavior (start frame shape, event surfacing, tool messages) and
+TurnRecorder's canceled/interrupted audio semantics without any live services.
+"""
+import asyncio
+import json
+
+import numpy as np
+import pytest
+import websockets
+from websockets.asyncio.server import serve
+
+from converse_sdk import ConverseError, ConverseMode, RelayMode, ConverseSession, TurnRecorder, float32_to_pcm16
+
+
+def run_with_server(handler, client):
+    """Serve `handler` on port 0 and run `client(port)` under one asyncio loop."""
+    async def main():
+        async with serve(handler, "127.0.0.1", 0, max_size=None) as server:
+            port = server.sockets[0].getsockname()[1]
+            return await asyncio.wait_for(client(port), timeout=10)
+    return asyncio.run(main())
+
+
+def test_connect_sends_start_and_surfaces_events_and_audio():
+    seen = {}
+
+    async def handler(ws):
+        seen["start"] = json.loads(await ws.recv())
+        await ws.send(json.dumps({"type": "ready"}))
+        pcm = await ws.recv()                       # one uplink frame
+        seen["uplink"] = pcm
+        await ws.send(json.dumps({"type": "turn", "ttfa_ms": 123}))
+        await ws.send(np.array([0.5, -0.5], dtype="<f4").tobytes())
+        await ws.send(json.dumps({"type": "utterance", "text": "hi there"}))
+        await ws.send(json.dumps({"type": "done"}))
+
+    async def client(port):
+        session = await ConverseSession.connect(
+            f"ws://127.0.0.1:{port}/ws", session_id="t1", mode=ConverseMode(
+                greeting=False,
+                tools=[{"name": "f", "parameters": {"type": "object"}, "read_only": True}]))
+        events = []
+        async with session:
+            await session.send_audio(np.zeros(160, dtype=np.float32))
+            async for ev in session.events():
+                events.append(ev)
+                if ev.type == "done":
+                    break
+        return events
+
+    events = run_with_server(handler, client)
+    assert seen["start"]["type"] == "start"
+    assert seen["start"]["session_id"] == "t1"
+    assert seen["start"]["audio"]["sr"] == 16000
+    assert seen["start"]["mode"]["greeting"] is False
+    assert seen["start"]["mode"]["tools"][0]["name"] == "f"
+    assert seen["uplink"] == float32_to_pcm16(np.zeros(160, dtype=np.float32))
+    types = [e.type for e in events]
+    assert types == ["ready", "turn", "audio", "utterance", "done"]
+    turn = events[1]
+    assert turn.data["ttfa_ms"] == 123 and turn.t_ms >= 0
+    audio = events[2]
+    assert np.allclose(audio.audio, [0.5, -0.5])
+
+
+def test_mode_types_reject_wrong_runtime_values():
+    invalid = [
+        lambda: ConverseMode(voice=1),
+        lambda: ConverseMode(instructions={}),
+        lambda: ConverseMode(tools="not-a-list"),
+        lambda: ConverseMode(web_search="false"),
+        lambda: ConverseMode(flow=1),
+        lambda: RelayMode(provider="gemini-live", model=1),
+        lambda: RelayMode(provider="gemini-live", voice=[]),
+        lambda: RelayMode(provider="gemini-live", web_search="false"),
+    ]
+    for construct in invalid:
+        with pytest.raises(TypeError):
+            construct()
+
+
+def test_unserializable_mode_fails_before_websocket_connect(monkeypatch):
+    calls = 0
+
+    async def fail_if_called(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        raise AssertionError("websocket opened before start serialization")
+
+    monkeypatch.setattr(websockets, "connect", fail_if_called)
+    with pytest.raises(TypeError, match="JSON serializable"):
+        asyncio.run(ConverseSession.connect(
+            "ws://example.invalid/ws", mode=ConverseMode(tools=[{"schema": object()}])))
+    assert calls == 0
+
+
+
+def test_mode_types_make_invalid_capability_combinations_unserializable():
+    combined = ConverseMode(tools=[], web_search=True)
+    assert combined.to_wire()["tools"] == [] and combined.to_wire()["web_search"] is True
+    relay = RelayMode(provider="gemini-live", model="gemini-live")
+    assert relay.to_wire() == {
+        "kind": "relay", "provider": "gemini-live", "model": "gemini-live",
+        "web_search": False,
+    }
+
+def test_connect_raises_on_broker_error():
+    async def handler(ws):
+        await ws.recv()
+        await ws.send(json.dumps({"type": "error", "detail": "unauthorized"}))
+
+    async def client(port):
+        with pytest.raises(ConverseError, match="unauthorized"):
+            await ConverseSession.connect(f"ws://127.0.0.1:{port}/ws")
+        return True
+
+    assert run_with_server(handler, client)
+
+
+def test_tool_result_and_cancel_wire_shape():
+    frames = []
+
+    async def handler(ws):
+        await ws.recv()
+        await ws.send(json.dumps({"type": "ready"}))
+        frames.append(json.loads(await ws.recv()))
+        frames.append(json.loads(await ws.recv()))
+        frames.append(json.loads(await ws.recv()))
+
+    async def client(port):
+        async with await ConverseSession.connect(f"ws://127.0.0.1:{port}/ws") as session:
+            await session.send_tool_result("call-1", {"status": "ok", "rows": [1, 2]})
+            await session.send_tool_cancel("call-2")
+            await session.send_tool_progress("call-3", "running the test suite")
+            await asyncio.sleep(0.05)
+        return True
+
+    assert run_with_server(handler, client)
+    assert frames[0] == {"type": "tool_result", "id": "call-1",
+                         "content": {"status": "ok", "rows": [1, 2]}}
+    assert frames[1] == {"type": "tool_cancel", "id": "call-2"}
+    assert frames[2] == {"type": "tool_progress", "id": "call-3",
+                         "note": "running the test suite"}
+
+
+def test_turn_recorder_canceled_clears_only_current_turn_and_interrupted_keeps():
+    from converse_sdk.session import SessionEvent
+
+    rec = TurnRecorder()
+    a1 = np.full(160, 0.1, dtype=np.float32)
+    rec.feed(SessionEvent("turn", 100.0))
+    rec.feed(SessionEvent("audio", 150.0, audio=a1))
+    rec.feed(SessionEvent("done", 500.0))
+    rec.mark_turn_boundary()
+
+    # Turn 2: audio arrives, then a pre-audible rescind wipes ONLY turn 2's audio.
+    a2 = np.full(80, 0.2, dtype=np.float32)
+    rec.feed(SessionEvent("audio", 700.0, audio=a2))
+    rec.feed(SessionEvent("canceled", 750.0))
+    assert rec.canceled_count == 1
+    assert len(rec.waveform()) == 160          # turn 1 audio intact
+    assert rec.first_audio_ms is None          # re-latches on the reply actually heard
+
+    # The re-answer arrives, then a barge: interrupted keeps the heard fragment.
+    a3 = np.full(320, 0.3, dtype=np.float32)
+    rec.feed(SessionEvent("audio", 900.0, audio=a3))
+    rec.feed(SessionEvent("interrupted", 1000.0))
+    assert rec.interrupted_count == 1
+    assert len(rec.waveform()) == 160 + 320
+
+
+def test_aligned_waveform_places_audio_at_arrival_times():
+    from converse_sdk.session import SessionEvent
+
+    rec = TurnRecorder(sr=16000)
+    burst = np.ones(1600, dtype=np.float32)     # 100 ms of audio
+    rec.feed(SessionEvent("audio", 1000.0, audio=burst))          # arrives at 1.0 s
+    rec.feed(SessionEvent("audio", 1010.0, audio=burst))          # burst right behind it
+    wave = rec.aligned_waveform(end_ms=2000.0)
+    assert len(wave) == 32000                   # exactly 2 s timeline
+    assert not wave[: int(0.99 * 16000)].any()  # silence before first arrival
+    start = 16000
+    assert wave[start: start + 3200].all()      # both frames contiguous from 1.0 s
+    assert not wave[start + 3200:].any()