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

avartha/control.py

@@ -0,0 +1,441 @@
+"""Customer control plane at /control/v1, authenticated with Avartha bearer keys.
+
+Responses retain their JSON fields so additive platform changes remain visible.
+Writes are never automatically retried: endpoint creation may provision hardware.
+"""
+
+import asyncio
+import math
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Self
+from urllib.parse import quote, unquote, urlsplit
+
+import httpx
+from pydantic import JsonValue
+
+from . import _config
+from .errors import EndpointFailedError, PlatformAPIError
+
+type Object = dict[str, JsonValue]
+
+
+def _object(value: JsonValue) -> Object:
+    if not isinstance(value, dict):
+        raise ValueError("Expected a JSON object from the platform.")
+    return value
+
+
+def _objects(value: JsonValue) -> list[Object]:
+    if not isinstance(value, list):
+        raise ValueError("Expected a JSON array from the platform.")
+    return [_object(item) for item in value]
+
+
+def _segment(value: str) -> str:
+    if not value or value in {".", ".."} or any(c in value for c in "/\\"):
+        raise ValueError("Resource identifiers must be nonempty path segments.")
+    return quote(value, safe="")
+
+
+def _target(base_url: str, path: str) -> str:
+    parts = urlsplit(path)
+    decoded = unquote(parts.path)
+    if (
+        parts.scheme
+        or parts.netloc
+        or parts.query
+        or parts.fragment
+        or "\\" in decoded
+        or any(part in {".", ".."} for part in decoded.split("/"))
+    ):
+        raise ValueError("Use a relative control-plane path without query or traversal segments.")
+    return f"{base_url}/{path.lstrip('/')}"
+
+
+def _decode(response: httpx.Response) -> JsonValue:
+    if not response.is_success:
+        raise PlatformAPIError(response)
+    if response.status_code == 204 or not response.content:
+        return None
+    return response.json()
+
+
+def _positive(value: float, name: str) -> None:
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be finite and positive.")
+
+
+def _ready(endpoint: Object) -> bool:
+    if endpoint.get("status") in {"failed", "stopped", "stopping"}:
+        raise EndpointFailedError(endpoint)
+    replicas = endpoint.get("replicas")
+    accepting_ready = replicas.get("accepting_ready") if isinstance(replicas, dict) else None
+    return (
+        endpoint.get("status") == "running"
+        and isinstance(accepting_ready, int)
+        and accepting_ready > 0
+    )
+
+
+class Control:
+    """Platform root configuration plus catalog, organizations and endpoints."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        _positive(timeout, "timeout")
+        self.base_url = _config.platform_url(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.endpoints = Endpoints(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Object | None = None,
+        params: Mapping[str, str] | None = None,
+        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,
+        )
+        return _decode(response)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.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 Catalog:
+    def __init__(self, control: Control) -> None:
+        self._control = control
+
+    def models(self) -> list[Object]:
+        return _objects(self._control.request("GET", "catalog/models"))
+
+    def skus(self, *, provider: str) -> JsonValue:
+        return self._control.request("GET", "catalog/skus", params={"provider": provider})
+
+
+class Organizations:
+    def __init__(self, control: Control) -> None:
+        self._control = control
+
+    def list(self) -> list[Object]:
+        return _objects(self._control.request("GET", "organizations"))
+
+    def get(self, organization_id: str) -> Object:
+        return _object(self._control.request("GET", f"organizations/{_segment(organization_id)}"))
+
+    def limits(self, organization_id: str) -> Object:
+        """Return quota policy, current usage, and any pending increase request."""
+        return _object(
+            self._control.request("GET", f"organizations/{_segment(organization_id)}/limits")
+        )
+
+
+class Endpoints:
+    def __init__(self, control: Control) -> None:
+        self._control = control
+
+    def list(self, *, workspace_id: str) -> list[Object]:
+        return _objects(
+            self._control.request("GET", "endpoints", params={"workspace_id": workspace_id})
+        )
+
+    def get(self, endpoint_id: str, *, timeout: float | None = None) -> Object:
+        return _object(
+            self._control.request("GET", f"endpoints/{_segment(endpoint_id)}", timeout=timeout)
+        )
+
+    def create(
+        self,
+        *,
+        workspace_id: str,
+        model_slug: str,
+        name: str,
+        sku: Object,
+        cloud_connection_id: str | None = None,
+    ) -> Object:
+        """Persist launch intent; use wait_until_ready to observe provisioning."""
+        body: Object = {
+            "workspace_id": workspace_id,
+            "model_slug": model_slug,
+            "name": name,
+            "sku": sku,
+        }
+        if cloud_connection_id is not None:
+            body["cloud_connection_id"] = cloud_connection_id
+        return _object(self._control.request("POST", "endpoints", json=body))
+
+    def stop(self, endpoint_id: str) -> Object:
+        return _object(self._control.request("POST", f"endpoints/{_segment(endpoint_id)}/stop"))
+
+    def delete(self, endpoint_id: str) -> None:
+        self._control.request("DELETE", f"endpoints/{_segment(endpoint_id)}")
+
+    def management(self, endpoint_id: str) -> Object:
+        return _object(
+            self._control.request("GET", f"endpoints/{_segment(endpoint_id)}/management")
+        )
+
+    def update_scaling(
+        self, endpoint_id: str, *, expected_generation: int, policy: Object
+    ) -> JsonValue:
+        return self._control.request(
+            "PATCH",
+            f"endpoints/{_segment(endpoint_id)}/scaling",
+            json={"expected_generation": expected_generation, "policy": policy},
+        )
+
+    def update_routing(
+        self, endpoint_id: str, *, expected_generation: int, policy: Object
+    ) -> JsonValue:
+        return self._control.request(
+            "PATCH",
+            f"endpoints/{_segment(endpoint_id)}/routing",
+            json={"expected_generation": expected_generation, "policy": policy},
+        )
+
+    def wait_until_ready(
+        self,
+        endpoint_id: str,
+        *,
+        timeout: float = 600,
+        poll_interval: float = 2,
+    ) -> Object:
+        """Wait for a running endpoint with an accepting replica; fail on teardown.
+
+        timeout bounds polling and each HTTP request's timeout budget. Network
+        errors propagate; no hidden retry or replay of a creation request occurs.
+        """
+        _positive(timeout, "timeout")
+        _positive(poll_interval, "poll_interval")
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(
+                    f"Endpoint {endpoint_id} was not ready within {timeout} seconds."
+                )
+            endpoint = self.get(endpoint_id, timeout=min(remaining, self._control._timeout))
+            if _ready(endpoint):
+                return endpoint
+            remaining = deadline - time.monotonic()
+            if remaining > 0:
+                time.sleep(min(poll_interval, remaining))
+
+
+class AsyncControl:
+    """Platform root configuration plus catalog, organizations and endpoints."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        _positive(timeout, "timeout")
+        self.base_url = _config.platform_url(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.endpoints = AsyncEndpoints(self)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Object | None = None,
+        params: Mapping[str, str] | None = None,
+        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,
+        )
+        return _decode(response)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    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()
+
+
+class AsyncCatalog:
+    def __init__(self, control: AsyncControl) -> None:
+        self._control = control
+
+    async def models(self) -> list[Object]:
+        return _objects(await self._control.request("GET", "catalog/models"))
+
+    async def skus(self, *, provider: str) -> JsonValue:
+        return await self._control.request("GET", "catalog/skus", params={"provider": provider})
+
+
+class AsyncOrganizations:
+    def __init__(self, control: AsyncControl) -> None:
+        self._control = control
+
+    async def list(self) -> list[Object]:
+        return _objects(await self._control.request("GET", "organizations"))
+
+    async def get(self, organization_id: str) -> Object:
+        return _object(
+            await self._control.request("GET", f"organizations/{_segment(organization_id)}")
+        )
+
+    async def limits(self, organization_id: str) -> Object:
+        """Return quota policy, current usage, and any pending increase request."""
+        return _object(
+            await self._control.request("GET", f"organizations/{_segment(organization_id)}/limits")
+        )
+
+
+class AsyncEndpoints:
+    def __init__(self, control: AsyncControl) -> None:
+        self._control = control
+
+    async def list(self, *, workspace_id: str) -> list[Object]:
+        return _objects(
+            await self._control.request("GET", "endpoints", params={"workspace_id": workspace_id})
+        )
+
+    async def get(self, endpoint_id: str, *, timeout: float | None = None) -> Object:
+        return _object(
+            await self._control.request(
+                "GET", f"endpoints/{_segment(endpoint_id)}", timeout=timeout
+            )
+        )
+
+    async def create(
+        self,
+        *,
+        workspace_id: str,
+        model_slug: str,
+        name: str,
+        sku: Object,
+        cloud_connection_id: str | None = None,
+    ) -> Object:
+        """Persist launch intent; use wait_until_ready to observe provisioning."""
+        body: Object = {
+            "workspace_id": workspace_id,
+            "model_slug": model_slug,
+            "name": name,
+            "sku": sku,
+        }
+        if cloud_connection_id is not None:
+            body["cloud_connection_id"] = cloud_connection_id
+        return _object(await self._control.request("POST", "endpoints", json=body))
+
+    async def stop(self, endpoint_id: str) -> Object:
+        return _object(
+            await self._control.request("POST", f"endpoints/{_segment(endpoint_id)}/stop")
+        )
+
+    async def delete(self, endpoint_id: str) -> None:
+        await self._control.request("DELETE", f"endpoints/{_segment(endpoint_id)}")
+
+    async def management(self, endpoint_id: str) -> Object:
+        return _object(
+            await self._control.request("GET", f"endpoints/{_segment(endpoint_id)}/management")
+        )
+
+    async def update_scaling(
+        self, endpoint_id: str, *, expected_generation: int, policy: Object
+    ) -> JsonValue:
+        return await self._control.request(
+            "PATCH",
+            f"endpoints/{_segment(endpoint_id)}/scaling",
+            json={"expected_generation": expected_generation, "policy": policy},
+        )
+
+    async def update_routing(
+        self, endpoint_id: str, *, expected_generation: int, policy: Object
+    ) -> JsonValue:
+        return await self._control.request(
+            "PATCH",
+            f"endpoints/{_segment(endpoint_id)}/routing",
+            json={"expected_generation": expected_generation, "policy": policy},
+        )
+
+    async def wait_until_ready(
+        self,
+        endpoint_id: str,
+        *,
+        timeout: float = 600,
+        poll_interval: float = 2,
+    ) -> Object:
+        """Wait for a running endpoint with an accepting replica; fail on teardown.
+
+        timeout bounds polling and each HTTP request's timeout budget. Network
+        errors propagate; no hidden retry or replay of a creation request occurs.
+        """
+        _positive(timeout, "timeout")
+        _positive(poll_interval, "poll_interval")
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError(
+                    f"Endpoint {endpoint_id} was not ready within {timeout} seconds."
+                )
+            endpoint = await self.get(endpoint_id, timeout=min(remaining, self._control._timeout))
+            if _ready(endpoint):
+                return endpoint
+            remaining = deadline - time.monotonic()
+            if remaining > 0:
+                await asyncio.sleep(min(poll_interval, remaining))

avartha/conversational_ai/__init__.py

@@ -0,0 +1,19 @@
+"""ElevenLabs-compatible conversation runtime and client tool registration."""
+
+from .conversation import (
+    AsyncAudioInterface,
+    AsyncConversation,
+    AudioInterface,
+    ClientTools,
+    Conversation,
+    ConversationInitiationData,
+)
+
+__all__ = [
+    "AsyncAudioInterface",
+    "AsyncConversation",
+    "AudioInterface",
+    "ClientTools",
+    "Conversation",
+    "ConversationInitiationData",
+]

avartha/conversational_ai/conversation.py

@@ -0,0 +1,19 @@
+"""Use the upstream conversation runtime without changing its protocol."""
+
+from elevenlabs.conversational_ai.conversation import (
+    AsyncAudioInterface,
+    AsyncConversation,
+    AudioInterface,
+    ClientTools,
+    Conversation,
+    ConversationInitiationData,
+)
+
+__all__ = [
+    "AsyncAudioInterface",
+    "AsyncConversation",
+    "AudioInterface",
+    "ClientTools",
+    "Conversation",
+    "ConversationInitiationData",
+]

avartha/conversational_ai/default_audio_interface.py

@@ -0,0 +1,5 @@
+"""Optional microphone/speaker support; install avartha-python-sdk[audio]."""
+
+from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
+
+__all__ = ["DefaultAudioInterface"]

avartha/elevenlabs.py

@@ -0,0 +1,120 @@
+"""ElevenLabs clients configured for Avartha inference.
+
+All generated resources and wire types are upstream objects. A supplied HTTP
+client remains caller-owned; close() only closes a client created here.
+
+Realtime TTS is the exception, so the sync constructor replaces `_text_to_speech`
+with the corrected client from `_realtime_tts`: upstream's helper sends an
+envelope the gateway refuses. That assignment is the only private-attribute
+access here besides the `_ws_base_url` upstream pins to wss even for
+http://localhost.
+"""
+
+from types import TracebackType
+from typing import Any, Self, cast
+
+import httpx
+from elevenlabs.client import AsyncElevenLabs as _AsyncElevenLabs
+from elevenlabs.client import ElevenLabs as _ElevenLabs
+
+from . import _config
+from ._config import Tier
+from ._realtime_tts import AvarthaRealtimeTextToSpeechClient
+
+
+class ElevenLabs(_ElevenLabs):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        tier: Tier = "serverless",
+        headers: dict[str, str] | None = None,
+        timeout: float | None = 240,
+        follow_redirects: bool | None = True,
+        httpx_client: httpx.Client | None = None,
+        **kwargs: Any,
+    ) -> None:
+        key, url = _config.api_key(api_key), _config.elevenlabs_url(base_url, tier=tier)
+        self._owned_http_client = None
+        if httpx_client is None:
+            httpx_client = httpx.Client(timeout=timeout, follow_redirects=bool(follow_redirects))
+            self._owned_http_client = httpx_client
+        super().__init__(
+            api_key=key,
+            base_url=url,
+            headers=headers,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+            httpx_client=httpx_client,
+            **kwargs,
+        )
+        self._text_to_speech = AvarthaRealtimeTextToSpeechClient(
+            client_wrapper=self._client_wrapper
+        )
+        self._text_to_speech._ws_base_url = _config.websocket_url(url)
+
+    @property
+    def text_to_speech(self) -> AvarthaRealtimeTextToSpeechClient:
+        return cast(AvarthaRealtimeTextToSpeechClient, self._text_to_speech)
+
+    def close(self) -> None:
+        if self._owned_http_client is not None:
+            self._owned_http_client.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 AsyncElevenLabs(_AsyncElevenLabs):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        tier: Tier = "serverless",
+        headers: dict[str, str] | None = None,
+        timeout: float | None = 240,
+        follow_redirects: bool | None = True,
+        httpx_client: httpx.AsyncClient | None = None,
+        **kwargs: Any,
+    ) -> None:
+        key, url = _config.api_key(api_key), _config.elevenlabs_url(base_url, tier=tier)
+        self._owned_http_client = None
+        if httpx_client is None:
+            httpx_client = httpx.AsyncClient(
+                timeout=timeout, follow_redirects=bool(follow_redirects)
+            )
+            self._owned_http_client = httpx_client
+        super().__init__(
+            api_key=key,
+            base_url=url,
+            headers=headers,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+            httpx_client=httpx_client,
+            **kwargs,
+        )
+
+    async def close(self) -> None:
+        if self._owned_http_client is not None:
+            await self._owned_http_client.aclose()
+
+    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()

avartha/errors.py

@@ -0,0 +1,35 @@
+"""Platform errors. Inference errors keep their upstream SDK exception classes."""
+
+import httpx
+from pydantic import JsonValue
+
+from ._config import ConfigurationError
+
+
+class PlatformAPIError(Exception):
+    """Non-success platform response, including field-scoped validation errors."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        self.status_code = response.status_code
+        self.request_id = response.headers.get("x-request-id")
+        self.retry_after = response.headers.get("retry-after")
+        try:
+            self.body: JsonValue = response.json()
+        except ValueError:
+            self.body = response.text
+        self.field_errors = self.body.get("errors", []) if isinstance(self.body, dict) else []
+        message = self.body.get("error", self.body) if isinstance(self.body, dict) else self.body
+        super().__init__(f"Platform API returned HTTP {self.status_code}: {message}")
+
+
+class EndpointFailedError(Exception):
+    def __init__(self, endpoint: dict[str, JsonValue]) -> None:
+        self.endpoint = endpoint
+        super().__init__(
+            f"Endpoint {endpoint.get('id')} entered {endpoint.get('status')}: "
+            f"{endpoint.get('error')}"
+        )
+
+
+__all__ = ["ConfigurationError", "EndpointFailedError", "PlatformAPIError"]