regent-control 0.1.0__py3-none-any.whl

regent_control/__init__.py

@@ -0,0 +1,85 @@
+"""Regent Control — Python SDK.
+
+Two integration models:
+
+* **Gate-direct** (:class:`RegentControl` / :class:`AsyncRegentControl`): your code
+  authorizes an action, gets a scoped token, performs it, reports the outcome.
+* **Sidecar-routing** (:class:`SidecarSession` / :class:`AsyncSidecarSession`): your
+  code makes its normal HTTP call pointed at the sidecar, which injects the real
+  credential — the agent never holds the provider secret.
+
+A policy ``deny`` is a normal result of :meth:`RegentControl.authorize`; opt into
+raising via ``decision.raise_for_status()`` / ``authorize_or_raise``. The sidecar
+session raises the typed error automatically.
+"""
+
+from __future__ import annotations
+
+from regent_control.client import (
+    DEFAULT_BASE_URL,
+    AsyncRegentControl,
+    RegentControl,
+)
+from regent_control.crypto import derive_agent_secret, hmac_sha256_hex
+from regent_control.decorator import guarded
+from regent_control.errors import (
+    AgentNotActive,
+    ControlDenied,
+    ControlError,
+    ControlNetworkError,
+    Escalated,
+    IdentityNotResolved,
+    MandateExceeded,
+    MandateNotFound,
+    PolicyDenied,
+    DuplicateRequest,
+    RiskThresholdExceeded,
+    VelocityExceeded,
+    ToolNotAllowed,
+)
+from regent_control.sidecar import AsyncSidecarSession, SidecarSession
+from regent_control.types import (
+    CompleteResult,
+    Decision,
+    DecisionCode,
+    Escalation,
+    Obligation,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    # gate-direct
+    "RegentControl",
+    "AsyncRegentControl",
+    # sidecar-routing
+    "SidecarSession",
+    "AsyncSidecarSession",
+    # decorator
+    "guarded",
+    # types
+    "Decision",
+    "DecisionCode",
+    "Obligation",
+    "Escalation",
+    "CompleteResult",
+    # crypto
+    "derive_agent_secret",
+    "hmac_sha256_hex",
+    # errors
+    "ControlError",
+    "ControlNetworkError",
+    "ControlDenied",
+    "IdentityNotResolved",
+    "AgentNotActive",
+    "PolicyDenied",
+    "ToolNotAllowed",
+    "MandateNotFound",
+    "MandateExceeded",
+    "DuplicateRequest",
+    "RiskThresholdExceeded",
+    "VelocityExceeded",
+    "Escalated",
+]

regent_control/_http.py

@@ -0,0 +1,137 @@
+"""Internal HTTP layer (sync + async). Not part of the public surface.
+
+* Bearer API-key auth; optional HMAC-SHA256 body signing (``X-Agent-Signature``).
+* Retries network errors / 429 / 5xx with exponential backoff.
+* A 200 carrying a ``deny`` decision is NOT an error — the JSON is returned and
+  the caller (the client) interprets it. Only transport/auth/validation fail.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, replace
+from typing import Any
+
+import httpx
+
+from regent_control.crypto import hmac_sha256_hex
+from regent_control.errors import ControlError, ControlNetworkError
+
+_RETRYABLE = {429, 500, 502, 503, 504}
+
+
+@dataclass(slots=True)
+class HttpConfig:
+    base_url: str
+    api_key: str
+    agent_secret: str | None = None
+    timeout_seconds: float = 10.0
+    max_retries: int = 2
+
+
+def _headers(cfg: HttpConfig, payload: str, extra: dict[str, str] | None) -> dict[str, str]:
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "Authorization": f"Bearer {cfg.api_key}",
+        "User-Agent": "regent-control-python/0.1.0",
+    }
+    if extra:
+        headers.update(extra)
+    if cfg.agent_secret:
+        sig = hmac_sha256_hex(cfg.agent_secret, payload)
+        headers["X-Agent-Signature"] = f"hmac-sha256={sig}"
+        headers["X-Agent-Signature-Timestamp"] = str(int(time.time()))
+    return headers
+
+
+def _interpret(resp: httpx.Response) -> dict[str, Any] | None:
+    """Return parsed JSON on success, None to signal a retryable status."""
+    if resp.status_code in _RETRYABLE:
+        return None
+    if resp.status_code >= 400:
+        rid = resp.headers.get("x-request-id") or resp.headers.get("x-correlation-id")
+        detail = ""
+        try:
+            detail = resp.json().get("detail") or resp.text
+        except Exception:  # noqa: BLE001
+            detail = resp.text
+        raise ControlError(
+            f"control plane returned {resp.status_code}: {detail}",
+            status_code=resp.status_code,
+            request_id=rid,
+        )
+    return resp.json()
+
+
+def _backoff_seconds(attempt: int) -> float:
+    return min(0.2 * (2**attempt), 2.0)
+
+
+class HttpClient:
+    """Synchronous transport."""
+
+    def __init__(self, cfg: HttpConfig, client: httpx.Client | None = None) -> None:
+        self._cfg = replace(cfg, base_url=cfg.base_url.rstrip("/"))
+        self._client = client or httpx.Client(timeout=self._cfg.timeout_seconds)
+        self._owns = client is None
+
+    def post(self, path: str, body: Any, extra_headers: dict[str, str] | None = None) -> dict[str, Any]:
+        import json as _json
+
+        payload = _json.dumps(body or {}, separators=(",", ":"))
+        url = f"{self._cfg.base_url}{path}"
+        headers = _headers(self._cfg, payload, extra_headers)
+        last_exc: Exception | None = None
+        for attempt in range(self._cfg.max_retries + 1):
+            try:
+                resp = self._client.post(url, content=payload, headers=headers)
+                parsed = _interpret(resp)
+                if parsed is not None:
+                    return parsed
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                last_exc = exc
+            if attempt < self._cfg.max_retries:
+                time.sleep(_backoff_seconds(attempt))
+        if last_exc is not None:
+            raise ControlNetworkError(f"request to {url} failed: {last_exc}", last_exc)
+        raise ControlNetworkError(f"request to {url} exhausted retries")
+
+    def close(self) -> None:
+        if self._owns:
+            self._client.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous transport (same behavior as :class:`HttpClient`)."""
+
+    def __init__(self, cfg: HttpConfig, client: httpx.AsyncClient | None = None) -> None:
+        self._cfg = replace(cfg, base_url=cfg.base_url.rstrip("/"))
+        self._client = client or httpx.AsyncClient(timeout=self._cfg.timeout_seconds)
+        self._owns = client is None
+
+    async def post(self, path: str, body: Any, extra_headers: dict[str, str] | None = None) -> dict[str, Any]:
+        import json as _json
+
+        payload = _json.dumps(body or {}, separators=(",", ":"))
+        url = f"{self._cfg.base_url}{path}"
+        headers = _headers(self._cfg, payload, extra_headers)
+        last_exc: Exception | None = None
+        for attempt in range(self._cfg.max_retries + 1):
+            try:
+                resp = await self._client.post(url, content=payload, headers=headers)
+                parsed = _interpret(resp)
+                if parsed is not None:
+                    return parsed
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                last_exc = exc
+            if attempt < self._cfg.max_retries:
+                await asyncio.sleep(_backoff_seconds(attempt))
+        if last_exc is not None:
+            raise ControlNetworkError(f"request to {url} failed: {last_exc}", last_exc)
+        raise ControlNetworkError(f"request to {url} exhausted retries")
+
+    async def aclose(self) -> None:
+        if self._owns:
+            await self._client.aclose()

regent_control/client.py

@@ -0,0 +1,261 @@
+"""Gate-direct clients — :class:`RegentControl` (sync) and :class:`AsyncRegentControl`.
+
+This is the "wrap-and-gate" model: your code asks the Decision API to authorize a
+proposed action, gets an ``allow`` with a short-lived scoped token, performs the
+action attaching that token, then reports the outcome with :meth:`complete`.
+
+For the "no key in the agent" model where the sidecar injects the real credential,
+use :class:`regent_control.sidecar.SidecarSession` instead.
+
+    control = RegentControl(api_key=KEY, agent_id="agent_42")
+    d = control.authorize("stripe", "refund.create",
+                          amount_usd=50, mandate_id="mnd_1",
+                          user_token=rep_id_token, intent="refund duplicate charge",
+                          facts={"account_status": "active", "refund_to_original": True})
+    if not d.allowed:
+        ...                              # d.code / d.reason — handle deny/escalate
+    do_refund(scoped_token=d.token)      # the token authorizes the downstream call
+    control.complete(d.decision_id, status="success", downstream_ref=refund_id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from regent_control._http import AsyncHttpClient, HttpClient, HttpConfig
+from regent_control.crypto import derive_agent_secret
+from regent_control.types import CompleteResult, CompleteStatus, Decision
+
+DEFAULT_BASE_URL = "https://api.regentprotocol.org"
+
+_DECISIONS = "/v1/control/decisions"
+
+
+def _build_request(
+    agent_id: str,
+    tool: str,
+    action: str,
+    resource: str | None,
+    args: dict[str, Any] | None,
+    context: dict[str, Any] | None,
+    *,
+    amount_usd: float | None,
+    mandate_id: str | None,
+    idempotency_key: str | None,
+    user_token: str | None,
+    intent: str | None,
+    reasoning_summary: str | None,
+    task: str | None,
+    session_id: str | None,
+    user_ref: str | None,
+    op: str | None,
+    resource_type: str | None,
+    account_status: str | None,
+    refund_to_original: bool | None,
+    facts: dict[str, Any] | None,
+) -> tuple[dict[str, Any], dict[str, str] | None]:
+    ctx: dict[str, Any] = {
+        "session_id": session_id,
+        "user_ref": user_ref,
+        "amount_usd": amount_usd,
+        "mandate_id": mandate_id,
+        "idempotency_key": idempotency_key,
+        "user_token": user_token,
+        "intent": intent,
+        "reasoning_summary": reasoning_summary,
+        "task": task,
+        "op": op,
+        "resource_type": resource_type,
+        "account_status": account_status,
+        "refund_to_original": refund_to_original,
+    }
+    if facts:
+        ctx.update(facts)
+    if context:
+        ctx.update(context)
+    ctx = {k: v for k, v in ctx.items() if v is not None}  # gate has safe defaults
+    body = {
+        "agent_id": agent_id,
+        "tool": tool,
+        "action": action,
+        "resource": resource,
+        "args": args or {},
+        "context": ctx,
+    }
+    headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+    return body, headers
+
+
+class RegentControl:
+    """Synchronous gate-direct client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        agent_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        agent_secret: str | None = None,
+        sign_requests: bool = False,
+        timeout_seconds: float = 10.0,
+        max_retries: int = 2,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._agent_id = agent_id
+        if sign_requests and agent_secret is None:
+            agent_secret = derive_agent_secret(api_key, agent_id)
+        cfg = HttpConfig(
+            base_url=base_url, api_key=api_key, agent_secret=agent_secret,
+            timeout_seconds=timeout_seconds, max_retries=max_retries,
+        )
+        self._http = HttpClient(cfg, client=client)
+
+    @property
+    def agent_id(self) -> str:
+        return self._agent_id
+
+    def authorize(
+        self,
+        tool: str,
+        action: str,
+        *,
+        resource: str | None = None,
+        args: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        amount_usd: float | None = None,
+        mandate_id: str | None = None,
+        idempotency_key: str | None = None,
+        user_token: str | None = None,
+        intent: str | None = None,
+        reasoning_summary: str | None = None,
+        task: str | None = None,
+        session_id: str | None = None,
+        user_ref: str | None = None,
+        op: str | None = None,
+        resource_type: str | None = None,
+        account_status: str | None = None,
+        refund_to_original: bool | None = None,
+        facts: dict[str, Any] | None = None,
+    ) -> Decision:
+        """Authorize a proposed action. Returns allow / deny / escalate (never raises on deny)."""
+        body, headers = _build_request(
+            self._agent_id, tool, action, resource, args, context,
+            amount_usd=amount_usd, mandate_id=mandate_id, idempotency_key=idempotency_key,
+            user_token=user_token, intent=intent, reasoning_summary=reasoning_summary, task=task,
+            session_id=session_id, user_ref=user_ref, op=op, resource_type=resource_type,
+            account_status=account_status, refund_to_original=refund_to_original, facts=facts,
+        )
+        return Decision.from_wire(self._http.post(_DECISIONS, body, headers))
+
+    def authorize_or_raise(self, *args: Any, **kwargs: Any) -> Decision:
+        """Like :meth:`authorize` but raises the typed error unless the verdict is ``allow``."""
+        return self.authorize(*args, **kwargs).raise_for_status()
+
+    def complete(
+        self,
+        decision_id: str,
+        *,
+        status: CompleteStatus,
+        downstream_ref: str | None = None,
+        error: str | None = None,
+    ) -> CompleteResult:
+        """Report the outcome of an authorized action (closes audit, reconciles counters)."""
+        body = {"status": status, "downstream_ref": downstream_ref, "error": error}
+        raw = self._http.post(f"{_DECISIONS}/{decision_id}/complete", body)
+        return CompleteResult.from_wire(raw)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> RegentControl:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncRegentControl:
+    """Asynchronous gate-direct client (mirror of :class:`RegentControl`)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        agent_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        agent_secret: str | None = None,
+        sign_requests: bool = False,
+        timeout_seconds: float = 10.0,
+        max_retries: int = 2,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._agent_id = agent_id
+        if sign_requests and agent_secret is None:
+            agent_secret = derive_agent_secret(api_key, agent_id)
+        cfg = HttpConfig(
+            base_url=base_url, api_key=api_key, agent_secret=agent_secret,
+            timeout_seconds=timeout_seconds, max_retries=max_retries,
+        )
+        self._http = AsyncHttpClient(cfg, client=client)
+
+    @property
+    def agent_id(self) -> str:
+        return self._agent_id
+
+    async def authorize(
+        self,
+        tool: str,
+        action: str,
+        *,
+        resource: str | None = None,
+        args: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        amount_usd: float | None = None,
+        mandate_id: str | None = None,
+        idempotency_key: str | None = None,
+        user_token: str | None = None,
+        intent: str | None = None,
+        reasoning_summary: str | None = None,
+        task: str | None = None,
+        session_id: str | None = None,
+        user_ref: str | None = None,
+        op: str | None = None,
+        resource_type: str | None = None,
+        account_status: str | None = None,
+        refund_to_original: bool | None = None,
+        facts: dict[str, Any] | None = None,
+    ) -> Decision:
+        body, headers = _build_request(
+            self._agent_id, tool, action, resource, args, context,
+            amount_usd=amount_usd, mandate_id=mandate_id, idempotency_key=idempotency_key,
+            user_token=user_token, intent=intent, reasoning_summary=reasoning_summary, task=task,
+            session_id=session_id, user_ref=user_ref, op=op, resource_type=resource_type,
+            account_status=account_status, refund_to_original=refund_to_original, facts=facts,
+        )
+        return Decision.from_wire(await self._http.post(_DECISIONS, body, headers))
+
+    async def authorize_or_raise(self, *args: Any, **kwargs: Any) -> Decision:
+        return (await self.authorize(*args, **kwargs)).raise_for_status()
+
+    async def complete(
+        self,
+        decision_id: str,
+        *,
+        status: CompleteStatus,
+        downstream_ref: str | None = None,
+        error: str | None = None,
+    ) -> CompleteResult:
+        body = {"status": status, "downstream_ref": downstream_ref, "error": error}
+        raw = await self._http.post(f"{_DECISIONS}/{decision_id}/complete", body)
+        return CompleteResult.from_wire(raw)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncRegentControl:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

regent_control/crypto.py

@@ -0,0 +1,21 @@
+"""HMAC helpers — must match the server.
+
+The per-agent signing secret is ``HMAC-SHA256(api_key, agent_id)``; a signed
+request carries ``X-Agent-Signature: hmac-sha256=<hex>`` over the raw JSON body.
+This is identical to ``@regent/control-sdk`` (TypeScript), so an agent can be
+moved between the two with the same credentials.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def hmac_sha256_hex(secret: str, message: str) -> str:
+    return hmac.new(secret.encode("utf-8"), message.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def derive_agent_secret(api_key: str, agent_id: str) -> str:
+    """The per-agent HMAC secret: ``HMAC-SHA256(api_key, agent_id)`` as hex."""
+    return hmac_sha256_hex(api_key, agent_id)

regent_control/decorator.py

@@ -0,0 +1,72 @@
+"""``@guarded`` — wrap a tool function so every call is authorized first.
+
+The decorator authorizes the action before the function runs, raises the typed
+error on a non-allow, optionally injects the scoped token, and reports the outcome
+with ``complete`` (``success`` / ``failed``) when the function returns or raises.
+
+    control = RegentControl(api_key=KEY, agent_id="agent_42")
+
+    @guarded(control, tool="payments", action="refund.create", amount_arg="amount_usd")
+    def issue_refund(*, charge: str, amount_usd: float, scoped_token: str = "") -> str:
+        return provider.refund(charge, amount_usd, token=scoped_token)
+
+    issue_refund(charge="ch_1", amount_usd=50)     # authorized → runs → completed
+    issue_refund(charge="ch_1", amount_usd=999)    # raises MandateExceeded; never runs
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def guarded(
+    control: Any,
+    *,
+    tool: str,
+    action: str,
+    amount_arg: str | None = None,
+    pass_token_as: str | None = "scoped_token",
+    **authz: Any,
+) -> Callable[[F], F]:
+    """Decorator factory. ``control`` is a :class:`~regent_control.client.RegentControl`.
+
+    * ``amount_arg`` — the name of a keyword argument whose value is the action's
+      ``amount_usd`` (so a money action is gated against its mandate).
+    * ``pass_token_as`` — if the wrapped function declares this parameter, the allow
+      token is injected into it. Set to ``None`` to never inject.
+    * ``**authz`` — any other static ``authorize`` kwargs (``mandate_id``, ``op``,
+      ``user_token``, ``intent``, ``facts``, …). Per-call values can be supplied via
+      a ``control_context`` keyword on the call, merged over these.
+    """
+
+    def deco(fn: F) -> F:
+        sig = inspect.signature(fn)
+        wants_token = pass_token_as is not None and pass_token_as in sig.parameters
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            per_call = kwargs.pop("control_context", None) or {}
+            amount = kwargs.get(amount_arg) if amount_arg else None
+            decision = control.authorize(
+                tool, action,
+                amount_usd=amount if isinstance(amount, (int, float)) else None,
+                **{**authz, **per_call},
+            )
+            decision.raise_for_status()  # deny/escalate → typed error; never runs fn
+            if wants_token:
+                kwargs[pass_token_as] = decision.token
+            try:
+                result = fn(*args, **kwargs)
+            except Exception as exc:  # noqa: BLE001 — report then re-raise
+                control.complete(decision.decision_id, status="failed", error=str(exc))
+                raise
+            control.complete(decision.decision_id, status="success")
+            return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return deco