opal-agent-sdk 0.1.1__tar.gz

opal_agent_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Optimizely, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opal_agent_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: opal-agent-sdk
+Version: 0.1.1
+Summary: Async Python SDK for invoking Opal agents over PAT-authenticated REST and socket.io.
+Author-email: Optimizely <opal-team@optimizely.com>
+License: MIT
+Project-URL: Homepage, https://github.com/optimizely/opal-app
+Project-URL: Documentation, https://github.com/optimizely/opal-app/blob/main/docs/tech-spec/agent-framework/agent-sdk/python-sdk.md
+Project-URL: Source, https://github.com/optimizely/opal-app/tree/main/sdks/agent-sdk/python
+Keywords: opal,agent,sdk,ai,llm,async
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-socketio[asyncio_client]>=5.10
+Requires-Dist: pydantic>=2.6
+Provides-Extra: cli
+Requires-Dist: typer>=0.12; extra == "cli"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: typer>=0.12; extra == "dev"
+Dynamic: license-file
+
+# opal-agent-sdk (Python)
+
+Async Python SDK for invoking Opal agents from external programs over a PAT.
+
+**Tech spec:** [`docs/tech-spec/agent-framework/agent-sdk/python-sdk.md`](../../../docs/tech-spec/agent-framework/agent-sdk/python-sdk.md) in this repo.
+
+## Install
+
+```bash
+pip install opal-agent-sdk            # core
+pip install "opal-agent-sdk[cli]"     # adds the `opal` CLI
+```
+
+Python 3.10+. Async-only.
+
+## Quickstart
+
+```python
+import asyncio
+import os
+from opal_agent_sdk import OpalClient, PATAuth
+
+async def main() -> None:
+    async with OpalClient(auth=PATAuth(os.environ["OPAL_PAT"])) as client:
+        result = await client.agents.specialized.run(
+            agent_id="customer-service-bot",
+            parameters={"query": "Where is order #1234?"},
+        )
+        print(result.output_text)
+
+asyncio.run(main())
+```
+
+See [`examples/`](./examples) for more (one runnable snippet per spec Appendix A entry).
+
+## Status
+
+v0.1 — under active development on branch `opal_app_agent_sdk`. Wire contract pinned to Hypatia's `SdkEventEnvelope` + space-element responses via fixtures in [`tests/contract/`](./tests/contract).
+
+## Development
+
+```bash
+make install        # uv pip install -e ".[dev,cli]"
+make test           # pytest
+make lint           # ruff check
+make format         # ruff format
+make typecheck      # mypy --strict
+make check          # all of the above
+```

opal_agent_sdk-0.1.1/README.md

@@ -0,0 +1,49 @@
+# opal-agent-sdk (Python)
+
+Async Python SDK for invoking Opal agents from external programs over a PAT.
+
+**Tech spec:** [`docs/tech-spec/agent-framework/agent-sdk/python-sdk.md`](../../../docs/tech-spec/agent-framework/agent-sdk/python-sdk.md) in this repo.
+
+## Install
+
+```bash
+pip install opal-agent-sdk            # core
+pip install "opal-agent-sdk[cli]"     # adds the `opal` CLI
+```
+
+Python 3.10+. Async-only.
+
+## Quickstart
+
+```python
+import asyncio
+import os
+from opal_agent_sdk import OpalClient, PATAuth
+
+async def main() -> None:
+    async with OpalClient(auth=PATAuth(os.environ["OPAL_PAT"])) as client:
+        result = await client.agents.specialized.run(
+            agent_id="customer-service-bot",
+            parameters={"query": "Where is order #1234?"},
+        )
+        print(result.output_text)
+
+asyncio.run(main())
+```
+
+See [`examples/`](./examples) for more (one runnable snippet per spec Appendix A entry).
+
+## Status
+
+v0.1 — under active development on branch `opal_app_agent_sdk`. Wire contract pinned to Hypatia's `SdkEventEnvelope` + space-element responses via fixtures in [`tests/contract/`](./tests/contract).
+
+## Development
+
+```bash
+make install        # uv pip install -e ".[dev,cli]"
+make test           # pytest
+make lint           # ruff check
+make format         # ruff format
+make typecheck      # mypy --strict
+make check          # all of the above
+```

opal_agent_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opal-agent-sdk"
+version = "0.1.1"
+description = "Async Python SDK for invoking Opal agents over PAT-authenticated REST and socket.io."
+authors = [{ name = "Optimizely", email = "opal-team@optimizely.com" }]
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["opal", "agent", "sdk", "ai", "llm", "async"]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "python-socketio[asyncio_client]>=5.10",
+    "pydantic>=2.6",
+]
+
+[project.optional-dependencies]
+cli = ["typer>=0.12"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-httpx>=0.30.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.6.0",
+    "mypy>=1.10.0",
+    "typer>=0.12",
+]
+
+[project.scripts]
+opal = "opal_agent_sdk.cli.main:app"
+
+[project.urls]
+"Homepage" = "https://github.com/optimizely/opal-app"
+"Documentation" = "https://github.com/optimizely/opal-app/blob/main/docs/tech-spec/agent-framework/agent-sdk/python-sdk.md"
+"Source" = "https://github.com/optimizely/opal-app/tree/main/sdks/agent-sdk/python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+opal_agent_sdk = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
+ignore = [
+    "B008", # function call in argument defaults — common in typer commands
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+# Tests are mypy-light on purpose — assertions in tests aren't worth strict types.
+exclude = ["tests/", "build/"]
+
+[[tool.mypy.overrides]]
+module = ["socketio.*", "engineio.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers"
+asyncio_mode = "auto"
+markers = [
+    "integration: opt-in tests that hit localdev (require OPAL_INTEGRATION=1)",
+]
+
+[tool.coverage.run]
+source = ["src/opal_agent_sdk"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "\\.\\.\\.",
+]

opal_agent_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opal_agent_sdk-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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)