avartha-python-sdk 0.0.2__tar.gz → 0.0.4__tar.gz

avartha_python_sdk-0.0.4/MANIFEST.in

@@ -0,0 +1,9 @@
+# Start from an allowlist, including when setuptools discovers tracked files.
+global-exclude *
+include LICENSE THIRD_PARTY_NOTICES README.md pyproject.toml setup.py MANIFEST.in
+recursive-include src/avartha *.py py.typed
+exclude src/avartha/_version.py
+recursive-include src/avartha_python_sdk.egg-info PKG-INFO SOURCES.txt dependency_links.txt requires.txt top_level.txt
+include docs/pypi.md docs/compatibility.md docs/migration.md docs/platform.md
+include examples/realtime.py examples/tts.py examples/tts_multi_context.py
+include examples/realtime_asr.py examples/endpoints.py

avartha_python_sdk-0.0.4/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: avartha-python-sdk
+Version: 0.0.4
+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 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
+
+```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, endpoints | `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.

{avartha_python_sdk-0.0.2 → avartha_python_sdk-0.0.4}/README.md

@@ -5,9 +5,9 @@
 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:
+**Familiar Python interfaces for OpenAI Realtime and ElevenLabs speech.** Change
+client, type, and exception imports, then configure Avartha credentials, URLs,
+and model/voice IDs. The supported APIs use the same method names and event loops:
 
 ```diff
 -from openai import OpenAI, AsyncOpenAI
@@ -19,20 +19,17 @@ the upstream resource methods, request types, response objects, and event loops:
 +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. See the guides
-below for compatibility details and historical test results.
-[Migration details](docs/migration.md) · [Protocol audit and triage](docs/audit/report.md) · [Initial live test results](docs/preview-testing.md)
+Neither vendor SDK needs to be installed. Avartha supports Realtime text,
+streaming speech, HTTP discovery, and platform management. Managed inference is
+**WebSocket-only**; Chat Completions, Responses, and HTTP speech inference are
+unavailable. See the guides below for supported features and migration steps.
 
 ## Documentation
 
-- [Drop-in migration from OpenAI and ElevenLabs](docs/migration.md)
+- [Migrating 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
 
@@ -78,6 +75,8 @@ with OpenAI() as client:
             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)
@@ -96,14 +95,14 @@ with OpenAI() as client:
         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.
+Model availability depends on your workspace, environment, and tier. Replace
+the example IDs with models returned for your key and the protocol you need:
+`openai_realtime`, `elevenlabs_tts`, or `elevenlabs_asr`.
 
 ## Async usage
 
-Use `AsyncOpenAI`, await operations, and iterate with `async for`. Request
-parameters and event types remain the upstream SDK's own.
+Use `AsyncOpenAI`, await operations, and iterate with `async for`. The sync and
+async clients accept the same request parameters and return the same event types.
 
 ```python
 import asyncio
@@ -128,6 +127,8 @@ async def main():
                 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)
@@ -141,11 +142,11 @@ asyncio.run(main())
 ## 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.
+It provides ElevenLabs-compatible realtime speech and discovery APIs.
 
 ### Text to speech
 
-Discover voices for the selected TTS model using the upstream request options:
+Discover voices for the selected TTS model using `request_options`:
 
 ```python
 from avartha import ElevenLabs
@@ -183,11 +184,19 @@ with ElevenLabs() as client:
             output.writeframes(chunk)
 ```
 
-Avartha's helper sends the gateway-compatible envelope and defaults to
-`pcm_24000`. Use `AsyncElevenLabs` and `async for` for async TTS; `text` accepts
-either a regular iterable or an async iterable. Run the
+The default output format is `pcm_24000`. Use `AsyncElevenLabs` and `async for`
+for async TTS; the async client's `text` accepts either a regular iterable or
+an async iterable. Run the
 [TTS example](examples/tts.py) with `--async` to use that client.
 
+Text fragments are forwarded as supplied, without waiting for word or sentence
+boundaries or adding spaces. Include any intended whitespace in your text.
+The Avartha Platform handles buffering and segmentation. Available audio continues
+to arrive while the text producer is paused; when synthesis starts depends on the model.
+
+The SDK's single-context and multi-context TTS helpers always use
+`auto_mode=true`. `auto_mode=False` and `default_mode` are not supported.
+
 For multiple utterances on one connection, use `connect_multi_context` on
 either client. A background consumer can iterate over the session before contexts
 are created and between turns; messages are keyed by `message.context_id`.
@@ -196,8 +205,8 @@ Session iteration waits until the connection closes via `close_socket()` or when
 its `with` or `async with` block exits. See the [multi-context example](examples/tts_multi_context.py)
 and [TTS lifecycle details](docs/compatibility.md#realtime-tts).
 
-HTTP `text_to_speech.stream` and `.convert` remain inherited methods but are not
-supported by managed inference.
+HTTP `text_to_speech.stream` and `.convert` are not provided by this SDK;
+managed inference uses the realtime methods above.
 
 ### Speech to text
 
@@ -211,22 +220,23 @@ python examples/realtime_asr.py mistralai/voxtral-mini-4b-realtime-2602 speech-1
 ```
 
 `previous_text` is optional text context for transcription. When omitted from
-`connection.send` data, the official SDK sends `null`, meaning no context.
-Current preview accepts this default; existing audio-send code works unchanged,
-with no empty-string workaround needed.
+`connection.send` data, Avartha sends `null`, meaning no context. You can omit
+this field when streaming audio without prior text.
 
 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.
+Agent management, tools, knowledge bases, and conversation sessions/history are
+currently unavailable. Accessing `client.conversational_ai` raises
+`NotImplementedError`.
+
+ElevenLabs-compatible `conversational_ai` support is planned for an upcoming
+release, including agent creation, tools, knowledge-base documents, and
+conversations.
 
-Against a service that implements ElevenLabs agent management, the original
-calls work unchanged:
+The following example previews the planned API. It requires that future SDK
+release and a service implementing the corresponding agent endpoints:
 
 ```python
 from avartha import ElevenLabs
@@ -245,46 +255,56 @@ with ElevenLabs(base_url="https://your-compatible-agent-service") as client:
     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)
+The planned `avartha.conversational_ai` namespace will also include
+`Conversation`, `AsyncConversation`, and `ClientTools`.
 
 ## Using types
 
-Continue importing types and exceptions from the upstream packages. The adapter
-returns their original objects:
+Import types and exceptions from Avartha. The SDK provides its own classes for
+the supported APIs, preserving upstream fields and serialization methods.
+Neither `openai` nor `elevenlabs` needs to be installed:
 
 ```python
 from avartha import OpenAI
-from openai.types import Model
+from avartha.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.
+Use `avartha.types.realtime` for OpenAI-compatible Realtime events and
+`avartha.types.speech` for ElevenLabs-compatible speech types. These namespaces
+cover the APIs supported by Avartha. Platform management responses are JSON
+dictionaries and lists.
+
+ElevenLabs-compatible transcription options are also available from the root:
+
+```python
+from avartha import AudioFormat, CommitStrategy, RealtimeAudioOptions
+
+options = RealtimeAudioOptions(
+    model_id="your-avartha-asr-model",
+    audio_format=AudioFormat.PCM_16000,
+    sample_rate=16000,
+    commit_strategy=CommitStrategy.VAD,
+)
+```
 
 ## Handling errors
 
-Keep existing vendor exception handlers. For HTTP discovery:
+Import exception classes from Avartha too; upstream exception classes will not
+catch Avartha's exceptions. For HTTP discovery:
 
 ```python
-import openai
-from avartha import OpenAI
+from avartha import APIConnectionError, APIStatusError, OpenAI
 
 with OpenAI() as client:
     try:
         client.models.list()
-    except openai.APIConnectionError as error:
+    except APIConnectionError as error:
         print("Connection failed:", error)
-    except openai.APIStatusError as error:
+    except APIStatusError as error:
         print("Request failed:", error.status_code, error.request_id)
 ```
 
@@ -293,17 +313,21 @@ 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.
+ElevenLabs-compatible HTTP/TTS helper errors, including speech HTTP network
+failures and timeouts, use `avartha.ApiError`.
+ASR also emits `RealtimeEvents.ERROR`.
 
 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.
+network failures and timeouts use `avartha.ApiError`.
+
+For speech and management HTTP request failures without a server response,
+`ApiError.status_code` and `ApiError.headers` are `None`, and `ApiError.body`
+describes the failure. The original exception is available as `error.__cause__`.
 
 ## Retries and timeouts
 
-Upstream constructor options pass through:
+Set timeouts and retries for OpenAI-compatible HTTP discovery on the client:
 
 ```python
 from avartha import OpenAI
@@ -312,20 +336,20 @@ 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
+HTTP and WebSocket retry settings are separate. The OpenAI-compatible clients accept
 `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.
+cancelling. ElevenLabs `timeout` configures HTTP calls; it does not set a
+WebSocket receive deadline. Platform management writes are never retried
+automatically. See [timeouts and cleanup](docs/migration.md#timeouts-retries-and-closing-clients).
 
 ## Configuration
 
 | Client | Meaning of explicit `base_url` |
 | --- | --- |
 | `OpenAI`, `AsyncOpenAI` | Full inference base: `https://platform.preview.avartha.ai/inference/serverless/openai/v1` |
-| `ElevenLabs`, `AsyncElevenLabs` | Dialect root before `/v1`: `https://platform.preview.avartha.ai/inference/serverless/elevenlabs` |
+| `ElevenLabs`, `AsyncElevenLabs` | Speech service root before `/v1`: `https://platform.preview.avartha.ai/inference/serverless/elevenlabs` |
 | `Avartha`, `AsyncAvartha`, `Control`, `AsyncControl` | Platform root: `https://platform.preview.avartha.ai` |
 
 Without an explicit URL, protocol clients derive their URL from
@@ -336,13 +360,12 @@ precedence over `tier`. `AVARTHA_ELEVENLABS_BASE_URL` overrides the derived spee
 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.
+Vendor default keys and base URL variables are not substituted.
 [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.
+Always close clients or use context managers. OpenAI manages and closes its HTTP
+client; custom `http_client` arguments are unsupported. ElevenLabs and Control
+close only HTTP clients they created. Close active WebSocket sessions separately.
 
 ## Platform management
 
@@ -360,34 +383,24 @@ with Avartha() as client:
 ```
 
 `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,
+`client.realtime` and `client.models` are shortcuts to the corresponding OpenAI
+resources, including model listing and retrieval. `AsyncAvartha`, `Control`,
+and `AsyncControl` are available too. Workspace administration includes
+organization creation, renaming, deletion, leaving, member roles, and invitation
+creation, revocation, and acceptance. For example,
+`client.control.organizations.members.list("your-workspace-id")` lists members.
+See [workspace administration](docs/platform.md#workspace-administration) for
+sync/async usage and server permissions.
+
+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 PortAudio and the `audio` extra:
-
-```sh
-python -m pip install 'avartha-python-sdk[audio]'
-```
-
-For development, clone the repository and run:
-
-```sh
-git clone https://github.com/avartha/avartha-python-sdk.git
-cd avartha-python-sdk
-python -m venv .venv
-. .venv/bin/activate
-make install-dev
-make check
-```
+## Examples
 
-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.
+Runnable examples cover [Realtime text](examples/realtime.py),
+[TTS](examples/tts.py), [multi-context TTS](examples/tts_multi_context.py),
+[ASR](examples/realtime_asr.py), and [endpoint management](examples/endpoints.py).
+Microphone capture and speaker playback are handled by your application.
 
-Live testing is explicit and consumes inference credits. See
-[preview testing](docs/preview-testing.md) for the runner and current results.
+Running inference examples consumes credits.

{avartha_python_sdk-0.0.2 → avartha_python_sdk-0.0.4}/THIRD_PARTY_NOTICES

@@ -1,15 +1,15 @@
 Third-party schema notices
 ==========================
 
-The WebSocket data declarations under src/avartha/types/realtime, responses,
-shared, shared_params, model.py, and websocket_connection_options.py are derived from
-OpenAI Python 3.13.0. Model discovery contracts are captured in
-tests/fixtures/openai-models-3.13.0.json. Declarations under
-src/avartha/types/speech are derived from ElevenLabs Python 2.68.0.
-Avartha removed descriptions and legacy Pydantic branches and replaced runtime
-imports. Speech contract source hashes are in tests/fixtures/elevenlabs-2.68.0.json
-and tests/fixtures/speech-http-2.68.0.json. These notices
-apply to those declarations; the Avartha proprietary LICENSE remains unchanged.
+The declarations in avartha.types.realtime, avartha.types.responses,
+avartha.types.shared, avartha.types.shared_params, avartha.types.model, and
+avartha.types.websocket_connection_options are derived from OpenAI Python
+3.13.0. The declarations in avartha.types.speech are derived from ElevenLabs
+Python 2.68.0.
+
+Avartha modified these declarations by removing descriptions and legacy
+Pydantic branches and replacing runtime imports. These notices apply to those
+declarations; the Avartha proprietary LICENSE remains unchanged.
 
 OpenAI Python 3.13.0
 --------------------