avartha-python-sdk 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
avartha/__init__.py CHANGED
@@ -30,7 +30,12 @@ from ._openai_http_errors import UnprocessableEntityError as OpenAIUnprocessable
30
30
  from ._pacing import WebSocketLimits
31
31
  from ._realtime_asr import AudioFormat, CommitStrategy, RealtimeAudioOptions, RealtimeEvents
32
32
  from ._realtime_tts import DEFAULT_OUTPUT_FORMAT as DEFAULT_TTS_OUTPUT_FORMAT
33
- from ._realtime_tts import AsyncMultiContextSession, MultiContextSession, audio_bytes
33
+ from ._realtime_tts import (
34
+ AsyncMultiContextSession,
35
+ MultiContextSession,
36
+ TextToSpeechOutputFormat,
37
+ audio_bytes,
38
+ )
34
39
  from ._sentinels import NOT_GIVEN, NotGiven, Omit, not_given, omit
35
40
  from .client import AsyncAvartha, Avartha
36
41
  from .control import AsyncControl, Control
@@ -91,6 +96,7 @@ __all__ = [
91
96
  "PlatformAPIError",
92
97
  "RealtimeAudioOptions",
93
98
  "RealtimeEvents",
99
+ "TextToSpeechOutputFormat",
94
100
  "VoiceSettings",
95
101
  "WebSocketLimits",
96
102
  "audio_bytes",
@@ -0,0 +1,355 @@
1
+ """Typed resources for Avartha's conversation routes.
2
+
3
+ Their parameters are the ones the platform accepts, which is a small subset of ElevenLabs
4
+ 2.68.0. It refuses unknown query parameters, so the vendor's other filters would only fail.
5
+ """
6
+
7
+ import json
8
+ from collections.abc import Mapping
9
+ from typing import Any, Never
10
+
11
+ from ._speech_config import RequestOptions
12
+ from ._speech_http import (
13
+ AsyncHttpResponse,
14
+ AsyncSpeechHTTPClient,
15
+ HttpResponse,
16
+ SpeechHTTPClient,
17
+ segment,
18
+ )
19
+ from .types.conversational_ai import (
20
+ ConversationSignedUrlResponseModel,
21
+ GetConversationResponseModel,
22
+ GetConversationsPageResponseModel,
23
+ TokenResponseModel,
24
+ )
25
+
26
+ _BASE = "v1/convai"
27
+
28
+
29
+ def _encoded(value: Mapping[str, Any] | None) -> str | None:
30
+ return None if not value else json.dumps(value, separators=(",", ":"))
31
+
32
+
33
+ def _mint_params(
34
+ agent_id: str,
35
+ origin: str | None,
36
+ conversation_config_override: Mapping[str, Any] | None,
37
+ dynamic_variables: Mapping[str, Any] | None,
38
+ ) -> dict[str, Any]:
39
+ return {
40
+ "agent_id": agent_id,
41
+ "origin": origin,
42
+ "conversation_config_override": _encoded(conversation_config_override),
43
+ "dynamic_variables": _encoded(dynamic_variables),
44
+ }
45
+
46
+
47
+ class RawConversations:
48
+ def __init__(self, client: SpeechHTTPClient) -> None:
49
+ self._client = client
50
+
51
+ def get_signed_url(
52
+ self,
53
+ *,
54
+ agent_id: str,
55
+ origin: str | None = None,
56
+ conversation_config_override: Mapping[str, Any] | None = None,
57
+ dynamic_variables: Mapping[str, Any] | None = None,
58
+ request_options: RequestOptions | None = None,
59
+ ) -> HttpResponse[ConversationSignedUrlResponseModel]:
60
+ return self._client.get(
61
+ f"{_BASE}/conversation/get-signed-url",
62
+ ConversationSignedUrlResponseModel,
63
+ params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
64
+ request_options=request_options,
65
+ )
66
+
67
+ def get_webrtc_token(
68
+ self,
69
+ *,
70
+ agent_id: str,
71
+ origin: str | None = None,
72
+ conversation_config_override: Mapping[str, Any] | None = None,
73
+ dynamic_variables: Mapping[str, Any] | None = None,
74
+ request_options: RequestOptions | None = None,
75
+ ) -> HttpResponse[TokenResponseModel]:
76
+ return self._client.get(
77
+ f"{_BASE}/conversation/token",
78
+ TokenResponseModel,
79
+ params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
80
+ request_options=request_options,
81
+ )
82
+
83
+ def list(
84
+ self, *, cursor: str | None = None, request_options: RequestOptions | None = None
85
+ ) -> HttpResponse[GetConversationsPageResponseModel]:
86
+ return self._client.get(
87
+ f"{_BASE}/conversations",
88
+ GetConversationsPageResponseModel,
89
+ params={"cursor": cursor},
90
+ request_options=request_options,
91
+ )
92
+
93
+ def get(
94
+ self,
95
+ conversation_id: str,
96
+ *,
97
+ format: str | None = None,
98
+ request_options: RequestOptions | None = None,
99
+ ) -> HttpResponse[GetConversationResponseModel]:
100
+ return self._client.get(
101
+ f"{_BASE}/conversations/{segment(conversation_id)}",
102
+ GetConversationResponseModel,
103
+ params={"format": format},
104
+ request_options=request_options,
105
+ )
106
+
107
+ def end(
108
+ self, conversation_id: str, *, request_options: RequestOptions | None = None
109
+ ) -> HttpResponse[GetConversationResponseModel]:
110
+ return self._client.post(
111
+ f"{_BASE}/conversations/{segment(conversation_id)}/end",
112
+ GetConversationResponseModel,
113
+ params={},
114
+ request_options=request_options,
115
+ )
116
+
117
+
118
+ class Conversations:
119
+ """Mint connection grants and read or end conversations."""
120
+
121
+ def __init__(self, client: SpeechHTTPClient) -> None:
122
+ self.with_raw_response = RawConversations(client)
123
+
124
+ def get_signed_url(
125
+ self,
126
+ *,
127
+ agent_id: str,
128
+ origin: str | None = None,
129
+ conversation_config_override: Mapping[str, Any] | None = None,
130
+ dynamic_variables: Mapping[str, Any] | None = None,
131
+ request_options: RequestOptions | None = None,
132
+ ) -> ConversationSignedUrlResponseModel:
133
+ """Mint a single-use WebSocket URL that expires in 30 seconds."""
134
+ return self.with_raw_response.get_signed_url(
135
+ agent_id=agent_id,
136
+ origin=origin,
137
+ conversation_config_override=conversation_config_override,
138
+ dynamic_variables=dynamic_variables,
139
+ request_options=request_options,
140
+ ).data
141
+
142
+ def get_webrtc_token(
143
+ self,
144
+ *,
145
+ agent_id: str,
146
+ origin: str | None = None,
147
+ conversation_config_override: Mapping[str, Any] | None = None,
148
+ dynamic_variables: Mapping[str, Any] | None = None,
149
+ request_options: RequestOptions | None = None,
150
+ ) -> TokenResponseModel:
151
+ """Mint a grant for a browser's WebRTC connection."""
152
+ return self.with_raw_response.get_webrtc_token(
153
+ agent_id=agent_id,
154
+ origin=origin,
155
+ conversation_config_override=conversation_config_override,
156
+ dynamic_variables=dynamic_variables,
157
+ request_options=request_options,
158
+ ).data
159
+
160
+ def list(
161
+ self, *, cursor: str | None = None, request_options: RequestOptions | None = None
162
+ ) -> GetConversationsPageResponseModel:
163
+ """Return up to 100 conversations; pass next_cursor as cursor for the next page."""
164
+ return self.with_raw_response.list(cursor=cursor, request_options=request_options).data
165
+
166
+ def get(
167
+ self,
168
+ conversation_id: str,
169
+ *,
170
+ format: str | None = None,
171
+ request_options: RequestOptions | None = None,
172
+ ) -> GetConversationResponseModel:
173
+ """Return a conversation's status, retained transcript, and billing."""
174
+ return self.with_raw_response.get(
175
+ conversation_id, format=format, request_options=request_options
176
+ ).data
177
+
178
+ def end(
179
+ self, conversation_id: str, *, request_options: RequestOptions | None = None
180
+ ) -> GetConversationResponseModel:
181
+ """End a conversation; ending one that has finished is safe. Avartha extension."""
182
+ return self.with_raw_response.end(conversation_id, request_options=request_options).data
183
+
184
+
185
+ class AsyncRawConversations:
186
+ def __init__(self, client: AsyncSpeechHTTPClient) -> None:
187
+ self._client = client
188
+
189
+ async def get_signed_url(
190
+ self,
191
+ *,
192
+ agent_id: str,
193
+ origin: str | None = None,
194
+ conversation_config_override: Mapping[str, Any] | None = None,
195
+ dynamic_variables: Mapping[str, Any] | None = None,
196
+ request_options: RequestOptions | None = None,
197
+ ) -> AsyncHttpResponse[ConversationSignedUrlResponseModel]:
198
+ return await self._client.get(
199
+ f"{_BASE}/conversation/get-signed-url",
200
+ ConversationSignedUrlResponseModel,
201
+ params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
202
+ request_options=request_options,
203
+ )
204
+
205
+ async def get_webrtc_token(
206
+ self,
207
+ *,
208
+ agent_id: str,
209
+ origin: str | None = None,
210
+ conversation_config_override: Mapping[str, Any] | None = None,
211
+ dynamic_variables: Mapping[str, Any] | None = None,
212
+ request_options: RequestOptions | None = None,
213
+ ) -> AsyncHttpResponse[TokenResponseModel]:
214
+ return await self._client.get(
215
+ f"{_BASE}/conversation/token",
216
+ TokenResponseModel,
217
+ params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
218
+ request_options=request_options,
219
+ )
220
+
221
+ async def list(
222
+ self, *, cursor: str | None = None, request_options: RequestOptions | None = None
223
+ ) -> AsyncHttpResponse[GetConversationsPageResponseModel]:
224
+ return await self._client.get(
225
+ f"{_BASE}/conversations",
226
+ GetConversationsPageResponseModel,
227
+ params={"cursor": cursor},
228
+ request_options=request_options,
229
+ )
230
+
231
+ async def get(
232
+ self,
233
+ conversation_id: str,
234
+ *,
235
+ format: str | None = None,
236
+ request_options: RequestOptions | None = None,
237
+ ) -> AsyncHttpResponse[GetConversationResponseModel]:
238
+ return await self._client.get(
239
+ f"{_BASE}/conversations/{segment(conversation_id)}",
240
+ GetConversationResponseModel,
241
+ params={"format": format},
242
+ request_options=request_options,
243
+ )
244
+
245
+ async def end(
246
+ self, conversation_id: str, *, request_options: RequestOptions | None = None
247
+ ) -> AsyncHttpResponse[GetConversationResponseModel]:
248
+ return await self._client.post(
249
+ f"{_BASE}/conversations/{segment(conversation_id)}/end",
250
+ GetConversationResponseModel,
251
+ params={},
252
+ request_options=request_options,
253
+ )
254
+
255
+
256
+ class AsyncConversations:
257
+ """Mint connection grants and read or end conversations."""
258
+
259
+ def __init__(self, client: AsyncSpeechHTTPClient) -> None:
260
+ self.with_raw_response = AsyncRawConversations(client)
261
+
262
+ async def get_signed_url(
263
+ self,
264
+ *,
265
+ agent_id: str,
266
+ origin: str | None = None,
267
+ conversation_config_override: Mapping[str, Any] | None = None,
268
+ dynamic_variables: Mapping[str, Any] | None = None,
269
+ request_options: RequestOptions | None = None,
270
+ ) -> ConversationSignedUrlResponseModel:
271
+ """Mint a single-use WebSocket URL that expires in 30 seconds."""
272
+ response = await self.with_raw_response.get_signed_url(
273
+ agent_id=agent_id,
274
+ origin=origin,
275
+ conversation_config_override=conversation_config_override,
276
+ dynamic_variables=dynamic_variables,
277
+ request_options=request_options,
278
+ )
279
+ return response.data
280
+
281
+ async def get_webrtc_token(
282
+ self,
283
+ *,
284
+ agent_id: str,
285
+ origin: str | None = None,
286
+ conversation_config_override: Mapping[str, Any] | None = None,
287
+ dynamic_variables: Mapping[str, Any] | None = None,
288
+ request_options: RequestOptions | None = None,
289
+ ) -> TokenResponseModel:
290
+ """Mint a grant for a browser's WebRTC connection."""
291
+ response = await self.with_raw_response.get_webrtc_token(
292
+ agent_id=agent_id,
293
+ origin=origin,
294
+ conversation_config_override=conversation_config_override,
295
+ dynamic_variables=dynamic_variables,
296
+ request_options=request_options,
297
+ )
298
+ return response.data
299
+
300
+ async def list(
301
+ self, *, cursor: str | None = None, request_options: RequestOptions | None = None
302
+ ) -> GetConversationsPageResponseModel:
303
+ """Return up to 100 conversations; pass next_cursor as cursor for the next page."""
304
+ response = await self.with_raw_response.list(cursor=cursor, request_options=request_options)
305
+ return response.data
306
+
307
+ async def get(
308
+ self,
309
+ conversation_id: str,
310
+ *,
311
+ format: str | None = None,
312
+ request_options: RequestOptions | None = None,
313
+ ) -> GetConversationResponseModel:
314
+ """Return a conversation's status, retained transcript, and billing."""
315
+ response = await self.with_raw_response.get(
316
+ conversation_id, format=format, request_options=request_options
317
+ )
318
+ return response.data
319
+
320
+ async def end(
321
+ self, conversation_id: str, *, request_options: RequestOptions | None = None
322
+ ) -> GetConversationResponseModel:
323
+ """End a conversation; ending one that has finished is safe. Avartha extension."""
324
+ response = await self.with_raw_response.end(
325
+ conversation_id, request_options=request_options
326
+ )
327
+ return response.data
328
+
329
+
330
+ class _ConversationalAi:
331
+ def __getattr__(self, name: str) -> Never:
332
+ if name.startswith("_"):
333
+ raise AttributeError(name)
334
+ if name == "twilio":
335
+ # Phone calls need workspace features that aren't available to every workspace.
336
+ raise NotImplementedError(
337
+ "conversational_ai.twilio is not available in this SDK. "
338
+ "conversational_ai.conversations is available."
339
+ )
340
+ raise NotImplementedError(
341
+ f"conversational_ai.{name} is not implemented. ElevenLabs-schema agents, tools, and "
342
+ "knowledge bases will be implemented in a future release; "
343
+ "conversational_ai.conversations is available, "
344
+ "and Control.voice_agents manages Avartha voice agents."
345
+ )
346
+
347
+
348
+ class ConversationalAi(_ConversationalAi):
349
+ def __init__(self, client: SpeechHTTPClient) -> None:
350
+ self.conversations = Conversations(client)
351
+
352
+
353
+ class AsyncConversationalAi(_ConversationalAi):
354
+ def __init__(self, client: AsyncSpeechHTTPClient) -> None:
355
+ self.conversations = AsyncConversations(client)
avartha/_openai_http.py CHANGED
@@ -133,7 +133,10 @@ def _check_status(response: httpx.Response) -> None:
133
133
  body = response.json()
134
134
  except ValueError:
135
135
  body = response.text
136
- error_body = body.get("error", body) if isinstance(body, dict) else body
136
+ # OpenAI nests error details; the platform also returns flat envelopes whose
137
+ # string `error` is a message, with code/type/param alongside it.
138
+ nested = body.get("error") if isinstance(body, dict) else None
139
+ error_body = nested if isinstance(nested, dict) else body
137
140
  cls = {
138
141
  400: BadRequestError,
139
142
  401: AuthenticationError,
avartha/_realtime_asr.py CHANGED
@@ -5,7 +5,8 @@ import base64
5
5
  import inspect
6
6
  import json
7
7
  import logging
8
- from collections.abc import Callable
8
+ import math
9
+ from collections.abc import Callable, Mapping
9
10
  from enum import Enum
10
11
  from typing import Any, Literal, Required, TypedDict, cast
11
12
 
@@ -34,6 +35,10 @@ class CommitStrategy(str, Enum): # noqa: UP042 - preserve the upstream str() re
34
35
 
35
36
  type RealtimeEntityDetection = str | list[str]
36
37
 
38
+ # `silence` is the default. A semantic model must also be loaded by the
39
+ # deployment: shipped Qwen3-ASR profiles load `turn_eot_t3_v1`, not `smart_turn_v3`.
40
+ type TurnModel = Literal["silence", "smart_turn_v3", "turn_eot_t3_v1"]
41
+
37
42
 
38
43
  class RealtimeEvents(str, Enum): # noqa: UP042 - preserve the upstream str() representation
39
44
  OPEN = "open"
@@ -70,8 +75,8 @@ class _SharedOptions(TypedDict, total=False):
70
75
  vad_threshold: float
71
76
  min_speech_duration_ms: int
72
77
  min_silence_duration_ms: int
73
- # Avartha turn controls require VAD; availability is validated by the server.
74
- turn_model: Literal["silence", "smart_turn_v3"]
78
+ # Avartha turn controls require VAD; the server checks the model is loaded.
79
+ turn_model: TurnModel
75
80
  turn_threshold: float
76
81
  language_code: str
77
82
  secondary_languages: list[str]
@@ -102,6 +107,113 @@ class AudioChunk(TypedDict, total=False):
102
107
  previous_text: str | None
103
108
 
104
109
 
110
+ # Settings the runtime accepts only with commit_strategy=vad.
111
+ _VAD_OPTIONS = (
112
+ "vad_silence_threshold_secs",
113
+ "vad_threshold",
114
+ "min_speech_duration_ms",
115
+ "min_silence_duration_ms",
116
+ "turn_model",
117
+ "turn_threshold",
118
+ )
119
+ # Fixed runtime bounds; refusing them locally avoids a connection that the
120
+ # server would close with the same explanation.
121
+ _VAD_HISTORY_MS = 8000
122
+ _VAD_FRAME_MS = 32
123
+ _VAD_PREFIX_MS = 300
124
+ # Shipped Qwen3-ASR context-biasing limits, counted after trimming each term.
125
+ # The server also caps the terms' combined tokenizer tokens (about 40); that
126
+ # depends on the model's tokenizer and is checked only by the server.
127
+ _MAX_KEYTERMS = 16
128
+ _MAX_KEYTERM_WORDS = 40
129
+ _MAX_KEYTERM_BYTES = 128
130
+
131
+
132
+ def _number(name: str, value: Any) -> float:
133
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
134
+ raise ValueError(f"{name} must be a finite number")
135
+ return float(value)
136
+
137
+
138
+ def _milliseconds(name: str, value: Any) -> int:
139
+ if isinstance(value, bool) or not isinstance(value, int) or not 0 <= value <= _VAD_HISTORY_MS:
140
+ raise ValueError(f"{name} must be an integer from 0 to {_VAD_HISTORY_MS}")
141
+ return int(value)
142
+
143
+
144
+ def _check_keyterms(keyterms: Any) -> None:
145
+ if isinstance(keyterms, str) or not isinstance(keyterms, (list, tuple)):
146
+ raise ValueError("keyterms must be a list of strings, one per term")
147
+ if len(keyterms) > _MAX_KEYTERMS:
148
+ raise ValueError(f"{len(keyterms)} keyterms; the server allows {_MAX_KEYTERMS}")
149
+ words = 0
150
+ for index, term in enumerate(keyterms):
151
+ if not isinstance(term, str):
152
+ raise ValueError(f"keyterms[{index}] must be a string")
153
+ if not term.strip():
154
+ raise ValueError(f"keyterms[{index}] is blank; omit it")
155
+ try:
156
+ size = len(term.encode("utf-8"))
157
+ except UnicodeEncodeError:
158
+ raise ValueError(f"keyterms[{index}] is not valid UTF-8 text") from None
159
+ if size > _MAX_KEYTERM_BYTES:
160
+ raise ValueError(
161
+ f"keyterms[{index}] has {size} UTF-8 bytes; the server allows {_MAX_KEYTERM_BYTES}"
162
+ )
163
+ if any(ord(c) < 0x20 or 0x7F <= ord(c) <= 0x9F for c in term):
164
+ raise ValueError(f"keyterms[{index}] contains a control character")
165
+ words += len(term.split())
166
+ if words > _MAX_KEYTERM_WORDS:
167
+ raise ValueError(f"keyterms have {words} words; the server allows {_MAX_KEYTERM_WORDS}")
168
+
169
+
170
+ def _check_options(options: Mapping[str, Any], strategy: CommitStrategy) -> None:
171
+ """Refuse settings the Avartha ASR runtime always refuses, before connecting."""
172
+ given = {key: value for key, value in options.items() if value is not None}
173
+ vad_options = [key for key in _VAD_OPTIONS if key in given]
174
+ if vad_options and strategy != CommitStrategy.VAD:
175
+ verb = "requires" if len(vad_options) == 1 else "require"
176
+ raise ValueError(f"{', '.join(vad_options)} {verb} commit_strategy=CommitStrategy.VAD")
177
+ turn_model = given.get("turn_model", "silence")
178
+ if "turn_threshold" in given:
179
+ if turn_model == "silence":
180
+ raise ValueError(
181
+ "turn_threshold requires a semantic turn_model such as 'turn_eot_t3_v1'"
182
+ )
183
+ if not 0 < _number("turn_threshold", given["turn_threshold"]) < 1:
184
+ raise ValueError("turn_threshold must be strictly between 0 and 1")
185
+ if "vad_threshold" in given and not 0 < _number("vad_threshold", given["vad_threshold"]) < 1:
186
+ raise ValueError("vad_threshold must be strictly between 0 and 1")
187
+ silence = 1.0 if turn_model == "silence" else 2.0
188
+ if "vad_silence_threshold_secs" in given:
189
+ silence = _number("vad_silence_threshold_secs", given["vad_silence_threshold_secs"])
190
+ if not 0.2 <= silence <= 5.0:
191
+ raise ValueError("vad_silence_threshold_secs must be from 0.2 to 5.0 seconds")
192
+ if "min_speech_duration_ms" in given:
193
+ speech = _milliseconds("min_speech_duration_ms", given["min_speech_duration_ms"])
194
+ frames = math.ceil(max(1, speech) / _VAD_FRAME_MS)
195
+ if frames * _VAD_FRAME_MS + _VAD_PREFIX_MS > _VAD_HISTORY_MS:
196
+ raise ValueError(
197
+ "min_speech_duration_ms, rounded up to 32 ms frames, plus 300 ms of "
198
+ "prefix audio must fit the 8,000 ms ASR history"
199
+ )
200
+ if "min_silence_duration_ms" in given:
201
+ pause = _milliseconds("min_silence_duration_ms", given["min_silence_duration_ms"])
202
+ if pause / 1000 >= silence:
203
+ raise ValueError(
204
+ "min_silence_duration_ms must be shorter than vad_silence_threshold_secs "
205
+ f"({silence:g} s)"
206
+ )
207
+ if "language_code" in given:
208
+ code = given["language_code"]
209
+ if not isinstance(code, str) or code.strip().lower() in {"", "auto"}:
210
+ raise ValueError(
211
+ "language_code must name a supported language; omit it for automatic detection"
212
+ )
213
+ if "keyterms" in given:
214
+ _check_keyterms(given["keyterms"])
215
+
216
+
105
217
  _NON_ERRORS = {
106
218
  RealtimeEvents.OPEN,
107
219
  RealtimeEvents.CLOSE,
@@ -231,9 +343,17 @@ class RealtimeConnection:
231
343
  process = self.ffmpeg_process
232
344
  assert process is not None and process.stdout is not None
233
345
  try:
346
+ sent_audio = False
234
347
  while chunk := await process.stdout.read(8192):
235
348
  await self.send({"audio_base_64": base64.b64encode(chunk).decode("ascii")})
349
+ sent_audio = True
236
350
  await asyncio.sleep(0.01)
351
+ if await process.wait() != 0:
352
+ raise RuntimeError(f"FFmpeg exited with status {process.returncode}")
353
+ if sent_audio:
354
+ # EOF supplies no silence to trigger VAD; request the final turn
355
+ # explicitly and leave the receive task alive to deliver it.
356
+ await self.commit()
237
357
  except Exception as exc:
238
358
  await self._emit(RealtimeEvents.ERROR, {"error": f"FFmpeg streaming error: {exc}"})
239
359
  finally:
@@ -241,9 +361,12 @@ class RealtimeConnection:
241
361
 
242
362
 
243
363
  class ScribeRealtime:
244
- def __init__(self, api_key: str, base_url: str) -> None:
364
+ def __init__(
365
+ self, api_key: str, base_url: str, *, headers: Mapping[str, str] | None = None
366
+ ) -> None:
245
367
  self.api_key = api_key
246
368
  self.base_url = base_url
369
+ self.headers = dict(headers or {})
247
370
 
248
371
  async def connect(
249
372
  self, options: RealtimeAudioOptions | RealtimeUrlOptions
@@ -261,7 +384,11 @@ class ScribeRealtime:
261
384
  )
262
385
  if not audio_format or not sample_rate:
263
386
  raise ValueError("audio_format and sample_rate are required for manual audio mode")
387
+ expected_rate = int(audio_format.value.rsplit("_", 1)[1])
388
+ if sample_rate != expected_rate:
389
+ raise ValueError(f"sample_rate must be {expected_rate} for {audio_format.value}")
264
390
  strategy = options.get("commit_strategy", CommitStrategy.MANUAL)
391
+ _check_options(options, strategy)
265
392
  parameters: dict[str, Any] = {
266
393
  "model_id": options["model_id"],
267
394
  "audio_format": audio_format.value,
@@ -279,7 +406,9 @@ class ScribeRealtime:
279
406
  parameters.pop("include_timestamps", None)
280
407
  else:
281
408
  parameters["include_timestamps"] = str(parameters["include_timestamps"]).lower()
282
- headers = {} if options.get("token") else {"xi-api-key": self.api_key}
409
+ headers = {"xi-api-key": self.api_key, **self.headers}
410
+ if options.get("token"):
411
+ headers = {key: value for key, value in headers.items() if key.lower() != "xi-api-key"}
283
412
  if not options.get("token") and not self.api_key:
284
413
  raise ValueError(
285
414
  "An api_key or a single-use token is required for realtime transcription"
@@ -41,6 +41,7 @@ from ._realtime_resources import (
41
41
  RealtimeResponseResource,
42
42
  RealtimeSessionResource,
43
43
  )
44
+ from ._realtime_sampling import check_sampling
44
45
  from ._sentinels import Omit, omit
45
46
  from ._unsupported import UnsupportedResource
46
47
  from ._websocket import AsyncConnect
@@ -105,6 +106,7 @@ def _check_text_frame(data: bytes | str) -> None:
105
106
  raise UnsupportedOperationError(
106
107
  "Realtime audio and transcription are not supported"
107
108
  )
109
+ check_sampling(config, "session" if kind == "session.update" else "response")
108
110
  inputs = config.get("input")
109
111
  if isinstance(inputs, list):
110
112
  for item in inputs:
@@ -174,10 +176,20 @@ class _ConnectionState(EventHandlers):
174
176
  payload = json.loads(data)
175
177
  except (ValueError, RecursionError):
176
178
  return
179
+ # A fresh session greeting isn't application recovery: a server may
180
+ # greet every connection before rejecting admission with a retryable close.
177
181
  if (
178
182
  isinstance(payload, dict)
179
183
  and isinstance(payload.get("type"), str)
180
- and payload["type"] not in {"", "error"}
184
+ and (
185
+ payload["type"]
186
+ in {"response.output_text.delta", "response.function_call_arguments.delta"}
187
+ or (
188
+ payload["type"] == "response.done"
189
+ and isinstance(payload.get("response"), dict)
190
+ and payload["response"].get("status") == "completed"
191
+ )
192
+ )
181
193
  ):
182
194
  self._attempt = 0
183
195