Python SDK — Converse

You provide the media layer. The Python SDK does not open a microphone, play audio or cancel echo.

Python SDK reference

The Python SDK is an asynchronous, headless session client. It converts audio frames and exposes events, but it does not open a microphone, play audio or cancel echo.

uv add converse-sdk

import os
from converse_sdk import ConverseMode, ConverseSession

async with await ConverseSession.connect(
    'wss://converse.trelis.com/ws',
    api_key=os.environ['CONVERSE_API_KEY'],
    mode=ConverseMode(web_search=False),
) as session:
    await session.send_audio(processed_frame)
    async for event in session.events():
        if event.type == 'audio':
            play_or_store(event.audio)
        else:
            print(event.type, event.data)

ConverseSession.connect

await ConverseSession.connect(url, *, session_id=None, sr=16000, api_key=None, mode=None, user=None, timezone=None, capabilities=None, connect_timeout_s=15.0)

Returns after ready. Raises ConverseError for a server rejection before ready and TimeoutError when the connection deadline expires.

Methods and helpers

API	Description
`send_audio(chunk)`	Sends bytes as PCM16 or converts a NumPy Float32 array to PCM16.
`stream_audio(audio, sr=16000, chunk_ms=100, realtime=True)`	Chunks and optionally paces a waveform; returns actual send timestamps.
`events()`	Async iterator of `SessionEvent(type, t_ms, data, audio)`.
`now_ms()` / `start_t`	Monotonic session timing relative to the start of `connect()`.
`reset()`	Clears server conversation context on the live connection.
`send_tool_result(id, content)`	Resolves a client tool call with JSON content.
`send_tool_progress(id, note)`	Adds progress to conversation context without resolving the call.
`send_tool_cancel(id)`	Cancels a client-owned tool call.
`send_client_event(event, **fields)`	Sends playback lifecycle events such as `playback_stopped`.
`close()`	Closes the session and its receive task.
`TurnRecorder`	Builds an assistant waveform from session events for recording or offline processing.

ConverseMode accepts voice, instructions, tools, web_search, flow and greeting. Contact us if your integration requires a third-party speech-to-speech relay.

Exported audio helpers are chunk_audio, float32_to_pcm16, pcm16_to_float32, f32le_to_float32 and to_ws_url.