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

{avartha_python_sdk-0.0.6 → avartha_python_sdk-0.0.7}/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.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.6
+Version: 0.0.7
 Summary: Python clients for Avartha Realtime text, streaming speech, and platform management
 Author-email: "Avartha Inc." <team@avartha.ai>
 License-Expression: LicenseRef-Avartha-Proprietary
@@ -109,12 +109,14 @@ 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` |
+| Placing phone calls from Twilio numbers | `ElevenLabs` / `AsyncElevenLabs`: `conversational_ai.twilio.outbound_call` |
 | 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`.
+and file transcription are unavailable. ElevenLabs-schema agent management is not
+implemented, and accessing it under `conversational_ai` raises `NotImplementedError`.
 
 ## Migrating and handling errors
 

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

@@ -137,7 +137,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,9 +163,9 @@ 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
@@ -184,7 +186,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.
@@ -239,44 +243,74 @@ 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:
 
-ElevenLabs-compatible `conversational_ai` support is planned for an upcoming
-release, including agent creation, tools, knowledge-base documents, and
-conversations.
+```python
+from avartha import Control
 
-The following example previews the planned API. It requires that future SDK
-release and a service implementing the corresponding agent endpoints:
+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"])
+```
+
+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`.
+An agent can also call someone from one of the workspace's Twilio numbers. Pass an
+`idempotency_key`, so a retry can't ring them twice, and check `placed.success`:
+
+```python
+placed = client.conversational_ai.twilio.outbound_call(
+    agent_id="your-agent-id",
+    agent_phone_number_id="your-twilio-number-id",
+    to_number="+14155550100",
+    idempotency_key="order-1042-reminder",
+)
+```
+
+See [placing a phone call](docs/voice-conversations.md#placing-a-phone-call) for its
+prerequisites and how to follow the call.
+
+ElevenLabs-schema agent management, tools, and knowledge bases are not implemented.
+Accessing them under `client.conversational_ai` raises `NotImplementedError`.
 
 ## Using types
 
@@ -356,9 +390,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.7}/docs/compatibility.md

@@ -20,16 +20,19 @@ use HTTP.
 | 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 |
+| 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` |
+| 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) |
+| Placing phone calls | Sync/async `conversational_ai.twilio.outbound_call` | Outbound calling enabled, a key with `voice_calls_place`, a Twilio number, and a published agent; see [placing a phone call](voice-conversations.md#placing-a-phone-call) |
+| 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; the feature enabled; 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 |
 
 See [platform management](platform.md) for workspace roles, invitation
-requirements, and permissions.
+requirements, voice agents, and permissions.
 
 ## OpenAI Realtime text
 
@@ -50,6 +53,43 @@ 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.
 
+### 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.
+
+### 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 +205,43 @@ 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.
+
 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 +335,20 @@ 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. Supported
+encodings and rates depend on the server. 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 +364,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.

{avartha_python_sdk-0.0.6 → avartha_python_sdk-0.0.7}/docs/migration.md

@@ -76,6 +76,11 @@ Keep `client.realtime.connect`, `session.update`,
 The same applies to `AsyncOpenAI` with `await` and `async for`.
 [Complete usage examples](../README.md#usage).
 
+The GA Realtime session has no `temperature`. Avartha accepts `temperature`
+(0 to 2) and other sampling controls in `session.update` and as per-response
+overrides in `response.create`; see
+[sampling controls](compatibility.md#sampling-controls).
+
 ### Types, errors, and integrations
 
 Replace `openai.types` imports with the corresponding `avartha.types` imports;
@@ -159,12 +164,19 @@ use `avartha.ApiError`. WebSocket exceptions retain the `websockets` classes.
 | Speech discovery | `models.list`, `voices.get_all`, `voices.search`, `voices.get`, `voices.settings.get` | Typed sync/async HTTP resources |
 | ASR languages | `speech_to_text.languages.list(model_id=...)` | Typed sync/async Avartha extension |
 | HTTP TTS, file ASR | `text_to_speech.convert`, `text_to_speech.stream`, `speech_to_text.convert` | Unavailable in this SDK |
-| Agents, tools, knowledge bases, conversation sessions/history | `conversational_ai` | Currently unavailable |
+| Conversation sessions and history | `conversational_ai.conversation`, `conversational_ai.conversations` | A documented subset; see [voice conversations](voice-conversations.md) |
+| Placing phone calls | `conversational_ai.twilio.outbound_call` | A documented subset; see [placing a phone call](voice-conversations.md#placing-a-phone-call) |
+| Registering Twilio calls | `conversational_ai.twilio.register_call` | Unavailable in this SDK |
+| Agents, tools, knowledge bases | `conversational_ai` | Not implemented |
 
 Replace `avartha.legacy.ElevenLabs` and `avartha.legacy.AsyncElevenLabs` imports
 with `avartha.ElevenLabs` and `avartha.AsyncElevenLabs`.
-`conversational_ai` access raises `NotImplementedError`. The old conversation
-runtime, `play`/`save`/`stream` re-exports, and `audio` extra were removed.
+Accessing agents, tools, or knowledge bases under `conversational_ai` raises
+`NotImplementedError`; Avartha's own voice agents use a different schema and are managed
+with [`Control.voice_agents`](platform.md#voice-agents). Conversations use
+`avartha.conversational_ai`; call `wait_for_session_start()` before sending, and pass
+your own audio interface, because `DefaultAudioInterface` is not included. The
+`play`/`save`/`stream` re-exports and `audio` extra were removed.
 Write received PCM bytes to a WAV file or use your application's audio player;
 see [the TTS example](../examples/tts.py).
 
@@ -219,9 +231,13 @@ See [supported HTTP endpoints and server prerequisites](compatibility.md#speech-
 
 ### Speech-specific configuration
 
-Avartha TTS returns PCM and defaults to `pcm_24000`. Select an `output_format`
-supported by your model. Write a WAV header with the corresponding sample rate
-or encode the PCM yourself; the SDK does not convert audio formats.
+Avartha TTS defaults to `pcm_24000`, unlike ElevenLabs' MP3 default. The
+runtime converts to the selected `output_format`: raw PCM at 8 to 48 kHz, MP3,
+or G.711 `ulaw_8000` and `alaw_8000`. See
+[output formats](compatibility.md#output-formats-timeouts-and-timestamps).
+Add a WAV header to PCM for a WAV file; the SDK returns the bytes unchanged.
+`inactivity_timeout` (1 to 180 seconds) sets how long a context waits for more
+text; the runtime default is 20 seconds.
 Single-context and multi-context TTS always use `auto_mode=true`.
 `auto_mode=False` and `default_mode` are unsupported.
 
@@ -291,7 +307,11 @@ It defaults to off and is separate from microphone echo cancellation.
 Use `keyterms=["Avartha", "Kubernetes"]` for vocabulary hints on models that
 support them. The SDK sends each term as a separate query parameter and handles
 URL encoding. Hints do not guarantee a spelling and are not a free-form prompt.
-`language_code` can constrain recognition to a supported language; use
+Up to 16 terms and 40 words in total are accepted; the server also limits their
+combined tokens, as described under
+[vocabulary hints](compatibility.md#vocabulary-hints-and-language).
+`language_code` hints the spoken language, such as `"en"` or `"en-US"`; omit it
+for automatic detection. A hint does not guarantee a different transcript. Use
 `speech_to_text.languages.list(model_id=...)` to check language support.
 
 #### Ending an utterance
@@ -302,17 +322,21 @@ complete. This waits for the send, not the transcript: wait for
 `RealtimeEvents.COMMITTED_TRANSCRIPT` before treating transcription as complete.
 Do not commit an empty audio buffer as a completion check.
 
-For automatic commits, use `commit_strategy=CommitStrategy.VAD`. Set
-`turn_model="silence"` for silence-based turn detection; omitting it uses the
-server's default. Tune `vad_silence_threshold_secs` for the silence
-wait and `vad_threshold` for speech detection sensitivity. VAD controls require
-VAD mode; omit them in manual mode.
-
-On servers supporting Smart Turn, add `turn_model="smart_turn_v3"`. It uses an
-end-of-turn model to judge whether the speaker has finished, with a silence
-timeout as fallback. `turn_threshold` controls its decision threshold, defaults
-to `0.5`, and must be strictly between `0` and `1`. Only pass this threshold with
-Smart Turn. For example, inside an async client context:
+For automatic commits, use `commit_strategy=CommitStrategy.VAD`. Without
+`turn_model`, or with `turn_model="silence"`, a turn ends after
+`vad_silence_threshold_secs` of silence (1 second by default). Tune
+`vad_threshold` for speech detection sensitivity. VAD controls require VAD mode;
+the SDK raises `ValueError` if you pass them in manual mode.
+
+Semantic turn detection uses an end-of-turn model to judge whether the speaker
+has finished, so a hesitation need not end the utterance. Shipped Qwen3-ASR
+deployments load `turn_model="turn_eot_t3_v1"`, with a `turn_threshold`
+default of `0.79`. `turn_model="smart_turn_v3"` (default threshold `0.5`)
+requires a deployment that loads it; the server refuses a model it has not loaded.
+The threshold must be strictly between `0` and `1` and needs a semantic model.
+Sustained silence still ends the turn after `vad_silence_threshold_secs`, which
+defaults to 2 seconds with either semantic model. For example, inside an async
+client context:
 
 ```python
 from avartha import AudioFormat, CommitStrategy, RealtimeAudioOptions
@@ -322,12 +346,16 @@ options = RealtimeAudioOptions(
     audio_format=AudioFormat.PCM_16000,
     sample_rate=16000,
     commit_strategy=CommitStrategy.VAD,
-    turn_model="smart_turn_v3",
-    turn_threshold=0.5,
+    turn_model="turn_eot_t3_v1",
+    turn_threshold=0.79,
 )
 connection = await client.speech_to_text.realtime.connect(options)
 ```
 
+`await connection.commit()` also works in VAD mode and skips the remaining
+silence wait. Final decoding and delivery still take time after a commit.
+See [turn detection](compatibility.md#turn-detection) for every range.
+
 #### Transcript details
 
 `include_logprobs=True` requests word log probabilities in final transcripts.