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

{avartha_python_sdk-0.0.2 → avartha_python_sdk-0.0.3}/AGENTS.md

@@ -13,4 +13,9 @@ 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.
 
+Keep customer-facing docs free of internal commit IDs, private source links,
+and internal issue references. Record verification provenance with the tests.
+Preserve existing audit and validation records, including their evidence, when
+updating customer-facing guides.
+
 Run `make check` before finishing. Do not add bot attribution to commits or docs.

{avartha_python_sdk-0.0.2 → avartha_python_sdk-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.2
+Version: 0.0.3
 Summary: Python clients for Avartha inference, voice agents, and platform management
 Author-email: "Avartha Inc." <team@avartha.ai>
 License-Expression: LicenseRef-Avartha-Proprietary
@@ -38,9 +38,9 @@ Dynamic: license-file
 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
@@ -52,17 +52,15 @@ 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)
@@ -111,6 +109,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)
@@ -129,14 +129,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
@@ -161,6 +161,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)
@@ -174,11 +176,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
@@ -216,11 +218,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`.
@@ -229,8 +239,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
 
@@ -244,22 +254,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
@@ -278,46 +289,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)
 ```
 
@@ -326,17 +347,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
@@ -345,20 +370,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
@@ -369,13 +394,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
 
@@ -393,34 +417,25 @@ 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. For SDK development and checks,
+see [Contributing](CONTRIBUTING.md).