avartha-python-sdk 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

avartha/__init__.py

@@ -28,7 +28,7 @@ from ._openai_http_errors import (
 )
 from ._openai_http_errors import UnprocessableEntityError as OpenAIUnprocessableEntityError
 from ._pacing import WebSocketLimits
-from ._realtime_asr import AudioFormat, CommitStrategy, RealtimeEvents
+from ._realtime_asr import AudioFormat, CommitStrategy, RealtimeAudioOptions, RealtimeEvents
 from ._realtime_tts import DEFAULT_OUTPUT_FORMAT as DEFAULT_TTS_OUTPUT_FORMAT
 from ._realtime_tts import AsyncMultiContextSession, MultiContextSession, audio_bytes
 from ._sentinels import NOT_GIVEN, NotGiven, Omit, not_given, omit
@@ -89,6 +89,7 @@ __all__ = [
     "MultiContextSession",
     "OpenAI",
     "PlatformAPIError",
+    "RealtimeAudioOptions",
     "RealtimeEvents",
     "VoiceSettings",
     "WebSocketLimits",

avartha/_exceptions.py

@@ -22,7 +22,11 @@ class WebSocketConnectionClosedError(OpenAIError):
 
 
 class ApiError(Exception):
-    """ElevenLabs-compatible speech error, retaining the original server payload."""
+    """Speech API error or speech/management HTTP request failure.
+
+    Server errors retain their response payload. HTTP request failures have no
+    status or headers and retain the underlying exception as ``__cause__``.
+    """
 
     def __init__(
         self,

avartha/_http_errors.py

@@ -0,0 +1,16 @@
+"""Translate speech and management HTTP request failures to public API errors."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import httpx
+
+from ._exceptions import ApiError
+
+
+@contextmanager
+def wrap_httpx_errors() -> Iterator[None]:
+    try:
+        yield
+    except httpx.RequestError as error:
+        raise ApiError(body=str(error) or type(error).__name__) from error

avartha/_realtime_tts.py

@@ -1,8 +1,8 @@
 """Gateway-compatible sync and async realtime TTS helpers.
 
 The pinned upstream helper omits `auto_mode` and sends generation controls the
-managed gateway rejects. These clients share a compatible envelope, preserve
-upstream chunking and errors, and use owned multi-context message types.
+managed gateway rejects. These clients share a compatible envelope, send
+text fragments unchanged, preserve errors, and use owned multi-context message types.
 """
 
 import asyncio
@@ -65,10 +65,6 @@ OMIT = cast(Any, ...)
 # so their native PCM rate is the only workable default.
 DEFAULT_OUTPUT_FORMAT: OutputFormat = "pcm_24000"
 
-# Upstream's splitter set, copied because the chunk boundaries are wire
-# behaviour and upstream ships no async chunker to reuse.
-SPLITTERS = (".", ",", "?", "!", ";", ":", "—", "-", "(", ")", "[", "]", "}", " ")
-
 
 def _given[T](value: T) -> T | None:
     """Upstream's OMIT sentinel means "not supplied" and must never reach the wire."""
@@ -130,7 +126,7 @@ def _close_text(iterator: Iterator[str], *, concurrent: bool = False) -> bool:
 
 
 def _until_stopped(source: Iterator[str], stopped: Event) -> Iterator[str]:
-    """Check between raw reads, even while the chunker buffers an unfinished word."""
+    """Stop reading caller input once the audio stream closes."""
     while not stopped.is_set():
         text = next(source, None)
         if text is None or stopped.is_set():
@@ -171,22 +167,11 @@ async def _sync_chunks(chunks: Iterable[str]) -> AsyncGenerator[str]:
 
 
 async def _achunks(chunks: AsyncIterable[str]) -> AsyncGenerator[str]:
-    """Apply upstream chunk boundaries and release the underlying async source."""
+    """Pass text through unchanged and release the underlying async source."""
     source = aiter(chunks)
-    buffer = ""
     try:
         async for text in source:
-            if buffer.endswith(SPLITTERS):
-                yield buffer if buffer.endswith(" ") else buffer + " "
-                buffer = text
-            elif text.startswith(SPLITTERS):
-                output = buffer + text[0]
-                yield output if output.endswith(" ") else output + " "
-                buffer = text[1:]
-            else:
-                buffer += text
-        if buffer:
-            yield buffer + " "
+            yield text
     finally:
         if close := getattr(source, "aclose", None):
             await close()
@@ -217,6 +202,10 @@ class AvarthaRealtimeTextToSpeechClient:
     ) -> Iterator[bytes]:
         """Stream `text` to `voice_id` and yield raw audio frames.
 
+        Nonempty text fragments are forwarded unchanged, including whitespace.
+        The Avartha Platform handles buffering and segmentation. Empty items are
+        skipped; only iterator exhaustion sends EOF.
+
         `output_format` defaults to `DEFAULT_OUTPUT_FORMAT`. `voice_settings` is
         forwarded when supplied, but the gateway rejects any non-null value;
         leave it unset unless the platform has gained support for it.
@@ -249,6 +238,9 @@ class AvarthaRealtimeTextToSpeechClient:
                     with closing(text_chunker(_until_stopped(text, stopped))) as chunks:
                         while not stopped.is_set():
                             chunk = next(chunks, None)
+                            if chunk == "":
+                                # Empty source items are not the wire's EOF control.
+                                continue
                             if stopped.wait(pacer.delay()):
                                 break
                             socket.send(json.dumps({"text": chunk if chunk is not None else ""}))
@@ -365,6 +357,8 @@ class AvarthaAsyncRealtimeTextToSpeechClient:
                 chunks = _achunks(text) if isinstance(text, AsyncIterable) else _sync_chunks(text)
                 async with aclosing(chunks):
                     async for chunk in chunks:
+                        if chunk == "":
+                            continue
                         await pacer.pace_async()
                         await socket.send(json.dumps({"text": chunk}))
                 await pacer.pace_async()
@@ -510,10 +504,7 @@ class _MultiContextProtocol:
         if text == "":
             return _frame(SendTextMulti(text="", context_id=context_id))
         context.pending = True
-        # Upstream's chunker guarantees a trailing space and the protocol wants
-        # one, so supply it when the caller's chunk lacks it.
-        spaced = text if text.endswith(" ") else text + " "
-        return _frame(SendTextMulti(text=spaced, context_id=context_id))
+        return _frame(SendTextMulti(text=text, context_id=context_id))
 
     def flush(self, context_id: str) -> dict[str, Any]:
         context = self._open(context_id)
@@ -596,7 +587,7 @@ class MultiContextSession:
             self.send(context_id, text)
 
     def send(self, context_id: str, text: str) -> None:
-        """Append text, or send an empty-text keepalive, to an open context.
+        """Append text unchanged, or send an empty-text keepalive, to an open context.
 
         A keepalive preserves pending speech without generating or flushing it.
         """
@@ -764,7 +755,7 @@ class AsyncMultiContextSession:
                 await self._send(context_id, lambda protocol: protocol.send(context_id, text))
 
     async def send(self, context_id: str, text: str) -> None:
-        """Append text, or send an empty-text keepalive, to an open context.
+        """Append text unchanged, or send an empty-text keepalive, to an open context.
 
         A keepalive preserves pending speech without generating or flushing it.
         """

avartha/_speech_config.py

@@ -54,21 +54,6 @@ def remove_none_from_dict(value: dict[str, Any]) -> dict[str, Any]:
     return {key: item for key, item in value.items() if item is not None}
 
 
-SPLITTERS = (".", ",", "?", "!", ";", ":", "—", "-", "(", ")", "[", "]", "}", " ")
-
-
 def text_chunker(chunks: Iterable[str]) -> Generator[str]:
-    """Preserve the frozen helper's punctuation and trailing-space boundaries."""
-    pending = ""
-    for chunk in chunks:
-        if pending.endswith(SPLITTERS):
-            yield pending if pending.endswith(" ") else pending + " "
-            pending = chunk
-        elif chunk.startswith(SPLITTERS):
-            part = pending + chunk[0]
-            yield part if part.endswith(" ") else part + " "
-            pending = chunk[1:]
-        else:
-            pending += chunk
-    if pending:
-        yield pending + " "
+    """Pass text through unchanged; the Avartha Platform handles buffering and segmentation."""
+    yield from chunks

avartha/_speech_http.py

@@ -14,6 +14,7 @@ import httpx
 
 from ._config import not_vendor_host
 from ._exceptions import ApiError, UnprocessableEntityError
+from ._http_errors import wrap_httpx_errors
 from ._models import construct
 from ._speech_config import RequestOptions, jsonable_encoder
 from .errors import ConfigurationError
@@ -193,19 +194,20 @@ class SpeechHTTPClient:
         options = request_options or {}
         for attempt in range(max(0, options.get("max_retries", 2)) + 1):
             request = self._settings.request(self._client, path, params, options)
-            for redirects in range(self._client.max_redirects + 1):
-                response = self._client.send(request, follow_redirects=False)
-                if not self._follow_redirects or not response.has_redirect_location:
-                    break
-                try:
-                    target = _redirect(request, response)
-                    if redirects == self._client.max_redirects:
-                        raise httpx.TooManyRedirects(
-                            "Exceeded maximum allowed redirects.", request=request
-                        )
-                    request.url = target
-                finally:
-                    response.close()
+            with wrap_httpx_errors():
+                for redirects in range(self._client.max_redirects + 1):
+                    response = self._client.send(request, follow_redirects=False)
+                    if not self._follow_redirects or not response.has_redirect_location:
+                        break
+                    try:
+                        target = _redirect(request, response)
+                        if redirects == self._client.max_redirects:
+                            raise httpx.TooManyRedirects(
+                                "Exceeded maximum allowed redirects.", request=request
+                            )
+                        request.url = target
+                    finally:
+                        response.close()
             if (
                 response.status_code >= 500 or response.status_code in (408, 409, 429)
             ) and attempt < options.get("max_retries", 2):
@@ -258,19 +260,20 @@ class AsyncSpeechHTTPClient:
         options = request_options or {}
         for attempt in range(max(0, options.get("max_retries", 2)) + 1):
             request = self._settings.request(self._client, path, params, options)
-            for redirects in range(self._client.max_redirects + 1):
-                response = await self._client.send(request, follow_redirects=False)
-                if not self._follow_redirects or not response.has_redirect_location:
-                    break
-                try:
-                    target = _redirect(request, response)
-                    if redirects == self._client.max_redirects:
-                        raise httpx.TooManyRedirects(
-                            "Exceeded maximum allowed redirects.", request=request
-                        )
-                    request.url = target
-                finally:
-                    await response.aclose()
+            with wrap_httpx_errors():
+                for redirects in range(self._client.max_redirects + 1):
+                    response = await self._client.send(request, follow_redirects=False)
+                    if not self._follow_redirects or not response.has_redirect_location:
+                        break
+                    try:
+                        target = _redirect(request, response)
+                        if redirects == self._client.max_redirects:
+                            raise httpx.TooManyRedirects(
+                                "Exceeded maximum allowed redirects.", request=request
+                            )
+                        request.url = target
+                    finally:
+                        await response.aclose()
             if (
                 response.status_code >= 500 or response.status_code in (408, 409, 429)
             ) and attempt < options.get("max_retries", 2):

avartha/client.py

@@ -43,6 +43,7 @@ class Avartha:
             **(openai_options or {}),
         )
         self.realtime = self.openai.realtime
+        self.models = self.openai.models
 
     @cached_property
     def elevenlabs(self) -> ElevenLabs:
@@ -111,6 +112,7 @@ class AsyncAvartha:
             **(openai_options or {}),
         )
         self.realtime = self.openai.realtime
+        self.models = self.openai.models
 
     @cached_property
     def elevenlabs(self) -> AsyncElevenLabs:

avartha/control.py

@@ -9,16 +9,18 @@ import math
 import time
 from collections.abc import Mapping
 from types import TracebackType
-from typing import Self
+from typing import Literal, Self
 from urllib.parse import quote, unquote, urlsplit
 
 import httpx
 from pydantic import JsonValue
 
 from . import _config
+from ._http_errors import wrap_httpx_errors
 from .errors import EndpointFailedError, PlatformAPIError
 
 type Object = dict[str, JsonValue]
+type OrganizationRole = Literal["owner", "admin", "member"]
 
 
 def _object(value: JsonValue) -> Object:
@@ -80,7 +82,7 @@ def _ready(endpoint: Object) -> bool:
 
 
 class Control:
-    """Platform root configuration plus catalog, organizations and endpoints."""
+    """Customer catalog, workspaces, invitations, and dedicated endpoints."""
 
     def __init__(
         self,
@@ -91,13 +93,17 @@ class Control:
         http_client: httpx.Client | None = None,
     ) -> None:
         _positive(timeout, "timeout")
-        self.base_url = _config.platform_url(base_url) + "/control/v1"
+        self.base_url = (
+            _config.not_vendor_host(_config.platform_url(base_url), field="base_url")
+            + "/control/v1"
+        )
         self._headers = {"Authorization": f"Bearer {_config.api_key(api_key)}"}
         self._timeout = timeout
         self._owns_client = http_client is None
         self._client = http_client if http_client is not None else httpx.Client()
         self.catalog = Catalog(self)
         self.organizations = Organizations(self)
+        self.invitations = Invitations(self)
         self.endpoints = Endpoints(self)
 
     def request(
@@ -110,15 +116,16 @@ class Control:
         timeout: float | None = None,
     ) -> JsonValue:
         """Call another verified customer route relative to /control/v1."""
-        response = self._client.request(
-            method,
-            _target(self.base_url, path),
-            headers=self._headers,
-            json=json,
-            params=params,
-            timeout=self._timeout if timeout is None else timeout,
-            follow_redirects=False,
-        )
+        with wrap_httpx_errors():
+            response = self._client.request(
+                method,
+                _target(self.base_url, path),
+                headers=self._headers,
+                json=json,
+                params=params,
+                timeout=self._timeout if timeout is None else timeout,
+                follow_redirects=False,
+            )
         return _decode(response)
 
     def close(self) -> None:
@@ -149,8 +156,12 @@ class Catalog:
 
 
 class Organizations:
+    """Workspaces visible to the authenticated customer; permissions are server-enforced."""
+
     def __init__(self, control: Control) -> None:
         self._control = control
+        self.members = OrganizationMembers(control)
+        self.invitations = OrganizationInvitations(control)
 
     def list(self) -> list[Object]:
         return _objects(self._control.request("GET", "organizations"))
@@ -158,6 +169,26 @@ class Organizations:
     def get(self, organization_id: str) -> Object:
         return _object(self._control.request("GET", f"organizations/{_segment(organization_id)}"))
 
+    def create(self, *, name: str) -> Object:
+        """Create a workspace with the platform's default allocation."""
+        return _object(self._control.request("POST", "organizations", json={"name": name}))
+
+    def update(self, organization_id: str, *, name: str) -> Object:
+        """Rename a workspace as an owner or admin."""
+        return _object(
+            self._control.request(
+                "PATCH", f"organizations/{_segment(organization_id)}", json={"name": name}
+            )
+        )
+
+    def delete(self, organization_id: str) -> None:
+        """Delete a workspace as an owner."""
+        self._control.request("DELETE", f"organizations/{_segment(organization_id)}")
+
+    def leave(self, organization_id: str) -> None:
+        """Leave a workspace; the server refuses removal of its last owner."""
+        self._control.request("POST", f"organizations/{_segment(organization_id)}/leave")
+
     def limits(self, organization_id: str) -> Object:
         """Return quota policy, current usage, and any pending increase request."""
         return _object(
@@ -165,6 +196,88 @@ class Organizations:
         )
 
 
+class OrganizationMembers:
+    def __init__(self, control: Control) -> None:
+        self._control = control
+
+    def list(self, organization_id: str) -> list[Object]:
+        return _objects(
+            self._control.request("GET", f"organizations/{_segment(organization_id)}/members")
+        )
+
+    def update(self, organization_id: str, user_id: str, *, role: OrganizationRole) -> Object:
+        """Change a member's role, subject to owner/admin and last-owner rules."""
+        return _object(
+            self._control.request(
+                "PATCH",
+                f"organizations/{_segment(organization_id)}/members/{_segment(user_id)}",
+                json={"role": role},
+            )
+        )
+
+    def remove(self, organization_id: str, user_id: str) -> None:
+        self._control.request(
+            "DELETE", f"organizations/{_segment(organization_id)}/members/{_segment(user_id)}"
+        )
+
+
+class OrganizationInvitations:
+    def __init__(self, control: Control) -> None:
+        self._control = control
+
+    def list(self, organization_id: str) -> list[Object]:
+        return _objects(
+            self._control.request("GET", f"organizations/{_segment(organization_id)}/invitations")
+        )
+
+    def create(
+        self,
+        organization_id: str,
+        *,
+        role: OrganizationRole,
+        email: str | None = None,
+        entitlement_policy: Object | None = None,
+    ) -> Object:
+        """Create an invite; supplying email also asks the server to send it.
+
+        Targeted customer invites require a member entitlement policy. Inspect
+        delivery_warning in the response even when creation succeeds.
+        """
+        body: Object = {"role": role}
+        if email is not None:
+            body["email"] = email
+        if entitlement_policy is not None:
+            body["entitlement_policy"] = entitlement_policy
+        return _object(
+            self._control.request(
+                "POST", f"organizations/{_segment(organization_id)}/invitations", json=body
+            )
+        )
+
+    def revoke(self, organization_id: str, invitation_id: str) -> Object:
+        return _object(
+            self._control.request(
+                "DELETE",
+                f"organizations/{_segment(organization_id)}/invitations/{_segment(invitation_id)}",
+            )
+        )
+
+
+class Invitations:
+    """Preview and accept an invitation as the authenticated recipient."""
+
+    def __init__(self, control: Control) -> None:
+        self._control = control
+
+    def preview(self, token: str) -> Object:
+        """Read the invitation; the platform's preview route carries its token in the URL."""
+        return _object(self._control.request("GET", f"invitations/{_segment(token)}"))
+
+    def accept(self, *, token: str) -> Object:
+        """Join a workspace, sending the invitation token in the request body."""
+        return _object(self._control.request("POST", "invitations/accept", json={"token": token}))
+
+
 class Endpoints:
     def __init__(self, control: Control) -> None:
         self._control = control
@@ -258,7 +371,7 @@ class Endpoints:
 
 
 class AsyncControl:
-    """Platform root configuration plus catalog, organizations and endpoints."""
+    """Async customer catalog, workspaces, invitations, and dedicated endpoints."""
 
     def __init__(
         self,
@@ -269,13 +382,17 @@ class AsyncControl:
         http_client: httpx.AsyncClient | None = None,
     ) -> None:
         _positive(timeout, "timeout")
-        self.base_url = _config.platform_url(base_url) + "/control/v1"
+        self.base_url = (
+            _config.not_vendor_host(_config.platform_url(base_url), field="base_url")
+            + "/control/v1"
+        )
         self._headers = {"Authorization": f"Bearer {_config.api_key(api_key)}"}
         self._timeout = timeout
         self._owns_client = http_client is None
         self._client = http_client if http_client is not None else httpx.AsyncClient()
         self.catalog = AsyncCatalog(self)
         self.organizations = AsyncOrganizations(self)
+        self.invitations = AsyncInvitations(self)
         self.endpoints = AsyncEndpoints(self)
 
     async def request(
@@ -288,15 +405,16 @@ class AsyncControl:
         timeout: float | None = None,
     ) -> JsonValue:
         """Call another verified customer route relative to /control/v1."""
-        response = await self._client.request(
-            method,
-            _target(self.base_url, path),
-            headers=self._headers,
-            json=json,
-            params=params,
-            timeout=self._timeout if timeout is None else timeout,
-            follow_redirects=False,
-        )
+        with wrap_httpx_errors():
+            response = await self._client.request(
+                method,
+                _target(self.base_url, path),
+                headers=self._headers,
+                json=json,
+                params=params,
+                timeout=self._timeout if timeout is None else timeout,
+                follow_redirects=False,
+            )
         return _decode(response)
 
     async def close(self) -> None:
@@ -327,8 +445,12 @@ class AsyncCatalog:
 
 
 class AsyncOrganizations:
+    """Workspaces visible to the authenticated customer; permissions are server-enforced."""
+
     def __init__(self, control: AsyncControl) -> None:
         self._control = control
+        self.members = AsyncOrganizationMembers(control)
+        self.invitations = AsyncOrganizationInvitations(control)
 
     async def list(self) -> list[Object]:
         return _objects(await self._control.request("GET", "organizations"))
@@ -338,6 +460,26 @@ class AsyncOrganizations:
             await self._control.request("GET", f"organizations/{_segment(organization_id)}")
         )
 
+    async def create(self, *, name: str) -> Object:
+        """Create a workspace with the platform's default allocation."""
+        return _object(await self._control.request("POST", "organizations", json={"name": name}))
+
+    async def update(self, organization_id: str, *, name: str) -> Object:
+        """Rename a workspace as an owner or admin."""
+        return _object(
+            await self._control.request(
+                "PATCH", f"organizations/{_segment(organization_id)}", json={"name": name}
+            )
+        )
+
+    async def delete(self, organization_id: str) -> None:
+        """Delete a workspace as an owner."""
+        await self._control.request("DELETE", f"organizations/{_segment(organization_id)}")
+
+    async def leave(self, organization_id: str) -> None:
+        """Leave a workspace; the server refuses removal of its last owner."""
+        await self._control.request("POST", f"organizations/{_segment(organization_id)}/leave")
+
     async def limits(self, organization_id: str) -> Object:
         """Return quota policy, current usage, and any pending increase request."""
         return _object(
@@ -345,6 +487,92 @@ class AsyncOrganizations:
         )
 
 
+class AsyncOrganizationMembers:
+    def __init__(self, control: AsyncControl) -> None:
+        self._control = control
+
+    async def list(self, organization_id: str) -> list[Object]:
+        return _objects(
+            await self._control.request("GET", f"organizations/{_segment(organization_id)}/members")
+        )
+
+    async def update(self, organization_id: str, user_id: str, *, role: OrganizationRole) -> Object:
+        """Change a member's role, subject to owner/admin and last-owner rules."""
+        return _object(
+            await self._control.request(
+                "PATCH",
+                f"organizations/{_segment(organization_id)}/members/{_segment(user_id)}",
+                json={"role": role},
+            )
+        )
+
+    async def remove(self, organization_id: str, user_id: str) -> None:
+        await self._control.request(
+            "DELETE", f"organizations/{_segment(organization_id)}/members/{_segment(user_id)}"
+        )
+
+
+class AsyncOrganizationInvitations:
+    def __init__(self, control: AsyncControl) -> None:
+        self._control = control
+
+    async def list(self, organization_id: str) -> list[Object]:
+        return _objects(
+            await self._control.request(
+                "GET", f"organizations/{_segment(organization_id)}/invitations"
+            )
+        )
+
+    async def create(
+        self,
+        organization_id: str,
+        *,
+        role: OrganizationRole,
+        email: str | None = None,
+        entitlement_policy: Object | None = None,
+    ) -> Object:
+        """Create an invite; supplying email also asks the server to send it.
+
+        Targeted customer invites require a member entitlement policy. Inspect
+        delivery_warning in the response even when creation succeeds.
+        """
+        body: Object = {"role": role}
+        if email is not None:
+            body["email"] = email
+        if entitlement_policy is not None:
+            body["entitlement_policy"] = entitlement_policy
+        return _object(
+            await self._control.request(
+                "POST", f"organizations/{_segment(organization_id)}/invitations", json=body
+            )
+        )
+
+    async def revoke(self, organization_id: str, invitation_id: str) -> Object:
+        return _object(
+            await self._control.request(
+                "DELETE",
+                f"organizations/{_segment(organization_id)}/invitations/{_segment(invitation_id)}",
+            )
+        )
+
+
+class AsyncInvitations:
+    """Preview and accept an invitation as the authenticated recipient."""
+
+    def __init__(self, control: AsyncControl) -> None:
+        self._control = control
+
+    async def preview(self, token: str) -> Object:
+        """Read the invitation; the platform's preview route carries its token in the URL."""
+        return _object(await self._control.request("GET", f"invitations/{_segment(token)}"))
+
+    async def accept(self, *, token: str) -> Object:
+        """Join a workspace, sending the invitation token in the request body."""
+        return _object(
+            await self._control.request("POST", "invitations/accept", json={"token": token})
+        )
+
+
 class AsyncEndpoints:
     def __init__(self, control: AsyncControl) -> None:
         self._control = control