opal-agent-sdk 0.1.1__py3-none-any.whl

opal_agent_sdk/__init__.py

@@ -0,0 +1,72 @@
+"""Opal Agent SDK — async Python client for invoking Opal agents.
+
+Public symbols:
+- ``OpalClient`` — the async client
+- ``PATAuth`` — Personal Access Token auth strategy
+- ``OpalEvent`` — discriminated-union event for streams
+- ``OpalError`` (+ typed subclasses) — exception hierarchy
+- ``run`` / ``stream`` — module-level convenience helpers (Phase 6)
+
+See ``docs/tech-spec/agent-framework/agent-sdk/python-sdk.md`` in the opal-app repo.
+"""
+
+from opal_agent_sdk._auth import OpalAuth, PATAuth
+from opal_agent_sdk._config import OpalConfig
+from opal_agent_sdk._convenience import aclose, run, stream
+from opal_agent_sdk._version import __version__
+from opal_agent_sdk.client import OpalClient
+from opal_agent_sdk.errors import (
+    OpalAuthError,
+    OpalConcurrencyError,
+    OpalConnectionError,
+    OpalError,
+    OpalNotFoundError,
+    OpalRateLimitError,
+    OpalReplayMissedError,
+    OpalServerError,
+    OpalUnsupportedError,
+)
+from opal_agent_sdk.types import (
+    PAT,
+    Artifact,
+    CommitInfo,
+    FileAttachment,
+    OpalChatTurn,
+    OpalEvent,
+    OpalRunResult,
+    OpalSpace,
+    OpalStepExecution,
+    OpalWorkflowExecution,
+    TokenUsage,
+)
+
+__all__ = [
+    "PAT",
+    "Artifact",
+    "CommitInfo",
+    "FileAttachment",
+    "OpalAuth",
+    "OpalAuthError",
+    "OpalChatTurn",
+    "OpalClient",
+    "OpalConcurrencyError",
+    "OpalConfig",
+    "OpalConnectionError",
+    "OpalError",
+    "OpalEvent",
+    "OpalNotFoundError",
+    "OpalRateLimitError",
+    "OpalReplayMissedError",
+    "OpalRunResult",
+    "OpalServerError",
+    "OpalSpace",
+    "OpalStepExecution",
+    "OpalUnsupportedError",
+    "OpalWorkflowExecution",
+    "PATAuth",
+    "TokenUsage",
+    "__version__",
+    "aclose",
+    "run",
+    "stream",
+]

opal_agent_sdk/_auth.py

@@ -0,0 +1,53 @@
+"""Authentication strategies.
+
+v1 ships `PATAuth` only. `ClientCredentialsAuth` and `AuthorizationCodeAuth`
+follow in v1.1 with the same `auth=` constructor slot on `OpalClient`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class OpalAuth(Protocol):
+    """Protocol every auth strategy implements.
+
+    `apply()` mutates the headers mapping to add whatever the wire needs
+    (today: an `Authorization: Bearer <token>` header). `bearer_token`
+    exposes the raw token for socket.io handshakes that need it in the
+    `auth` payload rather than a header.
+    """
+
+    @property
+    def bearer_token(self) -> str: ...
+
+    def apply(self, headers: MutableMapping[str, str]) -> None: ...
+
+
+class PATAuth:
+    """Personal Access Token auth — the v1 default.
+
+    The token is opaque to the SDK; identity is resolved per-request by the
+    API Gateway via authz-server introspect. No caching, no refresh — when
+    the PAT is revoked, the next call raises ``OpalAuthError``.
+    """
+
+    __slots__ = ("_token",)
+
+    def __init__(self, token: str) -> None:
+        if not token or not isinstance(token, str):
+            raise ValueError("PATAuth requires a non-empty string token")
+        self._token = token
+
+    @property
+    def bearer_token(self) -> str:
+        return self._token
+
+    def apply(self, headers: MutableMapping[str, str]) -> None:
+        headers["Authorization"] = f"Bearer {self._token}"
+
+    def __repr__(self) -> str:
+        # Never log the token, even via repr().
+        return "PATAuth(token=<redacted>)"

opal_agent_sdk/_config.py

@@ -0,0 +1,64 @@
+"""Client configuration — endpoints, timeouts, retry policy."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from urllib.parse import urlparse, urlunparse
+
+_DEFAULT_BASE_URL = "https://api.opal.optimizely.com"
+
+
+def _derive_ws_url(base_url: str) -> str:
+    """Default WS URL: same host as base_url, http(s) → ws(s)."""
+    parsed = urlparse(base_url)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    return urlunparse((scheme, parsed.netloc, "", "", "", ""))
+
+
+@dataclass(frozen=True)
+class OpalConfig:
+    """Endpoint + timeout + retry configuration for an `OpalClient`.
+
+    `instance_id` is part of the URL path on hypatia endpoints
+    (``/api/v1/{instance_id}/agents/...``). The gateway routes ``/hypatia/api``
+    → ``hypatia:/api`` without rewriting the path, so the SDK is responsible
+    for filling in instance_id. A future improvement (not in v1) is for the
+    SDK to extract it lazily from the PAT JWT's ``instance_id`` claim.
+    """
+
+    base_url: str = _DEFAULT_BASE_URL
+    ws_url: str | None = None
+    instance_id: str | None = None
+    timeout_s: float = 30.0
+    retry_max_attempts: int = 3
+    verify_ssl: bool = True  # Localdev only — do not disable in production
+
+    @property
+    def effective_ws_url(self) -> str:
+        """Resolved WS URL — explicit `ws_url`, else derived from `base_url`."""
+        return self.ws_url if self.ws_url else _derive_ws_url(self.base_url)
+
+    def require_instance_id(self) -> str:
+        """Return ``instance_id`` or raise a clear error if it wasn't supplied."""
+        if not self.instance_id:
+            raise ValueError(
+                "instance_id is required for this call. Either pass "
+                "OpalConfig(instance_id=...) or set the OPAL_INSTANCE_ID "
+                "environment variable."
+            )
+        return self.instance_id
+
+    @classmethod
+    def from_env(cls) -> OpalConfig:
+        """Build a config from `OPAL_BASE_URL` / `OPAL_WS_URL` / `OPAL_INSTANCE_ID` env vars.
+
+        Endpoint vars have defaults; instance_id does not — it stays None and
+        ``require_instance_id()`` raises at call time if the caller never
+        supplied one.
+        """
+        return cls(
+            base_url=os.environ.get("OPAL_BASE_URL", _DEFAULT_BASE_URL),
+            ws_url=os.environ.get("OPAL_WS_URL") or None,
+            instance_id=os.environ.get("OPAL_INSTANCE_ID") or None,
+        )

opal_agent_sdk/_convenience.py

@@ -0,0 +1,118 @@
+"""Module-level convenience: ``from opal_agent_sdk import run, stream``.
+
+Wraps a process-global default :class:`OpalClient` built from environment
+variables on first call. The client is closed at interpreter exit via
+``atexit``. Anthropic-style convenience surface — fine for scripts, not
+recommended for long-lived services (use an explicit client there).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import logging
+import threading
+from collections.abc import AsyncIterator, Mapping
+from typing import Any
+
+from opal_agent_sdk._auth import PATAuth
+from opal_agent_sdk._config import OpalConfig
+from opal_agent_sdk.client import OpalClient
+from opal_agent_sdk.types import OpalEvent, OpalRunResult
+
+logger = logging.getLogger("opal_agent_sdk.convenience")
+
+_default_client: OpalClient | None = None
+_default_client_lock = threading.Lock()
+_atexit_registered = False
+
+
+def _build_default_client() -> OpalClient:
+    """Construct the singleton client from env vars.
+
+    Requires ``OPAL_PAT``; raises ``RuntimeError`` if missing so callers
+    aren't surprised by a delayed auth error on the first request.
+    """
+    import os
+
+    pat = os.environ.get("OPAL_PAT")
+    if not pat:
+        raise RuntimeError(
+            "OPAL_PAT environment variable is not set. The top-level run()/stream() "
+            "helpers require it. For explicit control, construct an OpalClient yourself."
+        )
+    return OpalClient(auth=PATAuth(pat), config=OpalConfig.from_env())
+
+
+def _get_default_client() -> OpalClient:
+    """Thread-safely fetch (or create) the process-global default client."""
+    global _default_client, _atexit_registered
+    with _default_client_lock:
+        if _default_client is None:
+            _default_client = _build_default_client()
+            if not _atexit_registered:
+                atexit.register(_close_default_client_at_exit)
+                _atexit_registered = True
+    return _default_client
+
+
+def _close_default_client_at_exit() -> None:
+    """Best-effort cleanup at interpreter shutdown.
+
+    If the user has their own event loop running (e.g. asyncio.run already
+    returned and the loop is gone, but they didn't aclose() us), call
+    ``asyncio.run(client.aclose())``. If that fails because a loop is still
+    running on this thread, log and bail — the OS will reclaim the
+    connection. Best-effort hygiene, not correctness.
+    """
+    global _default_client
+    client = _default_client
+    if client is None:
+        return
+    try:
+        asyncio.run(client.aclose())
+    except RuntimeError as exc:
+        logger.debug("default client atexit cleanup skipped: %s", exc)
+    _default_client = None
+
+
+async def aclose() -> None:
+    """Explicitly close the process-global default client.
+
+    Long-lived services that built one via ``run()``/``stream()`` should
+    call this at shutdown so resources are released deterministically.
+    """
+    global _default_client
+    with _default_client_lock:
+        client = _default_client
+        _default_client = None
+    if client is not None:
+        await client.aclose()
+
+
+async def run(
+    agent_id: str,
+    *,
+    parameters: Mapping[str, Any] | None = None,
+) -> OpalRunResult:
+    """Top-level convenience: run a specialized agent once using a default client.
+
+    Equivalent to::
+
+        async with OpalClient.from_env() as client:
+            return await client.agents.specialized.run(agent_id=..., parameters=...)
+
+    but the client is reused across calls within the process.
+    """
+    client = _get_default_client()
+    return await client.agents.specialized.run(agent_id, parameters=parameters)
+
+
+def stream(
+    agent_id: str,
+    *,
+    parameters: Mapping[str, Any] | None = None,
+) -> AsyncIterator[OpalEvent]:
+    """Top-level convenience: stream events from a specialized agent execution."""
+    client = _get_default_client()
+    return client.agents.specialized.stream(agent_id, parameters=parameters)

opal_agent_sdk/_http.py

@@ -0,0 +1,320 @@
+"""Internal async HTTP client wrapping httpx.AsyncClient.
+
+Handles auth header injection, X-Request-Id generation, error mapping, and
+retry-on-5xx for idempotent verbs. Not part of the public surface — callers
+use the namespaced APIs on `OpalClient` instead.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from opal_agent_sdk._auth import OpalAuth
+from opal_agent_sdk._config import OpalConfig
+from opal_agent_sdk.errors import (
+    OpalConnectionError,
+    OpalError,
+    OpalRateLimitError,
+    OpalServerError,
+    _http_status_to_error,
+)
+
+logger = logging.getLogger("opal_agent_sdk")
+
+# Methods that are safe to auto-retry on 5xx. POSTs that create resources
+# stay un-retried until server-side request-id dedup ships (see spec §15.6).
+_IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "DELETE"})
+
+
+def _read_request_id(response: httpx.Response) -> str | None:
+    """Pull the gateway's request id back out of the response for support correlation."""
+    value = response.headers.get("x-request-id") or response.headers.get("X-Request-Id")
+    return str(value) if value else None
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    """Parse a Retry-After header. Accepts seconds-as-int (RFC 7231 §7.1.3)."""
+    value = response.headers.get("retry-after") or response.headers.get("Retry-After")
+    if not value:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _raise_for_status(response: httpx.Response, *, body_preview: str | None = None) -> None:
+    """Map a non-2xx response to the right OpalError subclass and raise.
+
+    Body is best-effort decoded for the error message; if the body's already
+    been consumed by a streaming call, callers pass `body_preview` explicitly.
+    """
+    if response.is_success:
+        return
+
+    if body_preview is None:
+        try:
+            body_preview = response.text
+        except Exception:
+            body_preview = "<unreadable response body>"
+
+    cls = _http_status_to_error(response.status_code)
+    request_id = _read_request_id(response)
+    message = f"HTTP {response.status_code} from {response.request.url}: {body_preview[:500]}"
+
+    if cls is OpalRateLimitError:
+        raise OpalRateLimitError(
+            message,
+            status=response.status_code,
+            request_id=request_id,
+            retry_after_seconds=_retry_after_seconds(response),
+        )
+    raise cls(message, status=response.status_code, request_id=request_id)
+
+
+class _HttpClient:
+    """Thin wrapper around httpx.AsyncClient with auth + error mapping + retries.
+
+    Lifecycle: async context manager OR explicit `aclose()`. The client is
+    created lazily on first use so import-time cost stays zero.
+    """
+
+    def __init__(
+        self,
+        auth: OpalAuth,
+        config: OpalConfig,
+        *,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._auth = auth
+        self._config = config
+        self._client: httpx.AsyncClient | None = client
+        self._owns_client = client is None
+        if not config.verify_ssl:
+            logger.warning(
+                "SSL verification is disabled (verify_ssl=False). "
+                "This is intended for local development only — do not use in production."
+            )
+
+    async def __aenter__(self) -> _HttpClient:
+        self._ensure_client()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+            self._client = None
+
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self._config.base_url,
+                timeout=self._config.timeout_s,
+                verify=self._config.verify_ssl,
+            )
+        return self._client
+
+    def _build_headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {"X-Request-Id": str(uuid.uuid4())}
+        if self._config.instance_id:
+            headers["X-Instance-Id"] = self._config.instance_id
+        self._auth.apply(headers)
+        if extra:
+            headers.update(extra)
+        return headers
+
+    async def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Perform a non-streaming request; return parsed JSON.
+
+        Retries idempotent verbs up to `retry_max_attempts` on `OpalServerError`
+        with exponential backoff (1s, 2s, 4s).
+        """
+        return await self._with_retry(
+            method,
+            self._do_request_json,
+            method=method,
+            path=path,
+            params=params,
+            json=json,
+            content=content,
+            headers=headers,
+        )
+
+    async def _do_request_json(
+        self,
+        *,
+        method: str,
+        path: str,
+        params: Mapping[str, Any] | None,
+        json: Any | None,
+        content: bytes | str | None,
+        headers: Mapping[str, str] | None,
+    ) -> Any:
+        client = self._ensure_client()
+        try:
+            response = await client.request(
+                method,
+                path,
+                params=params,
+                json=json,
+                content=content,
+                headers=self._build_headers(headers),
+            )
+        except httpx.ConnectError as exc:
+            raise OpalConnectionError(f"connection error: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise OpalConnectionError(f"timeout: {exc}") from exc
+        except httpx.RequestError as exc:
+            raise OpalConnectionError(f"request error: {exc}") from exc
+
+        _raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    async def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> bytes:
+        """Perform a request and return raw bytes (e.g. canvas content fetches)."""
+        result = await self._with_retry(
+            method,
+            self._do_request_bytes,
+            method=method,
+            path=path,
+            params=params,
+            headers=headers,
+        )
+        assert isinstance(result, bytes)
+        return result
+
+    async def _do_request_bytes(
+        self,
+        *,
+        method: str,
+        path: str,
+        params: Mapping[str, Any] | None,
+        headers: Mapping[str, str] | None,
+    ) -> bytes:
+        client = self._ensure_client()
+        try:
+            response = await client.request(
+                method,
+                path,
+                params=params,
+                headers=self._build_headers(headers),
+            )
+        except httpx.ConnectError as exc:
+            raise OpalConnectionError(f"connection error: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise OpalConnectionError(f"timeout: {exc}") from exc
+        except httpx.RequestError as exc:
+            raise OpalConnectionError(f"request error: {exc}") from exc
+
+        _raise_for_status(response)
+        return response.content
+
+    @asynccontextmanager
+    async def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> AsyncIterator[httpx.Response]:
+        """Open a streaming response (used for SSE).
+
+        Streaming responses are not auto-retried — the caller may have already
+        consumed bytes by the time a downstream error fires.
+        """
+        client = self._ensure_client()
+        try:
+            async with client.stream(
+                method,
+                path,
+                params=params,
+                json=json,
+                content=content,
+                headers=self._build_headers(headers),
+            ) as response:
+                if not response.is_success:
+                    # Body's not consumed yet; eagerly read for the error message.
+                    body = await response.aread()
+                    _raise_for_status(response, body_preview=body.decode(errors="replace"))
+                yield response
+        except httpx.ConnectError as exc:
+            raise OpalConnectionError(f"connection error: {exc}") from exc
+        except httpx.TimeoutException as exc:
+            raise OpalConnectionError(f"timeout: {exc}") from exc
+        except httpx.RequestError as exc:
+            raise OpalConnectionError(f"request error: {exc}") from exc
+
+    async def _with_retry(
+        self,
+        http_method: str,
+        fn: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Retry-on-5xx for idempotent verbs. Otherwise call once.
+
+        `http_method` is the HTTP verb (passed positionally to disambiguate it
+        from the `method=` kwarg already in `kwargs`, which is the same string
+        but flowing to the inner `fn`).
+        """
+        if http_method.upper() not in _IDEMPOTENT_METHODS:
+            return await fn(**kwargs)
+
+        delay = 1.0
+        last_exc: OpalError | None = None
+        for attempt in range(1, self._config.retry_max_attempts + 1):
+            try:
+                return await fn(**kwargs)
+            except OpalServerError as exc:
+                last_exc = exc
+                if attempt == self._config.retry_max_attempts:
+                    raise
+                logger.warning(
+                    "Retrying %s %s after 5xx (attempt %d/%d): %s",
+                    http_method,
+                    kwargs.get("path"),
+                    attempt,
+                    self._config.retry_max_attempts,
+                    exc,
+                )
+                await asyncio.sleep(delay)
+                delay *= 2
+        # Unreachable — loop either returns or raises.
+        assert last_exc is not None
+        raise last_exc