coval-agent-sdk 0.1.0__py3-none-any.whl

coval_agent_sdk/__init__.py

@@ -0,0 +1,29 @@
+"""Connect Python voice agents to Coval over outbound WebSockets."""
+
+from coval_agent_sdk.audio import AudioConnection
+from coval_agent_sdk.client import CovalVoiceClient
+from coval_agent_sdk.config import RunConfig
+from coval_agent_sdk.errors import CovalConnectionError
+from coval_agent_sdk.errors import CovalError
+from coval_agent_sdk.errors import CovalHttpError
+from coval_agent_sdk.errors import CovalTraceError
+from coval_agent_sdk.errors import RunError
+from coval_agent_sdk.results import ConversationResult
+from coval_agent_sdk.results import RunResult
+from coval_agent_sdk.results import TraceResult
+from coval_agent_sdk.telemetry import TraceExporter
+
+__all__ = [
+    "AudioConnection",
+    "ConversationResult",
+    "CovalConnectionError",
+    "CovalError",
+    "CovalHttpError",
+    "CovalTraceError",
+    "CovalVoiceClient",
+    "RunConfig",
+    "RunError",
+    "RunResult",
+    "TraceExporter",
+    "TraceResult",
+]

coval_agent_sdk/_audio.py

@@ -0,0 +1,101 @@
+"""Validate and pace serialized outbound PCM16 audio."""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import time
+
+from websockets.asyncio import client
+
+from coval_agent_sdk import _defaults
+from coval_agent_sdk import errors
+from coval_agent_sdk import results
+
+
+def validate_audio(audio: object) -> None:
+    """Reject invalid or oversized application audio before any wire write.
+
+    Args:
+        audio: PCM16 little-endian mono 16 kHz bytes.
+
+    Raises:
+        errors.CovalError: Audio is malformed or exceeds the 2 MiB limit.
+    """
+    if (
+        not isinstance(audio, bytes)
+        or len(audio) % _defaults.VOICE_SAMPLE_WIDTH_BYTES
+    ):
+        raise errors.CovalError("Audio must be even-length PCM16 bytes.")
+    if len(audio) > _defaults.MAX_SEND_BYTES:
+        raise errors.CovalError(
+            "Audio exceeds the 2 MiB limit; send smaller chunks."
+        )
+
+
+class PcmWriter:
+    """Own output serialization, cross-call pacing, and exact sent counts."""
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._next_send_at = 0.0
+        self.sent_bytes = 0
+
+    async def send(
+        self, websocket: client.ClientConnection, audio: bytes
+    ) -> None:
+        """Send validated chunks while retaining pacing between callers."""
+        async with self._lock:
+            for offset in range(0, len(audio), _defaults.VOICE_CHUNK_BYTES):
+                chunk = audio[offset : offset + _defaults.VOICE_CHUNK_BYTES]
+                await asyncio.sleep(
+                    max(0.0, self._next_send_at - time.monotonic())
+                )
+                await websocket.send(chunk)
+                self.sent_bytes += len(chunk)
+                self._next_send_at = max(
+                    self._next_send_at, time.monotonic()
+                ) + len(chunk) / (
+                    _defaults.VOICE_SAMPLE_RATE_HZ
+                    * _defaults.VOICE_CHANNEL_COUNT
+                    * _defaults.VOICE_SAMPLE_WIDTH_BYTES
+                )
+
+
+class ConnectionState:
+    """Private shared transport state; never exported by the public facade."""
+
+    def __init__(self, simulation_id: str) -> None:
+        self.simulation_id = simulation_id
+        self.websocket: client.ClientConnection | None = None
+        self.writer = PcmWriter()
+        self.input: collections.deque[bytes] = collections.deque()
+        self.buffered_bytes = 0
+        self.input_changed = asyncio.Event()
+        self.receiving = False
+        self.ready = asyncio.Event()
+        self.closed = asyncio.Event()
+        self.error: BaseException | None = None
+        self.completed = False
+        self.received_bytes = 0
+        self.result: results.ConversationResult | None = None
+
+    def feed_audio(self, audio: bytes) -> None:
+        """Bound unread audio without blocking terminal control frames."""
+        if self.buffered_bytes + len(audio) > _defaults.MAX_RECEIVE_BYTES:
+            raise errors.CovalError(
+                "Unread audio exceeded the 64 KiB receive buffer; "
+                "drain receive_audio() promptly into a bounded pipeline."
+            )
+        self.received_bytes += len(audio)
+        self.buffered_bytes += len(audio)
+        if audio:
+            self.input.append(audio)
+            self.input_changed.set()
+
+    def finish(self, error: BaseException | None = None) -> None:
+        """Wake readers and writers without manufacturing success."""
+        if self.error is None:
+            self.error = error
+        self.closed.set()
+        self.input_changed.set()

coval_agent_sdk/_connection.py

@@ -0,0 +1,165 @@
+"""Discover and claim one-use outbound relay connections."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import time
+from urllib import parse
+
+from websockets import exceptions
+from websockets.asyncio import client
+
+from coval_agent_sdk import _defaults
+from coval_agent_sdk import _http
+from coval_agent_sdk import errors
+
+
+@dataclasses.dataclass(frozen=True)
+class ConnectionOffer:
+    """Hold one short-lived, attempt-scoped relay credential.
+
+    Attributes:
+        wss_url: Secure relay WebSocket URL.
+        token: One-use credential, sent only in the upgrade header.
+        expires_at: Expiry as Unix epoch seconds.
+    """
+
+    wss_url: str
+    token: str
+    expires_at: float
+
+
+async def wait_for_offer(
+    api: _http.CovalApi, simulation_id: str
+) -> ConnectionOffer:
+    """Wait until the worker publishes a reachable relay and one-use token."""
+    deadline = time.monotonic() + _defaults.CONNECT_WAIT_SECONDS
+    path = f"simulations/{parse.quote(simulation_id, safe='')}/connect"
+    while time.monotonic() < deadline:
+        try:
+            connection = await api.get(path)
+        except (
+            errors.CovalHttpError,
+            errors.CovalConnectionError,
+        ) as exception:
+            if (
+                isinstance(exception, errors.CovalHttpError)
+                and exception.status_code
+                not in _defaults.RETRYABLE_HTTP_STATUSES
+            ):
+                raise
+            await asyncio.sleep(_defaults.POLL_INTERVAL_SECONDS)
+            continue
+        status = connection.get("status")
+        if status == "READY":
+            url = connection.get("wss_url")
+            token = connection.get("token")
+            expires_at = connection.get("expires_at")
+            if not isinstance(url, str) or not url.startswith("wss://"):
+                raise errors.CovalError(
+                    f"Simulation {simulation_id} returned "
+                    f"READY without a WSS URL."
+                )
+            if not isinstance(token, str) or not token:
+                raise errors.CovalError(
+                    f"Simulation {simulation_id} returned "
+                    f"READY without a token."
+                )
+            if (
+                not isinstance(expires_at, (int, float))
+                or expires_at <= time.time()
+            ):
+                raise errors.CovalError(
+                    f"Simulation {simulation_id} returned an "
+                    f"expired connection offer."
+                )
+            return ConnectionOffer(
+                wss_url=url, token=token, expires_at=float(expires_at)
+            )
+        if status in _defaults.TERMINAL_CONNECTION_STATUSES:
+            raise errors.CovalError(
+                f"Simulation {simulation_id} ended before connecting: {status}."
+            )
+        # An unattached attempt can expire while the worker prepares its
+        # replacement.
+        if status not in {"PENDING", "PROVISIONING", "EXPIRED"}:
+            raise errors.CovalError(
+                f"Simulation {simulation_id} returned "
+                f"unknown connection status {status!r}."
+            )
+        await asyncio.sleep(_defaults.POLL_INTERVAL_SECONDS)
+    raise errors.CovalError(
+        f"Simulation {simulation_id} did not "
+        f"publish a relay connection within "
+        f"{_defaults.CONNECT_WAIT_SECONDS} "
+        f"seconds."
+    )
+
+
+async def open_voice_connection(
+    api: _http.CovalApi, simulation_id: str
+) -> client.ClientConnection:
+    """Retry a live offer through transient WebSocket handshake failures."""
+    deadline = time.monotonic() + _defaults.CONNECT_WAIT_SECONDS
+    retry_delay_seconds = _defaults.POLL_INTERVAL_SECONDS
+    last_error: Exception | None = None
+    while time.monotonic() < deadline:
+        remaining_seconds = deadline - time.monotonic()
+        try:
+            offer = await asyncio.wait_for(
+                wait_for_offer(api, simulation_id), timeout=remaining_seconds
+            )
+        except asyncio.TimeoutError as exception:
+            raise errors.CovalError(
+                f"Simulation {simulation_id} did not "
+                f"offer a usable relay before its "
+                f"connect deadline."
+            ) from exception
+        while time.time() < offer.expires_at and time.monotonic() < deadline:
+            upgrade_timeout = min(
+                _defaults.HTTP_TIMEOUT_SECONDS,
+                offer.expires_at - time.time(),
+                deadline - time.monotonic(),
+            )
+            if upgrade_timeout <= 0:
+                break
+            try:
+                return await client.connect(
+                    offer.wss_url,
+                    additional_headers={
+                        "Authorization": f"Bearer {offer.token}"
+                    },
+                    open_timeout=upgrade_timeout,
+                    ping_interval=_defaults.WEBSOCKET_PING_INTERVAL_SECONDS,
+                    ping_timeout=_defaults.WEBSOCKET_PING_TIMEOUT_SECONDS,
+                    max_size=_defaults.VOICE_SAMPLE_RATE_HZ
+                    * _defaults.VOICE_SAMPLE_WIDTH_BYTES
+                    * 10,
+                )
+            except (
+                EOFError,
+                OSError,
+                asyncio.TimeoutError,
+                exceptions.WebSocketException,
+            ) as exception:
+                if client.process_exception(exception) is not None:
+                    raise errors.CovalError(
+                        f"Simulation {simulation_id} relay upgrade failed."
+                    ) from exception
+                last_error = exception
+                remaining_seconds = min(
+                    offer.expires_at - time.time(), deadline - time.monotonic()
+                )
+                if remaining_seconds <= 0:
+                    break
+                await asyncio.sleep(min(retry_delay_seconds, remaining_seconds))
+                retry_delay_seconds = min(
+                    retry_delay_seconds * 2, _defaults.CONNECT_RETRY_MAX_SECONDS
+                )
+        retry_delay_seconds = _defaults.POLL_INTERVAL_SECONDS
+    raise errors.CovalError(
+        f"Simulation {simulation_id} could not "
+        f"connect to its voice relay "
+        f"before the deadline."
+    ) from last_error

coval_agent_sdk/_defaults.py

@@ -0,0 +1,33 @@
+"""Internal API, relay, audio, and buffering defaults."""
+
+DEFAULT_API_BASE_URL = "https://api.coval.dev/v1"
+HTTP_TIMEOUT_SECONDS = 15
+POLL_INTERVAL_SECONDS = 2
+CONNECT_WAIT_SECONDS = 300
+CONNECT_RETRY_MAX_SECONDS = 8
+RUN_WAIT_SECONDS = 3_600
+MONITORING_RETRY_SECONDS = 30
+WEBSOCKET_PING_INTERVAL_SECONDS = 20
+WEBSOCKET_PING_TIMEOUT_SECONDS = 20
+VOICE_SAMPLE_RATE_HZ = 16_000
+VOICE_CHANNEL_COUNT = 1
+VOICE_SAMPLE_WIDTH_BYTES = 2
+VOICE_CHUNK_DURATION_SECONDS = 0.02
+VOICE_CHUNK_BYTES = int(
+    VOICE_SAMPLE_RATE_HZ
+    * VOICE_CHANNEL_COUNT
+    * VOICE_SAMPLE_WIDTH_BYTES
+    * VOICE_CHUNK_DURATION_SECONDS
+)
+MAX_SEND_BYTES = 2 * 1024 * 1024
+MAX_RECEIVE_BYTES = 64 * 1024
+CLOSE_CONFIRM_TIMEOUT_SECONDS = 10
+TERMINAL_CONNECTION_STATUSES = frozenset(
+    {"CONNECTED", "CLOSED", "FAILED", "CANCELLED"}
+)
+TERMINAL_RUN_STATUSES = frozenset({"COMPLETED", "FAILED", "CANCELLED"})
+TERMINAL_SIMULATION_STATUSES = TERMINAL_RUN_STATUSES | {"SKIPPED", "DELETED"}
+QUEUED_SIMULATION_STATUSES = frozenset({"PENDING", "IN QUEUE"})
+RETRYABLE_HTTP_STATUSES = frozenset({409, 429, 500, 502, 503, 504})
+
+TRACE_FLUSH_TIMEOUT_MILLISECONDS = 5_000

coval_agent_sdk/_exceptions.py

@@ -0,0 +1,15 @@
+"""Preserve primary exceptions while retaining secondary cleanup diagnostics."""
+
+from __future__ import annotations
+
+
+def add_cleanup_note(exception: BaseException, note: str) -> None:
+    """Attach secondary cleanup context where the runtime supports notes.
+
+    Args:
+        exception: Primary failure whose identity must be preserved.
+        note: Diagnostic describing a secondary cleanup failure.
+    """
+    add_note = getattr(exception, "add_note", None)
+    if callable(add_note):
+        add_note(note)

coval_agent_sdk/_http.py

@@ -0,0 +1,196 @@
+"""Private Coval API SDK transport with JSON and protobuf request support."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+from typing import cast
+from urllib import parse
+
+from coval_sdk import api_client
+from coval_sdk import configuration
+from coval_sdk import exceptions
+from urllib3 import exceptions as http_exceptions
+
+from coval_agent_sdk import _defaults
+from coval_agent_sdk import errors
+
+
+class CovalApi:
+    """Private adapter around the Coval API SDK request client."""
+
+    def __init__(
+        self,
+        *,
+        api_base_url: str,
+        api_key: str,
+        workspace_id: str | None = None,
+    ) -> None:
+        """Configure the API root and authentication headers.
+
+        Args:
+            api_base_url: API root including the version path.
+            api_key: Organization API key.
+            workspace_id: Optional workspace selector.
+        """
+        if parse.urlsplit(api_base_url).scheme not in {"http", "https"}:
+            raise ValueError("api_base_url must use http or https.")
+        self.api_base_url = api_base_url.rstrip("/")
+        self.api_key = api_key
+        self.workspace_id = workspace_id
+
+    async def get(
+        self, path: str, *, query: dict[str, str] | None = None
+    ) -> dict[str, Any]:
+        """Fetch an object resource without blocking the audio event loop.
+
+        Args:
+            path: Resource path relative to the configured API root.
+            query: Optional URL query parameters.
+
+        Returns:
+            The decoded JSON object.
+
+        Raises:
+            errors.CovalError: The request fails or returns non-object JSON.
+        """
+        return await asyncio.to_thread(
+            self._request_json, "GET", path, query, None
+        )
+
+    async def post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Post JSON once without automatically retrying mutations.
+
+        Args:
+            path: Resource path relative to the configured API root.
+            payload: JSON object to send.
+
+        Returns:
+            The decoded JSON response object.
+
+        Raises:
+            errors.CovalError: The request fails or returns non-object JSON.
+        """
+        return await asyncio.to_thread(
+            self._request_json, "POST", path, None, payload
+        )
+
+    def post_protobuf(
+        self, path: str, payload: bytes, *, headers: dict[str, str]
+    ) -> None:
+        """Post protobuf once from a worker thread, releasing request resources.
+
+        Args:
+            path: Resource path relative to the configured API root.
+            payload: Encoded protobuf request body.
+            headers: Additional endpoint-specific headers.
+
+        Raises:
+            errors.CovalError: The API rejects or cannot receive the request.
+        """
+        self._request(
+            "POST",
+            path,
+            None,
+            payload,
+            content_type="application/x-protobuf",
+            headers=headers,
+        )
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        query: dict[str, str] | None,
+        payload: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        body = self._request(method, path, query, payload)
+        try:
+            response_payload: object = json.loads(body)
+        except (ValueError, UnicodeError):
+            raise errors.CovalError(
+                f"Coval {method} {path} returned invalid JSON."
+            ) from None
+        if not isinstance(response_payload, dict):
+            raise errors.CovalError(
+                f"Coval {method} {path} returned a non-object JSON response."
+            )
+        return cast(dict[str, Any], response_payload)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        query: dict[str, str] | None,
+        payload: dict[str, Any] | bytes | None,
+        *,
+        content_type: str = "application/json",
+        headers: dict[str, str] | None = None,
+    ) -> bytes:
+        settings = configuration.Configuration(
+            host=self.api_base_url,
+            api_key={"Coval_Agents_API_ApiKeyAuth": self.api_key},
+            retries=0,
+        )
+        # The generated client leaves request/response members untyped. Keep
+        # that dynamic boundary here and validate JSON before returning it.
+        sdk: Any = api_client.ApiClient(settings)
+        request_headers = dict(headers or {})
+        request_headers.update(
+            {
+                "Accept": "application/json",
+                "Content-Type": content_type,
+            }
+        )
+        if self.workspace_id is not None:
+            request_headers["X-Coval-Workspace-Id"] = self.workspace_id
+        try:
+            # Discovery is not in the generated endpoint set. Keep request
+            # serialization and transport in the API SDK; models stay private.
+            parameters = sdk.param_serialize(
+                method=method,
+                resource_path=f"/{path.lstrip('/')}",
+                query_params=list((query or {}).items()),
+                header_params=request_headers,
+                body=payload,
+                auth_settings=["Coval_Agents_API_ApiKeyAuth"],
+            )
+            response = sdk.call_api(
+                *parameters,
+                _request_timeout=_defaults.HTTP_TIMEOUT_SECONDS,
+            )
+            try:
+                body = response.read()
+                if not 200 <= response.status <= 299:
+                    detail = body[:500].decode("utf-8", errors="replace")
+                    raise errors.CovalHttpError(
+                        status_code=response.status,
+                        message=(
+                            f"Coval {method} {path} returned HTTP "
+                            f"{response.status}: {detail}"
+                        ),
+                    )
+                return cast(bytes, body)
+            finally:
+                response.response.close()
+                response.response.release_conn()
+        except exceptions.ApiException as exception:
+            status: object = cast(Any, exception).status
+            if isinstance(status, int) and status != 0:
+                raise errors.CovalHttpError(
+                    status_code=status,
+                    message=(f"Coval {method} {path} returned HTTP {status}."),
+                ) from None
+            raise errors.CovalConnectionError(
+                f"Coval {method} {path} could not reach the API."
+            ) from None
+        except (http_exceptions.HTTPError, OSError) as exception:
+            raise errors.CovalConnectionError(
+                f"Coval {method} {path} could not reach the API: "
+                f"{type(exception).__name__}."
+            ) from None
+        finally:
+            # A cancelled coroutine cannot stop its blocking worker. The worker
+            # retains ownership and releases its pool after the bounded request.
+            sdk.rest_client.pool_manager.clear()