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

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

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      fuzz_seed:
+        description: Optional seed to replay speech HTTP and WebSocket fuzz inputs
+        type: string
+        default: ''
+  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]'
+      - name: Check SDK and local HTTP/WebSocket contracts
+        run: make check PYTEST_ARGS='--junitxml=artifacts/tests/results.xml'
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: tests-python-${{ matrix.python }}
+          path: artifacts/tests/results.xml
+          if-no-files-found: warn
+          retention-days: 14
+
+  preview-fuzz:
+    name: Preview WebSocket compatibility fuzz
+    # Fork and Dependabot PRs cannot access repository secrets. Keep their
+    # offline checks above; never use pull_request_target to run PR code.
+    # Feature branches use the PR run so pushes don't duplicate live workloads.
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name != 'push' ||
+       github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) &&
+      (github.event_name != 'pull_request' ||
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
+    concurrency:
+      group: preview-websocket-live
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            tests/fixtures/preview/constraints.txt
+      - run: python -m pip install -c tests/fixtures/preview/constraints.txt .
+      - name: Fuzz supported speech HTTP and WebSocket workflows
+        env:
+          AVARTHA_API_KEY: ${{ secrets.AVARTHA_API_KEY }}
+          FUZZ_SEED: ${{ inputs.fuzz_seed || github.run_id }}
+        run: >-
+          python scripts/preview_behavior.py
+          --fuzz-rounds 1 --fuzz-seed "$FUZZ_SEED"
+          --output artifacts/preview-fuzz
+      - name: Publish fuzz summary
+        if: always()
+        run: |
+          if [[ -f artifacts/preview-fuzz/summary.md ]]; then
+            cat artifacts/preview-fuzz/summary.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: preview-websocket-fuzz-${{ github.run_id }}-${{ github.run_attempt }}
+          path: artifacts/preview-fuzz/
+          if-no-files-found: warn
+          retention-days: 14

avartha_python_sdk-0.0.2/.github/workflows/preview-behavior.yml

@@ -0,0 +1,80 @@
+name: Preview WebSocket behavior
+
+on:
+  workflow_dispatch:
+    inputs:
+      scenario:
+        description: Optional exact scenario ID from the contract; empty runs all
+        type: string
+        default: ''
+      llm_model:
+        description: Optional text Realtime model; blank selects the first available
+        type: string
+        default: ''
+      tts_model:
+        description: Preview PCM24k TTS model
+        type: string
+        default: qwen/qwen3-tts-12hz-1.7b-base
+      asr_model:
+        description: Preview PCM16k ASR model
+        type: string
+        default: mistralai/voxtral-mini-4b-realtime-2602
+      voice:
+        description: Voice supported by the selected TTS model
+        type: string
+        default: carol
+
+permissions:
+  contents: read
+
+concurrency:
+  group: preview-websocket-live
+  cancel-in-progress: false
+
+jobs:
+  behavior:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 40
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            tests/fixtures/preview/constraints.txt
+      - run: python -m pip install -c tests/fixtures/preview/constraints.txt .
+      - name: Exercise supported preview WebSocket behaviors
+        env:
+          AVARTHA_API_KEY: ${{ secrets.AVARTHA_API_KEY }}
+          SCENARIO: ${{ inputs.scenario }}
+          LLM_MODEL: ${{ inputs.llm_model }}
+          TTS_MODEL: ${{ inputs.tts_model }}
+          ASR_MODEL: ${{ inputs.asr_model }}
+          VOICE: ${{ inputs.voice }}
+        run: |
+          args=(--tts-model "$TTS_MODEL" --asr-model "$ASR_MODEL" --voice "$VOICE")
+          if [[ -n "$LLM_MODEL" ]]; then
+            args+=(--llm-model "$LLM_MODEL")
+          fi
+          if [[ -n "$SCENARIO" ]]; then
+            args+=(--scenario "$SCENARIO")
+          fi
+          python scripts/preview_behavior.py "${args[@]}"
+      - name: Publish behavioral summary
+        if: always()
+        run: |
+          if [[ -f artifacts/preview-behavior/summary.md ]]; then
+            cat artifacts/preview-behavior/summary.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: preview-websocket-behavior
+          path: artifacts/preview-behavior/
+          if-no-files-found: warn
+          retention-days: 14

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.2}/.github/workflows/publish.yml

@@ -28,7 +28,7 @@ jobs:
           python-version: '3.12'
           cache: pip
           cache-dependency-path: pyproject.toml
-      - run: python -m pip install --upgrade pip build twine
+      - run: python -m pip install --upgrade pip build twine "setuptools-scm>=8,<9"
       - 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.
@@ -53,10 +53,15 @@ jobs:
     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:
+      - name: Check PyPI token
+        env:
+          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          if [ -z "$PYPI_API_TOKEN" ]; then
+            echo "::error::Set PYPI_API_TOKEN in the pypi environment before publishing."
+            exit 1
+          fi
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: python-package-distributions
@@ -64,3 +69,5 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
         with:
           packages-dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          attestations: false

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.2}/.gitignore

@@ -9,3 +9,5 @@ src/avartha/_version.py
 build/
 dist/
 .env
+*.wav
+artifacts/

avartha_python_sdk-0.0.2/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# 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.
+
+Owned protocol primitives must preserve the frozen WebSocket behavior.
+OpenAI and ElevenLabs compatibility is captured in protocol fixtures; neither
+package is needed for development or runtime. Exercise new behavior with real
+local WebSocket tests and those frozen contracts. OpenAI declarations are
+maintained in this repository. To regenerate speech schemas, use
+`make freeze-types FREEZE_ARGS=--elevenlabs-wheel=/path/to/elevenlabs-2.68.0-py3-none-any.whl`;
+the tool reads declarations from that offline wheel without installing or
+importing ElevenLabs. Review changes and third-party notices. Update the
+compatibility matrix when platform support changes; SDK support is separate.
+
+## WebSocket tests in GitHub Actions
+
+The **CI** workflow runs `make check` on Python 3.12, 3.13, and 3.14 for every
+push and pull request. Its **Check SDK and local WebSocket contracts** step
+includes the real loopback socket tests and saves per-test JUnit results in
+`tests-python-*` artifacts. These tests need no live credentials.
+
+Run the full live preview suite on a specific branch with:
+
+```sh
+gh workflow run preview-behavior.yml --ref YOUR_BRANCH
+```
+
+The repository secret `AVARTHA_API_KEY` supplies credentials. The workflow fails
+if any selected scenario fails, and publishes the scenario summary and JSON/JUnit
+reports even on failure. See the [live contract](docs/websocket-behavior.md) for
+its supported scenarios and limits.
+
+## Publishing a release
+
+Versions are derived from Git tags by `setuptools_scm`; a tag such as `v0.0.2`
+produces package version `0.0.2`. Do not edit `pyproject.toml` or
+`avartha.__version__` to set a release version.
+
+Configure publishing once:
+
+1. Create a PyPI API token scoped to the existing `avartha-python-sdk` project.
+2. In the GitHub repository's Settings → Environments, create the `pypi`
+   environment and add an environment secret named `PYPI_API_TOKEN` containing
+   the token. Store the token only as a secret, never in repository files.
+
+For each release:
+
+1. Merge the release changes into `main` and wait for CI on Python 3.12, 3.13,
+   and 3.14 to pass. Run `make check` locally and review the wheel/source archive.
+2. Create and publish a GitHub release with a new version tag targeting the
+   tested commit. For example, use `v0.0.2` for the release after `v0.0.1`.
+3. Wait for **Publish Release to PyPI** to succeed, then verify installation
+   with `python -m pip install avartha-python-sdk==0.0.2`.
+
+Publishing a GitHub release starts the workflow. Pushing a branch or tag alone
+does not publish. Manual workflow runs must select a release tag; the build
+requires its checked-out commit to have an exact tag. Each release must use a
+new version because PyPI does not allow existing distribution files to be
+replaced. The GitHub repository can remain private; uploaded PyPI artifacts
+are public.

{avartha_python_sdk-0.0.1 → avartha_python_sdk-0.0.2}/MANIFEST.in

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

avartha_python_sdk-0.0.2/Makefile

@@ -0,0 +1,30 @@
+PYTHON ?= python
+BUILD_FLAGS ?=
+PREVIEW_ARGS ?=
+FREEZE_ARGS ?=
+PYTEST_ARGS ?=
+.PHONY: install-dev lint format test test-preview test-preview-fuzz build check freeze-types
+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 $(PYTEST_ARGS)
+test-preview:
+	$(PYTHON) scripts/preview_behavior.py $(PREVIEW_ARGS)
+test-preview-fuzz:
+	$(PYTHON) scripts/preview_behavior.py --fuzz-rounds 1 $(PREVIEW_ARGS)
+build:
+	$(PYTHON) -m build $(BUILD_FLAGS)
+check: lint test build
+
+freeze-types:
+	$(PYTHON) scripts/freeze_realtime_types.py $(FREEZE_ARGS)
+	$(PYTHON) -m ruff format src/avartha/types
+	$(PYTHON) -m ruff check --fix --ignore E501 src/avartha/types
+	$(PYTHON) -m ruff format src/avartha/types

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.1
+Version: 0.0.2
 Summary: Python clients for Avartha inference, voice agents, and platform management
 Author-email: "Avartha Inc." <team@avartha.ai>
 License-Expression: LicenseRef-Avartha-Proprietary
@@ -17,13 +17,11 @@ 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
+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
-Provides-Extra: audio
-Requires-Dist: elevenlabs[pyaudio]<2.69,>=2.68.0; extra == "audio"
+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"
@@ -35,6 +33,8 @@ Dynamic: license-file
 
 # Avartha Python SDK
 
+[![PyPI version](https://img.shields.io/pypi/v/avartha-python-sdk)](https://pypi.org/project/avartha-python-sdk/)
+
 Synchronous and asynchronous Python clients for Avartha Realtime LLMs,
 streaming speech, and platform management. Requires Python 3.12+.
 
@@ -54,8 +54,8 @@ the upstream resource methods, request types, response objects, and event loops:
 
 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.
+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)
 
 ## Documentation
@@ -69,24 +69,24 @@ also found ASR and TTS mismatches with the official ElevenLabs client defaults.
 
 ## Installation
 
-The repository is private and the package has not been published to PyPI.
-With GitHub access configured, install from source:
+Install from [PyPI](https://pypi.org/project/avartha-python-sdk/):
 
 ```sh
-git clone https://github.com/avartha/avartha-python-sdk.git
-python -m pip install ./avartha-python-sdk
+python -m pip install avartha-python-sdk
 ```
 
-Set your Avartha API key and platform root:
+Set your Avartha API key and platform root. Update `AVARTHA_BASE_URL` to match
+your environment:
 
 ```sh
 export AVARTHA_API_KEY='avk_...'
-export AVARTHA_BASE_URL='https://platform.avartha.ai'
+export AVARTHA_BASE_URL='https://platform.preview.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.
+Clients default to `https://platform.preview.avartha.ai` and the `serverless`
+inference tier. Set `AVARTHA_BASE_URL` to use another platform root. 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
 
@@ -216,19 +216,21 @@ with ElevenLabs() as client:
             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.
+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
+[TTS example](examples/tts.py) with `--async` to use that client.
 
-`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).
+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`.
+For a finite batch, create and flush contexts, then iterate over `session.drain()`.
+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.
 
 ### Speech to text
 
@@ -241,11 +243,10 @@ transcript/error callbacks, streams chunks, commits, and closes the connection:
 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.
+`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.
 
 File-based HTTP `speech_to_text.convert` is retired on managed inference.
 
@@ -356,12 +357,13 @@ Control-plane writes are never retried automatically.
 
 | 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` |
+| `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` |
+| `Avartha`, `AsyncAvartha`, `Control`, `AsyncControl` | Platform root: `https://platform.preview.avartha.ai` |
 
 Without an explicit URL, protocol clients derive their URL from
-`AVARTHA_BASE_URL`. Set `tier="dedicated"` for dedicated inference; there is no
+`AVARTHA_BASE_URL`, defaulting to `https://platform.preview.avartha.ai` and the
+`serverless` tier. 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.
@@ -398,10 +400,17 @@ scaling, routing, stopping, and deletion are described in the
 
 ## Examples and development
 
-For local microphone/speaker support, install the `audio` extra from the
-repository (`python -m pip install '.[audio]'`) and PortAudio.
+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

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

@@ -1,5 +1,7 @@
 # Avartha Python SDK
 
+[![PyPI version](https://img.shields.io/pypi/v/avartha-python-sdk)](https://pypi.org/project/avartha-python-sdk/)
+
 Synchronous and asynchronous Python clients for Avartha Realtime LLMs,
 streaming speech, and platform management. Requires Python 3.12+.
 
@@ -19,8 +21,8 @@ the upstream resource methods, request types, response objects, and event loops:
 
 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.
+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)
 
 ## Documentation
@@ -34,24 +36,24 @@ also found ASR and TTS mismatches with the official ElevenLabs client defaults.
 
 ## Installation
 
-The repository is private and the package has not been published to PyPI.
-With GitHub access configured, install from source:
+Install from [PyPI](https://pypi.org/project/avartha-python-sdk/):
 
 ```sh
-git clone https://github.com/avartha/avartha-python-sdk.git
-python -m pip install ./avartha-python-sdk
+python -m pip install avartha-python-sdk
 ```
 
-Set your Avartha API key and platform root:
+Set your Avartha API key and platform root. Update `AVARTHA_BASE_URL` to match
+your environment:
 
 ```sh
 export AVARTHA_API_KEY='avk_...'
-export AVARTHA_BASE_URL='https://platform.avartha.ai'
+export AVARTHA_BASE_URL='https://platform.preview.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.
+Clients default to `https://platform.preview.avartha.ai` and the `serverless`
+inference tier. Set `AVARTHA_BASE_URL` to use another platform root. 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
 
@@ -181,19 +183,21 @@ with ElevenLabs() as client:
             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.
+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
+[TTS example](examples/tts.py) with `--async` to use that client.
 
-`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).
+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`.
+For a finite batch, create and flush contexts, then iterate over `session.drain()`.
+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.
 
 ### Speech to text
 
@@ -206,11 +210,10 @@ transcript/error callbacks, streams chunks, commits, and closes the connection:
 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.
+`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.
 
 File-based HTTP `speech_to_text.convert` is retired on managed inference.
 
@@ -321,12 +324,13 @@ Control-plane writes are never retried automatically.
 
 | 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` |
+| `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` |
+| `Avartha`, `AsyncAvartha`, `Control`, `AsyncControl` | Platform root: `https://platform.preview.avartha.ai` |
 
 Without an explicit URL, protocol clients derive their URL from
-`AVARTHA_BASE_URL`. Set `tier="dedicated"` for dedicated inference; there is no
+`AVARTHA_BASE_URL`, defaulting to `https://platform.preview.avartha.ai` and the
+`serverless` tier. 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.
@@ -363,10 +367,17 @@ scaling, routing, stopping, and deletion are described in the
 
 ## Examples and development
 
-For local microphone/speaker support, install the `audio` extra from the
-repository (`python -m pip install '.[audio]'`) and PortAudio.
+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