converse-sdk

The headless Python SDK for the Trelis Converse realtime voice API. Use it for telephony bridges, services, evaluations and custom devices.

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:

import os

from converse_sdk import ConverseMode, ConverseSession, ToolDefinition

lookup_tool: ToolDefinition = {
    "name": "lookup_order",
    "description": "Look up an order by ID.",
    "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}},
    "read_only": True,
    "wait_for_tool": True,
    "status_label": "order lookup",
    "deferred": True,
    "deferred_timeout": 7200,
    "notify_on_complete": True,
}

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?",
        tools=[lookup_tool],
    ),
)

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)
        elif event.type == "tool_deferred_resume":
            resume_host_job(event.data["handle"])

For work that should release the voice turn immediately, call send_tool_deferred(id, handle, status_label=...) before continuing it in the background. Save session.resume_token from the connected session; after a transport loss, pass it as resume_token=... to the replacement ConverseSession.connect(...) call so pending jobs are re-announced as tool_deferred_resume events within the broker's bounded resume window.

The SDK deliberately does not own capture, playback, pacing or echo cancellation. Live playback integrations must implement the playback contract.

See the complete Python reference and the Twilio bridge quickstart.

WebRTC transport (experimental)

Experimental: the API is stable, but this transport is newly shipped and still being hardened on real networks; ws remains the default and recommended fallback.

Pass transport="webrtc" to ConverseSession.connect(...) to carry the session over WebRTC (UDP) instead of the default WebSocket. Requires pip install "converse-sdk[webrtc]" (or uv add). ws remains the default; most headless callers are fine on it. See the Python guide's WebRTC section.

Proprietary software. All rights reserved.