avartha-python-sdk 0.0.1__py3-none-any.whl

avartha/openai.py

@@ -0,0 +1,106 @@
+"""Import-compatible OpenAI clients configured for Avartha.
+
+Resource methods, response objects, errors, SSE and Realtime connections are
+provided by the official openai package. Continue importing types from openai.
+
+Subclassing alone does not keep an Avartha key on an Avartha host. The official
+constructor reads OPENAI_* variables for credentials, identifiers and headers,
+and accepts arguments that recompute the base URL, so both are fenced below.
+copy() and with_options() rebuild through __init__ and inherit the same fence.
+"""
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from openai import AsyncOpenAI as _AsyncOpenAI
+from openai import OpenAI as _OpenAI
+
+from . import _config
+from ._config import ConfigurationError, Tier
+
+VENDOR_IDENTITY = ("organization", "project", "webhook_secret", "admin_api_key")
+
+
+def _arguments(
+    api_key: str | Callable[[], str] | None,
+    base_url: str | None,
+    tier: Tier,
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    """Upstream constructor arguments, with vendor routing refused."""
+    if kwargs.pop("data_residency", None) is not None:
+        raise ConfigurationError(
+            "data_residency selects an OpenAI-hosted region. Use base_url or tier to "
+            "choose an Avartha service instead."
+        )
+    websocket_base_url = kwargs.pop("websocket_base_url", None)
+    return {
+        "api_key": api_key if callable(api_key) else _config.api_key(api_key),
+        "base_url": _config.openai_url(tier=tier)
+        if base_url is None
+        else _config.not_vendor_host(_config.http_url(str(base_url)), field="base_url"),
+        "websocket_base_url": None
+        if websocket_base_url is None
+        else _config.websocket_override(str(websocket_base_url)),
+        **kwargs,
+    }
+
+
+def _seal(client: Any, arguments: Mapping[str, Any]) -> None:
+    """Restore the caller's identity and headers, then confirm the routing.
+
+    Upstream sources the identity arguments from OPENAI_* variables and merges
+    OPENAI_CUSTOM_HEADERS into the default headers, where an Authorization entry
+    overrides the Avartha bearer. Reinstating exactly what the caller passed
+    discards all of it without re-parsing the environment. Private attribute
+    access is confined here; see the pinned range in pyproject.toml.
+    """
+    for name in VENDOR_IDENTITY:
+        setattr(client, name, arguments.get(name))
+    client._custom_headers = dict(arguments.get("default_headers") or {})
+    client._ambient_authorizations = frozenset()
+    _config.not_vendor_host(str(client.base_url), field="base_url")
+    if client.websocket_base_url is not None:
+        _config.not_vendor_host(str(client.websocket_base_url), field="websocket_base_url")
+
+
+class _WebSocketURL:
+    """Keep constructor, copy, and later assignments on the same URL contract."""
+
+    @property
+    def websocket_base_url(self) -> str | None:
+        return self._avartha_websocket_base_url
+
+    @websocket_base_url.setter
+    def websocket_base_url(self, value: str | None) -> None:
+        self._avartha_websocket_base_url = (
+            None if value is None else _config.websocket_override(str(value))
+        )
+
+
+class OpenAI(_WebSocketURL, _OpenAI):
+    def __init__(
+        self,
+        *,
+        api_key: str | Callable[[], str] | None = None,
+        base_url: str | None = None,
+        tier: Tier = "serverless",
+        **kwargs: Any,
+    ) -> None:
+        arguments = _arguments(api_key, base_url, tier, kwargs)
+        super().__init__(**arguments)
+        _seal(self, arguments)
+
+
+class AsyncOpenAI(_WebSocketURL, _AsyncOpenAI):
+    def __init__(
+        self,
+        *,
+        api_key: str | Callable[[], str] | None = None,
+        base_url: str | None = None,
+        tier: Tier = "serverless",
+        **kwargs: Any,
+    ) -> None:
+        arguments = _arguments(api_key, base_url, tier, kwargs)
+        super().__init__(**arguments)
+        _seal(self, arguments)

avartha_python_sdk-0.0.1.dist-info/METADATA

@@ -0,0 +1,417 @@
+Metadata-Version: 2.4
+Name: avartha-python-sdk
+Version: 0.0.1
+Summary: Python clients for Avartha inference, voice agents, and platform management
+Author-email: "Avartha Inc." <team@avartha.ai>
+License-Expression: LicenseRef-Avartha-Proprietary
+Project-URL: Repository, https://github.com/avartha/avartha-python-sdk
+Project-URL: Issues, https://github.com/avartha/avartha-python-sdk/issues
+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
+Requires-Dist: openai[realtime]<4,>=3.13.0
+Requires-Dist: elevenlabs<2.69,>=2.68.0
+Requires-Dist: httpx<0.29,>=0.28.1
+Requires-Dist: websockets<16,>=15.0.1
+Requires-Dist: pydantic<3,>=2.11
+Provides-Extra: audio
+Requires-Dist: elevenlabs[pyaudio]<2.69,>=2.68.0; extra == "audio"
+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 LLMs,
+streaming speech, and platform management. Requires Python 3.12+.
+
+**Drop-in Python interfaces for OpenAI Realtime and ElevenLabs speech.** Change
+the client import and configure Avartha credentials, URLs, and model IDs. Keep
+the upstream resource methods, request types, response objects, and event loops:
+
+```diff
+-from openai import OpenAI, AsyncOpenAI
++from avartha import OpenAI, AsyncOpenAI
+```
+
+```diff
+-from elevenlabs.client import ElevenLabs, AsyncElevenLabs
++from avartha import ElevenLabs, AsyncElevenLabs
+```
+
+These classes extend the official SDKs. Compatibility depends on the server's
+supported endpoints. Avartha managed inference is **WebSocket-only**; legacy
+Chat Completions, Responses, and HTTP speech calls are retired. Preview testing
+also found ASR and TTS mismatches with the official ElevenLabs client defaults.
+[Migration details](docs/migration.md) · [Protocol audit and triage](docs/audit/report.md) · [Initial live test results](docs/preview-testing.md)
+
+## Documentation
+
+- [Drop-in migration from OpenAI and ElevenLabs](docs/migration.md)
+- [Compatibility and endpoint coverage](docs/compatibility.md)
+- [Protocol audit: defaults, message sequences, errors, and triage](docs/audit/report.md)
+- [Platform management](docs/platform.md)
+- [Runnable examples](examples)
+- [Contributing](CONTRIBUTING.md)
+
+## Installation
+
+The repository is private and the package has not been published to PyPI.
+With GitHub access configured, install from source:
+
+```sh
+git clone https://github.com/avartha/avartha-python-sdk.git
+python -m pip install ./avartha-python-sdk
+```
+
+Set your Avartha API key and platform root:
+
+```sh
+export AVARTHA_API_KEY='avk_...'
+export AVARTHA_BASE_URL='https://platform.avartha.ai'
+```
+
+For preview, set `AVARTHA_BASE_URL=https://platform.preview.avartha.ai`.
+Both protocol clients derive their service URLs from this root. Use model and
+voice IDs from the selected environment; vendor IDs are not mapped automatically.
+
+## Usage
+
+Use the OpenAI Realtime interface for LLM inference. The client reads
+`AVARTHA_API_KEY` from the environment; `api_key` can also be passed explicitly.
+
+```python
+from avartha import OpenAI
+
+with OpenAI() as client:
+    with client.realtime.connect(model="google/gemma-4-26b-a4b-it") 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":
+                break
+            elif event.type == "error":
+                raise RuntimeError(event.error.message)
+```
+
+Keep the connection open for additional turns. Create another conversation item
+and response on the same connection to preserve conversation state.
+
+To discover available models and their enabled protocols:
+
+```python
+from avartha import OpenAI
+
+with OpenAI() as client:
+    for model in client.models.list():
+        print(model.id, model.to_dict().get("protocols", []))
+```
+
+The preview catalog currently includes Gemma for `openai_realtime`, Qwen for
+`elevenlabs_tts`, and Voxtral for `elevenlabs_asr`. Availability is workspace-
+and tier-specific; discovery is authoritative for your key.
+
+## Async usage
+
+Use `AsyncOpenAI`, await operations, and iterate with `async for`. Request
+parameters and event types remain the upstream SDK's own.
+
+```python
+import asyncio
+from avartha import AsyncOpenAI
+
+
+async def main():
+    async with AsyncOpenAI() as client:
+        async with client.realtime.connect(model="google/gemma-4-26b-a4b-it") as connection:
+            await connection.session.update(
+                session={"type": "realtime", "output_modalities": ["text"]}
+            )
+            await connection.conversation.item.create(
+                item={
+                    "type": "message",
+                    "role": "user",
+                    "content": [{"type": "input_text", "text": "Explain Python dictionaries."}],
+                }
+            )
+            await connection.response.create()
+            async for event in connection:
+                if event.type == "response.output_text.delta":
+                    print(event.delta, end="", flush=True)
+                elif event.type == "response.done":
+                    break
+                elif event.type == "error":
+                    raise RuntimeError(event.error.message)
+
+
+asyncio.run(main())
+```
+
+[Complete Realtime example](examples/realtime.py).
+
+## Streaming speech
+
+`ElevenLabs()` defaults to the same Avartha platform root and serverless tier.
+Its method names and wire messages come from the official ElevenLabs package.
+
+### Text to speech
+
+Discover voices for the selected TTS model using the upstream request options:
+
+```python
+from avartha import ElevenLabs
+
+with ElevenLabs() as client:
+    voices = client.voices.get_all(
+        request_options={
+            "additional_query_parameters": {"model_id": "qwen/qwen3-tts-12hz-1.7b-base"}
+        }
+    )
+    for voice in voices.voices:
+        print(voice.voice_id)
+```
+
+Stream text over a WebSocket with `convert_realtime`. Avartha returns PCM;
+select a sample rate supported by your model and write a WAV header for playback.
+This example uses Qwen's 24 kHz output:
+
+```python
+import wave
+from avartha import ElevenLabs
+
+with ElevenLabs() as client:
+    audio = client.text_to_speech.convert_realtime(
+        voice_id="carol",
+        model_id="qwen/qwen3-tts-12hz-1.7b-base",
+        output_format="pcm_24000",
+        text=iter(["Welcome. ", "How can I help?"]),
+    )
+    with wave.open("welcome.wav", "wb") as output:
+        output.setnchannels(1)
+        output.setsampwidth(2)
+        output.setframerate(24000)
+        for chunk in audio:
+            output.writeframes(chunk)
+```
+
+The official TTS helper currently fails on preview: Vajra requires
+`auto_mode=true` and rejects the helper's hardcoded `try_trigger_generation`
+and `generation_config` fields. Raw single- and multi-context TTS both succeeded
+with native pacing, so this is a client/runtime contract mismatch, not a model
+outage. See [the diagnosis](docs/preview-testing.md#tts-vajra-rejects-official-client-defaults).
+The example above preserves the vendor interface and requires that mismatch to
+be resolved on the service.
+
+`convert_realtime` is synchronous, matching upstream. The pinned ElevenLabs SDK
+has no multi-context helper; the platform's `multi-stream-input` WebSocket is a
+separate vendor protocol surface. HTTP `text_to_speech.stream` and `.convert`
+remain inherited methods but are not supported by managed inference.
+[Runnable TTS example](examples/tts.py).
+
+### Speech to text
+
+Realtime ASR uses `await client.speech_to_text.realtime.connect(...)` on both
+ElevenLabs client variants. Send mono PCM16 audio and await a committed transcript.
+[The complete example](examples/realtime_asr.py) reads a WAV file, registers
+transcript/error callbacks, streams chunks, commits, and closes the connection:
+
+```sh
+python examples/realtime_asr.py mistralai/voxtral-mini-4b-realtime-2602 speech-16k.wav
+```
+
+**Preview workaround:** pass `previous_text=""` in each `connection.send` data
+dictionary when you have no context. The official SDK otherwise sends
+`previous_text: null`, which preview currently rejects. Both sync-client and
+async-client ASR sessions passed with the empty-string workaround. This is an
+application option, not a change to the SDK's wire protocol.
+
+File-based HTTP `speech_to_text.convert` is retired on managed inference.
+
+## Agents
+
+The SDK retains the complete ElevenLabs `conversational_ai` namespace, including
+agent creation, tools, knowledge-base documents, and conversations. **Managed
+Avartha agent CRUD does not currently implement the ElevenLabs endpoints.**
+Its native control API uses a different schema. Preview's ElevenLabs-shaped
+conversation-list endpoint did respond successfully.
+
+Against a service that implements ElevenLabs agent management, the original
+calls work unchanged:
+
+```python
+from avartha import ElevenLabs
+
+with ElevenLabs(base_url="https://your-compatible-agent-service") as client:
+    agent = client.conversational_ai.agents.create(
+        name="Support",
+        conversation_config={
+            "agent": {
+                "first_message": "What can I help you with?",
+                "prompt": {"prompt": "Help customers find concise, accurate answers."},
+            },
+            "tts": {"voice_id": "your-voice"},
+        },
+    )
+    print(agent.agent_id)
+```
+
+`Conversation`, `AsyncConversation`, and `ClientTools` are the upstream classes,
+also available from `avartha.conversational_ai`. `AsyncConversation` takes a
+**sync** ElevenLabs client, matching upstream. Agent session execution has local
+contract coverage; it was not exercised against a published preview agent.
+
+- [Agent, tool, and knowledge-base example](examples/agents.py)
+- [Conversation with client tools](examples/conversation.py)
+
+## Using types
+
+Continue importing types and exceptions from the upstream packages. The adapter
+returns their original objects:
+
+```python
+from avartha import OpenAI
+from openai.types import Model
+
+with OpenAI() as client:
+    models: list[Model] = client.models.list().data
+    print([model.to_dict() for model in models])
+```
+
+Use `openai.types` and `elevenlabs.types` for their full type catalogs.
+`avartha.types` is not a replacement namespace. Platform management responses
+are JSON dictionaries and lists.
+
+## Handling errors
+
+Keep existing vendor exception handlers. For HTTP discovery:
+
+```python
+import openai
+from avartha import OpenAI
+
+with OpenAI() as client:
+    try:
+        client.models.list()
+    except openai.APIConnectionError as error:
+        print("Connection failed:", error)
+    except openai.APIStatusError as error:
+        print("Request failed:", error.status_code, error.request_id)
+```
+
+Realtime server errors are events, so handle `event.type == "error"` in the
+receive loop. Inspect `response.done.response.status` for completion, failure,
+or cancellation; a terminal event alone does not prove successful inference.
+Connection failures can raise WebSocket exceptions.
+
+ElevenLabs HTTP/TTS helper errors remain `elevenlabs.core.api_error.ApiError`;
+ASR also emits `RealtimeEvents.ERROR`. The upstream TTS helper can omit a
+server error's details when the gateway closes the socket.
+
+Management failures use `avartha.PlatformAPIError`, retaining the HTTP status,
+response body, field errors, request ID, and `Retry-After` header. Management
+network failures are `httpx` exceptions.
+
+## Retries and timeouts
+
+Upstream constructor options pass through:
+
+```python
+from avartha import OpenAI
+
+with OpenAI(timeout=30.0, max_retries=0) as client:
+    print(client.models.list())
+```
+
+HTTP and WebSocket retry settings are separate. The pinned OpenAI client accepts
+`client.realtime.connect(..., max_retries=0)` to disable automatic reconnection,
+and `websocket_connection_options` for transport settings. Use `asyncio.timeout`
+when an async operation needs an overall deadline. Close active sessions when
+cancelling. ElevenLabs `timeout` does not bound every WebSocket receive; the
+live smoke runner isolates its synchronous TTS helper to enforce a deadline.
+Control-plane writes are never retried automatically.
+
+## Configuration
+
+| Client | Meaning of explicit `base_url` |
+| --- | --- |
+| `OpenAI`, `AsyncOpenAI` | Full inference base: `https://platform.avartha.ai/inference/serverless/openai/v1` |
+| `ElevenLabs`, `AsyncElevenLabs` | Dialect root before `/v1`: `https://platform.avartha.ai/inference/serverless/elevenlabs` |
+| `Avartha`, `AsyncAvartha`, `Control`, `AsyncControl` | Platform root: `https://platform.avartha.ai` |
+
+Without an explicit URL, protocol clients derive their URL from
+`AVARTHA_BASE_URL`. Set `tier="dedicated"` for dedicated inference; there is no
+automatic fallback between tiers. An explicit protocol `base_url` takes
+precedence over `tier`. `AVARTHA_ELEVENLABS_BASE_URL` overrides the derived speech
+root, and an explicit ElevenLabs `base_url` overrides that environment variable.
+
+Keys are read at construction from `AVARTHA_API_KEY` or `api_key`.
+Vendor default keys and base URL variables are not substituted. Keep custom
+upstream transports and type imports where needed; OpenAI 3 uses HTTPX2.
+[Migration configuration](docs/migration.md#configuration).
+
+Always close clients or use context managers. OpenAI retains its upstream
+HTTP-client ownership behavior. ElevenLabs and Control close only clients they
+created. Close active WebSocket sessions separately.
+
+## Platform management
+
+Use the combined `Avartha` client for inference plus management:
+
+```python
+from avartha import Avartha
+
+with Avartha() as client:
+    print(client.control.catalog.models())
+    print(client.control.catalog.skus(provider="modal"))
+    print(client.control.organizations.list())
+    print(client.control.organizations.limits("your-workspace-id"))
+    print(client.control.endpoints.list(workspace_id="your-workspace-id"))
+```
+
+`client.openai` and `client.elevenlabs` are the protocol clients;
+`client.realtime` is a shortcut to the OpenAI resource. `AsyncAvartha`, `Control`,
+and `AsyncControl` are available too. Endpoint creation, readiness waiting,
+scaling, routing, stopping, and deletion are described in the
+[management guide](docs/platform.md).
+
+## Examples and development
+
+For local microphone/speaker support, install the `audio` extra from the
+repository (`python -m pip install '.[audio]'`) and PortAudio.
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+make install-dev
+make check
+```
+
+On images without `ensurepip`, install `uv` and use
+`make check BUILD_FLAGS=--installer=uv`. CI runs on Python 3.12–3.14. Default
+tests use mock HTTP transports and local WebSockets without cloud inference.
+`make build` produces wheel and source archives; publication is separate.
+
+Live testing is explicit and consumes inference credits. See
+[preview testing](docs/preview-testing.md) for the runner and current results.

avartha_python_sdk-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+avartha/__init__.py,sha256=8Lu-1TX1d0p7p0F4llqBn4uUWW5FjFzw28VAu7xqA3Q,1288
+avartha/_config.py,sha256=aH56waOtEHCZiEcS4HmqeL74C28KjSteWhH9fJWTOKQ,5300
+avartha/_realtime_tts.py,sha256=-v1QVEoCKKbvHYCoSBzic_yAmgGtv44dVxG5PyJEn70,5552
+avartha/_version.py,sha256=8OsTLsIVB9D0HdPTmt5rVwyVUBe9xTVGkRslXicxzkM,520
+avartha/client.py,sha256=71fjDILDN4wn0yfJu8I8LtkrD80hG7tG6KlOpb981eg,5520
+avartha/control.py,sha256=X3OGXkpxYmSc418a_g6cQsbW9-2K2y6iEA_eRb3j1c0,14970
+avartha/elevenlabs.py,sha256=WBSO0wnkrBQrtIvCdopQj_5sW_O3riWEWNYJUkNit9k,3946
+avartha/errors.py,sha256=ywIQTnYzZ5Jm8P-lIwlwyRuH7QcOQE-iIB-yi5PjU6w,1333
+avartha/openai.py,sha256=f4o0tDHEMgYQzSQTYJs049cOx0ZtXYT430ya4bD54So,3950
+avartha/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+avartha/conversational_ai/__init__.py,sha256=0-A3bhDzfIugXIkilT36io-4x9SluP61Uuakvu8WI28,407
+avartha/conversational_ai/conversation.py,sha256=CBUsG4VVjh1p6UoSQldG64WtS0ihF_bjfA-M3mKsA4Q,431
+avartha/conversational_ai/default_audio_interface.py,sha256=jxx1V6zJTZgH--MalNUynrnRxXic6gXYoYzzBwQTkME,203
+avartha_python_sdk-0.0.1.dist-info/licenses/LICENSE,sha256=1ulXrK7aq7kBXX1scK6IiOgnbwqpmK6kWIB3CYznVG8,1135
+avartha_python_sdk-0.0.1.dist-info/METADATA,sha256=wjoXaOGIo1YMsX1NL_X6QelNGDvHi9CmzET4BttV4I8,15898
+avartha_python_sdk-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+avartha_python_sdk-0.0.1.dist-info/top_level.txt,sha256=cj2kDXl33tO2IPWPduSTukcwozPnYKOsVUVE9QZRUr0,8
+avartha_python_sdk-0.0.1.dist-info/RECORD,,

avartha_python_sdk-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

avartha_python_sdk-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 Avartha Inc. All Rights Reserved.
+
+This software and its associated documentation (the "Software") are the
+proprietary and confidential property of Avartha Inc.
+
+No license or other right to use, copy, modify, distribute, sublicense,
+publish, display, perform, transmit, or create derivative works of the
+Software is granted except under a separate written agreement with
+Avartha Inc. Any use of the Software without such authorization is strictly
+prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+AVARTHA INC. BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+Third-Party Software
+
+The Software may include or interact with third-party components. Those
+components remain subject to their respective license terms and notices.
+Nothing in this license limits or supersedes rights granted by third-party
+licenses or claims ownership of third-party copyrights.

avartha_python_sdk-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+avartha