agentrust-py 0.0.4__tar.gz → 0.0.5__tar.gz

{agentrust_py-0.0.4 → agentrust_py-0.0.5}/CHANGELOG.md

@@ -7,6 +7,24 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.0.5] - 2026-10-26
+
+### Added
+- `agentrust_sdk.adapters.langgraph.governed_tools` — every LangGraph tool call is pre-checked before it runs, held for human review on `escalate`, and post-checked; refusals become error `ToolMessage`s. See `docs/framework-adapters/langgraph.md`.
+- `agentrust_sdk.adapters._core.Governor` — the shared pre-check / hold / run / post-check core for framework connectors, with `current_envelope` for the trust chain.
+- `AgentTrustClient.get_resolution()` / `AsyncAgentTrustClient.get_resolution()`, `pre_check(parent_envelope_id=...)`, and `ValidateResponse.review_id`.
+- `AgentTrustNode(on_block="route")` and `AgentTrustNode.as_runnable()`.
+- `EmbeddedGateway(manifests=...)` and `register_manifest()` for the pre-check tool-trust gate.
+
+### Changed
+- `AgentTrustNode` defaults its gateway URL to `SDK_CONFIG.gateway_url` and lets `GatewayUnavailableError` propagate in closed mode.
+- The `langgraph` extra now allows LangGraph 1.x (`>=0.2,<2.0`).
+
+### Fixed
+- The SDK wheel now ships its policy files (`base.yaml`, the financial and medical packs, `default-policy.json`, `profiles/`). Before, an installed SDK — including 0.0.4 from PyPI — ran the embedded gateway on fallback rules because the files were left out of the package. The release workflow now fails if a built wheel cannot find them.
+
+---
+
 ## [Unreleased]
 
 ### Added

{agentrust_py-0.0.4 → agentrust_py-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentrust-py
-Version: 0.0.4
+Version: 0.0.5
 Summary: AgentTrust Edge — Full Governance Platform. Policy Engine + MAD Classifier + HITL + Kill Switch.
 Project-URL: Homepage, https://agentrust.io
 Project-URL: Documentation, https://docs.agentrust.io
@@ -29,6 +29,7 @@ Requires-Dist: crewai<1.0.0,>=0.80.0; extra == 'crewai'
 Provides-Extra: dev
 Requires-Dist: fastapi>=0.137.1; extra == 'dev'
 Requires-Dist: httpx<1.0.0,>=0.27.0; extra == 'dev'
+Requires-Dist: langgraph<2.0.0,>=0.2.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest>=9.1.0; extra == 'dev'
 Requires-Dist: respx>=0.21.0; extra == 'dev'
@@ -47,7 +48,7 @@ Requires-Dist: uvicorn<1.0.0,>=0.29.0; extra == 'full'
 Provides-Extra: langchain
 Requires-Dist: langchain<1.0.0,>=0.2.0; extra == 'langchain'
 Provides-Extra: langgraph
-Requires-Dist: langgraph<1.0.0,>=0.2.0; extra == 'langgraph'
+Requires-Dist: langgraph<2.0.0,>=0.2.0; extra == 'langgraph'
 Provides-Extra: llm
 Requires-Dist: openai<2.0.0,>=1.0.0; extra == 'llm'
 Provides-Extra: openai

{agentrust_py-0.0.4 → agentrust_py-0.0.5}/agentrust_sdk/__init__.py

@@ -41,6 +41,8 @@ from .adapters.mcp import mcp_tool_guard, MCPServerGuard
 from .adapters.autogen import AgentTrustReplyHook, AgentTrustGroupChatMonitor
 from .adapters.claude_agents import ClaudeAgentGuard
 from .adapters.openai_agents import agent_guard as openai_agent_guard, OpenAIAgentsGuard, SwarmGuard
+from .adapters.crewai import AgentTrustCallback
+from .adapters.langgraph import AgentTrustNode
 from .decorator import BlockedError, harness, validate  # validate = alias
 from .tool_tracking import track_tool, timed_tool
 from .embedded import EmbeddedGateway, embed_gateway
@@ -145,4 +147,4 @@ __all__ = [
     "validate",
 ]
 
-__version__ = "0.0.4"
+__version__ = "0.0.5"

agentrust_py-0.0.5/agentrust_sdk/adapters/_core.py

@@ -0,0 +1,372 @@
+"""
+Governor — the shared governance core every framework connector runs on.
+
+A connector (a "binding") only finds the framework's tool-execution and
+output hooks and translates framework objects. Everything else lives here:
+
+    guard_tool(name, args, call)
+        pre-check ─► approve/retry ─► call() ─► post-check ─► Allowed(result)
+                  ─► block          ─► Refused
+                  ─► escalate       ─► hold for the human review
+                                       approved ─► call() ...   else ─► Refused
+                  ─► gateway down   ─► closed: Refused   open/queue: call()
+
+    check_output(input, output)  →  /validate on a final answer
+
+While ``call()`` runs, ``current_envelope`` holds the pre-check envelope id,
+so a governed call made inside it (a tool that runs a sub-agent) sends it as
+``parent_envelope_id`` and the gateway checks the trust chain.
+
+``on_block="refuse"`` returns a ``Refused`` the binding hands back to the
+agent as a tool result, so the agent can replan. ``on_block="raise"`` raises
+``BlockedError`` (or ``GatewayUnavailableError`` in closed mode) instead.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Literal
+
+from .. import client as _client
+from ..client import GatewayUnavailableError
+from ..config import SDK_CONFIG
+from ..decorator import BlockedError
+from ..models import ValidateResponse
+from ..tiers import UPGRADE_MESSAGES, Capability, is_allowed
+
+logger = logging.getLogger(__name__)
+
+# Envelope of the governed call currently running in this context.
+current_envelope: ContextVar[str | None] = ContextVar("agentrust_current_envelope", default=None)
+
+# The no-op response a client returns when the SDK is disabled or the gateway
+# is unreachable in open/queue mode. It is not a real ledger row, so it is
+# never used as a parent and never post-checked.
+_NOOP_ENVELOPE = "disabled"
+
+_PROCEED = {"approve", "retry"}
+_HOLD = {"escalate", "request_evidence"}
+
+OnBlock = Literal["refuse", "raise"]
+
+
+@dataclass(frozen=True)
+class Allowed:
+    """The call ran (or the output passed); *result* is what to hand back."""
+
+    result: Any
+    envelope_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Refused:
+    """The call did not run, or its result is withheld."""
+
+    message: str
+    reason: str
+    envelope_id: str | None = None
+    reason_code: str | None = None
+    outcome: str = "block"
+
+
+def _real_envelope(envelope_id: str | None) -> str | None:
+    return envelope_id if envelope_id and envelope_id != _NOOP_ENVELOPE else None
+
+
+def check_adapter_tier(capability: Capability, api_key: str | None = None) -> None:
+    """Raise RuntimeError when *api_key*'s tier does not include *capability*.
+
+    Skipped in development/demo/test environments, without a key, and for
+    keys that are not AgentTrust ``at_`` keys (e.g. an embedded gateway token).
+    """
+    env = os.environ.get("AGENTRUST_ENV", "production").lower()
+    key = api_key or SDK_CONFIG.api_key
+    if env in ("development", "dev", "demo", "test") or not key or not key.startswith("at_"):
+        return
+    from ..auth import resolve_key
+
+    if not is_allowed(capability, resolve_key(key).tier):
+        msg = UPGRADE_MESSAGES.get(capability, f"{capability.value} is not available on this tier.")
+        raise RuntimeError(f"[AgentTrust] {msg}")
+
+
+class Governor:
+    """Pre-check, hold, run and post-check one agent's tool calls."""
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        framework: str,
+        on_block: OnBlock = "refuse",
+        review_timeout_s: float = 300.0,
+        user: str = "unknown",
+        base_url: str | None = None,
+        api_key: str | None = None,
+        poll_initial_s: float = 1.0,
+        poll_max_s: float = 5.0,
+        client_factory: Callable[[], Any] | None = None,
+        async_client_factory: Callable[[], Any] | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+        asleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+    ) -> None:
+        if on_block not in ("refuse", "raise"):
+            raise ValueError("on_block must be 'refuse' or 'raise'")
+        self.agent_id = agent_id
+        self.framework = framework
+        self.on_block = on_block
+        self.review_timeout_s = review_timeout_s
+        self.user = user
+        self._client_factory = client_factory or (
+            lambda: _client.AgentTrustClient(base_url=base_url, api_key=api_key)
+        )
+        self._async_client_factory = async_client_factory or (
+            lambda: _client.AsyncAgentTrustClient(base_url=base_url, api_key=api_key)
+        )
+        self._poll_initial_s = poll_initial_s
+        self._poll_max_s = poll_max_s
+        self._clock = clock
+        self._sleep = sleep
+        self._asleep = asleep
+
+    # ------------------------------------------------------------------
+    # Tool calls
+    # ------------------------------------------------------------------
+
+    def guard_tool(
+        self, name: str, args: dict[str, Any], call: Callable[[], Any], *, input: str = "",
+    ) -> Allowed | Refused:
+        """Govern one tool call; *call* runs only when the gateway allows it."""
+        if not SDK_CONFIG.enabled:
+            return Allowed(call())
+
+        with self._client_factory() as client:
+            try:
+                pre = client.pre_check(**self._pre_check_kwargs(name, args, input))
+            except GatewayUnavailableError as exc:
+                return self._unavailable(exc)
+
+            outcome = pre.decision.outcome
+            if outcome in _HOLD:
+                held = self._hold(client, pre)
+                if held is not None:
+                    return held
+            elif outcome not in _PROCEED:
+                return self._refuse_decision(pre)
+
+            envelope_id = _real_envelope(pre.envelope_id)
+            t0 = time.perf_counter()
+            token = current_envelope.set(envelope_id) if envelope_id else None
+            try:
+                result = call()
+            finally:
+                if token is not None:
+                    current_envelope.reset(token)
+            if envelope_id is None:
+                return Allowed(result)
+
+            try:
+                post = client.post_check(**self._post_check_kwargs(envelope_id, name, args, result, t0))
+            except GatewayUnavailableError as exc:
+                return self._unavailable(exc)
+            return self._after_post_check(post, result, envelope_id)
+
+    async def aguard_tool(
+        self, name: str, args: dict[str, Any], call: Callable[[], Awaitable[Any]], *, input: str = "",
+    ) -> Allowed | Refused:
+        """Async counterpart of guard_tool; *call* returns an awaitable."""
+        if not SDK_CONFIG.enabled:
+            return Allowed(await call())
+
+        async with self._async_client_factory() as client:
+            try:
+                pre = await client.pre_check(**self._pre_check_kwargs(name, args, input))
+            except GatewayUnavailableError as exc:
+                return self._unavailable(exc)
+
+            outcome = pre.decision.outcome
+            if outcome in _HOLD:
+                held = await self._ahold(client, pre)
+                if held is not None:
+                    return held
+            elif outcome not in _PROCEED:
+                return self._refuse_decision(pre)
+
+            envelope_id = _real_envelope(pre.envelope_id)
+            t0 = time.perf_counter()
+            token = current_envelope.set(envelope_id) if envelope_id else None
+            try:
+                result = await call()
+            finally:
+                if token is not None:
+                    current_envelope.reset(token)
+            if envelope_id is None:
+                return Allowed(result)
+
+            try:
+                post = await client.post_check(
+                    **self._post_check_kwargs(envelope_id, name, args, result, t0)
+                )
+            except GatewayUnavailableError as exc:
+                return self._unavailable(exc)
+            return self._after_post_check(post, result, envelope_id)
+
+    # ------------------------------------------------------------------
+    # Final output
+    # ------------------------------------------------------------------
+
+    def check_output(self, *, input: str, output: dict[str, Any], user: str | None = None) -> Allowed | Refused:
+        """Validate a final answer. ``Allowed.result`` is the ValidateResponse.
+
+        Closed mode lets ``GatewayUnavailableError`` propagate: there is no
+        call to refuse, so the caller must stop.
+        """
+        with self._client_factory() as client:
+            resp = client.validate(**self._validate_kwargs(input, output, user))
+        return self._output_verdict(resp)
+
+    async def acheck_output(
+        self, *, input: str, output: dict[str, Any], user: str | None = None,
+    ) -> Allowed | Refused:
+        async with self._async_client_factory() as client:
+            resp = await client.validate(**self._validate_kwargs(input, output, user))
+        return self._output_verdict(resp)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _pre_check_kwargs(self, name: str, args: dict[str, Any], input: str) -> dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "action": name,
+            "params": args,
+            "user": self.user,
+            "input": input,
+            "framework": self.framework,
+            "parent_envelope_id": current_envelope.get(),
+        }
+
+    @staticmethod
+    def _post_check_kwargs(
+        envelope_id: str, name: str, args: dict[str, Any], result: Any, t0: float,
+    ) -> dict[str, Any]:
+        output = result if isinstance(result, dict) else {"result": str(result)}
+        return {
+            "pre_check_envelope_id": envelope_id,
+            "output": output,
+            "latency_ms": (time.perf_counter() - t0) * 1000,
+            "tools_called": [{"name": name, "arguments": args, "result": result}],
+        }
+
+    def _validate_kwargs(self, input: str, output: dict[str, Any], user: str | None) -> dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "user": user or self.user,
+            "input": input,
+            "output": output,
+            "framework": self.framework,
+            "parent_envelope_id": current_envelope.get(),
+        }
+
+    def _after_post_check(self, post: ValidateResponse, result: Any, envelope_id: str) -> Allowed | Refused:
+        if post.decision.outcome == "block":
+            return self._refuse_decision(post)
+        return Allowed(result, envelope_id)
+
+    def _output_verdict(self, resp: ValidateResponse) -> Allowed | Refused:
+        if resp.decision.outcome == "block":
+            return self._refused(
+                resp.decision.reason, _real_envelope(resp.envelope_id), resp.decision.reason_code,
+                outcome="block", raise_blocked=False,
+            )
+        return Allowed(resp, _real_envelope(resp.envelope_id))
+
+    def _hold(self, client: Any, pre: ValidateResponse) -> Refused | None:
+        """Wait for the review; None means approved (run the call)."""
+        if not pre.review_id:
+            return self._refused_no_review(pre)
+        deadline = self._clock() + self.review_timeout_s
+        interval = self._poll_initial_s
+        while True:
+            status = client.get_resolution(pre.envelope_id)
+            if status.status != "pending":
+                return self._resolved(pre, status)
+            remaining = deadline - self._clock()
+            if remaining <= 0:
+                return self._timed_out(pre)
+            self._sleep(min(interval, remaining))
+            interval = min(interval * 2, self._poll_max_s)
+
+    async def _ahold(self, client: Any, pre: ValidateResponse) -> Refused | None:
+        if not pre.review_id:
+            return self._refused_no_review(pre)
+        deadline = self._clock() + self.review_timeout_s
+        interval = self._poll_initial_s
+        while True:
+            status = await client.get_resolution(pre.envelope_id)
+            if status.status != "pending":
+                return self._resolved(pre, status)
+            remaining = deadline - self._clock()
+            if remaining <= 0:
+                return self._timed_out(pre)
+            await self._asleep(min(interval, remaining))
+            interval = min(interval * 2, self._poll_max_s)
+
+    def _resolved(self, pre: ValidateResponse, status: Any) -> Refused | None:
+        if status.status == "approved":
+            logger.info("[AgentTrust] review approved for envelope %s", pre.envelope_id)
+            return None
+        reason = f"human review {status.status}" + (f": {status.reason}" if status.reason else "")
+        return self._refused(reason, pre.envelope_id, f"review_{status.status}", outcome=pre.decision.outcome)
+
+    def _timed_out(self, pre: ValidateResponse) -> Refused:
+        logger.warning(
+            "[AgentTrust] review %s for envelope %s not decided within %.0fs; denying",
+            pre.review_id, pre.envelope_id, self.review_timeout_s,
+        )
+        return self._refused(
+            f"human review not decided within {self.review_timeout_s:.0f}s",
+            pre.envelope_id, "review_timeout", outcome=pre.decision.outcome,
+        )
+
+    def _refused_no_review(self, pre: ValidateResponse) -> Refused:
+        return self._refused(
+            f"needs human review but no review was opened ({pre.decision.reason})",
+            pre.envelope_id, "review_unavailable", outcome=pre.decision.outcome,
+        )
+
+    def _refuse_decision(self, resp: ValidateResponse) -> Refused:
+        return self._refused(
+            resp.decision.reason, _real_envelope(resp.envelope_id), resp.decision.reason_code,
+            outcome=resp.decision.outcome,
+        )
+
+    def _unavailable(self, exc: GatewayUnavailableError) -> Refused:
+        if self.on_block == "raise":
+            raise exc
+        logger.warning("[AgentTrust] gateway unavailable, refusing (fail-closed): %s", exc)
+        return self._refused(
+            "AgentTrust gateway unavailable and AGENTRUST_FAILURE_MODE=closed",
+            None, "gateway_unavailable", raise_blocked=False,
+        )
+
+    def _refused(
+        self, reason: str, envelope_id: str | None, reason_code: str | None,
+        *, outcome: str = "block", raise_blocked: bool = True,
+    ) -> Refused:
+        if raise_blocked and self.on_block == "raise":
+            raise BlockedError(outcome, reason, envelope_id or "")
+        where = f" (envelope {envelope_id})" if envelope_id else ""
+        return Refused(
+            message=f"Blocked by AgentTrust: {reason}{where}",
+            reason=reason,
+            envelope_id=envelope_id,
+            reason_code=reason_code,
+            outcome=outcome,
+        )

{agentrust_py-0.0.4 → agentrust_py-0.0.5}/agentrust_sdk/adapters/autogen.py

@@ -207,7 +207,7 @@ class AgentTrustGroupChatMonitor:
         api_key: str | None = None,
         user: str = "autogen-group",
         block_on_block: bool = False,  # Default False — group chats tolerate review
-        framework: str = "AutoGen-GroupChat",
+        framework: str = "AutoGen",
     ) -> None:
         _check_tier(api_key)
         self._agent_id = agent_id

{agentrust_py-0.0.4 → agentrust_py-0.0.5}/agentrust_sdk/adapters/claude_agents.py

@@ -25,7 +25,7 @@ Usage::
     def run_agent(query: str) -> str:
         ...
 
-Requires Developer tier.
+Requires Team tier.
 """
 from __future__ import annotations
 
@@ -144,7 +144,7 @@ class ClaudeAgentGuard:
         api_key: str | None = None,
         user: str = "claude-agent",
         block_on_block: bool = True,
-        framework: str = "Claude-Agents",
+        framework: str = "Claude Agents",
     ) -> None:
         _check_tier(api_key)
         self._agent_id = agent_id