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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.5
+Version: 0.0.6
 Summary: Python clients for Avartha Realtime text, streaming speech, and platform management
 Author-email: "Avartha Inc." <team@avartha.ai>
 License-Expression: LicenseRef-Avartha-Proprietary

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

@@ -221,7 +221,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,12 +231,20 @@ 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, Smart Turn, 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

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

@@ -124,9 +124,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
@@ -258,6 +262,39 @@ Audio formats and `voice_settings` depend on the selected model. Specifying an
 option in the SDK does not make it available on the server. Runnable examples:
 [single-context](../examples/tts.py), [multi-context](../examples/tts_multi_context.py).
 
+## 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.
+
+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. 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.
+
+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.6}/docs/migration.md

@@ -191,9 +191,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,8 +211,10 @@ 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
@@ -248,8 +248,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 +278,94 @@ 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.
+`language_code` can constrain recognition to a supported language; 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`. 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:
+
+```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="smart_turn_v3",
+    turn_threshold=0.5,
+)
+connection = await client.speech_to_text.realtime.connect(options)
+```
+
+#### 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 |

{avartha_python_sdk-0.0.5 → avartha_python_sdk-0.0.6}/examples/realtime_asr.py

@@ -1,7 +1,8 @@
-"""Stream mono, signed 16-bit PCM WAV audio with the ElevenLabs ASR protocol.
+"""Stream 16 kHz mono, signed 16-bit PCM WAV audio with the ElevenLabs ASR protocol.
 
 Set AVARTHA_API_KEY and optionally AVARTHA_BASE_URL.
-Run: python examples/realtime_asr.py MODEL_ID speech.wav
+Run: python examples/realtime_asr.py MODEL_ID speech-16k.wav
+Convert other sample rates before running; this example does not resample audio.
 """
 
 import argparse
@@ -39,6 +40,7 @@ async def run(model: str, audio_path: str):
 
             connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, lambda event: print(event["text"]))
             connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, transcript)
+            connection.on(RealtimeEvents.WARNING, lambda event: print("Warning:", event))
             connection.on(RealtimeEvents.ERROR, failed)
             try:
                 while chunk := audio.readframes(sample_rate // 10):

{avartha_python_sdk-0.0.5 → avartha_python_sdk-0.0.6}/src/avartha/_realtime_asr.py

@@ -7,7 +7,7 @@ import json
 import logging
 from collections.abc import Callable
 from enum import Enum
-from typing import Any, Required, TypedDict, cast
+from typing import Any, Literal, Required, TypedDict, cast
 
 from websockets.asyncio.client import ClientConnection
 
@@ -45,6 +45,7 @@ class RealtimeEvents(str, Enum):  # noqa: UP042 - preserve the upstream str() re
     COMMITTED_TRANSCRIPT = "committed_transcript"
     COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS = "committed_transcript_with_timestamps"
     COMMITTED_TRANSCRIPT_ENTITIES = "committed_transcript_entities"
+    WARNING = "warning"
     ERROR = "error"
     AUTH_ERROR = "auth_error"
     QUOTA_EXCEEDED = "quota_exceeded"
@@ -69,9 +70,15 @@ class _SharedOptions(TypedDict, total=False):
     vad_threshold: float
     min_speech_duration_ms: int
     min_silence_duration_ms: int
+    # Avartha turn controls require VAD; availability is validated by the server.
+    turn_model: Literal["silence", "smart_turn_v3"]
+    turn_threshold: float
     language_code: str
     secondary_languages: list[str]
     include_timestamps: bool
+    # Avartha extensions: diarization also requires include_timestamps=True.
+    diarize: bool
+    include_logprobs: bool
     include_language_detection: bool
     keyterms: list[str]
     no_verbatim: bool
@@ -105,6 +112,7 @@ _NON_ERRORS = {
     RealtimeEvents.COMMITTED_TRANSCRIPT,
     RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS,
     RealtimeEvents.COMMITTED_TRANSCRIPT_ENTITIES,
+    RealtimeEvents.WARNING,
     RealtimeEvents.ERROR,
 }
 

{avartha_python_sdk-0.0.5 → avartha_python_sdk-0.0.6}/src/avartha/_speech_http.py

@@ -5,7 +5,7 @@ import email.utils
 import json
 import random
 import time
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from datetime import UTC, datetime
 from typing import Any
 from urllib.parse import quote
@@ -38,6 +38,9 @@ class HttpResponse[T]:
     def close(self) -> None:
         self._response.close()
 
+    def map_data[U](self, transform: Callable[[T], U]) -> "HttpResponse[U]":
+        return HttpResponse(self._response, transform(self.data))
+
 
 class AsyncHttpResponse[T]:
     """Async variant of the typed HTTP response wrapper."""
@@ -57,6 +60,9 @@ class AsyncHttpResponse[T]:
     async def close(self) -> None:
         await self._response.aclose()
 
+    def map_data[U](self, transform: Callable[[T], U]) -> "AsyncHttpResponse[U]":
+        return AsyncHttpResponse(self._response, transform(self.data))
+
 
 def segment(value: str) -> str:
     if value in {".", ".."}:

{avartha_python_sdk-0.0.5 → avartha_python_sdk-0.0.6}/src/avartha/_speech_resources.py

@@ -8,6 +8,7 @@ an Avartha extension. Transport and credentials are handled inside the SDK.
 import builtins
 from collections.abc import Sequence
 
+from ._exceptions import ApiError
 from ._speech_config import RequestOptions
 from ._speech_http import (
     AsyncHttpResponse,
@@ -17,7 +18,42 @@ from ._speech_http import (
     segment,
 )
 from .types.speech import GetVoicesResponse, GetVoicesV2Response, Model, Voice, VoiceSettings
-from .types.speech_language import SpeechLanguageList
+from .types.speech_language import SpeechLanguage, SpeechLanguageList
+
+
+def _model_languages(models: list[Model], model_id: str) -> SpeechLanguageList:
+    matches = [model for model in models if model.model_id == model_id]
+    if len(matches) != 1:
+        raise ApiError(body=f"ASR model {model_id!r} is missing or ambiguous in the model catalog")
+    model = matches[0]
+    model_type = getattr(model, "model_type", None)
+    # Direct ASR runtimes expose vendor capabilities without Platform's type tag.
+    is_asr = model_type == "speech_to_text" or (
+        model_type is None
+        and model.can_do_text_to_speech is False
+        and model.can_do_voice_conversion is False
+    )
+    if not is_asr:
+        raise ApiError(body=f"Model {model_id!r} is not identified as ASR in the model catalog")
+    languages = model.languages
+    if languages is None:
+        raise ApiError(body=f"Language metadata is unavailable for ASR model {model_id!r}")
+    if not isinstance(languages, list) or any(
+        not isinstance(getattr(language, "language_id", None), str)
+        or not language.language_id
+        or not isinstance(getattr(language, "name", None), str)
+        or not language.name
+        for language in languages
+    ):
+        raise ApiError(body=f"Invalid language metadata for ASR model {model_id!r}")
+    return SpeechLanguageList(
+        object="list",
+        model=model_id,
+        language_hints_supported=bool(languages),
+        languages=[
+            SpeechLanguage(code=language.language_id, name=language.name) for language in languages
+        ],
+    )
 
 
 class RawVoices:
@@ -137,12 +173,13 @@ class RawLanguages:
     def list(
         self, *, model_id: str, request_options: RequestOptions | None = None
     ) -> HttpResponse[SpeechLanguageList]:
-        return self._client.get(
-            "v1/speech-to-text/languages",
-            SpeechLanguageList,
-            params={"model_id": model_id},
+        response = self._client.get(
+            "v1/models",
+            builtins.list[Model],
+            params={},
             request_options=request_options,
         )
+        return response.map_data(lambda models: _model_languages(models, model_id))
 
 
 class Voices:
@@ -361,12 +398,13 @@ class AsyncRawLanguages:
     async def list(
         self, *, model_id: str, request_options: RequestOptions | None = None
     ) -> AsyncHttpResponse[SpeechLanguageList]:
-        return await self._client.get(
-            "v1/speech-to-text/languages",
-            SpeechLanguageList,
-            params={"model_id": model_id},
+        response = await self._client.get(
+            "v1/models",
+            builtins.list[Model],
+            params={},
             request_options=request_options,
         )
+        return response.map_data(lambda models: _model_languages(models, model_id))
 
 
 class AsyncVoices:

{avartha_python_sdk-0.0.5 → avartha_python_sdk-0.0.6}/src/avartha_python_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avartha-python-sdk
-Version: 0.0.5
+Version: 0.0.6
 Summary: Python clients for Avartha Realtime text, streaming speech, and platform management
 Author-email: "Avartha Inc." <team@avartha.ai>
 License-Expression: LicenseRef-Avartha-Proprietary