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.
