avartha-python-sdk 0.0.3__py3-none-any.whl → 0.0.5__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/_config.py CHANGED
@@ -8,12 +8,28 @@ from urllib.parse import urlsplit, urlunsplit
8
8
 
9
9
  import httpx
10
10
 
11
- Tier = Literal["serverless", "dedicated"]
11
+ Tier = Literal["serverless"]
12
12
  DEFAULT_BASE_URL = "https://platform.preview.avartha.ai"
13
13
 
14
14
 
15
15
  class ConfigurationError(ValueError):
16
- """Missing credentials or an invalid service URL."""
16
+ """Missing credentials, an unsupported tier, or an invalid service URL."""
17
+
18
+
19
+ def validate_tier(tier: Tier) -> None:
20
+ if tier != "serverless":
21
+ raise ConfigurationError(
22
+ "Only tier='serverless' is supported. Dedicated capacity is unavailable."
23
+ )
24
+
25
+
26
+ def reject_dedicated_url(value: str) -> str:
27
+ """Reject the dedicated inference route, including behind a proxy prefix."""
28
+ if re.search(r"(?:^|/)inference/dedicated(?:/|$)", httpx.URL(value).path):
29
+ raise ConfigurationError(
30
+ "Dedicated capacity is unavailable. Use a serverless inference URL."
31
+ )
32
+ return value
17
33
 
18
34
 
19
35
  def api_key(value: str | None) -> str:
@@ -41,12 +57,13 @@ def http_url(value: str) -> str:
41
57
  or (parts.port is not None and not 1 <= parts.port <= 65535)
42
58
  ):
43
59
  raise ValueError("Invalid URL authority")
44
- return str(httpx.URL(value)).rstrip("/")
60
+ normalized = str(httpx.URL(value)).rstrip("/")
45
61
  except (ValueError, httpx.InvalidURL):
46
62
  raise ConfigurationError(
47
63
  "Use an absolute http(s) base URL without credentials, query, fragment, "
48
64
  "whitespace, or backslashes."
49
65
  ) from None
66
+ return reject_dedicated_url(normalized)
50
67
 
51
68
 
52
69
  def platform_url(value: str | None = None) -> str:
@@ -60,20 +77,18 @@ def platform_url(value: str | None = None) -> str:
60
77
 
61
78
 
62
79
  def openai_url(root: str | None = None, tier: Tier = "serverless") -> str:
63
- if tier not in {"serverless", "dedicated"}:
64
- raise ConfigurationError("tier must be 'serverless' or 'dedicated'.")
65
- return f"{platform_url(root)}/inference/{tier}/openai/v1"
80
+ validate_tier(tier)
81
+ return f"{platform_url(root)}/inference/serverless/openai/v1"
66
82
 
67
83
 
68
84
  def elevenlabs_url(
69
85
  value: str | None = None, *, root: str | None = None, tier: Tier = "serverless"
70
86
  ) -> str:
87
+ validate_tier(tier)
71
88
  override = value if value is not None else os.getenv("AVARTHA_ELEVENLABS_BASE_URL")
72
89
  if override is not None:
73
90
  return http_url(override)
74
- if tier not in {"serverless", "dedicated"}:
75
- raise ConfigurationError("tier must be 'serverless' or 'dedicated'.")
76
- return f"{platform_url(root)}/inference/{tier}/elevenlabs"
91
+ return f"{platform_url(root)}/inference/serverless/elevenlabs"
77
92
 
78
93
 
79
94
  def websocket_url(value: str) -> str:
@@ -147,4 +162,4 @@ def websocket_override(value: str) -> str:
147
162
  "websocket_base_url must be the service base before /realtime; "
148
163
  "the SDK appends /realtime when connecting."
149
164
  )
150
- return not_vendor_host(normalized, field="websocket_base_url")
165
+ return not_vendor_host(reject_dedicated_url(normalized), field="websocket_base_url")
avartha/client.py CHANGED
@@ -16,6 +16,12 @@ class Avartha:
16
16
 
17
17
  openai_options, elevenlabs_options and control_options are forwarded to
18
18
  their respective constructors (for timeouts, transports, retry settings).
19
+
20
+ Live STT through elevenlabs.speech_to_text.realtime remains asynchronous.
21
+ Await connect(), send(), commit(), and the transcription connection's close().
22
+ Register callbacks with on() without awaiting. Use AsyncAvartha for an async
23
+ application.
24
+ Close live sessions separately before closing this client.
19
25
  """
20
26
 
21
27
  def __init__(
@@ -30,6 +36,9 @@ class Avartha:
30
36
  elevenlabs_options: dict[str, Any] | None = None,
31
37
  control_options: dict[str, Any] | None = None,
32
38
  ) -> None:
39
+ _config.validate_tier(tier)
40
+ for options in (openai_options, elevenlabs_options):
41
+ _config.validate_tier((options or {}).get("tier", "serverless"))
33
42
  key, root = _config.api_key(api_key), _config.platform_url(base_url)
34
43
  self._elevenlabs_base_url = _config.elevenlabs_url(
35
44
  elevenlabs_base_url, root=root, tier=tier
@@ -99,6 +108,9 @@ class AsyncAvartha:
99
108
  elevenlabs_options: dict[str, Any] | None = None,
100
109
  control_options: dict[str, Any] | None = None,
101
110
  ) -> None:
111
+ _config.validate_tier(tier)
112
+ for options in (openai_options, elevenlabs_options):
113
+ _config.validate_tier((options or {}).get("tier", "serverless"))
102
114
  key, root = _config.api_key(api_key), _config.platform_url(base_url)
103
115
  self._elevenlabs_base_url = _config.elevenlabs_url(
104
116
  elevenlabs_base_url, root=root, tier=tier
avartha/elevenlabs.py CHANGED
@@ -45,6 +45,7 @@ class _Client:
45
45
  environment: str | Enum | None = None,
46
46
  websocket_limits: WebSocketLimits | None = None,
47
47
  ) -> None:
48
+ _config.validate_tier(tier)
48
49
  self.api_key = _config.api_key(api_key)
49
50
  if base_url is None and environment is not None:
50
51
  base_url = str(environment.value) if isinstance(environment, Enum) else environment
avartha/openai.py CHANGED
@@ -121,6 +121,7 @@ class _Client:
121
121
  _enforce_credentials: bool = True,
122
122
  tier: Tier = "serverless",
123
123
  ) -> None:
124
+ _config.validate_tier(tier)
124
125
  if data_residency is not None:
125
126
  raise ConfigurationError(
126
127
  "data_residency selects a vendor host; use an Avartha base_url."
@@ -3,4 +3,6 @@
3
3
  from typing import Literal, TypeAlias
4
4
 
5
5
  __all__ = ["RealtimeReasoningEffort"]
6
- RealtimeReasoningEffort: TypeAlias = Literal["minimal", "low", "medium", "high", "xhigh"]
6
+ RealtimeReasoningEffort: TypeAlias = Literal[
7
+ "none", "minimal", "low", "medium", "high", "xhigh", "max"
8
+ ]
@@ -0,0 +1,141 @@
1
+ Metadata-Version: 2.4
2
+ Name: avartha-python-sdk
3
+ Version: 0.0.5
4
+ Summary: Python clients for Avartha Realtime text, streaming speech, and platform management
5
+ Author-email: "Avartha Inc." <team@avartha.ai>
6
+ License-Expression: LicenseRef-Avartha-Proprietary
7
+ Classifier: Development Status :: 3 - Alpha
8
+ Classifier: Intended Audience :: Developers
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Python :: 3.14
14
+ Classifier: Typing :: Typed
15
+ Requires-Python: >=3.12
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ License-File: THIRD_PARTY_NOTICES
19
+ Requires-Dist: httpx<0.29,>=0.28.1
20
+ Requires-Dist: websockets<16,>=15.0.1
21
+ Requires-Dist: pydantic<3,>=2.11
22
+ Requires-Dist: typing-extensions<5,>=4.12
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest<10,>=8; extra == "dev"
25
+ Requires-Dist: pytest-asyncio<2,>=1; extra == "dev"
26
+ Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
27
+ Requires-Dist: mypy<3,>=2.3; extra == "dev"
28
+ Requires-Dist: build<2,>=1; extra == "dev"
29
+ Requires-Dist: setuptools-scm<9,>=8; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # Avartha Python SDK
33
+
34
+ Synchronous and asynchronous Python clients for Avartha Realtime text,
35
+ streaming speech, and platform management. Requires Python 3.12+.
36
+
37
+ ## Install
38
+
39
+ ```sh
40
+ python -m pip install avartha-python-sdk
41
+ ```
42
+
43
+ Configure your Avartha API key and platform root:
44
+
45
+ ```sh
46
+ export AVARTHA_API_KEY='avk_...'
47
+ export AVARTHA_BASE_URL='https://platform.preview.avartha.ai'
48
+ ```
49
+
50
+ Clients default to the preview platform and support only serverless inference.
51
+ Set `AVARTHA_BASE_URL` for another environment. Use model and voice IDs available
52
+ to your workspace. Unsupported tier values and dedicated inference URLs raise
53
+ `ConfigurationError` locally before any request.
54
+
55
+ ## Discover models
56
+
57
+ ```python
58
+ from avartha import OpenAI
59
+
60
+ with OpenAI() as client:
61
+ for model in client.models.list():
62
+ print(model.id, model.to_dict().get("protocols", []))
63
+ ```
64
+
65
+ Choose a model supporting `openai_realtime` for text, `elevenlabs_tts` for
66
+ speech synthesis, or `elevenlabs_asr` for speech recognition.
67
+
68
+ ## Generate text
69
+
70
+ Replace `your-avartha-model` with a Realtime text model returned by discovery:
71
+
72
+ ```python
73
+ from avartha import OpenAI
74
+
75
+ with OpenAI() as client:
76
+ with client.realtime.connect(model="your-avartha-model") as connection:
77
+ connection.session.update(session={"type": "realtime", "output_modalities": ["text"]})
78
+ connection.conversation.item.create(
79
+ item={
80
+ "type": "message",
81
+ "role": "user",
82
+ "content": [{"type": "input_text", "text": "Explain Python dictionaries."}],
83
+ }
84
+ )
85
+ connection.response.create()
86
+ for event in connection:
87
+ if event.type == "response.output_text.delta":
88
+ print(event.delta, end="", flush=True)
89
+ elif event.type == "response.done":
90
+ if event.response.status != "completed":
91
+ raise RuntimeError(f"Response ended with status: {event.response.status}")
92
+ break
93
+ elif event.type == "error":
94
+ raise RuntimeError(event.error.message)
95
+ ```
96
+
97
+ For asynchronous text generation, use `AsyncOpenAI`, `async with`, `await`,
98
+ and `async for`. Close clients and active WebSocket sessions when finished.
99
+ Inference consumes credits.
100
+
101
+ ## Supported workflows
102
+
103
+ | Workflow | Client and interface |
104
+ | --- | --- |
105
+ | Realtime text | `OpenAI` / `AsyncOpenAI`: `realtime.connect` |
106
+ | Model discovery | `OpenAI` / `AsyncOpenAI`: `models.list`, `models.retrieve` |
107
+ | Streaming TTS | `ElevenLabs` / `AsyncElevenLabs`: `text_to_speech.convert_realtime` |
108
+ | Multi-context TTS | `ElevenLabs` / `AsyncElevenLabs`: `text_to_speech.connect_multi_context` |
109
+ | Realtime ASR | `await client.speech_to_text.realtime.connect(...)` on either speech client |
110
+ | Speech discovery | Speech clients: models, voices, voice settings, ASR languages |
111
+ | Workspaces, members, invitations | `Control` / `AsyncControl` |
112
+ | Combined inference and management | `Avartha` / `AsyncAvartha` |
113
+
114
+ Managed inference uses WebSockets; Chat Completions, Responses, HTTP TTS,
115
+ and file transcription are unavailable. Agent management and conversation
116
+ sessions are planned; accessing `conversational_ai` currently raises
117
+ `NotImplementedError`.
118
+
119
+ ## Migrating and handling errors
120
+
121
+ Import clients, types, and exceptions from `avartha`. Neither the OpenAI nor
122
+ ElevenLabs SDK needs to be installed. The supported interfaces are compatible
123
+ with OpenAI Python 3.13.0 and ElevenLabs Python 2.68.0. Model and voice IDs are
124
+ specific to the selected Avartha environment.
125
+
126
+ OpenAI-compatible HTTP discovery uses `avartha.APIStatusError` and
127
+ `avartha.APIConnectionError`. Speech HTTP errors use `avartha.ApiError`.
128
+ Management HTTP status errors use `avartha.PlatformAPIError`. Speech and
129
+ management HTTP network failures also raise `avartha.ApiError`, with no status
130
+ or headers and the original exception in `__cause__`.
131
+
132
+ Handle Realtime server error events in the receive loop. HTTP timeout and
133
+ retry settings do not configure WebSocket connections. Management writes are
134
+ never retried automatically.
135
+
136
+ ## Complete guides and examples
137
+
138
+ The [source archive on PyPI](https://pypi.org/project/avartha-python-sdk/#files)
139
+ includes `README.md`, customer guides in `docs/`, and runnable examples in
140
+ `examples/`. Download and unpack the archive to read the migration, compatibility,
141
+ and platform-management guides and run the text, speech, and endpoint examples.
@@ -1,5 +1,5 @@
1
1
  avartha/__init__.py,sha256=fusR2DiiRSAaZCIhLrxRdyJWjA8p9uL4PAVGXbArjXM,2821
2
- avartha/_config.py,sha256=IqEdSm8MPQOXThcs_ew98Eys4R7d4l-5ZYAiPzEm29Y,5880
2
+ avartha/_config.py,sha256=mzaHiqYH_7N4okLijiRbJlCNyxvZn4Ni_A_OAZDtOTA,6314
3
3
  avartha/_exceptions.py,sha256=_QY7SEw2nqyOz3pNxDWi40GW1xqB3EZxJ0t4iJ-YBpQ,1588
4
4
  avartha/_http_errors.py,sha256=gU8eapqYcI7Q3M8lAxwVH-qwz-TnQf2loBThFKG0ka8,406
5
5
  avartha/_models.py,sha256=KB4PeFvktbSOKbT-qMX5tjsExEg9cwufZ3ourx8GcVI,7331
@@ -15,14 +15,13 @@ avartha/_speech_config.py,sha256=jL0M8Z6MGXzfgf3Lm7QMMEKDtVXCW5-jrqz5WEtu9g4,178
15
15
  avartha/_speech_http.py,sha256=LNcHPLleuLDQNfMIlUD-ijua5h4VPhqXAmcDrXB8Cdg,10632
16
16
  avartha/_speech_resources.py,sha256=61DKhTnz_bpOTjY_CpeR0mXs9ui9-XeaYgpSDNk_NpE,16954
17
17
  avartha/_unsupported.py,sha256=qrbsxi2SL6co5M2uLs4fTVOoISuUm58khoayeL22gPE,637
18
- avartha/_version.py,sha256=_imd66x09sTd41VCdBD0RFplr2e75yP5Ped99So9xP0,520
19
18
  avartha/_websocket.py,sha256=9R05huh1n8spuyg1n_aIJN0Uk_kLG7BbNPD88wogIKY,855
20
19
  avartha/_ws_state.py,sha256=Im2W-UJtCBimYU5vlYBbVRL06DGwuw0Q5ufy4sSGIeM,5049
21
- avartha/client.py,sha256=jm4CYnzORxtWn2LiVIfBff53dNsUiJjuFb6V01lxBTQ,5006
20
+ avartha/client.py,sha256=vNZmmWWdGhSxdwb-lqBbioP4DK4MpoUgFWLJfqR5zxo,5677
22
21
  avartha/control.py,sha256=jB7I4ccDBaVh2OMLZXhEeAsGNparMLURZQXnh-I__ss,23894
23
- avartha/elevenlabs.py,sha256=bZ0yoloj_I58CpeGe-UVQUdjUlQkGWXCx7qn017lXmQ,5426
22
+ avartha/elevenlabs.py,sha256=tFugwzE8XKbQZsK7P6w6fGXGz76Udp5vt039uVwzOi8,5462
24
23
  avartha/errors.py,sha256=8HMwf2P4VXwk4tRC5ZwceVOUFkRD0wEu9Bn1gljIj0Y,1333
25
- avartha/openai.py,sha256=Xfdf12krOkQv_r8NmCHTfi9JluiethE_NDni-gN3jEI,11919
24
+ avartha/openai.py,sha256=9xlmNdx0E2HWYUf5tEI1UbS82y7XerY1T76Jx7sQv18,11955
26
25
  avartha/pagination.py,sha256=_5qt1bAPKQiXjrHcD0J93yNpBKBhbTRzZfnL9WCUwMw,1471
27
26
  avartha/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
28
27
  avartha/conversational_ai/__init__.py,sha256=Pc7h5OczniKnF54UvMYVILdU-pCXyZ9YnxtzggBc294,217
@@ -123,7 +122,7 @@ avartha/types/realtime/realtime_mcp_tool_execution_error_param.py,sha256=ESoZmAb
123
122
  avartha/types/realtime/realtime_mcphttp_error.py,sha256=LsYLVdqDZ4jUGvlUTpSdKAdgad73-0ls2tk4Z6M5nX8,269
124
123
  avartha/types/realtime/realtime_mcphttp_error_param.py,sha256=X1dGkZnFu8MQqQU78gvOLPHIWR0L7ZJKG_x7hb1zCPQ,370
125
124
  avartha/types/realtime/realtime_reasoning.py,sha256=5v3tvYRDDjnJTpT0amG9jLd1dxV2Qy7mAenDnhmDhTc,307
126
- avartha/types/realtime/realtime_reasoning_effort.py,sha256=ayokU5AgzVYViDq0nB7V0TBW_Ulbn5DTPKTdyjZK0n0,230
125
+ avartha/types/realtime/realtime_reasoning_effort.py,sha256=LFk2Oyv60GonPWfBI7FM0MFrnTCviZWNWPey6aYcRK8,251
127
126
  avartha/types/realtime/realtime_reasoning_param.py,sha256=YIMK-W-iZq3-PqBQFw8nYC4dIrhDbQJtkRqjvmZuwY8,355
128
127
  avartha/types/realtime/realtime_response.py,sha256=mCQWWODuBHpEjQfWevtJ8BZ7lYmWxhhc415hWrMjGl8,1493
129
128
  avartha/types/realtime/realtime_response_create_audio_output.py,sha256=h7Y4MqXEViQdliq81eLn601kGEnxam5ZCaPWNeO4VHU,741
@@ -249,9 +248,9 @@ avartha/types/speech/voice_sharing_response.py,sha256=KRO9Rq80wTYV5of2bRrFTVJSDf
249
248
  avartha/types/speech/voice_sharing_response_category.py,sha256=0yFm6b7R4piHdNTdBWTQYKpNPxW8r2HJvnMdVpT7s5U,241
250
249
  avartha/types/speech/voice_sharing_state.py,sha256=8EBRbrRaDhUEap39kDXmt54AYeG172fnuBmRV1TSHP4,201
251
250
  avartha/types/speech/voice_verification_response.py,sha256=IL_Z1OTIiR9mvuaWzF9-GsL7pMRZ5fJeV_W3FfjLTTY,770
252
- avartha_python_sdk-0.0.3.dist-info/licenses/LICENSE,sha256=1ulXrK7aq7kBXX1scK6IiOgnbwqpmK6kWIB3CYznVG8,1135
253
- avartha_python_sdk-0.0.3.dist-info/licenses/THIRD_PARTY_NOTICES,sha256=t5pUaCILEOze2IsP3TD9I382AtW4njjqZTg9yOfUKbc,13211
254
- avartha_python_sdk-0.0.3.dist-info/METADATA,sha256=BdfP9tDdpnUBoGoiw3EudFW_lwJs_xeur5ExB4G0f68,17211
255
- avartha_python_sdk-0.0.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
256
- avartha_python_sdk-0.0.3.dist-info/top_level.txt,sha256=cj2kDXl33tO2IPWPduSTukcwozPnYKOsVUVE9QZRUr0,8
257
- avartha_python_sdk-0.0.3.dist-info/RECORD,,
251
+ avartha_python_sdk-0.0.5.dist-info/licenses/LICENSE,sha256=1ulXrK7aq7kBXX1scK6IiOgnbwqpmK6kWIB3CYznVG8,1135
252
+ avartha_python_sdk-0.0.5.dist-info/licenses/THIRD_PARTY_NOTICES,sha256=R62M0553miTc6E42IVFLUIYkLFim_mf_Abq1lty0IaQ,13081
253
+ avartha_python_sdk-0.0.5.dist-info/METADATA,sha256=H30kDxD_ubuCN9uf6E0sH4jhxeQlFK2g1EHcur57C7o,5633
254
+ avartha_python_sdk-0.0.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
255
+ avartha_python_sdk-0.0.5.dist-info/top_level.txt,sha256=cj2kDXl33tO2IPWPduSTukcwozPnYKOsVUVE9QZRUr0,8
256
+ avartha_python_sdk-0.0.5.dist-info/RECORD,,
@@ -1,15 +1,15 @@
1
1
  Third-party schema notices
2
2
  ==========================
3
3
 
4
- The WebSocket data declarations under src/avartha/types/realtime, responses,
5
- shared, shared_params, model.py, and websocket_connection_options.py are derived from
6
- OpenAI Python 3.13.0. Model discovery contracts are captured in
7
- tests/fixtures/openai-models-3.13.0.json. Declarations under
8
- src/avartha/types/speech are derived from ElevenLabs Python 2.68.0.
9
- Avartha removed descriptions and legacy Pydantic branches and replaced runtime
10
- imports. Speech contract source hashes are in tests/fixtures/elevenlabs-2.68.0.json
11
- and tests/fixtures/speech-http-2.68.0.json. These notices
12
- apply to those declarations; the Avartha proprietary LICENSE remains unchanged.
4
+ The declarations in avartha.types.realtime, avartha.types.responses,
5
+ avartha.types.shared, avartha.types.shared_params, avartha.types.model, and
6
+ avartha.types.websocket_connection_options are derived from OpenAI Python
7
+ 3.13.0. The declarations in avartha.types.speech are derived from ElevenLabs
8
+ Python 2.68.0.
9
+
10
+ Avartha modified these declarations by removing descriptions and legacy
11
+ Pydantic branches and replacing runtime imports. These notices apply to those
12
+ declarations; the Avartha proprietary LICENSE remains unchanged.
13
13
 
14
14
  OpenAI Python 3.13.0
15
15
  --------------------
avartha/_version.py DELETED
@@ -1,24 +0,0 @@
1
- # file generated by vcs-versioning
2
- # don't change, don't track in version control
3
- from __future__ import annotations
4
-
5
- __all__ = [
6
- "__version__",
7
- "__version_tuple__",
8
- "version",
9
- "version_tuple",
10
- "__commit_id__",
11
- "commit_id",
12
- ]
13
-
14
- version: str
15
- __version__: str
16
- __version_tuple__: tuple[int | str, ...]
17
- version_tuple: tuple[int | str, ...]
18
- commit_id: str | None
19
- __commit_id__: str | None
20
-
21
- __version__ = version = '0.0.3'
22
- __version_tuple__ = version_tuple = (0, 0, 3)
23
-
24
- __commit_id__ = commit_id = None
@@ -1,441 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: avartha-python-sdk
3
- Version: 0.0.3
4
- Summary: Python clients for Avartha inference, voice agents, and platform management
5
- Author-email: "Avartha Inc." <team@avartha.ai>
6
- License-Expression: LicenseRef-Avartha-Proprietary
7
- Project-URL: Repository, https://github.com/avartha/avartha-python-sdk
8
- Project-URL: Issues, https://github.com/avartha/avartha-python-sdk/issues
9
- Classifier: Development Status :: 3 - Alpha
10
- Classifier: Intended Audience :: Developers
11
- Classifier: Operating System :: OS Independent
12
- Classifier: Programming Language :: Python :: 3
13
- Classifier: Programming Language :: Python :: 3.12
14
- Classifier: Programming Language :: Python :: 3.13
15
- Classifier: Programming Language :: Python :: 3.14
16
- Classifier: Typing :: Typed
17
- Requires-Python: >=3.12
18
- Description-Content-Type: text/markdown
19
- License-File: LICENSE
20
- License-File: THIRD_PARTY_NOTICES
21
- Requires-Dist: httpx<0.29,>=0.28.1
22
- Requires-Dist: websockets<16,>=15.0.1
23
- Requires-Dist: pydantic<3,>=2.11
24
- Requires-Dist: typing-extensions<5,>=4.12
25
- Provides-Extra: dev
26
- Requires-Dist: pytest<10,>=8; extra == "dev"
27
- Requires-Dist: pytest-asyncio<2,>=1; extra == "dev"
28
- Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
29
- Requires-Dist: mypy<3,>=2.3; extra == "dev"
30
- Requires-Dist: build<2,>=1; extra == "dev"
31
- Requires-Dist: setuptools-scm<9,>=8; extra == "dev"
32
- Dynamic: license-file
33
-
34
- # Avartha Python SDK
35
-
36
- [![PyPI version](https://img.shields.io/pypi/v/avartha-python-sdk)](https://pypi.org/project/avartha-python-sdk/)
37
-
38
- Synchronous and asynchronous Python clients for Avartha Realtime LLMs,
39
- streaming speech, and platform management. Requires Python 3.12+.
40
-
41
- **Familiar Python interfaces for OpenAI Realtime and ElevenLabs speech.** Change
42
- client, type, and exception imports, then configure Avartha credentials, URLs,
43
- and model/voice IDs. The supported APIs use the same method names and event loops:
44
-
45
- ```diff
46
- -from openai import OpenAI, AsyncOpenAI
47
- +from avartha import OpenAI, AsyncOpenAI
48
- ```
49
-
50
- ```diff
51
- -from elevenlabs.client import ElevenLabs, AsyncElevenLabs
52
- +from avartha import ElevenLabs, AsyncElevenLabs
53
- ```
54
-
55
- Neither vendor SDK needs to be installed. Avartha supports Realtime text,
56
- streaming speech, HTTP discovery, and platform management. Managed inference is
57
- **WebSocket-only**; Chat Completions, Responses, and HTTP speech inference are
58
- unavailable. See the guides below for supported features and migration steps.
59
-
60
- ## Documentation
61
-
62
- - [Migrating from OpenAI and ElevenLabs](docs/migration.md)
63
- - [Compatibility and endpoint coverage](docs/compatibility.md)
64
- - [Platform management](docs/platform.md)
65
- - [Runnable examples](examples)
66
- - [Contributing](CONTRIBUTING.md)
67
-
68
- ## Installation
69
-
70
- Install from [PyPI](https://pypi.org/project/avartha-python-sdk/):
71
-
72
- ```sh
73
- python -m pip install avartha-python-sdk
74
- ```
75
-
76
- Set your Avartha API key and platform root. Update `AVARTHA_BASE_URL` to match
77
- your environment:
78
-
79
- ```sh
80
- export AVARTHA_API_KEY='avk_...'
81
- export AVARTHA_BASE_URL='https://platform.preview.avartha.ai'
82
- ```
83
-
84
- Clients default to `https://platform.preview.avartha.ai` and the `serverless`
85
- inference tier. Set `AVARTHA_BASE_URL` to use another platform root. Both protocol
86
- clients derive their service URLs from this root. Use model and voice IDs from
87
- the selected environment; vendor IDs are not mapped automatically.
88
-
89
- ## Usage
90
-
91
- Use the OpenAI Realtime interface for LLM inference. The client reads
92
- `AVARTHA_API_KEY` from the environment; `api_key` can also be passed explicitly.
93
-
94
- ```python
95
- from avartha import OpenAI
96
-
97
- with OpenAI() as client:
98
- with client.realtime.connect(model="google/gemma-4-26b-a4b-it") as connection:
99
- connection.session.update(session={"type": "realtime", "output_modalities": ["text"]})
100
- connection.conversation.item.create(
101
- item={
102
- "type": "message",
103
- "role": "user",
104
- "content": [{"type": "input_text", "text": "Explain Python dictionaries."}],
105
- }
106
- )
107
- connection.response.create()
108
- for event in connection:
109
- if event.type == "response.output_text.delta":
110
- print(event.delta, end="", flush=True)
111
- elif event.type == "response.done":
112
- if event.response.status != "completed":
113
- raise RuntimeError(f"Response ended with status: {event.response.status}")
114
- break
115
- elif event.type == "error":
116
- raise RuntimeError(event.error.message)
117
- ```
118
-
119
- Keep the connection open for additional turns. Create another conversation item
120
- and response on the same connection to preserve conversation state.
121
-
122
- To discover available models and their enabled protocols:
123
-
124
- ```python
125
- from avartha import OpenAI
126
-
127
- with OpenAI() as client:
128
- for model in client.models.list():
129
- print(model.id, model.to_dict().get("protocols", []))
130
- ```
131
-
132
- Model availability depends on your workspace, environment, and tier. Replace
133
- the example IDs with models returned for your key and the protocol you need:
134
- `openai_realtime`, `elevenlabs_tts`, or `elevenlabs_asr`.
135
-
136
- ## Async usage
137
-
138
- Use `AsyncOpenAI`, await operations, and iterate with `async for`. The sync and
139
- async clients accept the same request parameters and return the same event types.
140
-
141
- ```python
142
- import asyncio
143
- from avartha import AsyncOpenAI
144
-
145
-
146
- async def main():
147
- async with AsyncOpenAI() as client:
148
- async with client.realtime.connect(model="google/gemma-4-26b-a4b-it") as connection:
149
- await connection.session.update(
150
- session={"type": "realtime", "output_modalities": ["text"]}
151
- )
152
- await connection.conversation.item.create(
153
- item={
154
- "type": "message",
155
- "role": "user",
156
- "content": [{"type": "input_text", "text": "Explain Python dictionaries."}],
157
- }
158
- )
159
- await connection.response.create()
160
- async for event in connection:
161
- if event.type == "response.output_text.delta":
162
- print(event.delta, end="", flush=True)
163
- elif event.type == "response.done":
164
- if event.response.status != "completed":
165
- raise RuntimeError(f"Response ended with status: {event.response.status}")
166
- break
167
- elif event.type == "error":
168
- raise RuntimeError(event.error.message)
169
-
170
-
171
- asyncio.run(main())
172
- ```
173
-
174
- [Complete Realtime example](examples/realtime.py).
175
-
176
- ## Streaming speech
177
-
178
- `ElevenLabs()` defaults to the same Avartha platform root and serverless tier.
179
- It provides ElevenLabs-compatible realtime speech and discovery APIs.
180
-
181
- ### Text to speech
182
-
183
- Discover voices for the selected TTS model using `request_options`:
184
-
185
- ```python
186
- from avartha import ElevenLabs
187
-
188
- with ElevenLabs() as client:
189
- voices = client.voices.get_all(
190
- request_options={
191
- "additional_query_parameters": {"model_id": "qwen/qwen3-tts-12hz-1.7b-base"}
192
- }
193
- )
194
- for voice in voices.voices:
195
- print(voice.voice_id)
196
- ```
197
-
198
- Stream text over a WebSocket with `convert_realtime`. Avartha returns PCM;
199
- select a sample rate supported by your model and write a WAV header for playback.
200
- This example uses Qwen's 24 kHz output:
201
-
202
- ```python
203
- import wave
204
- from avartha import ElevenLabs
205
-
206
- with ElevenLabs() as client:
207
- audio = client.text_to_speech.convert_realtime(
208
- voice_id="carol",
209
- model_id="qwen/qwen3-tts-12hz-1.7b-base",
210
- output_format="pcm_24000",
211
- text=iter(["Welcome. ", "How can I help?"]),
212
- )
213
- with wave.open("welcome.wav", "wb") as output:
214
- output.setnchannels(1)
215
- output.setsampwidth(2)
216
- output.setframerate(24000)
217
- for chunk in audio:
218
- output.writeframes(chunk)
219
- ```
220
-
221
- The default output format is `pcm_24000`. Use `AsyncElevenLabs` and `async for`
222
- for async TTS; the async client's `text` accepts either a regular iterable or
223
- an async iterable. Run the
224
- [TTS example](examples/tts.py) with `--async` to use that client.
225
-
226
- Text fragments are forwarded as supplied, without waiting for word or sentence
227
- boundaries or adding spaces. Include any intended whitespace in your text.
228
- The Avartha Platform handles buffering and segmentation. Available audio continues
229
- to arrive while the text producer is paused; when synthesis starts depends on the model.
230
-
231
- The SDK's single-context and multi-context TTS helpers always use
232
- `auto_mode=true`. `auto_mode=False` and `default_mode` are not supported.
233
-
234
- For multiple utterances on one connection, use `connect_multi_context` on
235
- either client. A background consumer can iterate over the session before contexts
236
- are created and between turns; messages are keyed by `message.context_id`.
237
- For a finite batch, create and flush contexts, then iterate over `session.drain()`.
238
- Session iteration waits until the connection closes via `close_socket()` or when
239
- its `with` or `async with` block exits. See the [multi-context example](examples/tts_multi_context.py)
240
- and [TTS lifecycle details](docs/compatibility.md#realtime-tts).
241
-
242
- HTTP `text_to_speech.stream` and `.convert` are not provided by this SDK;
243
- managed inference uses the realtime methods above.
244
-
245
- ### Speech to text
246
-
247
- Realtime ASR uses `await client.speech_to_text.realtime.connect(...)` on both
248
- ElevenLabs client variants. Send mono PCM16 audio and await a committed transcript.
249
- [The complete example](examples/realtime_asr.py) reads a WAV file, registers
250
- transcript/error callbacks, streams chunks, commits, and closes the connection:
251
-
252
- ```sh
253
- python examples/realtime_asr.py mistralai/voxtral-mini-4b-realtime-2602 speech-16k.wav
254
- ```
255
-
256
- `previous_text` is optional text context for transcription. When omitted from
257
- `connection.send` data, Avartha sends `null`, meaning no context. You can omit
258
- this field when streaming audio without prior text.
259
-
260
- File-based HTTP `speech_to_text.convert` is retired on managed inference.
261
-
262
- ## Agents
263
-
264
- Agent management, tools, knowledge bases, and conversation sessions/history are
265
- currently unavailable. Accessing `client.conversational_ai` raises
266
- `NotImplementedError`.
267
-
268
- ElevenLabs-compatible `conversational_ai` support is planned for an upcoming
269
- release, including agent creation, tools, knowledge-base documents, and
270
- conversations.
271
-
272
- The following example previews the planned API. It requires that future SDK
273
- release and a service implementing the corresponding agent endpoints:
274
-
275
- ```python
276
- from avartha import ElevenLabs
277
-
278
- with ElevenLabs(base_url="https://your-compatible-agent-service") as client:
279
- agent = client.conversational_ai.agents.create(
280
- name="Support",
281
- conversation_config={
282
- "agent": {
283
- "first_message": "What can I help you with?",
284
- "prompt": {"prompt": "Help customers find concise, accurate answers."},
285
- },
286
- "tts": {"voice_id": "your-voice"},
287
- },
288
- )
289
- print(agent.agent_id)
290
- ```
291
-
292
- The planned `avartha.conversational_ai` namespace will also include
293
- `Conversation`, `AsyncConversation`, and `ClientTools`.
294
-
295
- ## Using types
296
-
297
- Import types and exceptions from Avartha. The SDK provides its own classes for
298
- the supported APIs, preserving upstream fields and serialization methods.
299
- Neither `openai` nor `elevenlabs` needs to be installed:
300
-
301
- ```python
302
- from avartha import OpenAI
303
- from avartha.types import Model
304
-
305
- with OpenAI() as client:
306
- models: list[Model] = client.models.list().data
307
- print([model.to_dict() for model in models])
308
- ```
309
-
310
- Use `avartha.types.realtime` for OpenAI-compatible Realtime events and
311
- `avartha.types.speech` for ElevenLabs-compatible speech types. These namespaces
312
- cover the APIs supported by Avartha. Platform management responses are JSON
313
- dictionaries and lists.
314
-
315
- ElevenLabs-compatible transcription options are also available from the root:
316
-
317
- ```python
318
- from avartha import AudioFormat, CommitStrategy, RealtimeAudioOptions
319
-
320
- options = RealtimeAudioOptions(
321
- model_id="your-avartha-asr-model",
322
- audio_format=AudioFormat.PCM_16000,
323
- sample_rate=16000,
324
- commit_strategy=CommitStrategy.VAD,
325
- )
326
- ```
327
-
328
- ## Handling errors
329
-
330
- Import exception classes from Avartha too; upstream exception classes will not
331
- catch Avartha's exceptions. For HTTP discovery:
332
-
333
- ```python
334
- from avartha import APIConnectionError, APIStatusError, OpenAI
335
-
336
- with OpenAI() as client:
337
- try:
338
- client.models.list()
339
- except APIConnectionError as error:
340
- print("Connection failed:", error)
341
- except APIStatusError as error:
342
- print("Request failed:", error.status_code, error.request_id)
343
- ```
344
-
345
- Realtime server errors are events, so handle `event.type == "error"` in the
346
- receive loop. Inspect `response.done.response.status` for completion, failure,
347
- or cancellation; a terminal event alone does not prove successful inference.
348
- Connection failures can raise WebSocket exceptions.
349
-
350
- ElevenLabs-compatible HTTP/TTS helper errors, including speech HTTP network
351
- failures and timeouts, use `avartha.ApiError`.
352
- ASR also emits `RealtimeEvents.ERROR`.
353
-
354
- Management failures use `avartha.PlatformAPIError`, retaining the HTTP status,
355
- response body, field errors, request ID, and `Retry-After` header. Management
356
- network failures and timeouts use `avartha.ApiError`.
357
-
358
- For speech and management HTTP request failures without a server response,
359
- `ApiError.status_code` and `ApiError.headers` are `None`, and `ApiError.body`
360
- describes the failure. The original exception is available as `error.__cause__`.
361
-
362
- ## Retries and timeouts
363
-
364
- Set timeouts and retries for OpenAI-compatible HTTP discovery on the client:
365
-
366
- ```python
367
- from avartha import OpenAI
368
-
369
- with OpenAI(timeout=30.0, max_retries=0) as client:
370
- print(client.models.list())
371
- ```
372
-
373
- HTTP and WebSocket retry settings are separate. The OpenAI-compatible clients accept
374
- `client.realtime.connect(..., max_retries=0)` to disable automatic reconnection,
375
- and `websocket_connection_options` for transport settings. Use `asyncio.timeout`
376
- when an async operation needs an overall deadline. Close active sessions when
377
- cancelling. ElevenLabs `timeout` configures HTTP calls; it does not set a
378
- WebSocket receive deadline. Platform management writes are never retried
379
- automatically. See [timeouts and cleanup](docs/migration.md#timeouts-retries-and-closing-clients).
380
-
381
- ## Configuration
382
-
383
- | Client | Meaning of explicit `base_url` |
384
- | --- | --- |
385
- | `OpenAI`, `AsyncOpenAI` | Full inference base: `https://platform.preview.avartha.ai/inference/serverless/openai/v1` |
386
- | `ElevenLabs`, `AsyncElevenLabs` | Speech service root before `/v1`: `https://platform.preview.avartha.ai/inference/serverless/elevenlabs` |
387
- | `Avartha`, `AsyncAvartha`, `Control`, `AsyncControl` | Platform root: `https://platform.preview.avartha.ai` |
388
-
389
- Without an explicit URL, protocol clients derive their URL from
390
- `AVARTHA_BASE_URL`, defaulting to `https://platform.preview.avartha.ai` and the
391
- `serverless` tier. Set `tier="dedicated"` for dedicated inference; there is no
392
- automatic fallback between tiers. An explicit protocol `base_url` takes
393
- precedence over `tier`. `AVARTHA_ELEVENLABS_BASE_URL` overrides the derived speech
394
- root, and an explicit ElevenLabs `base_url` overrides that environment variable.
395
-
396
- Keys are read at construction from `AVARTHA_API_KEY` or `api_key`.
397
- Vendor default keys and base URL variables are not substituted.
398
- [Migration configuration](docs/migration.md#configuration).
399
-
400
- Always close clients or use context managers. OpenAI manages and closes its HTTP
401
- client; custom `http_client` arguments are unsupported. ElevenLabs and Control
402
- close only HTTP clients they created. Close active WebSocket sessions separately.
403
-
404
- ## Platform management
405
-
406
- Use the combined `Avartha` client for inference plus management:
407
-
408
- ```python
409
- from avartha import Avartha
410
-
411
- with Avartha() as client:
412
- print(client.control.catalog.models())
413
- print(client.control.catalog.skus(provider="modal"))
414
- print(client.control.organizations.list())
415
- print(client.control.organizations.limits("your-workspace-id"))
416
- print(client.control.endpoints.list(workspace_id="your-workspace-id"))
417
- ```
418
-
419
- `client.openai` and `client.elevenlabs` are the protocol clients;
420
- `client.realtime` and `client.models` are shortcuts to the corresponding OpenAI
421
- resources, including model listing and retrieval. `AsyncAvartha`, `Control`,
422
- and `AsyncControl` are available too. Workspace administration includes
423
- organization creation, renaming, deletion, leaving, member roles, and invitation
424
- creation, revocation, and acceptance. For example,
425
- `client.control.organizations.members.list("your-workspace-id")` lists members.
426
- See [workspace administration](docs/platform.md#workspace-administration) for
427
- sync/async usage and server permissions.
428
-
429
- Endpoint creation, readiness waiting,
430
- scaling, routing, stopping, and deletion are described in the
431
- [management guide](docs/platform.md).
432
-
433
- ## Examples
434
-
435
- Runnable examples cover [Realtime text](examples/realtime.py),
436
- [TTS](examples/tts.py), [multi-context TTS](examples/tts_multi_context.py),
437
- [ASR](examples/realtime_asr.py), and [endpoint management](examples/endpoints.py).
438
- Microphone capture and speaker playback are handled by your application.
439
-
440
- Running inference examples consumes credits. For SDK development and checks,
441
- see [Contributing](CONTRIBUTING.md).