avartha-python-sdk 0.0.1__tar.gz

avartha_python_sdk-0.0.1/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Avartha maintainers own all repository content.
+* @avartha/maintainers
+
+# Keep repository governance under maintainer review.
+/.github/ @avartha/maintainers

avartha_python_sdk-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  merge_group:
+    types: [checks_requested]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  check:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0  # setuptools_scm derives the version from git tags
+          fetch-tags: true
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install -e '.[dev]'
+      - run: make check

avartha_python_sdk-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish Release to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  IS_NIGHTLY_BUILD: "false"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          # setuptools_scm needs the full history and the tags to derive a version.
+          fetch-depth: 0
+          fetch-tags: true
+          ref: ${{ github.event.release.tag_name || github.ref }}
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip build twine
+      - name: Verify version from tag
+        # Refuse to build off an untagged commit: setuptools_scm would guess the
+        # next version and we would publish a release nobody tagged.
+        run: |
+          git describe --exact-match --tags HEAD
+          python -c "from setuptools_scm import get_version; print('scm version:', get_version())"
+      - run: python -m build
+      - name: Check distribution
+        run: |
+          twine check dist/*
+          ls -la dist/
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    environment:
+      name: pypi
+      url: https://pypi.org/p/avartha-python-sdk
+    permissions:
+      # Required for Trusted Publishing; no API token is stored in this repo.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist/

avartha_python_sdk-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+src/avartha/_version.py
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+.env

avartha_python_sdk-0.0.1/AGENTS.md

@@ -0,0 +1,16 @@
+# Avartha Python SDK
+
+Use Python 3.12+, a src layout, typed public APIs, and the Makefile targets.
+Preserve the Avartha proprietary LICENSE notice inherited from Vidhi.
+Run `git status --short` before edits. Keep changes scoped.
+
+Preserve upstream OpenAI and ElevenLabs method signatures, event types, wire
+payloads, and exception classes. Prefer the official dependencies to recreating
+vendor protocols. Cover adapters with HTTP contract tests and real local
+WebSocket tests. Never silently route an Avartha key to a vendor hostname.
+
+Only expose platform endpoints verified against avartha/platform. Document
+server prerequisites separately from SDK support. Keep private SDK attribute
+access isolated and pin the dependency range it was tested against.
+
+Run `make check` before finishing. Do not add bot attribution to commits or docs.

avartha_python_sdk-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+Use Python 3.12+ and run `make install-dev` in a virtual environment.
+`make format` applies formatting; `make check` runs lint, type checking, tests,
+and wheel/source builds. Read AGENTS.md for compatibility rules.
+
+Protocol behavior should come from the official client dependencies. When an
+adapter needs a private upstream attribute, isolate it, constrain the dependency
+version, and add a local WebSocket regression test. Update the compatibility
+matrix when platform support changes; client availability is not server support.
+
+Release steps: update both pyproject.toml and avartha.__version__, run `make check`,
+review the wheel/sdist, tag the reviewed version, then publish through the
+organization's approved package publication process. No publication is automatic.

avartha_python_sdk-0.0.1/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/MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE README.md CONTRIBUTING.md Makefile AGENTS.md
+recursive-include docs *.md *.json *.csv
+recursive-include examples *.py
+recursive-include tests *.py
+include .github/workflows/ci.yml
+include .github/workflows/publish.yml
+include setup.py
+recursive-include scripts *.py

avartha_python_sdk-0.0.1/Makefile

@@ -0,0 +1,17 @@
+PYTHON ?= python
+BUILD_FLAGS ?=
+.PHONY: install-dev lint format test build check
+install-dev:
+	$(PYTHON) -m pip install -e '.[dev]'
+lint:
+	$(PYTHON) -m ruff check .
+	$(PYTHON) -m ruff format --check .
+	$(PYTHON) -m mypy
+format:
+	$(PYTHON) -m ruff check --fix .
+	$(PYTHON) -m ruff format .
+test:
+	$(PYTHON) -m pytest
+build:
+	$(PYTHON) -m build $(BUILD_FLAGS)
+check: lint test build

avartha_python_sdk-0.0.1/PKG-INFO

@@ -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.