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 +7 -1
- avartha/_conversation_resources.py +355 -0
- avartha/_openai_http.py +4 -1
- avartha/_realtime_asr.py +134 -5
- avartha/_realtime_openai.py +13 -1
- avartha/_realtime_sampling.py +77 -0
- avartha/_realtime_tts.py +197 -30
- avartha/_speech_http.py +46 -3
- avartha/control.py +528 -3
- avartha/conversational_ai/__init__.py +21 -3
- avartha/conversational_ai/conversation.py +747 -0
- avartha/elevenlabs.py +32 -13
- avartha/realtime/speech.py +9 -1
- avartha/types/conversational_ai.py +52 -0
- avartha/types/realtime/realtime_response_create_params.py +8 -0
- avartha/types/realtime/realtime_response_create_params_param.py +9 -0
- avartha/types/realtime/realtime_session_create_request.py +8 -0
- avartha/types/realtime/realtime_session_create_request_param.py +9 -0
- avartha/types/voice_agents.py +207 -0
- {avartha_python_sdk-0.0.6.dist-info → avartha_python_sdk-0.0.8.dist-info}/METADATA +16 -11
- {avartha_python_sdk-0.0.6.dist-info → avartha_python_sdk-0.0.8.dist-info}/RECORD +25 -20
- {avartha_python_sdk-0.0.6.dist-info → avartha_python_sdk-0.0.8.dist-info}/WHEEL +1 -1
- {avartha_python_sdk-0.0.6.dist-info → avartha_python_sdk-0.0.8.dist-info}/licenses/LICENSE +0 -0
- {avartha_python_sdk-0.0.6.dist-info → avartha_python_sdk-0.0.8.dist-info}/licenses/THIRD_PARTY_NOTICES +0 -0
- {avartha_python_sdk-0.0.6.dist-info → avartha_python_sdk-0.0.8.dist-info}/top_level.txt +0 -0
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
|
|
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
|
-
|
|
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
|
-
|
|
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;
|
|
74
|
-
turn_model:
|
|
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__(
|
|
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 = {
|
|
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"
|
avartha/_realtime_openai.py
CHANGED
|
@@ -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
|
|
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
|
|