Metadata-Version: 2.4
Name: avartha-python-sdk
Version: 0.0.5
Summary: Python clients for Avartha Realtime text, streaming speech, and platform management
Author-email: "Avartha Inc." <team@avartha.ai>
License-Expression: LicenseRef-Avartha-Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: websockets<16,>=15.0.1
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: typing-extensions<5,>=4.12
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=1; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Requires-Dist: mypy<3,>=2.3; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: setuptools-scm<9,>=8; extra == "dev"
Dynamic: license-file

# Avartha Python SDK

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

## Install

```sh
python -m pip install avartha-python-sdk
```

Configure your Avartha API key and platform root:

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

Clients default to the preview platform and support only serverless inference.
Set `AVARTHA_BASE_URL` for another environment. Use model and voice IDs available
to your workspace. Unsupported tier values and dedicated inference URLs raise
`ConfigurationError` locally before any request.

## Discover models

```python
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:

```python
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

| Workflow | Client and interface |
| --- | --- |
| Realtime text | `OpenAI` / `AsyncOpenAI`: `realtime.connect` |
| Model discovery | `OpenAI` / `AsyncOpenAI`: `models.list`, `models.retrieve` |
| Streaming TTS | `ElevenLabs` / `AsyncElevenLabs`: `text_to_speech.convert_realtime` |
| Multi-context TTS | `ElevenLabs` / `AsyncElevenLabs`: `text_to_speech.connect_multi_context` |
| Realtime ASR | `await client.speech_to_text.realtime.connect(...)` on either speech client |
| Speech discovery | Speech clients: models, voices, voice settings, ASR languages |
| Workspaces, members, invitations | `Control` / `AsyncControl` |
| Combined inference and management | `Avartha` / `AsyncAvartha` |

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](https://pypi.org/project/avartha-python-sdk/#files)
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.
