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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.5
+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.5 → 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.
@@ -221,7 +225,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.
 
-Send mono PCM16 audio and await a committed transcript.
+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.
+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:
 
@@ -229,44 +235,82 @@ transcript/error callbacks, streams chunks, commits, and closes the connection:
 python examples/realtime_asr.py mistralai/voxtral-mini-4b-realtime-2602 speech-16k.wav
 ```
 
-`previous_text` is optional text context for transcription. When omitted from
-`connection.send` data, Avartha sends `null`, meaning no context. You can omit
-this field when streaming audio without prior text.
+Current ASR models reject nonempty `previous_text`. Omit it from
+`connection.send`; the SDK sends `null`. An empty string is also accepted.
+For vocabulary hints on supported models, pass `keyterms` in the connection
+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, 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`.
+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
 
@@ -346,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.5 → 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,
@@ -124,9 +164,13 @@ Speech discovery uses these HTTP routes under
 | `voices.search(...)` | `/v2/voices` | Same; supported filters are `search`, `page_size` (1–100), `next_page_token`, and `include_total_count` |
 | `voices.get(voice_id)` | `/v1/voices/{voice_id}` | Voice exists for the selected model |
 | `voices.settings.get(voice_id)` | `/v1/voices/{voice_id}/settings` | Same; server reports supported `speed=1.0` |
-| `speech_to_text.languages.list(model_id=...)` | `/v1/speech-to-text/languages` | A routable ASR model; runtime reports supported languages or unavailable hints |
+| `speech_to_text.languages.list(model_id=...)` | `/v1/models` | Selects the ASR model's language metadata from the speech catalog |
 
 All methods have sync and async variants and typed raw-response access.
+The language helper maps catalog `language_id` entries to `code`. An empty
+language list means hints are unsupported; missing metadata or an unavailable
+model raises `ApiError`. Its raw-response wrapper retains the catalog response's
+HTTP status and headers while exposing the selected model's typed language list.
 Model/voice methods retain upstream signatures; language discovery is an
 Avartha extension. Pass the TTS `model_id` through
 `request_options.additional_query_parameters`, especially when multiple TTS
@@ -161,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
@@ -254,10 +335,105 @@ 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
+
+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.
+Vocabulary hints use `keyterms` on models that support them.
+
+The SDK forwards background filtering (`filter_background_audio`), vocabulary
+hints (`keyterms`), manual/VAD commit controls, and `include_timestamps`.
+It additionally exposes Avartha's `diarize`, `include_logprobs`, `turn_model`,
+and `turn_threshold` options on both audio-chunk and URL connections. These
+extensions are not a claim of upstream ElevenLabs realtime feature parity.
+Omitted extension options are not added to the query; explicit booleans are
+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. 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.
+`RealtimeEvents.WARNING` delivers nonfatal warnings without also dispatching
+`ERROR`. A timing warning can replace a timed result; the preceding plain
+committed transcript remains usable. See the
+[ASR options and event guidance](migration.md#recognition-and-context-hints).
+
 ## URLs and authentication
 
 - `Avartha` and `Control` accept a platform root, including a proxy prefix.

{avartha_python_sdk-0.0.5 → 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).
 
@@ -191,9 +203,7 @@ with ElevenLabs() as client:
     if voices:
         voice = client.voices.get(voices[0].voice_id, request_options=options)
         settings = client.voices.settings.get(voice.voice_id, request_options=options)
-    languages = client.speech_to_text.languages.list(
-        model_id="mistralai/voxtral-mini-4b-realtime-2602"
-    )
+    languages = client.speech_to_text.languages.list(model_id="YOUR_ASR_MODEL_ID")
 ```
 
 Use `AsyncElevenLabs` with `async with` and `await` for each call. Each resource
@@ -213,15 +223,21 @@ available as `error.__cause__`.
 `model_id` is an Avartha query extension for voice discovery. Specify it when
 more than one TTS model is available. The platform supports `search`, `page_size`,
 `next_page_token`, and `include_total_count` on `voices.search`; other vendor
-filters are forwarded and may be rejected by the server. ASR language hints
-can be unavailable, with `language_hints_supported=False` and an empty list.
+filters are forwarded and may be rejected by the server. The language helper
+selects the requested ASR model from `models.list()`. An empty language list
+means hints are unsupported (`language_hints_supported=False`); a missing
+model or missing language metadata raises `ApiError` instead.
 See [supported HTTP endpoints and server prerequisites](compatibility.md#speech-http-discovery).
 
 ### 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.
 
@@ -248,8 +264,17 @@ transcripts. Handlers can be ordinary functions or async functions.
 ASR events retain their names and raw dictionary payloads, including the
 deprecated `UNACCEPTED_TERMS_ERROR` callback alias.
 
-`previous_text` supplies optional text context for transcription. When omitted,
-Avartha sends `null`, meaning no context. Audio-send code can omit the field:
+Current ASR models require raw 16 kHz mono PCM16 samples without a file header.
+For audio chunks, select `AudioFormat.PCM_16000` and `sample_rate=16000`, and
+convert other formats or sample rates before sending. The SDK does not
+resample chunks or convert their encoding. URL mode uses FFmpeg to convert the
+source to the required format and requires FFmpeg on `PATH`.
+
+Nonempty `previous_text` is unsupported by current ASR models. The SDK
+preserves this protocol field, but the server rejects nonempty values rather
+than using them as context. Omission, `None`, or an empty string supplies no
+context. Use `keyterms` in the connection options for vocabulary hints on
+supported models. Audio-send code can omit `previous_text`; the SDK sends `null`:
 
 ```python
 async def send_audio(connection, encoded_chunk):
@@ -269,6 +294,106 @@ In an application or notebook with a running event loop, await the workflow
 directly instead of calling `asyncio.run()`. Close the live session before
 leaving the client context; closing the client only closes its HTTP transports.
 
+#### Recognition and context hints
+
+Pass options to `realtime.connect()` using `RealtimeAudioOptions` for audio
+chunks or `RealtimeUrlOptions` for an audio URL. The SDK forwards these settings;
+the selected model and server must support them.
+
+`filter_background_audio=True` enables experimental background speech filtering
+on supported models. Use it to reduce transcription of background speakers.
+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.
+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
+
+`commit_strategy=CommitStrategy.MANUAL` is the default. Send audio, then call
+`await connection.commit()` when your application decides the utterance is
+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`. 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
+
+options = RealtimeAudioOptions(
+    model_id="YOUR_ASR_MODEL_ID",
+    audio_format=AudioFormat.PCM_16000,
+    sample_rate=16000,
+    commit_strategy=CommitStrategy.VAD,
+    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.
+These are model scores, not calibrated confidence percentages. This option does
+not enable timestamps. `include_timestamps=True` requests a separate
+`RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS` event after the plain
+committed transcript. Use it to enrich the same utterance, not append a duplicate.
+
+`diarize=True` requests speaker labels and requires `include_timestamps=True`.
+On supported models, timed `words` entries can include `speaker_id` alongside
+`start` and `end`. Speaker labels may be absent if diarization fails; timestamps
+can still be returned. These three options default to off. For a model and
+language that support the requested details:
+
+Add `include_timestamps=True`, `diarize=True`, and `include_logprobs=True` to
+the `RealtimeAudioOptions` above before connecting. Omit options you do not need.
+
+Register handlers before sending audio. Callbacks receive the unmodified server
+dictionary, including word scores, timestamps, and speaker labels:
+
+```python
+from avartha import RealtimeEvents
+
+connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, lambda event: print(event["text"]))
+connection.on(
+    RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS,
+    lambda event: print(event.get("words", [])),
+)
+connection.on(RealtimeEvents.WARNING, lambda event: print("Warning:", event))
+connection.on(RealtimeEvents.ERROR, lambda event: print("Error:", event))
+```
+
+If timing cannot be produced, the server can send a `WARNING` instead of the
+timed event. Retain the plain committed transcript. Warnings do not trigger the
+`ERROR` callback or close the SDK connection. When waiting for optional metadata,
+handle both the timed event and the warning, and use an application timeout.
+Do not close immediately after the plain final if you still need its metadata.
+
 ## Configuration
 
 | Setting | Avartha behavior |