avartha-python-sdk 0.0.1__py3-none-any.whl

avartha/__init__.py

@@ -0,0 +1,42 @@
+"""Avartha Python SDK: upstream protocol compatibility and platform management."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+from elevenlabs import AudioFormat, CommitStrategy, RealtimeEvents, VoiceSettings
+from elevenlabs.play import play, save, stream
+
+from ._realtime_tts import DEFAULT_OUTPUT_FORMAT as DEFAULT_TTS_OUTPUT_FORMAT
+from .client import AsyncAvartha, Avartha
+from .control import AsyncControl, Control
+from .elevenlabs import AsyncElevenLabs, ElevenLabs
+from .errors import ConfigurationError, EndpointFailedError, PlatformAPIError
+from .openai import AsyncOpenAI, OpenAI
+
+try:
+    # Populated from the git tag at build time by setuptools_scm.
+    __version__ = _dist_version("avartha-python-sdk")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled tree
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "AsyncAvartha",
+    "AsyncControl",
+    "AsyncElevenLabs",
+    "AsyncOpenAI",
+    "AudioFormat",
+    "Avartha",
+    "CommitStrategy",
+    "ConfigurationError",
+    "DEFAULT_TTS_OUTPUT_FORMAT",
+    "Control",
+    "ElevenLabs",
+    "EndpointFailedError",
+    "OpenAI",
+    "PlatformAPIError",
+    "RealtimeEvents",
+    "VoiceSettings",
+    "play",
+    "save",
+    "stream",
+]

avartha/_config.py

@@ -0,0 +1,140 @@
+"""Avartha configuration; vendor environment variables are never credentials."""
+
+import os
+import re
+from ipaddress import IPv6Address
+from typing import Literal
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+
+Tier = Literal["serverless", "dedicated"]
+DEFAULT_BASE_URL = "https://platform.avartha.ai"
+
+
+class ConfigurationError(ValueError):
+    """Missing credentials or an invalid service URL."""
+
+
+def api_key(value: str | None) -> str:
+    key = value if value is not None else os.environ.get("AVARTHA_API_KEY")
+    if not key or not key.strip():
+        raise ConfigurationError("Set api_key or AVARTHA_API_KEY to an Avartha API key.")
+    return key
+
+
+def http_url(value: str) -> str:
+    parts = urlsplit(value)
+    if (
+        parts.scheme not in {"http", "https"}
+        or not parts.hostname
+        or parts.username is not None
+        or parts.password is not None
+        or parts.query
+        or parts.fragment
+    ):
+        raise ConfigurationError(
+            "Use an absolute http(s) base URL without credentials, query, or fragment."
+        )
+    return value.rstrip("/")
+
+
+def platform_url(value: str | None = None) -> str:
+    url = http_url(value if value is not None else os.getenv("AVARTHA_BASE_URL", DEFAULT_BASE_URL))
+    path = urlsplit(url).path
+    if "/inference/" in path or path.endswith("/control/v1"):
+        raise ConfigurationError(
+            "base_url must be the platform root, before /inference or /control."
+        )
+    return url
+
+
+def openai_url(root: str | None = None, tier: Tier = "serverless") -> str:
+    if tier not in {"serverless", "dedicated"}:
+        raise ConfigurationError("tier must be 'serverless' or 'dedicated'.")
+    return f"{platform_url(root)}/inference/{tier}/openai/v1"
+
+
+def elevenlabs_url(
+    value: str | None = None, *, root: str | None = None, tier: Tier = "serverless"
+) -> str:
+    override = value if value is not None else os.getenv("AVARTHA_ELEVENLABS_BASE_URL")
+    if override is not None:
+        return http_url(override)
+    if tier not in {"serverless", "dedicated"}:
+        raise ConfigurationError("tier must be 'serverless' or 'dedicated'.")
+    return f"{platform_url(root)}/inference/{tier}/elevenlabs"
+
+
+def websocket_url(value: str) -> str:
+    parts = urlsplit(value)
+    return urlunsplit(parts._replace(scheme={"https": "wss", "http": "ws"}[parts.scheme]))
+
+
+VENDOR_HOSTS = ("openai.com", "openai.azure.com")
+
+
+def not_vendor_host(value: str, *, field: str) -> str:
+    """Refuse a URL that would send an Avartha credential to a vendor endpoint."""
+    host = (urlsplit(value).hostname or "").lower().rstrip(".")
+    if any(host == vendor or host.endswith(f".{vendor}") for vendor in VENDOR_HOSTS):
+        raise ConfigurationError(
+            f"{field} resolves to the vendor host {host!r}. An Avartha API key must never "
+            "be sent to a vendor endpoint; use the official vendor package for that."
+        )
+    return value
+
+
+def websocket_override(value: str) -> str:
+    """Return a canonical WebSocket service base suitable for upstream joining.
+
+    OpenAI appends `/realtime` to this URL's raw path. Query strings would be
+    corrupted by that join, so request query parameters belong in connect().
+    Validate before parsing as urllib silently removes some whitespace/controls.
+    """
+    message = (
+        "websocket_base_url must be an absolute wss:// service URL with a "
+        "valid hostname and port (1-65535), without credentials, whitespace, "
+        "backslashes, query, or fragment."
+    )
+    try:
+        if (
+            not value
+            or any(char.isspace() or ord(char) < 32 or ord(char) == 127 for char in value)
+            or any(char in value for char in "\\?#")
+            or re.search(r"%(?![0-9a-fA-F]{2})", value)
+        ):
+            raise ValueError("Invalid URL characters")
+        parts = urlsplit(value)
+        if (
+            parts.scheme != "wss"
+            or not parts.hostname
+            or parts.username is not None
+            or parts.password is not None
+            or parts.netloc.endswith(":")
+            or (parts.port is not None and not 1 <= parts.port <= 65535)
+        ):
+            raise ValueError("Invalid URL authority")
+        # Use the declared HTTPX dependency for IDNA, IPv6, and path escaping.
+        url = httpx.URL(urlunsplit(parts))
+        host = url.raw_host.decode("ascii")
+        if ":" in host:
+            url = url.copy_with(host=str(IPv6Address(host)))
+        else:
+            hostname = host.removesuffix(".")
+            if len(hostname) > 253 or any(
+                re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label) is None
+                for label in hostname.split(".")
+            ):
+                raise ValueError("Invalid hostname")
+    except (ValueError, httpx.InvalidURL):
+        # Do not expose userinfo or credential-like query values in diagnostics.
+        raise ConfigurationError(message) from None
+
+    normalized = str(url).rstrip("/")
+    if url.path.rstrip("/").endswith("/realtime"):
+        raise ConfigurationError(
+            "websocket_base_url must be the service base before /realtime; "
+            "the SDK appends /realtime when connecting."
+        )
+    return not_vendor_host(normalized, field="websocket_base_url")

avartha/_realtime_tts.py

@@ -0,0 +1,138 @@
+"""Realtime text-to-speech for the Avartha gateway.
+
+The official `convert_realtime` hard-codes three values the gateway refuses and
+`request_options` cannot reach: it omits `auto_mode`, sends
+`try_trigger_generation: true`, and sends a populated `generation_config`. Its
+`mp3_44100_128` default format is refused too, and every rejection closes the
+socket 1011, so upstream's helper fails on every Avartha TTS model. Only the
+request envelope is corrected here; chunking, the message sequence, the yielded
+audio and the raised `ApiError` stay upstream's.
+"""
+
+import base64
+import json
+from collections.abc import Iterator, Mapping
+from typing import Any, cast
+
+import websockets
+from elevenlabs.core.api_error import ApiError
+from elevenlabs.core.jsonable_encoder import jsonable_encoder
+from elevenlabs.core.remove_none_from_dict import remove_none_from_dict
+from elevenlabs.core.request_options import RequestOptions
+from elevenlabs.realtime_tts import RealtimeTextToSpeechClient, text_chunker
+from elevenlabs.types import OutputFormat
+from elevenlabs.types.voice_settings import VoiceSettings
+from elevenlabs.url_utils import build_ws_url
+from websockets.sync.client import connect
+
+OMIT = cast(Any, ...)
+
+# Avartha publishes no sample rate and the TTS models refuse every other format,
+# so their native PCM rate is the only workable default.
+DEFAULT_OUTPUT_FORMAT: OutputFormat = "pcm_24000"
+
+# How long a send loop looks for audio before pushing the next chunk.
+DRAIN_TIMEOUT = 1e-2
+
+
+def _given[T](value: T) -> T | None:
+    """Upstream's OMIT sentinel means "not supplied" and must never reach the wire."""
+    return None if value is OMIT else value
+
+
+def _path(voice_id: str, endpoint: str) -> list[str]:
+    return ["v1", "text-to-speech", voice_id, endpoint]
+
+
+def _query(model_id: str | None, output_format: OutputFormat | None) -> dict[str, Any]:
+    return remove_none_from_dict(
+        {
+            "model_id": model_id,
+            "output_format": output_format or DEFAULT_OUTPUT_FORMAT,
+            "auto_mode": "true",
+        }
+    )
+
+
+def _headers(base: Mapping[str, str], request_options: RequestOptions | None) -> dict[str, str]:
+    extra = request_options.get("additional_headers", {}) if request_options else {}
+    return cast(dict[str, str], jsonable_encoder(remove_none_from_dict({**base, **extra})))
+
+
+def _opening(voice_settings: VoiceSettings | None) -> str:
+    """The single-space message the gateway requires before any text."""
+    frame: dict[str, Any] = {"text": " "}
+    if voice_settings is not None:
+        frame["voice_settings"] = voice_settings.dict()
+    return json.dumps(frame)
+
+
+def _audio(payload: Any) -> bytes | None:
+    encoded = payload.get("audio") if isinstance(payload, Mapping) else None
+    return base64.b64decode(encoded) if encoded else None
+
+
+def _failure(received: Any, closed: websockets.exceptions.ConnectionClosed) -> ApiError | None:
+    """The error a closed socket deserves, or None once the stream finished cleanly.
+
+    Upstream inspects the last payload *sent* here, so the gateway's own
+    diagnosis is thrown away; report what actually arrived instead.
+    """
+    if isinstance(received, Mapping) and "message" in received:
+        return ApiError(body=dict(received), status_code=closed.code)
+    if closed.code != 1000:
+        return ApiError(body=closed.reason, status_code=closed.code)
+    return None
+
+
+class AvarthaRealtimeTextToSpeechClient(RealtimeTextToSpeechClient):
+    """Upstream realtime TTS with the gateway-compatible request envelope."""
+
+    def convert_realtime(
+        self,
+        voice_id: str,
+        *,
+        text: Iterator[str],
+        model_id: str | None = OMIT,
+        output_format: OutputFormat | None = None,
+        voice_settings: VoiceSettings | None = OMIT,
+        request_options: RequestOptions | None = None,
+    ) -> Iterator[bytes]:
+        """Stream `text` to `voice_id` and yield raw audio frames.
+
+        `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.
+        """
+        with connect(
+            build_ws_url(
+                self._ws_base_url,
+                _path(voice_id, "stream-input"),
+                _query(_given(model_id), output_format),
+            ),
+            additional_headers=_headers(self._client_wrapper.get_headers(), request_options),
+        ) as socket:
+            received: Any = None
+            try:
+                socket.send(_opening(_given(voice_settings)))
+            except websockets.exceptions.ConnectionClosedError as closed:
+                raise ApiError(body=closed.reason, status_code=closed.code) from closed
+
+            try:
+                for chunk in text_chunker(text):
+                    socket.send(json.dumps({"text": chunk}))
+                    try:
+                        received = json.loads(socket.recv(DRAIN_TIMEOUT))
+                    except TimeoutError:
+                        continue
+                    if audio := _audio(received):
+                        yield audio
+
+                socket.send(json.dumps({"text": ""}))
+                while True:
+                    received = json.loads(socket.recv())
+                    if audio := _audio(received):
+                        yield audio
+            except websockets.exceptions.ConnectionClosed as closed:
+                if failure := _failure(received, closed):
+                    raise failure from closed

avartha/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

avartha/client.py

@@ -0,0 +1,159 @@
+"""Convenience clients combining protocol clients with Avartha management."""
+
+from functools import cached_property
+from types import TracebackType
+from typing import Any, Self
+
+from . import _config
+from ._config import Tier
+from .control import AsyncControl, Control
+from .elevenlabs import AsyncElevenLabs, ElevenLabs
+from .openai import AsyncOpenAI, OpenAI
+
+
+class Avartha:
+    """Use a platform root URL; protocol-specific clients accept full service URLs.
+
+    openai_options, elevenlabs_options and control_options are forwarded to
+    their respective constructors (for timeouts, transports, retry settings).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        tier: Tier = "serverless",
+        elevenlabs_base_url: str | None = None,
+        elevenlabs_api_key: str | None = None,
+        openai_options: dict[str, Any] | None = None,
+        elevenlabs_options: dict[str, Any] | None = None,
+        control_options: dict[str, Any] | None = None,
+    ) -> None:
+        key, root = _config.api_key(api_key), _config.platform_url(base_url)
+        self._elevenlabs_base_url = _config.elevenlabs_url(
+            elevenlabs_base_url, root=root, tier=tier
+        )
+        self._elevenlabs_api_key = elevenlabs_api_key if elevenlabs_api_key is not None else key
+        self._elevenlabs_options = dict(elevenlabs_options or {})
+        self._control_config = {"api_key": key, "base_url": root, **(control_options or {})}
+        self.openai = OpenAI(
+            api_key=key,
+            base_url=_config.openai_url(root, tier),
+            **(openai_options or {}),
+        )
+        # These are the actual upstream resources, preserving their typed methods.
+        self.chat = self.openai.chat
+        self.responses = self.openai.responses
+        self.completions = self.openai.completions
+        self.realtime = self.openai.realtime
+        self.audio = self.openai.audio
+        self.models = self.openai.models
+
+    @cached_property
+    def elevenlabs(self) -> ElevenLabs:
+        return ElevenLabs(
+            api_key=self._elevenlabs_api_key,
+            base_url=self._elevenlabs_base_url,
+            **self._elevenlabs_options,
+        )
+
+    @cached_property
+    def control(self) -> Control:
+        return Control(**self._control_config)
+
+    def close(self) -> None:
+        try:
+            self.openai.close()
+        finally:
+            try:
+                if "elevenlabs" in self.__dict__:
+                    self.elevenlabs.close()
+            finally:
+                if "control" in self.__dict__:
+                    self.control.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncAvartha:
+    """Use a platform root URL; protocol-specific clients accept full service URLs.
+
+    openai_options, elevenlabs_options and control_options are forwarded to
+    their respective constructors (for timeouts, transports, retry settings).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        tier: Tier = "serverless",
+        elevenlabs_base_url: str | None = None,
+        elevenlabs_api_key: str | None = None,
+        openai_options: dict[str, Any] | None = None,
+        elevenlabs_options: dict[str, Any] | None = None,
+        control_options: dict[str, Any] | None = None,
+    ) -> None:
+        key, root = _config.api_key(api_key), _config.platform_url(base_url)
+        self._elevenlabs_base_url = _config.elevenlabs_url(
+            elevenlabs_base_url, root=root, tier=tier
+        )
+        self._elevenlabs_api_key = elevenlabs_api_key if elevenlabs_api_key is not None else key
+        self._elevenlabs_options = dict(elevenlabs_options or {})
+        self._control_config = {"api_key": key, "base_url": root, **(control_options or {})}
+        self.openai = AsyncOpenAI(
+            api_key=key,
+            base_url=_config.openai_url(root, tier),
+            **(openai_options or {}),
+        )
+        # These are the actual upstream resources, preserving their typed methods.
+        self.chat = self.openai.chat
+        self.responses = self.openai.responses
+        self.completions = self.openai.completions
+        self.realtime = self.openai.realtime
+        self.audio = self.openai.audio
+        self.models = self.openai.models
+
+    @cached_property
+    def elevenlabs(self) -> AsyncElevenLabs:
+        return AsyncElevenLabs(
+            api_key=self._elevenlabs_api_key,
+            base_url=self._elevenlabs_base_url,
+            **self._elevenlabs_options,
+        )
+
+    @cached_property
+    def control(self) -> AsyncControl:
+        return AsyncControl(**self._control_config)
+
+    async def close(self) -> None:
+        try:
+            await self.openai.close()
+        finally:
+            try:
+                if "elevenlabs" in self.__dict__:
+                    await self.elevenlabs.close()
+            finally:
+                if "control" in self.__dict__:
+                    await self.control.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()