avartha-python-sdk 0.0.6__tar.gz → 0.0.8__tar.gz

{avartha_python_sdk-0.0.6 → avartha_python_sdk-0.0.8}/MANIFEST.in

@@ -5,5 +5,6 @@ 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 docs/voice-conversations.md
 include examples/realtime.py examples/tts.py examples/tts_multi_context.py
-include examples/realtime_asr.py
+include examples/realtime_asr.py examples/voice_conversation.py

{avartha_python_sdk-0.0.6 → avartha_python_sdk-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.6
+Version: 0.0.8
 Summary: Python clients for Avartha Realtime text, streaming speech, and platform management
 Author-email: "Avartha Inc." <team@avartha.ai>
 License-Expression: LicenseRef-Avartha-Proprietary
@@ -33,11 +33,12 @@ Dynamic: license-file
 
 Synchronous and asynchronous Python clients for Avartha Realtime text,
 streaming speech, and platform management. Requires Python 3.12+.
+The guides and examples below use SDK 0.0.7 or later.
 
 ## Install
 
 ```sh
-python -m pip install avartha-python-sdk
+python -m pip install --upgrade 'avartha-python-sdk>=0.0.7'
 ```
 
 Configure your Avartha API key and platform root:
@@ -55,15 +56,18 @@ to your workspace. Unsupported tier values and dedicated inference URLs raise
 ## Discover models
 
 ```python
-from avartha import OpenAI
+from avartha import Avartha
 
-with OpenAI() as client:
+with Avartha() as client:
     for model in client.models.list():
         print(model.id, model.to_dict().get("protocols", []))
+    for model in client.elevenlabs.models.list():
+        print(model.model_id, getattr(model, "protocols", []))
 ```
 
-Choose a model supporting `openai_realtime` for text, `elevenlabs_tts` for
-speech synthesis, or `elevenlabs_asr` for speech recognition.
+`client.models` lists Voice LLMs; choose `openai_realtime` for text.
+`client.elevenlabs.models` lists speech models; choose `elevenlabs_tts` for
+speech synthesis or `elevenlabs_asr` for speech recognition.
 
 ## Generate text
 
@@ -109,12 +113,13 @@ Inference consumes credits.
 | 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 | `Control` / `AsyncControl` |
+| Voice agents: create, edit, publish, restore, delete | `Control` / `AsyncControl`: `voice_agents` |
+| Live conversations with published agents | `avartha.conversational_ai`: `Conversation`, `AsyncConversation` |
 | 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`.
+This SDK provides model inference over WebSockets; it does not wrap HTTP
+Chat Completions, Responses, speech synthesis, or file transcription. ElevenLabs-schema agent management is not
+implemented, and accessing it under `conversational_ai` raises `NotImplementedError`.
 
 ## Migrating and handling errors
 
@@ -138,4 +143,4 @@ never retried automatically.
 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.
+and platform-management guides and run the text, speech, and voice-agent examples.

{avartha_python_sdk-0.0.6 → avartha_python_sdk-0.0.8}/README.md

@@ -4,6 +4,7 @@
 
 Synchronous and asynchronous Python clients for Avartha Realtime LLMs,
 streaming speech, and platform management. Requires Python 3.12+.
+The guides and examples below use SDK 0.0.7 or later.
 
 **Familiar Python interfaces for OpenAI Realtime and ElevenLabs speech.** Change
 client, type, and exception imports, then configure Avartha credentials, URLs,
@@ -20,9 +21,11 @@ and model/voice IDs. The supported APIs use the same method names and event loop
 ```
 
 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.
+streaming speech, HTTP discovery, and platform management. This SDK uses
+WebSockets for model inference. It does not wrap HTTP Chat Completions,
+Responses, or speech synthesis. Enabled platform HTTP endpoints have their
+own model and workspace prerequisites. See the guides below for supported
+features and migration steps.
 
 ## Documentation
 
@@ -36,7 +39,7 @@ unavailable. See the guides below for supported features and migration steps.
 Install from [PyPI](https://pypi.org/project/avartha-python-sdk/):
 
 ```sh
-python -m pip install avartha-python-sdk
+python -m pip install --upgrade 'avartha-python-sdk>=0.0.7'
 ```
 
 Set your Avartha API key and platform root. Update `AVARTHA_BASE_URL` to match
@@ -88,16 +91,19 @@ and response on the same connection to preserve conversation state.
 To discover available models and their enabled protocols:
 
 ```python
-from avartha import OpenAI
+from avartha import Avartha
 
-with OpenAI() as client:
+with Avartha() as client:
     for model in client.models.list():
         print(model.id, model.to_dict().get("protocols", []))
+    for model in client.elevenlabs.models.list():
+        print(model.model_id, getattr(model, "protocols", []))
 ```
 
 Model availability depends on your workspace and environment. Replace
-the example IDs with models returned for your key and the protocol you need:
-`openai_realtime`, `elevenlabs_tts`, or `elevenlabs_asr`.
+the example IDs with models returned for your key. `client.models` lists
+Voice LLMs; choose `openai_realtime` for text. `client.elevenlabs.models` lists
+speech models; choose `elevenlabs_tts` or `elevenlabs_asr` for speech.
 
 ## Async usage
 
@@ -137,7 +143,9 @@ async def main():
 asyncio.run(main())
 ```
 
-[Complete Realtime example](examples/realtime.py).
+[Complete Realtime example](examples/realtime.py). Avartha also accepts
+`temperature` and other [sampling controls](docs/compatibility.md#sampling-controls)
+in `session.update` and `response.create`.
 
 ## Streaming speech
 
@@ -161,12 +169,13 @@ with ElevenLabs() as client:
         print(voice.voice_id)
 ```
 
-Stream text over a WebSocket with `convert_realtime`. Avartha returns PCM;
-select a sample rate supported by your model and write a WAV header for playback.
-This example uses Qwen's 24 kHz output:
+Stream text over a WebSocket with `convert_realtime`. The runtime converts the
+model's audio to the `output_format` you select: raw PCM at 8 to 48 kHz, MP3, or
+G.711 (`ulaw_8000`, `alaw_8000`). This example writes 24 kHz PCM to a WAV file:
 
 ```python
 import wave
+from contextlib import closing
 from avartha import ElevenLabs
 
 with ElevenLabs() as client:
@@ -176,7 +185,7 @@ with ElevenLabs() as client:
         output_format="pcm_24000",
         text=iter(["Welcome. ", "How can I help?"]),
     )
-    with wave.open("welcome.wav", "wb") as output:
+    with closing(audio), wave.open("welcome.wav", "wb") as output:
         output.setnchannels(1)
         output.setsampwidth(2)
         output.setframerate(24000)
@@ -184,7 +193,9 @@ with ElevenLabs() as client:
             output.writeframes(chunk)
 ```
 
-The default output format is `pcm_24000`. Use `AsyncElevenLabs` and `async for`
+The default output format is `pcm_24000`. See
+[output formats, timeouts, and timestamps](docs/compatibility.md#output-formats-timeouts-and-timestamps)
+for every format, `inactivity_timeout`, and character timestamps. 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.
@@ -221,8 +232,9 @@ Use `AsyncAvartha` or `AsyncElevenLabs` for an async application. See the
 [live STT execution guidance](docs/migration.md#live-speech-to-text) for scripts
 and applications with an existing event loop.
 
-Current ASR models require 16 kHz mono PCM16 audio. Convert other formats or
-sample rates before sending audio chunks; the SDK does not resample them.
+ASR accepts mono PCM16 at 8, 16, 22.05, 24, 44.1, or 48 kHz, and 8 kHz mu-law.
+Choose the `AudioFormat` and `sample_rate` that match your samples; the server
+resamples them, and the SDK sends chunks unchanged.
 Await a committed transcript before closing the session.
 [The complete example](examples/realtime_asr.py) reads a WAV file, registers
 transcript/error callbacks, streams chunks, commits, and closes the connection:
@@ -239,44 +251,59 @@ options instead.
 File-based HTTP `speech_to_text.convert` is retired on managed inference.
 
 Connection options cover background speech filtering, vocabulary hints,
-manual/VAD commits, Smart Turn, word log probabilities, timestamps, and speaker
-labels on supported models. Register `RealtimeEvents.WARNING` for nonfatal
+manual/VAD commits, semantic turn detection, word log probabilities, timestamps,
+and speaker labels on supported models. Register `RealtimeEvents.WARNING` for nonfatal
 warnings, including unavailable timing metadata. See
 [ASR options and callbacks](docs/migration.md#recognition-and-context-hints)
 for configuration and server requirements.
 
 ## Agents
 
-Agent management, tools, knowledge bases, and conversation sessions/history are
-currently unavailable. Accessing `client.conversational_ai` raises
-`NotImplementedError`.
+`Control.voice_agents` creates, edits, publishes, restores, and deletes Avartha voice
+agents, using the platform's own schema. See [voice agents](docs/platform.md#voice-agents) for an
+example and the access each operation needs:
+
+```python
+from avartha import Control
 
-ElevenLabs-compatible `conversational_ai` support is planned for an upcoming
-release, including agent creation, tools, knowledge-base documents, and
-conversations.
+with Control() as client:
+    agent = client.voice_agents.create(
+        "your-workspace-id",
+        name="Support",
+        template_id="blank",
+        config={"schema_version": 1, "instructions": "Answer questions concisely."},
+    )
+    print(agent["id"], agent["generation"])
+```
 
-The following example previews the planned API. It requires that future SDK
-release and a service implementing the corresponding agent endpoints:
+Hold a live conversation with a published agent using `Conversation` or
+`AsyncConversation`. They follow the ElevenLabs conversation client for the subset the
+platform supports. See [voice conversations](docs/voice-conversations.md) for speech,
+per-call options, and conversation records:
 
 ```python
+import time
+
 from avartha import ElevenLabs
+from avartha.conversational_ai import Conversation
 
-with ElevenLabs(base_url="https://your-compatible-agent-service") as client:
-    agent = client.conversational_ai.agents.create(
-        name="Support",
-        conversation_config={
-            "agent": {
-                "first_message": "What can I help you with?",
-                "prompt": {"prompt": "Help customers find concise, accurate answers."},
-            },
-            "tts": {"voice_id": "your-voice"},
-        },
+with ElevenLabs() as client:
+    conversation = Conversation(
+        client,
+        "your-agent-id",
+        requires_auth=False,
+        callback_agent_response=lambda text: print("Agent:", text),
     )
-    print(agent.agent_id)
+    conversation.start_session()
+    conversation.wait_for_session_start()
+    conversation.send_user_message("What can you help me with?")
+    time.sleep(15)  # Replies arrive through the callbacks.
+    conversation.end_session()
+    conversation.wait_for_session_end()
 ```
 
-The planned `avartha.conversational_ai` namespace will also include
-`Conversation`, `AsyncConversation`, and `ClientTools`.
+ElevenLabs-schema agent management, tools, and knowledge bases are not implemented.
+Accessing them under `client.conversational_ai` raises `NotImplementedError`.
 
 ## Using types
 
@@ -356,9 +383,13 @@ with OpenAI(timeout=30.0, max_retries=0) as client:
     print(client.models.list())
 ```
 
-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`
+HTTP and WebSocket retry settings are separate. Realtime reconnection is opt-in:
+supply `on_reconnecting` to `client.realtime.connect(...)`. `max_retries` bounds
+consecutive recovery attempts; a session greeting alone does not reset the budget.
+Set `max_retries=0` to disable retries even when a callback is supplied.
+A reconnect opens a fresh session. The SDK does not replay session configuration,
+conversation history, or an interrupted response; the application must restore
+its state. Use `websocket_connection_options` for transport settings and `asyncio.timeout`
 when an async operation needs an overall deadline. Close active sessions when
 cancelling. ElevenLabs `timeout` configures HTTP calls; it does not set a
 WebSocket receive deadline. Platform management writes are never retried

{avartha_python_sdk-0.0.6 → avartha_python_sdk-0.0.8}/docs/compatibility.md

@@ -1,6 +1,7 @@
 # Compatibility and server support
 
-Avartha supports the OpenAI Python 3.13.0 Realtime text interface and the
+This guide covers Avartha Python SDK 0.0.7 or later. 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).
@@ -9,27 +10,32 @@ Avartha; see the [migration guide](migration.md).
 
 SDK support and server availability are separate. Select a model available to
 your workspace on serverless inference, and use only the features that model supports.
-Avartha managed inference uses WebSockets. Discovery and platform management
-use HTTP.
+These SDK model clients provide inference over WebSockets. Discovery and platform
+management use HTTP. The platform also has enabled HTTP inference routes that
+this SDK does not wrap: OpenAI speech/batch and Decisions, plus Chat Completions
+for authorized OpenRouter-provider workspaces. Those routes do not imply that
+ordinary workspace keys can use HTTP LLM inference.
 
 | Surface | SDK support | Server prerequisites |
 | --- | --- | --- |
 | 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 |
 | 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 |
+| Chat Completions, Responses, SSE, and OpenAI HTTP speech | No SDK wrappers | Enabled platform HTTP routes have separate prerequisites; use Realtime for this SDK’s model clients |
 | 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 |
+| Single-context TTS | Sync/async `convert_realtime` | A TTS model and voice; the runtime converts to the selected PCM, MP3 or G.711 format |
+| Multi-context TTS | Sync/async `connect_multi_context` | A model supporting multiple contexts; each utterance needs a new context ID. Character timestamps need a timestamp-capable model |
 | 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` |
+| HTTP TTS and file transcription | No SDK wrappers | Use these SDK realtime speech methods, or an explicitly enabled platform HTTP route |
+| Live conversations and their history | Sync/async `Conversation`, `AsyncConversation`, and `conversational_ai.conversations` | A published agent and an API key for its workspace; see [voice conversations](voice-conversations.md) |
+| ElevenLabs-schema agents, tools, knowledge bases | Not implemented | Accessing them under `conversational_ai` raises `NotImplementedError` |
+| Avartha voice agents: create, read, edit, publish, restore, delete | Sync/async `Control.voice_agents` | An API key with voice-agent management access to that workspace; capacity to publish |
 | Catalog, workspaces, members, and invitations | 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 |
+| API-key administration | No convenience resource; verified routes can use `Control.request` | A workspace-bound key with `keys` access and a creator who is still an Owner or Admin, or a console session |
 
 See [platform management](platform.md) for workspace roles, invitation
-requirements, and permissions.
+requirements, voice agents, and permissions.
 
 ## OpenAI Realtime text
 
@@ -50,6 +56,76 @@ 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.
 
+A new connection can rebuild a saved conversation on a compatible model.
+Before its first `response.create`, append the saved items in order: assistant
+messages with `role: "assistant"` and `output_text` content, and each tool call
+as a `function_call` item (`call_id`, `name`, and JSON-object `arguments`)
+followed by its `function_call_output`. Wait for each item's acknowledgement
+before requesting a reply. This rebuilds the input history, not the old session.
+
+### Sampling controls
+
+Avartha adds sampling controls to `session.update` and `response.create`:
+`temperature`, `top_p`, `top_k`, `min_p`, `presence_penalty`,
+`frequency_penalty`, and `repetition_penalty`. They are typed on
+`RealtimeSessionCreateRequestParam` and `RealtimeResponseCreateParamsParam`.
+They are not part of the upstream OpenAI GA Realtime contract, and are sent
+unchanged. Omitted fields use the deployment's sampling preset, which can differ
+by model, reasoning mode, and tool use. A session value applies to later
+responses, and `None` restores the preset for that field. A response value
+applies only to that response; `None` there keeps the session's value. A
+`session.updated` event echoes only the sampling values a `session.update` set.
+
+```python
+await connection.session.update(session={"type": "realtime", "temperature": 0.7})
+await connection.response.create(response={"temperature": 0.2})  # this response only
+```
+
+A temperature below `0.00001` decodes greedily. In the same event, leave
+`top_p`, `top_k`, and `min_p` unset or at their neutral values: `1`, `-1` or `0`,
+and `0`. Values outside these ranges raise `ValueError` before a frame is sent
+or queued, including through `send_raw()`:
+
+| Field | Accepted values |
+| --- | --- |
+| `temperature` | A finite number from 0 to 2 |
+| `top_p` | Greater than 0 and at most 1 |
+| `top_k` | An integer: `-1` or `0` (disabled), or 1 to 2,147,483,647 |
+| `min_p` | 0 to 1 |
+| `presence_penalty`, `frequency_penalty` | -2 to 2 |
+| `repetition_penalty` | A finite number greater than 0 |
+
+Active penalties also require deployment support; otherwise the server refuses
+them with an `error` event. Speech-to-text connections have no temperature setting.
+
+### Native options beyond the typed schema
+
+The SDK's public types cover its supported subset of the OpenAI schema and the
+sampling controls above. Some Avartha Realtime extensions, including
+`include_reasoning` and `reasoning.thinking_enabled`, are not yet declared in
+those types. A supported runtime can receive them as explicit JSON:
+
+```python
+import json
+
+await connection.send_raw(
+    json.dumps(
+        {
+            "type": "session.update",
+            "session": {"type": "realtime", "include_reasoning": True},
+        }
+    )
+)
+```
+
+This opts into reasoning output without changing the model's reasoning effort.
+The synchronous connection uses the same call without `await`. Raw frames still
+pass the SDK's text-only and sampling checks, and the server validates all
+remaining fields. A field's absence from the Python type does not establish
+server support; check the selected model and platform protocol documentation.
+
+### Unsupported operations
+
 Explicit audio/transcription/image requests raise `UnsupportedOperationError`
 before a frame is sent or queued. Audio event declarations remain importable for
 schema compatibility. Unsupported HTTP resources, including Chat Completions,
@@ -165,6 +241,59 @@ This does not change when the serving model starts generating audio.
 Both single-context and multi-context SDK helpers always send `auto_mode=true`.
 The SDK does not support `auto_mode=False` or `default_mode`.
 
+### Output formats, timeouts, and timestamps
+
+`output_format` selects the delivery encoding and sample rate. The runtime
+converts the model's native audio and keeps its channel count.
+`TextToSpeechOutputFormat` lists the accepted values:
+
+| Encoding | Formats |
+| --- | --- |
+| Raw PCM16, little-endian, no WAV header | `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_32000`, `pcm_44100`, `pcm_48000`, or the model's native rate |
+| MP3; the suffix is the bitrate in kbit/s | `mp3_22050_32`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192` |
+| G.711 telephony | `ulaw_8000`, `alaw_8000` |
+
+The SDK helpers send `DEFAULT_TTS_OUTPUT_FORMAT` (`pcm_24000`) when the argument
+is omitted, so the delivered rate does not depend on the model. Audio bytes are
+returned exactly as received: decode MP3 and G.711 with a matching decoder, and
+play or wrap PCM at the selected rate. Conversion can add first-audio latency.
+
+`inactivity_timeout` is an Avartha extension on `convert_realtime` and
+`connect_multi_context`. It is the number of seconds, from 1 to 180, the
+runtime waits for more text on a context before ending it; omission uses the
+runtime's 20-second default. WebSocket pings keep the connection open but do not
+reset this timer. In a multi-context session, `send(context_id, "")` refreshes
+only that context. The platform's connection watchdog is separate: it closes a
+connection after 90 seconds without traffic, or after `inactivity_timeout` plus
+10 seconds when that is longer.
+
+`connect_multi_context(..., sync_alignment=True)` requests approximate character
+timings on timestamp-capable models. They arrive in
+`AudioOutputMulti.normalized_alignment`, measured from the start of that
+message's audio. Alignment requires PCM or G.711 output; MP3 packets do not share
+the alignment clock. `convert_realtime` yields audio bytes only, so it has no
+alignment option.
+
+Out-of-range `inactivity_timeout` values, a non-boolean `sync_alignment`, and
+`sync_alignment=True` with MP3 raise `ValueError` before connecting. For
+`convert_realtime`, that happens when iteration starts.
+
+### Voice settings, warnings, and other query parameters
+
+ElevenLabs' `stability`, `similarity_boost`, and `style` (finite numbers from 0
+to 1) and `use_speaker_boost` (a boolean) are accepted in `voice_settings` for
+compatibility, but they do not change synthesis. `speed` must be omitted or 1.0.
+Other names, types, and ranges are refused. When accepted settings have no
+effect, the runtime sends a `warning` once per connection. The SDK logs it on
+the `avartha._realtime_tts` logger at `WARNING` level and keeps streaming: a
+warning never raises or settles a context.
+
+Pass other documented stream parameters, such as `language_code`, in
+`request_options={"additional_query_parameters": {...}}`. Values there override
+the SDK's own query values, and `None` omits one. Some models cannot detect the
+language of streamed text, so they refuse it unless `language_code` is set;
+send `"en"` for English text.
+
 Use `contextlib.closing(audio)` for the sync iterator or
 `contextlib.aclosing(audio)` for the async iterator when playback may stop early.
 Closing the iterator closes the socket and waits for its sender to stop. Started
@@ -258,17 +387,23 @@ 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.
 
-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:
+`voice_settings`, character timestamps, and the native rate 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).
 
 ## Realtime ASR
 
-Current ASR models require 16 kHz mono PCM16 audio. The SDK retains the other
-`AudioFormat` enum values for protocol compatibility; their presence does not
-imply server support. Audio-chunk mode sends samples unchanged. Convert the
-source before sending, or use URL mode, which requires FFmpeg and converts to
-16 kHz mono PCM16.
+Audio-chunk mode sends samples unchanged. Supply matching `audio_format` and
+`sample_rate`; mismatches raise `ValueError` before opening a socket. Every
+`AudioFormat` value is accepted: mono PCM16 at 8, 16, 22.05, 24, 44.1, or 48 kHz,
+and 8 kHz mu-law (`ULAW_8000`). The server resamples them for recognition. Send
+raw samples without a file header; a chunk can hold at most 320,000 decoded bytes
+and 160,000 samples, and must end on a sample boundary. URL mode requires FFmpeg and converts
+the source to 16 kHz mono PCM16. After a successful, nonempty source reaches EOF,
+the SDK commits the final turn and keeps receiving transcript events until the
+application closes the connection. FFmpeg failures emit `RealtimeEvents.ERROR`.
+Custom client headers also apply to the ASR WebSocket handshake.
 
 The SDK also preserves `previous_text` on audio chunks, but current ASR models
 accept only omission, `null`, or an empty string. Nonempty values are rejected.
@@ -284,9 +419,68 @@ sent as `true` or `false`.
 
 The server validates feature combinations and model availability. Diarization
 requires timestamps and a model with speaker-label support. Timestamps also
-depend on language support. Smart Turn requires VAD mode and a server with
-`smart_turn_v3` enabled; `turn_threshold` is only meaningful in that mode.
-Background filtering and vocabulary hints also depend on the model.
+depend on language support. Background filtering and vocabulary hints also
+depend on the model.
+
+### Turn detection
+
+`turn_model` takes `"silence"` (the default), `"smart_turn_v3"`, or
+`"turn_eot_t3_v1"` (the `TurnModel` type) and requires
+`commit_strategy=CommitStrategy.VAD`. The two semantic models estimate whether
+a pause means the speaker has finished. The deployment must load the requested
+model, and the server refuses one it has not loaded rather than substituting
+another. Shipped Qwen3-ASR deployments load `turn_eot_t3_v1`; on them,
+`smart_turn_v3` is refused.
+
+| Setting | Accepted values | Default |
+| --- | --- | --- |
+| `turn_threshold` | Strictly between 0 and 1; requires a semantic `turn_model` | `0.79` for `turn_eot_t3_v1`, `0.5` for `smart_turn_v3` |
+| `vad_silence_threshold_secs` | 0.2 to 5.0 seconds | `1.0` with `silence`; `2.0` as the fallback with a semantic model |
+| `vad_threshold` | Strictly between 0 and 1 | `0.5` |
+| `min_speech_duration_ms` | An integer; rounded up to 32 ms frames, plus 300 ms, it must fit 8,000 ms (at most 7,680) | Model-dependent |
+| `min_silence_duration_ms` | An integer below the silence threshold in milliseconds | Model-dependent |
+
+These settings raise `ValueError` before connecting when used without VAD
+mode, when out of range, or, for `turn_threshold`, with `turn_model="silence"`
+or no `turn_model`. `session_started.config` reports the effective values.
+
+The silence threshold controls when buffered audio is submitted, not how quickly
+the final transcript arrives. `connection.commit()` skips the remaining VAD
+wait, but queueing, final decoding, and delivery still take time.
+
+### Vocabulary hints and language
+
+`keyterms` biases recognition toward the listed terms on Qwen3-ASR deployments
+with context biasing. It does not guarantee a spelling. Each term is sent
+unchanged as its own query parameter. The server trims each term before
+counting, so the SDK checks these limits before connecting:
+
+- at most 16 terms;
+- at most 40 whitespace-separated words across all terms;
+- at most 128 UTF-8 bytes per term;
+- no blank terms or control characters.
+
+The server also caps the terms' combined tokens at about 40. It tokenizes each
+term separately with the model's tokenizer and reserves room for the separators
+it adds between terms. Sixteen terms can therefore exceed the token cap,
+especially invented names that use several tokens each. The
+SDK cannot measure tokens; the server's refusal reports the measured count and
+the limit. An error before `session_started` closes the connection.
+
+`language_code` is an optional spoken-language hint, fixed for the connection.
+Omit it for automatic detection; `""` and `"auto"` raise `ValueError`. Regional
+forms such as `en-US` match their base language. Qwen3-ASR adds the hint to
+its decoder prompt. A correct hint can leave the transcript unchanged, so it
+does not guarantee an accuracy change. Check support with
+`speech_to_text.languages.list(model_id=...)`.
+
+### Session timing
+
+Send the first audio chunk or commit within 30 seconds of connecting. WebSocket
+pings do not count toward this deadline, and the server closes an idle new
+session with an `input_error` event. After the first message, the server's
+pings keep the connection open between utterances. The one-hour session
+lifetime still applies. Close the connection when transcription is finished.
 
 Transcript callbacks preserve server dictionaries, including `words` with
 timing, speaker labels, and log probabilities when supplied.
@@ -315,4 +509,6 @@ committed transcript remains usable. See the
   fence. Pass `organization` or `project` explicitly to set them.
 - 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.
+  Published-agent signed URLs are available through
+  `conversational_ai.conversations.get_signed_url` and
+  `Conversation(requires_auth=True)`; see [voice conversations](voice-conversations.md).