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

avartha/__init__.py

@@ -30,7 +30,12 @@ from ._openai_http_errors import UnprocessableEntityError as OpenAIUnprocessable
 from ._pacing import WebSocketLimits
 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 ._realtime_tts import (
+    AsyncMultiContextSession,
+    MultiContextSession,
+    TextToSpeechOutputFormat,
+    audio_bytes,
+)
 from ._sentinels import NOT_GIVEN, NotGiven, Omit, not_given, omit
 from .client import AsyncAvartha, Avartha
 from .control import AsyncControl, Control
@@ -91,6 +96,7 @@ __all__ = [
     "PlatformAPIError",
     "RealtimeAudioOptions",
     "RealtimeEvents",
+    "TextToSpeechOutputFormat",
     "VoiceSettings",
     "WebSocketLimits",
     "audio_bytes",

avartha/_conversation_resources.py

@@ -0,0 +1,555 @@
+"""Typed resources for Avartha's conversation routes.
+
+Their parameters are the ones the platform accepts, which is a small subset of ElevenLabs
+2.68.0. It refuses unknown query parameters, so the vendor's other filters would only fail.
+"""
+
+import json
+from collections.abc import Mapping
+from typing import Any, Never
+
+from ._exceptions import UnsupportedOperationError
+from ._speech_config import RequestOptions
+from ._speech_http import (
+    AsyncHttpResponse,
+    AsyncSpeechHTTPClient,
+    HttpResponse,
+    SpeechHTTPClient,
+    segment,
+)
+from .types.conversational_ai import (
+    ConversationInitiationClientDataRequestInput,
+    ConversationSignedUrlResponseModel,
+    GetConversationResponseModel,
+    GetConversationsPageResponseModel,
+    TelephonyCallConfigInput,
+    TokenResponseModel,
+    TwilioOutboundCallResponse,
+)
+
+_BASE = "v1/convai"
+_OUTBOUND_CALL = f"{_BASE}/twilio/outbound-call"
+_IDEMPOTENCY_HEADER = "Idempotency-Key"
+# A 409 is left to the caller: the key was reused for a different call, or the workspace is at
+# its call limit, and ringing someone moments later wouldn't be expected.
+_DIAL_RETRY_STATUSES = (408, 429)
+
+
+def _encoded(value: Mapping[str, Any] | None) -> str | None:
+    return None if not value else json.dumps(value, separators=(",", ":"))
+
+
+def _mint_params(
+    agent_id: str,
+    origin: str | None,
+    conversation_config_override: Mapping[str, Any] | None,
+    dynamic_variables: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    return {
+        "agent_id": agent_id,
+        "origin": origin,
+        "conversation_config_override": _encoded(conversation_config_override),
+        "dynamic_variables": _encoded(dynamic_variables),
+    }
+
+
+def _dial_body(
+    agent_id: str,
+    agent_phone_number_id: str,
+    to_number: str,
+    conversation_initiation_client_data: ConversationInitiationClientDataRequestInput | None,
+    call_recording_enabled: bool | None,
+    telephony_call_config: TelephonyCallConfigInput | None,
+) -> dict[str, Any]:
+    optional = {
+        "conversation_initiation_client_data": conversation_initiation_client_data,
+        "call_recording_enabled": call_recording_enabled,
+        "telephony_call_config": telephony_call_config,
+    }
+    return {
+        "agent_id": agent_id,
+        "agent_phone_number_id": agent_phone_number_id,
+        "to_number": to_number,
+        **{name: value for name, value in optional.items() if value is not None},
+    }
+
+
+def _dial_options(
+    idempotency_key: str | None, request_options: RequestOptions | None
+) -> RequestOptions:
+    """Attach the key, and never retry without one: each keyless request rings someone."""
+    options: RequestOptions = {**(request_options or {})}
+    headers = dict(options.get("additional_headers") or {})
+    key_header = _IDEMPOTENCY_HEADER.lower()
+    if idempotency_key is not None:
+        headers = {name: value for name, value in headers.items() if name.lower() != key_header}
+        headers[_IDEMPOTENCY_HEADER] = idempotency_key
+    options["additional_headers"] = headers
+    if not any(name.lower() == key_header and value is not None for name, value in headers.items()):
+        options["max_retries"] = 0
+    return options
+
+
+def _refuse_register_call() -> Never:
+    raise UnsupportedOperationError(
+        "conversational_ai.twilio.register_call is not supported. Avartha answers calls to a "
+        "connected number with the agent assigned to it, and outbound_call places calls."
+    )
+
+
+class RawConversations:
+    def __init__(self, client: SpeechHTTPClient) -> None:
+        self._client = client
+
+    def get_signed_url(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> HttpResponse[ConversationSignedUrlResponseModel]:
+        return self._client.get(
+            f"{_BASE}/conversation/get-signed-url",
+            ConversationSignedUrlResponseModel,
+            params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
+            request_options=request_options,
+        )
+
+    def get_webrtc_token(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> HttpResponse[TokenResponseModel]:
+        return self._client.get(
+            f"{_BASE}/conversation/token",
+            TokenResponseModel,
+            params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
+            request_options=request_options,
+        )
+
+    def list(
+        self, *, cursor: str | None = None, request_options: RequestOptions | None = None
+    ) -> HttpResponse[GetConversationsPageResponseModel]:
+        return self._client.get(
+            f"{_BASE}/conversations",
+            GetConversationsPageResponseModel,
+            params={"cursor": cursor},
+            request_options=request_options,
+        )
+
+    def get(
+        self,
+        conversation_id: str,
+        *,
+        format: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> HttpResponse[GetConversationResponseModel]:
+        return self._client.get(
+            f"{_BASE}/conversations/{segment(conversation_id)}",
+            GetConversationResponseModel,
+            params={"format": format},
+            request_options=request_options,
+        )
+
+    def end(
+        self, conversation_id: str, *, request_options: RequestOptions | None = None
+    ) -> HttpResponse[GetConversationResponseModel]:
+        return self._client.post(
+            f"{_BASE}/conversations/{segment(conversation_id)}/end",
+            GetConversationResponseModel,
+            params={},
+            request_options=request_options,
+        )
+
+
+class Conversations:
+    """Mint connection grants and read or end conversations."""
+
+    def __init__(self, client: SpeechHTTPClient) -> None:
+        self.with_raw_response = RawConversations(client)
+
+    def get_signed_url(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ConversationSignedUrlResponseModel:
+        """Mint a single-use WebSocket URL that expires in 30 seconds."""
+        return self.with_raw_response.get_signed_url(
+            agent_id=agent_id,
+            origin=origin,
+            conversation_config_override=conversation_config_override,
+            dynamic_variables=dynamic_variables,
+            request_options=request_options,
+        ).data
+
+    def get_webrtc_token(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> TokenResponseModel:
+        """Mint a grant for a browser's WebRTC connection."""
+        return self.with_raw_response.get_webrtc_token(
+            agent_id=agent_id,
+            origin=origin,
+            conversation_config_override=conversation_config_override,
+            dynamic_variables=dynamic_variables,
+            request_options=request_options,
+        ).data
+
+    def list(
+        self, *, cursor: str | None = None, request_options: RequestOptions | None = None
+    ) -> GetConversationsPageResponseModel:
+        """Return up to 100 conversations; pass next_cursor as cursor for the next page."""
+        return self.with_raw_response.list(cursor=cursor, request_options=request_options).data
+
+    def get(
+        self,
+        conversation_id: str,
+        *,
+        format: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> GetConversationResponseModel:
+        """Return a conversation's status, retained transcript, and billing."""
+        return self.with_raw_response.get(
+            conversation_id, format=format, request_options=request_options
+        ).data
+
+    def end(
+        self, conversation_id: str, *, request_options: RequestOptions | None = None
+    ) -> GetConversationResponseModel:
+        """End a conversation; ending one that has finished is safe. Avartha extension."""
+        return self.with_raw_response.end(conversation_id, request_options=request_options).data
+
+
+class AsyncRawConversations:
+    def __init__(self, client: AsyncSpeechHTTPClient) -> None:
+        self._client = client
+
+    async def get_signed_url(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncHttpResponse[ConversationSignedUrlResponseModel]:
+        return await self._client.get(
+            f"{_BASE}/conversation/get-signed-url",
+            ConversationSignedUrlResponseModel,
+            params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
+            request_options=request_options,
+        )
+
+    async def get_webrtc_token(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncHttpResponse[TokenResponseModel]:
+        return await self._client.get(
+            f"{_BASE}/conversation/token",
+            TokenResponseModel,
+            params=_mint_params(agent_id, origin, conversation_config_override, dynamic_variables),
+            request_options=request_options,
+        )
+
+    async def list(
+        self, *, cursor: str | None = None, request_options: RequestOptions | None = None
+    ) -> AsyncHttpResponse[GetConversationsPageResponseModel]:
+        return await self._client.get(
+            f"{_BASE}/conversations",
+            GetConversationsPageResponseModel,
+            params={"cursor": cursor},
+            request_options=request_options,
+        )
+
+    async def get(
+        self,
+        conversation_id: str,
+        *,
+        format: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncHttpResponse[GetConversationResponseModel]:
+        return await self._client.get(
+            f"{_BASE}/conversations/{segment(conversation_id)}",
+            GetConversationResponseModel,
+            params={"format": format},
+            request_options=request_options,
+        )
+
+    async def end(
+        self, conversation_id: str, *, request_options: RequestOptions | None = None
+    ) -> AsyncHttpResponse[GetConversationResponseModel]:
+        return await self._client.post(
+            f"{_BASE}/conversations/{segment(conversation_id)}/end",
+            GetConversationResponseModel,
+            params={},
+            request_options=request_options,
+        )
+
+
+class AsyncConversations:
+    """Mint connection grants and read or end conversations."""
+
+    def __init__(self, client: AsyncSpeechHTTPClient) -> None:
+        self.with_raw_response = AsyncRawConversations(client)
+
+    async def get_signed_url(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ConversationSignedUrlResponseModel:
+        """Mint a single-use WebSocket URL that expires in 30 seconds."""
+        response = await self.with_raw_response.get_signed_url(
+            agent_id=agent_id,
+            origin=origin,
+            conversation_config_override=conversation_config_override,
+            dynamic_variables=dynamic_variables,
+            request_options=request_options,
+        )
+        return response.data
+
+    async def get_webrtc_token(
+        self,
+        *,
+        agent_id: str,
+        origin: str | None = None,
+        conversation_config_override: Mapping[str, Any] | None = None,
+        dynamic_variables: Mapping[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> TokenResponseModel:
+        """Mint a grant for a browser's WebRTC connection."""
+        response = await self.with_raw_response.get_webrtc_token(
+            agent_id=agent_id,
+            origin=origin,
+            conversation_config_override=conversation_config_override,
+            dynamic_variables=dynamic_variables,
+            request_options=request_options,
+        )
+        return response.data
+
+    async def list(
+        self, *, cursor: str | None = None, request_options: RequestOptions | None = None
+    ) -> GetConversationsPageResponseModel:
+        """Return up to 100 conversations; pass next_cursor as cursor for the next page."""
+        response = await self.with_raw_response.list(cursor=cursor, request_options=request_options)
+        return response.data
+
+    async def get(
+        self,
+        conversation_id: str,
+        *,
+        format: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> GetConversationResponseModel:
+        """Return a conversation's status, retained transcript, and billing."""
+        response = await self.with_raw_response.get(
+            conversation_id, format=format, request_options=request_options
+        )
+        return response.data
+
+    async def end(
+        self, conversation_id: str, *, request_options: RequestOptions | None = None
+    ) -> GetConversationResponseModel:
+        """End a conversation; ending one that has finished is safe. Avartha extension."""
+        response = await self.with_raw_response.end(
+            conversation_id, request_options=request_options
+        )
+        return response.data
+
+
+class RawTwilio:
+    def __init__(self, client: SpeechHTTPClient) -> None:
+        self._client = client
+
+    def outbound_call(
+        self,
+        *,
+        agent_id: str,
+        agent_phone_number_id: str,
+        to_number: str,
+        conversation_initiation_client_data: ConversationInitiationClientDataRequestInput
+        | None = None,
+        call_recording_enabled: bool | None = None,
+        telephony_call_config: TelephonyCallConfigInput | None = None,
+        idempotency_key: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> HttpResponse[TwilioOutboundCallResponse]:
+        return self._client.post(
+            _OUTBOUND_CALL,
+            TwilioOutboundCallResponse,
+            params={},
+            body=_dial_body(
+                agent_id,
+                agent_phone_number_id,
+                to_number,
+                conversation_initiation_client_data,
+                call_recording_enabled,
+                telephony_call_config,
+            ),
+            retry_statuses=_DIAL_RETRY_STATUSES,
+            request_options=_dial_options(idempotency_key, request_options),
+        )
+
+
+class Twilio:
+    """Place phone calls from one of the workspace's Twilio numbers."""
+
+    def __init__(self, client: SpeechHTTPClient) -> None:
+        self.with_raw_response = RawTwilio(client)
+
+    def outbound_call(
+        self,
+        *,
+        agent_id: str,
+        agent_phone_number_id: str,
+        to_number: str,
+        conversation_initiation_client_data: ConversationInitiationClientDataRequestInput
+        | None = None,
+        call_recording_enabled: bool | None = None,
+        telephony_call_config: TelephonyCallConfigInput | None = None,
+        idempotency_key: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> TwilioOutboundCallResponse:
+        """Ring to_number and connect the agent when someone answers.
+
+        Pass idempotency_key, an Avartha extension, so a repeated request returns the first
+        attempt instead of ringing again; only then does the SDK retry. Check success: False
+        means Twilio refused the call or didn't confirm it, and an unconfirmed call may still
+        ring.
+        """
+        return self.with_raw_response.outbound_call(
+            agent_id=agent_id,
+            agent_phone_number_id=agent_phone_number_id,
+            to_number=to_number,
+            conversation_initiation_client_data=conversation_initiation_client_data,
+            call_recording_enabled=call_recording_enabled,
+            telephony_call_config=telephony_call_config,
+            idempotency_key=idempotency_key,
+            request_options=request_options,
+        ).data
+
+    def register_call(self, **kwargs: Any) -> Never:
+        _refuse_register_call()
+
+
+class AsyncRawTwilio:
+    def __init__(self, client: AsyncSpeechHTTPClient) -> None:
+        self._client = client
+
+    async def outbound_call(
+        self,
+        *,
+        agent_id: str,
+        agent_phone_number_id: str,
+        to_number: str,
+        conversation_initiation_client_data: ConversationInitiationClientDataRequestInput
+        | None = None,
+        call_recording_enabled: bool | None = None,
+        telephony_call_config: TelephonyCallConfigInput | None = None,
+        idempotency_key: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> AsyncHttpResponse[TwilioOutboundCallResponse]:
+        return await self._client.post(
+            _OUTBOUND_CALL,
+            TwilioOutboundCallResponse,
+            params={},
+            body=_dial_body(
+                agent_id,
+                agent_phone_number_id,
+                to_number,
+                conversation_initiation_client_data,
+                call_recording_enabled,
+                telephony_call_config,
+            ),
+            retry_statuses=_DIAL_RETRY_STATUSES,
+            request_options=_dial_options(idempotency_key, request_options),
+        )
+
+
+class AsyncTwilio:
+    """Place phone calls from one of the workspace's Twilio numbers."""
+
+    def __init__(self, client: AsyncSpeechHTTPClient) -> None:
+        self.with_raw_response = AsyncRawTwilio(client)
+
+    async def outbound_call(
+        self,
+        *,
+        agent_id: str,
+        agent_phone_number_id: str,
+        to_number: str,
+        conversation_initiation_client_data: ConversationInitiationClientDataRequestInput
+        | None = None,
+        call_recording_enabled: bool | None = None,
+        telephony_call_config: TelephonyCallConfigInput | None = None,
+        idempotency_key: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> TwilioOutboundCallResponse:
+        """Ring to_number and connect the agent when someone answers.
+
+        Pass idempotency_key, an Avartha extension, so a repeated request returns the first
+        attempt instead of ringing again; only then does the SDK retry. Check success: False
+        means Twilio refused the call or didn't confirm it, and an unconfirmed call may still
+        ring.
+        """
+        response = await self.with_raw_response.outbound_call(
+            agent_id=agent_id,
+            agent_phone_number_id=agent_phone_number_id,
+            to_number=to_number,
+            conversation_initiation_client_data=conversation_initiation_client_data,
+            call_recording_enabled=call_recording_enabled,
+            telephony_call_config=telephony_call_config,
+            idempotency_key=idempotency_key,
+            request_options=request_options,
+        )
+        return response.data
+
+    def register_call(self, **kwargs: Any) -> Never:
+        _refuse_register_call()
+
+
+class _ConversationalAi:
+    def __getattr__(self, name: str) -> Never:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        raise NotImplementedError(
+            f"conversational_ai.{name} is not implemented. ElevenLabs-schema agents, tools, and "
+            "knowledge bases will be implemented in a future release; "
+            "conversational_ai.conversations and conversational_ai.twilio are available, "
+            "and Control.voice_agents manages Avartha voice agents."
+        )
+
+
+class ConversationalAi(_ConversationalAi):
+    def __init__(self, client: SpeechHTTPClient) -> None:
+        self.conversations = Conversations(client)
+        self.twilio = Twilio(client)
+
+
+class AsyncConversationalAi(_ConversationalAi):
+    def __init__(self, client: AsyncSpeechHTTPClient) -> None:
+        self.conversations = AsyncConversations(client)
+        self.twilio = AsyncTwilio(client)

avartha/_openai_http.py

@@ -133,7 +133,10 @@ def _check_status(response: httpx.Response) -> None:
         body = response.json()
     except ValueError:
         body = response.text
-    error_body = body.get("error", body) if isinstance(body, dict) else body
+    # OpenAI nests error details; the platform also returns flat envelopes whose
+    # string `error` is a message, with code/type/param alongside it.
+    nested = body.get("error") if isinstance(body, dict) else None
+    error_body = nested if isinstance(nested, dict) else body
     cls = {
         400: BadRequestError,
         401: AuthenticationError,