openbox-sdk-python 0.2.0__py3-none-any.whl

openbox_core/__init__.py

@@ -0,0 +1,59 @@
+"""OpenBox base SDK — governance core shared by every OpenBox framework SDK.
+
+IMPORT SAFETY: this module exports only pure names (version + errors). It must
+never eagerly import ``client``, ``identity``, ``gate``, ``runtime``, or any
+module that pulls in httpx, cryptography, OTel instrumentation, logging,
+wall-clock time, or random generation. Constrained framework paths (e.g. the
+workflow sandbox) rely on ``import openbox_core`` staying side-effect free —
+enforced by ``tests/test_import_safety.py``.
+
+Heavy entry points are imported explicitly by non-sandbox code:
+
+    from openbox_core.client import EvaluationClient
+    from openbox_core.runtime import OpenBoxRuntime
+"""
+
+from .errors import (
+    ApprovalExpiredError,
+    ApprovalRejectedError,
+    ApprovalTimeoutError,
+    ContractError,
+    GovernanceAPIError,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
+    OpenBoxAuthError,
+    OpenBoxConfigError,
+    OpenBoxError,
+    OpenBoxInsecureURLError,
+    OpenBoxNetworkError,
+    OpenBoxSigningError,
+    extract_governance_error,
+)
+
+# STATIC on purpose — never read via importlib.metadata. A metadata lookup
+# OPENS A FILE; with file instrumentation active (frameworks patch
+# builtins.open/io.open with governed wrappers) that read re-enters
+# governance; eagerly it can deadlock package init as a circular import, and
+# lazily it can recurse unboundedly when a per-request header builder resolves
+# the version. Keep in sync with pyproject.toml on release.
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "OpenBoxError",
+    "ContractError",
+    "OpenBoxConfigError",
+    "OpenBoxAuthError",
+    "OpenBoxNetworkError",
+    "OpenBoxInsecureURLError",
+    "OpenBoxSigningError",
+    "GovernanceBlockedError",
+    "GovernanceHaltError",
+    "GovernanceAPIError",
+    "GuardrailsValidationError",
+    "ApprovalExpiredError",
+    "ApprovalRejectedError",
+    "ApprovalTimeoutError",
+    "extract_governance_error",
+]

openbox_core/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""Framework adapter protocol package."""
+
+__all__: list[str] = []

openbox_core/adapters/base.py

@@ -0,0 +1,123 @@
+"""FrameworkAdapter protocol + the core default adapter.
+
+The adapter is the ONE seam where governance verdicts become framework-native
+effects. There is exactly one path: wrapper -> hook runtime -> adapter.
+Framework SDKs override the callbacks; the default ``CoreAdapter`` raises the
+core error types directly.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from ..contracts.results import EvaluationResult
+from ..errors import (
+    ApprovalExpiredError,
+    ApprovalRejectedError,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+)
+
+if TYPE_CHECKING:
+    from typing import NoReturn
+
+    from ..approvals import ApprovalPoller
+    from ..contracts.context import ActivityContext
+
+__all__ = ["FrameworkAdapter", "CoreAdapter"]
+
+
+@runtime_checkable
+class FrameworkAdapter(Protocol):
+    """Native-enforcement callbacks implemented by framework SDKs."""
+
+    name: str
+
+    async def handle_approval(self, result: EvaluationResult) -> None:
+        """Drive the framework's approval flow for REQUIRE_APPROVAL.
+
+        Return normally when approved; raise the framework's native rejection/
+        expiry error otherwise. Called BEFORE the real operation runs.
+
+        Adapters may ALSO define a plain-sync ``handle_approval_sync(result)``
+        (not part of the required protocol): when present, sync hook paths
+        delegate to it instead of driving the core inline poller. Frameworks
+        with retry-based HITL can raise their native pending error there.
+        """
+        ...
+
+    def raise_lifecycle_blocked(self, result: EvaluationResult) -> NoReturn:
+        """Produce the framework-native effect for a BLOCK/HALT lifecycle verdict."""
+        ...
+
+    def raise_hook_blocked(self, result: EvaluationResult) -> NoReturn:
+        """Produce the framework-native effect for a BLOCK/HALT started-hook
+        verdict. The real operation has NOT run."""
+        ...
+
+    def on_completed_hook_result(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
+        """React to a completed-hook verdict. The operation ALREADY ran —
+        implementations may only affect FUTURE execution (e.g. mark the
+        activity/session blocked); they must never pretend to undo work.
+
+        ``context`` is the span-resolved ActivityContext (may be None). Frameworks
+        that must bridge a completed BLOCK/HALT to native effects on the correct
+        run/activity read the workflow/run/activity keys from it."""
+        ...
+
+
+class CoreAdapter:
+    """Default adapter — raises core error types (framework-agnostic).
+
+    Args:
+        approval_poller: Optional ApprovalPoller enabling a real HITL wait.
+            Without one, REQUIRE_APPROVAL is fail-safe: rejected (the operation
+            does not run) rather than silently allowed.
+    """
+
+    name = "core"
+
+    def __init__(self, approval_poller: ApprovalPoller | None = None):
+        self._poller = approval_poller
+
+    async def handle_approval(self, result: EvaluationResult) -> None:
+        if self._poller is None or not result.approval_id:
+            raise ApprovalRejectedError(
+                "REQUIRE_APPROVAL verdict but no approval flow is configured — "
+                "failing safe (operation not run)"
+            )
+        approval = await self._poller.await_decision(
+            result.raw.get("workflow_id", ""),
+            result.raw.get("run_id", ""),
+            result.raw.get("activity_id", ""),
+        )
+        if approval.allow_shaped:
+            return
+        if approval.expired:
+            raise ApprovalExpiredError(approval.reason or "Approval window expired")
+        raise ApprovalRejectedError(approval.reason or "Approval rejected")
+
+    def raise_lifecycle_blocked(self, result: EvaluationResult) -> NoReturn:
+        self._raise_stop(result)
+
+    def raise_hook_blocked(self, result: EvaluationResult) -> NoReturn:
+        self._raise_stop(result)
+
+    def on_completed_hook_result(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
+        # Completed telemetry never undoes the operation; the runtime records
+        # abort/halt flags for FUTURE execution — nothing to do here.
+        return None
+
+    @staticmethod
+    def _raise_stop(result: EvaluationResult) -> NoReturn:
+        from ..contracts.results import Verdict
+
+        if result.verdict is Verdict.HALT:
+            raise GovernanceHaltError(result.reason or "Halted by governance policy")
+        raise GovernanceBlockedError(
+            result.verdict, result.reason or "Blocked by governance policy"
+        )

openbox_core/approvals.py

@@ -0,0 +1,106 @@
+"""Approval polling orchestration on top of ``EvaluationClient.poll_approval``.
+
+Owns the poll loop (interval/backoff), expiry handling, and timeout budget —
+but imposes NO framework retry strategy: adapters that drive their own
+approval UX call ``client.poll_approval`` directly and skip this module
+entirely.
+
+Terminal semantics:
+- allow-shaped        -> return the ApprovalResult (approved)
+- blocking / expired  -> return the ApprovalResult (caller inspects
+  ``is_blocking()``/``expired``; adapters translate to native errors)
+- budget exhausted    -> raise ApprovalTimeoutError (client-side condition)
+- poll failure (None) -> still pending; keep polling
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from .client import EvaluationClient
+from .contracts.results import ApprovalResult
+from .errors import ApprovalTimeoutError
+
+__all__ = ["ApprovalPoller"]
+
+
+class ApprovalPoller:
+    """Poll until an approval reaches a terminal state.
+
+    Args:
+        client: The EvaluationClient to poll through.
+        poll_interval_seconds: Base delay between polls.
+        max_wait_seconds: Total budget; ``None`` polls indefinitely.
+        backoff_multiplier: Interval growth per attempt (1.0 = constant).
+        max_interval_seconds: Interval ceiling when backing off.
+    """
+
+    def __init__(
+        self,
+        client: EvaluationClient,
+        *,
+        poll_interval_seconds: float = 5.0,
+        max_wait_seconds: float | None = None,
+        backoff_multiplier: float = 1.0,
+        max_interval_seconds: float = 60.0,
+        max_consecutive_failures: int = 60,
+    ):
+        self._client = client
+        self._interval = poll_interval_seconds
+        self._max_wait = max_wait_seconds
+        self._backoff = backoff_multiplier
+        self._max_interval = max_interval_seconds
+        # Genuine PENDING may legitimately wait forever (max_wait bounds it),
+        # but an UNREACHABLE Core must not hang the governed thread
+        # indefinitely: N consecutive poll failures raise ApprovalTimeoutError
+        # (fail-safe: the operation does not run).
+        self._max_consecutive_failures = max_consecutive_failures
+
+    def _next_interval(self, attempt: int) -> float:
+        return min(self._interval * (self._backoff**attempt), self._max_interval)
+
+    def _timed_out(self, started_at: float) -> bool:
+        return self._max_wait is not None and (time.monotonic() - started_at) >= self._max_wait
+
+    @staticmethod
+    def _is_terminal(result: ApprovalResult | None) -> bool:
+        return result is not None and not result.is_pending()
+
+    def wait_for_decision(
+        self, workflow_id: str, run_id: str, activity_id: str
+    ) -> ApprovalResult:
+        """Block until the approval is decided/expired, or the budget runs out."""
+        started_at = time.monotonic()
+        attempt = 0
+        consecutive_failures = 0
+        while True:
+            result = self._client.poll_approval(workflow_id, run_id, activity_id)
+            if self._is_terminal(result):
+                return result  # type: ignore[return-value]
+            consecutive_failures = consecutive_failures + 1 if result is None else 0
+            if consecutive_failures >= self._max_consecutive_failures:
+                raise ApprovalTimeoutError()
+            if self._timed_out(started_at):
+                raise ApprovalTimeoutError(int(self._max_wait * 1000))  # type: ignore[arg-type]
+            time.sleep(self._next_interval(attempt))
+            attempt += 1
+
+    async def await_decision(
+        self, workflow_id: str, run_id: str, activity_id: str
+    ) -> ApprovalResult:
+        """Async :meth:`wait_for_decision`."""
+        started_at = time.monotonic()
+        attempt = 0
+        consecutive_failures = 0
+        while True:
+            result = await self._client.apoll_approval(workflow_id, run_id, activity_id)
+            if self._is_terminal(result):
+                return result  # type: ignore[return-value]
+            consecutive_failures = consecutive_failures + 1 if result is None else 0
+            if consecutive_failures >= self._max_consecutive_failures:
+                raise ApprovalTimeoutError()
+            if self._timed_out(started_at):
+                raise ApprovalTimeoutError(int(self._max_wait * 1000))  # type: ignore[arg-type]
+            await asyncio.sleep(self._next_interval(attempt))
+            attempt += 1

openbox_core/client.py

@@ -0,0 +1,298 @@
+"""Sync + async EvaluationClient for OpenBox Core.
+
+Endpoints:
+    POST /api/v1/governance/evaluate   — lifecycle + hook evaluations
+    POST /api/v1/governance/approval   — HITL approval polling
+    GET  /api/v1/auth/validate         — API key / signing validation
+
+Transport rules:
+- Signed requests send ``content=body_bytes`` — NEVER ``json=`` (client-side
+  re-serialization breaks Core's body-hash verification).
+- ``httpx`` is imported lazily so this module never taints pure import paths.
+- Fail modes apply to NETWORK errors only — contract violations raise before
+  any send (see gate.py) and are never converted to fail-open ALLOWs:
+    * fail_open (default): return allow-shaped ``EvaluationResult`` with
+      ``fallback_used=True`` (callers can tell it apart from a policy ALLOW).
+    * fail_closed: raise ``GovernanceAPIError`` (adapters map to native
+      halt/block behavior).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from .contracts.results import ApprovalResult, EvaluationResult
+from .errors import (
+    GovernanceAPIError,
+    OpenBoxAuthError,
+    OpenBoxNetworkError,
+    map_signing_error,
+)
+from .identity import AgentIdentity, prepare_signed_request
+from .sdk_version import DEFAULT_SDK_ENGINE, DEFAULT_SDK_LANGUAGE
+
+__all__ = [
+    "EVALUATE_PATH",
+    "APPROVAL_PATH",
+    "AUTH_VALIDATE_PATH",
+    "EvaluationClient",
+    "check_expiration",
+]
+
+logger = logging.getLogger(__name__)
+
+EVALUATE_PATH = "/api/v1/governance/evaluate"
+APPROVAL_PATH = "/api/v1/governance/approval"
+AUTH_VALIDATE_PATH = "/api/v1/auth/validate"
+
+
+def check_expiration(data: dict) -> dict:
+    """Set ``expired=True`` if ``approval_expiration_time`` is past.
+
+    Modifies ``data`` in place and returns it. Handles ISO ``Z``, ISO offset,
+    and space-separated DB formats. Parse failures are logged, never raised.
+    """
+    expiration_time_str = data.get("approval_expiration_time")
+    if not expiration_time_str:
+        return data
+    try:
+        normalized = str(expiration_time_str).replace("Z", "+00:00").replace(" ", "T")
+        expiration_time = datetime.fromisoformat(normalized)
+        if expiration_time.tzinfo is None:
+            expiration_time = expiration_time.replace(tzinfo=UTC)
+        if datetime.now(UTC) > expiration_time:
+            data["expired"] = True
+    except (ValueError, TypeError) as e:
+        logger.warning(
+            f"Failed to parse approval_expiration_time '{expiration_time_str}': {e}"
+        )
+    return data
+
+
+def _extract_reason_code(body: bytes | None) -> str | None:
+    """Machine reason code from Core's JSON error body, if present."""
+    import json
+
+    if not body:
+        return None
+    try:
+        data = json.loads(body.decode("utf-8", errors="replace"))
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    code = data.get("reason_code") or data.get("code") or data.get("reason")
+    return code if isinstance(code, str) else None
+
+
+class EvaluationClient:
+    """HTTP client for the OpenBox Core governance API (sync + async).
+
+    Holds persistent ``httpx.Client``/``httpx.AsyncClient`` instances created
+    lazily on first use; call :meth:`close`/:meth:`aclose` on shutdown.
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        *,
+        timeout_seconds: float = 30.0,
+        on_api_error: str = "fail_open",
+        identity: AgentIdentity | None = None,
+        sdk_version: str | None = None,
+        sdk_engine: str = DEFAULT_SDK_ENGINE,
+        sdk_language: str = DEFAULT_SDK_LANGUAGE,
+        transport: Any = None,
+        async_transport: Any = None,
+    ):
+        """Args:
+            api_url: Core base URL (no trailing slash needed).
+            api_key: Bearer API key.
+            timeout_seconds: Per-request timeout.
+            on_api_error: "fail_open" (default) or "fail_closed".
+            identity: Loaded AgentIdentity for signed requests (None = unsigned).
+            sdk_version/sdk_engine/sdk_language: Values used to build
+                X-OpenBox-SDK-Version as openbox-{engine}-{language}-v{version}.
+            transport/async_transport: Optional httpx transports (tests inject
+                ``httpx.MockTransport`` here; production leaves them None).
+        """
+        if on_api_error not in ("fail_open", "fail_closed"):
+            raise ValueError(f"on_api_error must be 'fail_open' or 'fail_closed', got {on_api_error!r}")
+        self._api_url = api_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout_seconds
+        self._on_api_error = on_api_error
+        self._identity = identity
+        self._sdk_version = sdk_version
+        self._sdk_engine = sdk_engine
+        self._sdk_language = sdk_language
+        self._transport = transport
+        self._async_transport = async_transport
+        self._sync_client: Any = None
+        self._async_client: Any = None
+
+    # ── Transport plumbing ────────────────────────────────────────────────
+
+    def _sync(self) -> Any:
+        if self._sync_client is None:
+            import httpx
+
+            self._sync_client = httpx.Client(timeout=self._timeout, transport=self._transport)
+        return self._sync_client
+
+    def _async(self) -> Any:
+        if self._async_client is None:
+            import httpx
+
+            self._async_client = httpx.AsyncClient(
+                timeout=self._timeout, transport=self._async_transport
+            )
+        return self._async_client
+
+    def close(self) -> None:
+        """Close the sync transport (idempotent)."""
+        if self._sync_client is not None:
+            self._sync_client.close()
+            self._sync_client = None
+
+    async def aclose(self) -> None:
+        """Close both transports (idempotent)."""
+        self.close()
+        if self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+
+    def _prepared(self, method: str, path: str, payload: dict | None) -> tuple[str, dict, bytes]:
+        headers, body = prepare_signed_request(
+            method,
+            path,
+            payload,
+            api_key=self._api_key,
+            identity=self._identity,
+            sdk_version=self._sdk_version,
+            sdk_engine=self._sdk_engine,
+            sdk_language=self._sdk_language,
+        )
+        return f"{self._api_url}{path}", headers, body
+
+    # ── Evaluate ──────────────────────────────────────────────────────────
+
+    def evaluate(self, payload: dict) -> EvaluationResult:
+        """POST a governance event; parse the verdict. Never raises on network
+        errors under fail_open — returns a ``fallback_used=True`` ALLOW."""
+        url, headers, body = self._prepared("POST", EVALUATE_PATH, payload)
+        try:
+            response = self._sync().post(url, content=body, headers=headers)
+        except Exception as e:  # network layer
+            return self._network_failure(f"Governance API unreachable: {e}")
+        return self._parse_evaluate_response(response)
+
+    async def aevaluate(self, payload: dict) -> EvaluationResult:
+        """Async :meth:`evaluate`."""
+        url, headers, body = self._prepared("POST", EVALUATE_PATH, payload)
+        try:
+            response = await self._async().post(url, content=body, headers=headers)
+        except Exception as e:
+            return self._network_failure(f"Governance API unreachable: {e}")
+        return self._parse_evaluate_response(response)
+
+    def _parse_evaluate_response(self, response: Any) -> EvaluationResult:
+        if response.status_code >= 400:
+            return self._network_failure(f"Governance API error: HTTP {response.status_code}")
+        try:
+            data = response.json()
+        except Exception as e:
+            return self._network_failure(f"Governance API returned unparseable body: {e}")
+        result = EvaluationResult.from_dict(data)
+        if result.verdict.should_stop():
+            logger.info(f"Governance blocked: {result.reason} (policy: {result.policy_id})")
+        return result
+
+    def _network_failure(self, reason: str) -> EvaluationResult:
+        """Apply the on_api_error policy to a NETWORK failure."""
+        logger.warning(reason)
+        if self._on_api_error == "fail_closed":
+            raise GovernanceAPIError(reason)
+        return EvaluationResult.fallback_allow(reason)
+
+    # ── Approval polling ──────────────────────────────────────────────────
+
+    def poll_approval(self, workflow_id: str, run_id: str, activity_id: str) -> ApprovalResult | None:
+        """Poll HITL approval status once. Returns None on poll failure
+        (callers treat None as still-pending and retry)."""
+        payload = {"workflow_id": workflow_id, "run_id": run_id, "activity_id": activity_id}
+        url, headers, body = self._prepared("POST", APPROVAL_PATH, payload)
+        try:
+            response = self._sync().post(url, content=body, headers=headers)
+        except Exception as e:
+            logger.warning(f"Failed to poll approval status: {e}")
+            return None
+        return self._parse_approval_response(response)
+
+    async def apoll_approval(
+        self, workflow_id: str, run_id: str, activity_id: str
+    ) -> ApprovalResult | None:
+        """Async :meth:`poll_approval`."""
+        payload = {"workflow_id": workflow_id, "run_id": run_id, "activity_id": activity_id}
+        url, headers, body = self._prepared("POST", APPROVAL_PATH, payload)
+        try:
+            response = await self._async().post(url, content=body, headers=headers)
+        except Exception as e:
+            logger.warning(f"Failed to poll approval status: {e}")
+            return None
+        return self._parse_approval_response(response)
+
+    def _parse_approval_response(self, response: Any) -> ApprovalResult | None:
+        if response.status_code != 200:
+            logger.warning(f"Failed to get approval status: HTTP {response.status_code}")
+            return None
+        try:
+            data = response.json()
+        except Exception as e:
+            logger.warning(f"Failed to parse approval response: {e}")
+            return None
+        check_expiration(data)
+        return ApprovalResult.from_dict(data)
+
+    # ── Auth validation ───────────────────────────────────────────────────
+
+    def validate_api_key(self) -> bool:
+        """GET /api/v1/auth/validate (signed when identity is configured).
+
+        Returns True on success. Raises OpenBoxAuthError / OpenBoxSigningError
+        on 401/403, OpenBoxNetworkError on connectivity failure.
+        """
+        url, headers, _ = self._prepared("GET", AUTH_VALIDATE_PATH, None)
+        try:
+            response = self._sync().get(url, headers=headers)
+        except Exception as e:
+            raise OpenBoxNetworkError(f"Cannot reach OpenBox Core at {self._api_url}: {e}") from e
+        return self._parse_auth_response(response)
+
+    async def avalidate_api_key(self) -> bool:
+        """Async :meth:`validate_api_key`."""
+        url, headers, _ = self._prepared("GET", AUTH_VALIDATE_PATH, None)
+        try:
+            response = await self._async().get(url, headers=headers)
+        except Exception as e:
+            raise OpenBoxNetworkError(f"Cannot reach OpenBox Core at {self._api_url}: {e}") from e
+        return self._parse_auth_response(response)
+
+    def _parse_auth_response(self, response: Any) -> bool:
+        if response.status_code == 200:
+            return True
+        if response.status_code in (401, 403):
+            # When signing is enabled, surface Core's machine reason code as an
+            # actionable signing error (signature_invalid, nonce_replayed, ...).
+            reason_code = (
+                _extract_reason_code(response.content) if self._identity is not None else None
+            )
+            if reason_code:
+                raise map_signing_error(reason_code)
+            raise OpenBoxAuthError("Invalid API key. Check your API key at dashboard.openbox.ai")
+        raise OpenBoxNetworkError(
+            f"Cannot reach OpenBox Core at {self._api_url}: HTTP {response.status_code}"
+        )