avartha-python-sdk 0.0.3__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.3 → avartha_python_sdk-0.0.4}/README.md

@@ -30,7 +30,6 @@ unavailable. See the guides below for supported features and migration steps.
 - [Compatibility and endpoint coverage](docs/compatibility.md)
 - [Platform management](docs/platform.md)
 - [Runnable examples](examples)
-- [Contributing](CONTRIBUTING.md)
 
 ## Installation
 
@@ -404,5 +403,4 @@ Runnable examples cover [Realtime text](examples/realtime.py),
 [ASR](examples/realtime_asr.py), and [endpoint management](examples/endpoints.py).
 Microphone capture and speaker playback are handled by your application.
 
-Running inference examples consumes credits. For SDK development and checks,
-see [Contributing](CONTRIBUTING.md).
+Running inference examples consumes credits.

{avartha_python_sdk-0.0.3 → 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
 --------------------

{avartha_python_sdk-0.0.3 → avartha_python_sdk-0.0.4}/docs/compatibility.md

@@ -1,73 +1,37 @@
-# Compatibility contract and server coverage
-
-## Owned implementation
-
-The base SDK uses owned OpenAI Realtime and ElevenLabs TTS/ASR WebSocket
-primitives plus typed speech HTTP discovery. Neither vendor SDK nor HTTPX2 is
-an installation, optional, development, or build dependency. Compatibility is
-frozen at OpenAI 3.13.0 and ElevenLabs 2.68.0. All supported clients use owned
-implementations, types, and errors; the legacy package and extra are removed.
-Agents, including conversation and audio runtimes, remain future work.
-
-Local validation covers every pinned OpenAI server-event variant, every text send
-helper, ASR query/payload/error parity, TTS context lifecycle, callbacks,
-reconnection budgets, cancellation, and import isolation. On 2026-09-15,
-[GitHub Actions passed all 16 preview scenarios at `e4b5908`](https://github.com/avartha/avartha-python-sdk/actions/runs/34922936293)
-without vendor SDKs installed: 14 SDK scenarios and two raw multi-context TTS
-protocol scenarios. The [frozen contract](websocket-behavior.md) defines their
-coverage and limits. Server findings below are historical prerequisites,
-separate from SDK compatibility.
-
-## Server baseline
-
-Inspected and tested on 2026-09-13:
-
-- OpenAI Python `3.13.0` and ElevenLabs Python `2.68.0` were the original
-  comparison references. Recorded contracts and owned schemas now preserve
-  compatibility without either SDK dependency or private vendor access.
-- WebSockets `15.0.1`, HTTPX `0.28.1`, and OpenAI's HTTPX2 transport.
-- Current `avartha/platform` main source at
-  [`1992c3ad`](https://github.com/avartha/platform/tree/1992c3ade7089195d622f98ba2676bde90812799).
-- Live preview at `https://platform.preview.avartha.ai`; its deployed source
-  revision was not independently identified. [Initial test report](preview-testing.md).
-- Expanded audit: **219 WebSocket cases, 21 HTTP cases, 6,750 local parser cases,
-  2,221 local state-machine sequences, and 58 triaged findings**.
-  [Full tables and evidence](audit/report.md).
-
-The original platform checkout used during scaffolding was older than preview.
-Its HTTP inference and missing-ElevenLabs assumptions are superseded by this audit.
-
-## What drop-in covers
-
-Owned clients preserve the in-scope method shapes, payloads, event schemas,
-and error attributes with their own types and exceptions. Change the `openai`
-import prefix to `avartha` for the supported Realtime text surface, and use
-Avartha speech clients, types, and errors in place of ElevenLabs imports.
-Compatibility is limited by the selected service and model; the SDK does not
-translate between protocols.
-
-| Surface | SDK support | Current managed platform / live preview |
+# Compatibility and server support
+
+Avartha supports the OpenAI Python 3.13.0 Realtime text interface and the
+ElevenLabs Python 2.68.0 realtime speech and discovery interfaces. Neither
+vendor SDK needs to be installed. Import clients, types, and exceptions from
+Avartha; see the [migration guide](migration.md).
+
+## Supported APIs
+
+SDK support and server availability are separate. Select a model available to
+your workspace and tier, and use only the features that model supports.
+Avartha managed inference uses WebSockets. Discovery and platform management
+use HTTP.
+
+| Surface | SDK support | Server prerequisites |
 | --- | --- | --- |
-| OpenAI Realtime text | Owned sync/async `client.realtime.connect()` clients | Text turns and function tools pass; cancellation, history, overrides, defaults, and recovery have gaps |
-| OpenAI Realtime audio, transcription, images, and older beta API | Explicitly unsupported | Outside the SDK text contract |
-| OpenAI model discovery | Owned sync/async `models.list()` and `models.retrieve(model)` | List and detail verified in platform source; results depend on caller and tier |
-| Chat Completions, Responses, SSE | Explicitly unsupported | Retired; HTTP 400 verified for Chat Completions and Responses |
-| OpenAI HTTP speech/transcription | Explicitly unsupported | Retired in current source |
-| ElevenLabs models and voices | Owned sync/async typed HTTP resources | Model list, voice list/search/detail/settings verified in platform source |
-| ASR languages | `speech_to_text.languages.list(model_id=...)` | Model-routed language discovery; hint availability depends on runtime |
-| Single-context TTS | Sync/async `convert_realtime` with a corrected request envelope | Sends `auto_mode=true`, omits unsupported generation controls, and defaults to `pcm_24000` |
-| Multi-context TTS | Sync/async `connect_multi_context`, returning owned message types | Contexts share one socket; flushing completes a context, and further utterances require new IDs |
-| Realtime ASR | Owned connection/events on both clients | Default `previous_text: null` and explicit empty-string context accepted on preview |
-| ElevenLabs HTTP TTS / file ASR | Not exposed | Not part of the managed WebSocket contract |
-| Agent CRUD, tools, knowledge base | Future implementation | No matching managed agent CRUD; Avartha native management has another schema |
-| Conversation listing | Future implementation | Empty unfiltered list passed; filters fail and populated native rows differ from vendor schemas |
-| Signed published-agent sessions | Future implementation | Routes exist; source rejects the official default initialization; published execution/audio untested |
-| Catalog, organizations, limits, endpoint reads | Avartha sync/async Control | Live reads passed |
-| Workspace lifecycle, members, invitations | Avartha sync/async Control | Verified server routes and local HTTP contracts; live mutations not exercised |
-| API-key administration | Not exposed by Control | Server requires a browser session |
-| Endpoint provisioning, updates, stop, delete | Avartha sync/async Control | Local contracts; live mutations not exercised |
-
-## Standalone OpenAI Realtime text
+| OpenAI Realtime text | Sync/async `realtime.connect()` | A model supporting `openai_realtime` and the requested session options |
+| OpenAI model discovery | Sync/async `models.list()` and `models.retrieve(model)` | A valid Avartha key; results depend on workspace and tier |
+| OpenAI Realtime audio, transcription, images, and beta API | Unavailable | Use speech clients for supported audio workflows |
+| Chat Completions, Responses, SSE, and OpenAI HTTP speech | Unavailable | Managed inference requires a Realtime connection |
+| Speech models and voices | Typed sync/async HTTP discovery | A visible speech model; voice discovery requires a routable TTS model |
+| ASR languages | Sync/async `speech_to_text.languages.list(model_id=...)` | A routable ASR model; language hints depend on the model |
+| Single-context TTS | Sync/async `convert_realtime` | A TTS model and voice supporting the selected PCM format |
+| Multi-context TTS | Sync/async `connect_multi_context` | A model supporting multiple contexts; each utterance needs a new context ID |
+| Realtime ASR | Async connections on both speech clients | An ASR model supporting the supplied audio format and sample rate |
+| HTTP TTS and file transcription | Unavailable | Use realtime speech methods |
+| Agents, tools, knowledge bases, conversation sessions/history | Planned; currently unavailable | Accessing `conversational_ai` raises `NotImplementedError` |
+| Catalog, workspaces, members, invitations, and endpoints | Sync/async `Control` | An Avartha API key with the required workspace role and allocation |
+| API-key administration | Unavailable through `Control` | Use the platform portal; these operations require a browser session |
+
+See [platform management](platform.md) for workspace roles, invitation
+requirements, endpoint readiness, and provisioning.
+
+## OpenAI Realtime text
 
 `avartha.OpenAI` / `Client` and `avartha.AsyncOpenAI` / `AsyncClient` support the
 current `client.realtime.connect()` API from OpenAI 3.13.0. Connection and resource
@@ -82,8 +46,9 @@ creation/cancellation, text deltas, function-call arguments and outputs, raw
 frames, sync/async iteration, callbacks, pre-connection buffering, and opt-in
 reconnection. Payloads and unknown event fields are preserved. Incomplete server
 events are constructed permissively; `to_dict()` and `to_json()` retain the
-pinned serialization behavior. The server must implement each requested feature;
-SDK support does not resolve the historical server gaps listed above.
+serialization methods. The server must implement each requested feature.
+Inspect `response.done.response.status` to distinguish successful completion
+from failure, cancellation, or an incomplete response.
 
 Explicit audio/transcription/image requests raise `UnsupportedOperationError`
 before a frame is sent or queued. Audio event declarations remain importable for
@@ -91,11 +56,9 @@ schema compatibility. Unsupported HTTP resources, including Chat Completions,
 Responses, and Realtime calls/client secrets, raise the same exception.
 The older `client.beta.realtime` wire schema is outside this contract.
 
-Constructor and `copy()` / `with_options()` configuration preserve the pinned
-parameter names and defaults except for the removed `http_client` argument,
-with an additional Avartha `tier` option.
-HTTP-only settings such as `timeout`, `max_retries`, and
-`_strict_response_validation` do not control the WebSocket. Use
+The constructor and `copy()` / `with_options()` accept an Avartha `tier` option;
+custom `http_client` arguments are unsupported.
+HTTP settings such as `timeout` and `max_retries` do not control the WebSocket. Use
 `websocket_connection_options` and the arguments to `realtime.connect()` for
 socket timeouts and retries. Closing a client closes its internally created HTTP
 transport and prevents new connections; each Realtime context owns its socket.
@@ -117,9 +80,8 @@ with OpenAI() as client:
     print(client.models.list().to_json())
 ```
 
-The following routes are verified against
-[`avartha/platform` at `88210801`](https://github.com/avartha/platform/blob/8821080151d3fddbe07619a5ec27163fe8b8be79/crates/api/src/deployment_handlers.rs),
-under `/inference/{serverless|dedicated}/openai/v1`:
+The client uses these HTTP routes under
+`/inference/{serverless|dedicated}/openai/v1`:
 
 | SDK method | GET path | Server prerequisites |
 | --- | --- | --- |
@@ -136,8 +98,8 @@ are unsupported.
 
 The transport is created on the first HTTP request and closed with the client.
 `copy()` and `with_options()` create clients with independently owned transports.
-`timeout`, `max_retries`, and `_strict_response_validation` apply to these HTTP
-calls. Transient failures retry twice by default; `max_retries=0` disables retries.
+`timeout` and `max_retries` apply to these HTTP calls.
+Transient failures retry twice by default; `max_retries=0` disables retries.
 Redirects must stay on the configured origin, including the platform redirect
 that decodes slashes in model IDs. Neither constructor nor copy method accepts
 `http_client`.
@@ -152,9 +114,8 @@ raise `APITimeoutError`. The OpenAI HTTP 422 class is
 
 ## Speech HTTP discovery
 
-The following read-only routes are verified against
-[`avartha/platform` at `cc56bd8d`](https://github.com/avartha/platform/blob/cc56bd8d93a05d575e88069e30d463f0c4b9175d/crates/api/src/deployment_handlers.rs),
-under `/inference/{serverless|dedicated}/elevenlabs`:
+Speech discovery uses these HTTP routes under
+`/inference/{serverless|dedicated}/elevenlabs`:
 
 | SDK method | GET path | Server prerequisites |
 | --- | --- | --- |
@@ -174,9 +135,10 @@ are forwarded without translation and are currently rejected by this server.
 Voice creation, deletion, default settings, model detail, and HTTP speech
 inference are not part of this resource set.
 
-HTTPX is an internal dependency. Applications need only construct the SDK
-client. HTTP contracts and local HTTP servers verify the owned transport;
-preview fuzzing exercises discovery separately from WebSocket inference.
+Failed HTTP responses raise `avartha.ApiError`, with status, headers, and body;
+HTTP 422 raises `avartha.UnprocessableEntityError`. HTTP network failures and
+timeouts also raise `avartha.ApiError`, with no status or headers, a description
+in `body`, and the original exception in `__cause__`.
 [Usage examples](migration.md#discover-models-voices-and-asr-languages).
 
 ## Realtime TTS
@@ -195,8 +157,6 @@ Text order and ingress pacing are preserved. The helpers
 use one socket reader and the WebSocket library's bounded buffers; a slow audio
 consumer applies backpressure instead of filling an unbounded SDK audio queue.
 This does not change when the serving model starts generating audio.
-See the [reception validation report](tts-reception-validation.md) for regression
-coverage and the limits of the live Preview evidence.
 
 Both single-context and multi-context SDK helpers always send `auto_mode=true`.
 The SDK does not support `auto_mode=False` or `default_mode`.
@@ -225,7 +185,7 @@ with the async client when available.
    before the server's inactivity deadline while the context remains open.
 3. `flush(context_id)` generates audio and completes that context. Alternatively,
    `close_context(context_id)` flushes pending text before closing the context.
-4. Receive owned audio/final messages. Use `message.context_id` to route audio
+4. Receive typed audio/final messages. Use `message.context_id` to route audio
    and `audio_bytes(message)` to decode it.
 
 **Connection consumer:** `for message in session` (or `async for`) waits for
@@ -286,16 +246,16 @@ for a replacement. Errors without a known
 context ID do not settle other contexts or hide missing finals.
 
 Keepalives require an existing context that has not been flushed, closed, or
-completed. Post-flush context reuse still requires the SDK, Platform, and runtime
-lifecycle work tracked by [ENG-777](https://linear.app/avartha/issue/ENG-777).
+completed. Create a new context ID for each utterance; reusing a context after
+flushing it is unsupported.
 
 TTS sends are paced automatically with headroom below the default ingress
 budget of 1,000 burst frames and 250 frames/second. If a deployment advertises
 different limits, pass its `websocket_limits` mapping to the `ElevenLabs` or
 `AsyncElevenLabs` constructor. Limits are applied separately to each socket.
 
-These helpers adapt the SDK to the managed TTS contract. They do not add server
-support for other codecs or non-null `voice_settings`. Runnable examples:
+Audio formats and `voice_settings` depend on the selected model. Specifying an
+option in the SDK does not make it available on the server. Runnable examples:
 [single-context](../examples/tts.py), [multi-context](../examples/tts_multi_context.py).
 
 ## URLs and authentication
@@ -306,9 +266,9 @@ support for other codecs or non-null `voice_settings`. Runnable examples:
   original `/v1/...` paths, using `xi-api-key`.
 - An explicit protocol `base_url` is a full dialect/service base. Speech also
   supports `AVARTHA_ELEVENLABS_BASE_URL` as an override.
-- Both adapters default to `serverless`; `tier="dedicated"` never falls back.
+- Both protocol clients default to `serverless`; `tier="dedicated"` never falls back.
 - HTTP/HTTPS maps to WS/WSS. No implicit hosted-vendor credential fallback exists.
-- Owned clients never read vendor environment variables. `OPENAI_ADMIN_KEY`,
+- Clients never read vendor environment variables. `OPENAI_ADMIN_KEY`,
   `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_CUSTOM_HEADERS`, `OPENAI_ORG_ID`,
   `OPENAI_PROJECT_ID` and `OPENAI_WEBHOOK_SECRET` never reach an Avartha request,
   and `base_url`, `websocket_base_url` and `data_residency` are refused when they
@@ -317,64 +277,3 @@ support for other codecs or non-null `voice_settings`. Runnable examples:
 - The ASR token option is preserved, including suppression of the API-key header
   when a token is supplied. Token issuance is a separate server prerequisite.
   Agent signed-URL handling will be implemented with the future Agents client.
-
-## Remaining server compatibility work
-
-The [expanded audit](audit/report.md) separates substantial feature work (A),
-bounded additions (B), and small corrections (C). It includes successful flows
-and expected rejections alongside defects; error quality and session recovery
-are tracked as required compatibility work.
-
-The Avartha Platform needs to support the official helper's default generation controls;
-the SDK now sends an envelope the gateway accepts, but `voice_settings` stays
-unusable because any non-null value is refused. A TTS rejection still collapses
-to a generic `upstream_error` regardless of cause, so the SDK reports the
-server's payload without being able to explain it. The original upstream errors
-and failures remain visible; the SDK does not turn failures into success.
-
-Programmatic agent creation with the ElevenLabs schema requires matching
-`/v1/convai/agents/...` endpoints. Current Avartha agent CRUD lives at
-`/control/v1/organizations/{workspace_id}/voice-agents` with a different request
-schema and generation rules. The SDK does not translate between those contracts.
-An empty conversation list does not establish populated history, filtering,
-agent CRUD, or conversation runtime compatibility. The official agent helper
-also sends initialization metadata the current gateway rejects, and its default
-audio playback rate differs from the advertised agent output rate.
-
-API-key administration and staff routes are outside the bearer-authenticated
-Control client's promised resources.
-
-## Validation
-
-HTTP contracts cover owned speech discovery and Control. OpenAI HTTP calls are
-tested for explicit local rejection without network requests. Loopback
-WebSocket tests exercise Realtime text and speech clients, including pacing,
-cancellation, context lifecycle, errors, authentication, and callback delivery.
-Frozen ElevenLabs 2.68.0 fixtures verify signatures, enum members, type
-serialization, and error attributes without installing that SDK. TTS text
-forwarding deliberately differs from upstream chunking: local WebSocket tests
-verify exact input text and delivery while the producer is paused.
-Frozen HTTP fixtures cover voice/model method signatures, query encoding, and
-nested response types. Loopback HTTP tests exercise every discovery method
-through internally managed transports and verify that fuzz assertions reject
-broken pagination, settings, model capabilities, and language metadata.
-
-OpenAI parser expectations are captured in
-[`tests/fixtures/openai/realtime.json`](../tests/fixtures/openai/realtime.json),
-with complete and incomplete payloads for all 46 pinned server-event variants.
-They do not require an installed OpenAI package. GitHub CI runs the complete
-local test suite, including real WebSocket tests.
-
-The explicit live runner exercises preview separately and exits nonzero on a
-failed check. It never provisions or deletes endpoints. Upstream WebSocket
-deprecation warnings remain visible in the local suite.
-
-## References
-
-- [Avartha managed realtime contract](https://github.com/avartha/platform/blob/1992c3ade7089195d622f98ba2676bde90812799/docs/realtime-protocol-migration.md)
-- [Avartha TTS contract](https://github.com/avartha/platform/blob/1992c3ade7089195d622f98ba2676bde90812799/docs/console/api/text-to-speech.rst)
-- [Avartha ASR contract](https://github.com/avartha/platform/blob/1992c3ade7089195d622f98ba2676bde90812799/docs/console/api/speech-to-text.rst)
-- [OpenAI Realtime guide](https://developers.openai.com/api/docs/guides/realtime)
-- [ElevenLabs streaming TTS](https://elevenlabs.io/docs/eleven-api/guides/how-to/websockets/realtime-tts)
-- [ElevenLabs realtime ASR](https://elevenlabs.io/docs/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)
-- [ElevenLabs agent creation](https://elevenlabs.io/docs/eleven-agents/api-reference/agents/create)

avartha_python_sdk-0.0.4/docs/pypi.md

@@ -0,0 +1,109 @@
+# 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.3 → avartha_python_sdk-0.0.4}/examples/tts.py

@@ -1,4 +1,4 @@
-"""ElevenLabs TTS interface; see docs/preview-testing.md for preview incompatibilities.
+"""Streaming TTS; see docs/compatibility.md for supported formats and lifecycle details.
 
 Set AVARTHA_API_KEY and optionally AVARTHA_BASE_URL.
 Defaults to the rate Avartha's TTS models serve; supply --sample-rate for others.