Avartha Python SDK

Synchronous and asynchronous Python clients for Avartha Realtime text, streaming speech, and platform management. Requires Python 3.12+.

Install

python -m pip install avartha-python-sdk

Configure your Avartha API key and platform root:

export AVARTHA_API_KEY='avk_...'
export AVARTHA_BASE_URL='https://platform.preview.avartha.ai'

Clients default to the preview platform and the serverless tier. Set AVARTHA_BASE_URL for another environment or tier="dedicated" for dedicated inference. Use model and voice IDs available to your workspace and tier.

Discover models

from avartha import OpenAI

with OpenAI() as client:
    for model in client.models.list():
        print(model.id, model.to_dict().get("protocols", []))

Choose a model supporting openai_realtime for text, elevenlabs_tts for speech synthesis, or elevenlabs_asr for speech recognition.

Generate text

Replace your-avartha-model with a Realtime text model returned by discovery:

from avartha import OpenAI

with OpenAI() as client:
    with client.realtime.connect(model="your-avartha-model") as connection:
        connection.session.update(session={"type": "realtime", "output_modalities": ["text"]})
        connection.conversation.item.create(
            item={
                "type": "message",
                "role": "user",
                "content": [{"type": "input_text", "text": "Explain Python dictionaries."}],
            }
        )
        connection.response.create()
        for event in connection:
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)
            elif event.type == "response.done":
                if event.response.status != "completed":
                    raise RuntimeError(f"Response ended with status: {event.response.status}")
                break
            elif event.type == "error":
                raise RuntimeError(event.error.message)

For asynchronous text generation, use AsyncOpenAI, async with, await, and async for. Close clients and active WebSocket sessions when finished. Inference consumes credits.

Supported workflows

Managed inference uses WebSockets; Chat Completions, Responses, HTTP TTS, and file transcription are unavailable. Agent management and conversation sessions are planned; accessing conversational_ai currently raises NotImplementedError.

Migrating and handling errors

Import clients, types, and exceptions from avartha. Neither the OpenAI nor ElevenLabs SDK needs to be installed. The supported interfaces are compatible with OpenAI Python 3.13.0 and ElevenLabs Python 2.68.0. Model and voice IDs are specific to the selected Avartha environment.

OpenAI-compatible HTTP discovery uses avartha.APIStatusError and avartha.APIConnectionError. Speech HTTP errors use avartha.ApiError. Management HTTP status errors use avartha.PlatformAPIError. Speech and management HTTP network failures also raise avartha.ApiError, with no status or headers and the original exception in __cause__.

Handle Realtime server error events in the receive loop. HTTP timeout and retry settings do not configure WebSocket connections. Management writes are never retried automatically.

Complete guides and examples

The source archive on PyPI includes README.md, customer guides in docs/, and runnable examples in examples/. Download and unpack the archive to read the migration, compatibility, and platform-management guides and run the text, speech, and endpoint examples.