agentrust-py 0.0.1a1__py3-none-any.whl

agentrust_sdk/adapters/autogen.py

@@ -0,0 +1,235 @@
+"""
+AutoGen adapter — AgentTrust governance for Microsoft AutoGen agents.
+
+Architecture doc (two-pager): "Connects to … AutoGen agents."
+
+Supports both AutoGen v0.2 (pyautogen) and AutoGen v0.4 (autogen-agentchat):
+
+Pattern 1 — AgentTrustReplyHook (v0.2 + v0.4):
+  Attach to any ConversableAgent / AssistantAgent to validate every reply
+  before it is sent.
+
+Pattern 2 — AgentTrustGroupChatMonitor (v0.2 GroupChat):
+  Wraps a GroupChat's speaker-selection to validate messages between agents.
+
+Usage::
+
+    from autogen import AssistantAgent
+    from agentrust_sdk.adapters.autogen import AgentTrustReplyHook
+
+    hook = AgentTrustReplyHook(agent_id="research-team")
+    assistant = AssistantAgent("researcher", llm_config={...})
+    hook.attach(assistant)
+
+Requires Team tier.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+def _check_tier(api_key: str | None = None) -> None:
+    from agentrust_sdk.auth import resolve_key
+    from agentrust_sdk.tiers import Capability, is_allowed
+    info = resolve_key(api_key)
+    if not is_allowed(Capability.CREWAI_ADAPTER, info.tier):
+        raise RuntimeError("[AgentTrust] AutoGen adapter requires Team tier or higher.")
+
+
+def _validate_sync(
+    agent_id: str,
+    base_url: str,
+    api_key: str | None,
+    user: str,
+    input_text: str,
+    output: dict,
+    framework: str,
+    block_on_block: bool,
+) -> None:
+    from agentrust_sdk.client import AgentTrustClient
+    from agentrust_sdk.decorator import _check_decision, BlockedError
+
+    try:
+        with AgentTrustClient(base_url=base_url, api_key=api_key) as client:
+            resp = client.validate(
+                agent_id=agent_id,
+                user=user,
+                input=input_text,
+                output=output,
+                framework=framework,
+            )
+        _check_decision(resp, block_on_block, False)
+    except BlockedError:
+        raise
+    except Exception as exc:
+        logger.warning("[AgentTrust] AutoGen validate failed (non-fatal): %s", exc)
+
+
+class AgentTrustReplyHook:
+    """
+    Reply hook that validates every AutoGen agent reply via AgentTrust.
+
+    Compatible with AutoGen v0.2 (pyautogen) reply_func mechanism and
+    AutoGen v0.4 (autogen-agentchat) message hook pattern.
+
+    Usage (v0.2)::
+
+        hook = AgentTrustReplyHook(agent_id="my-autogen")
+        assistant = AssistantAgent("researcher", llm_config={...})
+        hook.attach(assistant)
+
+    Usage (v0.4)::
+
+        hook = AgentTrustReplyHook(agent_id="my-autogen")
+        agent = AssistantAgent("researcher", model_client=..., tools=[...])
+        hook.attach_v4(agent)
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        user: str = "autogen",
+        block_on_block: bool = True,
+        framework: str = "AutoGen",
+    ) -> None:
+        _check_tier(api_key)
+        self._agent_id = agent_id
+        self._base_url = base_url
+        self._api_key = api_key
+        self._user = user
+        self._block_on_block = block_on_block
+        self._framework = framework
+
+    # ------------------------------------------------------------------
+    # AutoGen v0.2
+    # ------------------------------------------------------------------
+
+    def _reply_func(
+        self,
+        recipient: Any,
+        messages: list[dict] | None = None,
+        sender: Any = None,
+        config: Any = None,
+    ) -> tuple[bool, str | None]:
+        """AutoGen v0.2 reply function — registered via register_reply()."""
+        if not messages:
+            return False, None
+
+        last = messages[-1]
+        content = last.get("content", "") or ""
+        role = last.get("role", "assistant")
+
+        if role not in ("assistant", "user"):
+            return False, None
+
+        t0 = time.perf_counter()
+        output = {"content": content[:4000], "role": role}
+        _validate_sync(
+            self._agent_id, self._base_url, self._api_key,
+            self._user, content[:500], output, self._framework, self._block_on_block,
+        )
+        logger.debug(
+            "[AgentTrust] AutoGen reply validated in %.1f ms", (time.perf_counter() - t0) * 1000
+        )
+        return False, None  # False = don't override reply; None = no replacement content
+
+    def attach(self, agent: Any) -> None:
+        """Attach to an AutoGen v0.2 ConversableAgent / AssistantAgent."""
+        if not hasattr(agent, "register_reply"):
+            raise TypeError(
+                f"Expected a ConversableAgent with register_reply(), got {type(agent).__name__}"
+            )
+        agent.register_reply(
+            trigger=[],
+            reply_func=self._reply_func,
+            position=0,
+            name="agentrust_reply_hook",
+        )
+        logger.info(
+            "[AgentTrust] AutoGen reply hook attached to agent '%s'", getattr(agent, "name", "?")
+        )
+
+    # ------------------------------------------------------------------
+    # AutoGen v0.4
+    # ------------------------------------------------------------------
+
+    def attach_v4(self, agent: Any) -> None:
+        """Attach to an AutoGen v0.4 BaseChatAgent via on_messages hook."""
+        original_on_messages = agent.on_messages
+
+        async def _wrapped_on_messages(messages: Any, cancellation_token: Any = None) -> Any:
+            result = await original_on_messages(messages, cancellation_token)
+            # result is a Response object with a .chat_message attribute
+            content = ""
+            if hasattr(result, "chat_message") and result.chat_message:
+                content = getattr(result.chat_message, "content", "") or ""
+            output = {"content": content[:4000]}
+            _validate_sync(
+                self._agent_id, self._base_url, self._api_key,
+                self._user, content[:500], output, self._framework, self._block_on_block,
+            )
+            return result
+
+        agent.on_messages = _wrapped_on_messages
+        logger.info(
+            "[AgentTrust] AutoGen v0.4 hook attached to agent '%s'",
+            getattr(agent, "name", "?"),
+        )
+
+
+class AgentTrustGroupChatMonitor:
+    """
+    Monitors AutoGen GroupChat messages and validates each speaker's reply.
+
+    Usage::
+
+        from autogen import GroupChat, GroupChatManager
+        from agentrust_sdk.adapters.autogen import AgentTrustGroupChatMonitor
+
+        monitor = AgentTrustGroupChatMonitor(agent_id="planning-crew")
+        groupchat = GroupChat(agents=[...], messages=[])
+        manager = GroupChatManager(groupchat=groupchat)
+        monitor.attach(groupchat)
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        user: str = "autogen-group",
+        block_on_block: bool = False,  # Default False — group chats tolerate review
+        framework: str = "AutoGen-GroupChat",
+    ) -> None:
+        _check_tier(api_key)
+        self._agent_id = agent_id
+        self._base_url = base_url
+        self._api_key = api_key
+        self._user = user
+        self._block_on_block = block_on_block
+        self._framework = framework
+
+    def attach(self, groupchat: Any) -> None:
+        """Patch groupchat.append to intercept every new message."""
+        original_append = groupchat.append
+
+        def _governed_append(message: dict, speaker: Any) -> None:
+            content = message.get("content", "") or ""
+            _validate_sync(
+                self._agent_id, self._base_url, self._api_key,
+                self._user, content[:500],
+                {"content": content[:4000], "speaker": getattr(speaker, "name", str(speaker))},
+                self._framework, self._block_on_block,
+            )
+            original_append(message, speaker)
+
+        groupchat.append = _governed_append
+        logger.info("[AgentTrust] AutoGen GroupChatMonitor attached")

agentrust_sdk/adapters/claude_agents.py

@@ -0,0 +1,225 @@
+"""
+Claude Agents adapter — AgentTrust governance for Anthropic Claude tool-use agents.
+
+Architecture doc (two-pager): "Connects to … Claude Agents."
+
+Intercepts Anthropic API tool-use responses and validates each tool result
+before the agent continues.  Works with both:
+
+  - Direct anthropic.Anthropic() client loops
+  - Claude's tool_use content blocks in messages API responses
+
+Usage::
+
+    from anthropic import Anthropic
+    from agentrust_sdk.adapters.claude_agents import ClaudeAgentGuard
+
+    client = Anthropic()
+    guard = ClaudeAgentGuard(agent_id="invoice-agent")
+
+    # Wrap the anthropic client — all tool_use responses are validated
+    governed_client = guard.wrap_client(client)
+
+    # Or wrap a single agentic loop function
+    @guard.wrap_loop
+    def run_agent(query: str) -> str:
+        ...
+
+Requires Developer tier.
+"""
+from __future__ import annotations
+
+import functools
+import logging
+import time
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _check_tier(api_key: str | None = None) -> None:
+    from agentrust_sdk.auth import resolve_key
+    from agentrust_sdk.tiers import Capability, is_allowed
+    info = resolve_key(api_key)
+    # Reuse CREWAI_ADAPTER capability gate (Team tier) until a dedicated capability exists
+    if not is_allowed(Capability.CREWAI_ADAPTER, info.tier):
+        raise RuntimeError("[AgentTrust] Claude Agents adapter requires Team tier or higher.")
+
+
+def _extract_tool_calls(response: Any) -> list[dict]:
+    """Extract tool_use blocks from an Anthropic Message response."""
+    tool_calls = []
+    content = getattr(response, "content", []) or []
+    for block in content:
+        btype = getattr(block, "type", None)
+        if btype == "tool_use":
+            tool_calls.append({
+                "name": getattr(block, "name", ""),
+                "args": dict(getattr(block, "input", {}) or {}),
+                "id": getattr(block, "id", ""),
+            })
+    return tool_calls
+
+
+def _extract_text(response: Any) -> str:
+    content = getattr(response, "content", []) or []
+    for block in content:
+        if getattr(block, "type", None) == "text":
+            return getattr(block, "text", "")
+    return ""
+
+
+def _validate_response(
+    agent_id: str,
+    base_url: str,
+    api_key: str | None,
+    user: str,
+    input_text: str,
+    response: Any,
+    framework: str,
+    block_on_block: bool,
+) -> None:
+    from agentrust_sdk.client import AgentTrustClient
+    from agentrust_sdk.decorator import _check_decision, BlockedError
+
+    tool_calls = _extract_tool_calls(response)
+    output_text = _extract_text(response)
+    stop_reason = getattr(response, "stop_reason", "")
+    usage = getattr(response, "usage", None)
+    tokens = 0
+    if usage:
+        tokens = getattr(usage, "input_tokens", 0) + getattr(usage, "output_tokens", 0)
+
+    output: dict = {
+        "text": output_text[:2000],
+        "stop_reason": stop_reason,
+        "tool_calls": tool_calls,
+    }
+
+    try:
+        with AgentTrustClient(base_url=base_url, api_key=api_key) as client:
+            resp = client.validate(
+                agent_id=agent_id,
+                user=user,
+                input=input_text[:1000],
+                output=output,
+                framework=framework,
+                tools_called=tool_calls,
+                tokens=tokens,
+            )
+        _check_decision(resp, block_on_block, False)
+    except BlockedError:
+        raise
+    except Exception as exc:
+        logger.warning("[AgentTrust] Claude agent validate failed (non-fatal): %s", exc)
+
+
+class ClaudeAgentGuard:
+    """
+    Wraps Anthropic client messages.create() to validate every response.
+
+    Usage::
+
+        from anthropic import Anthropic
+        from agentrust_sdk.adapters.claude_agents import ClaudeAgentGuard
+
+        guard = ClaudeAgentGuard(agent_id="claims-agent")
+        client = Anthropic()
+        governed = guard.wrap_client(client)
+
+        # Now use `governed` instead of `client`:
+        response = governed.messages.create(
+            model="claude-opus-4-8",
+            max_tokens=1024,
+            tools=[...],
+            messages=[{"role": "user", "content": query}],
+        )
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        user: str = "claude-agent",
+        block_on_block: bool = True,
+        framework: str = "Claude-Agents",
+    ) -> None:
+        _check_tier(api_key)
+        self._agent_id = agent_id
+        self._base_url = base_url
+        self._api_key = api_key
+        self._user = user
+        self._block_on_block = block_on_block
+        self._framework = framework
+
+    def wrap_client(self, client: Any) -> Any:
+        """Return a proxy around *client* that validates every messages.create() call."""
+        guard = self
+
+        class _MessagesProxy:
+            def __init__(self, original: Any) -> None:
+                self._original = original
+
+            def create(self, *args: Any, **kwargs: Any) -> Any:
+                t0 = time.perf_counter()
+                response = self._original.create(*args, **kwargs)
+                latency_ms = (time.perf_counter() - t0) * 1000
+
+                messages = kwargs.get("messages", []) or []
+                last_user = next(
+                    (m.get("content", "") for m in reversed(messages) if m.get("role") == "user"),
+                    "",
+                )
+                input_text = last_user if isinstance(last_user, str) else str(last_user)[:500]
+
+                _validate_response(
+                    guard._agent_id, guard._base_url, guard._api_key,
+                    guard._user, input_text, response,
+                    guard._framework, guard._block_on_block,
+                )
+                return response
+
+        class _ClientProxy:
+            def __init__(self, orig: Any) -> None:
+                self.messages = _MessagesProxy(orig.messages)
+                self._orig = orig
+
+            def __getattr__(self, name: str) -> Any:
+                return getattr(self._orig, name)
+
+        return _ClientProxy(client)
+
+    def wrap_loop(self, fn: Any) -> Any:
+        """Decorator for an agentic loop function — validates the final return value."""
+        guard = self
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            t0 = time.perf_counter()
+            result = fn(*args, **kwargs)
+            latency_ms = (time.perf_counter() - t0) * 1000
+            output = result if isinstance(result, dict) else {"result": str(result)[:2000]}
+            input_text = (args[0] if args else "") or ""
+
+            from agentrust_sdk.client import AgentTrustClient
+            from agentrust_sdk.decorator import _check_decision, BlockedError
+            try:
+                with AgentTrustClient(base_url=guard._base_url, api_key=guard._api_key) as client:
+                    resp = client.validate(
+                        agent_id=guard._agent_id,
+                        user=guard._user,
+                        input=str(input_text)[:500],
+                        output=output,
+                        framework=guard._framework,
+                        latency_ms=latency_ms,
+                    )
+                _check_decision(resp, guard._block_on_block, False)
+            except BlockedError:
+                raise
+            except Exception as exc:
+                logger.warning("[AgentTrust] Claude loop validate failed (non-fatal): %s", exc)
+            return result
+
+        return wrapper

agentrust_sdk/adapters/crewai.py

@@ -0,0 +1,104 @@
+"""
+CrewAI adapter — AgentTrust callback for task execution.
+
+Requires Team tier. Gated at construction time.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+def _check_adapter_tier(api_key: str | None = None) -> None:
+    import os
+    env = os.environ.get("AGENTRUST_ENV", "production").lower()
+    if env in ("development", "dev", "demo", "test") or not api_key:
+        return
+    if not api_key.startswith("at_"):
+        return
+    from agentrust_sdk.auth import resolve_key
+    from agentrust_sdk.tiers import Capability, is_allowed, UPGRADE_MESSAGES
+    info = resolve_key(api_key)
+    if not is_allowed(Capability.CREWAI_ADAPTER, info.tier):
+        msg = UPGRADE_MESSAGES.get(Capability.CREWAI_ADAPTER, "CrewAI adapter requires Team tier.")
+        raise RuntimeError(f"[AgentTrust] {msg}")
+
+
+class AgentTrustCallback:
+    """
+    CrewAI task callback that validates output via AgentTrust.
+
+    Requires Team tier ($149/mo).
+
+    Usage::
+
+        from crewai import Task
+        from agentrust_sdk.adapters.crewai import AgentTrustCallback
+
+        cb = AgentTrustCallback(agent_id="research-crew")
+        task = Task(description="...", callback=cb.on_task_complete)
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        user: str = "crewai",
+        block_on_block: bool = True,
+        block_on_review: bool = False,
+        framework: str = "CrewAI",
+    ) -> None:
+        _check_adapter_tier(api_key)
+        self._agent_id = agent_id
+        self._base_url = base_url
+        self._api_key = api_key
+        self._user = user
+        self._block_on_block = block_on_block
+        self._block_on_review = block_on_review
+        self._framework = framework
+        self._last_result: Any = None
+
+    def on_task_complete(self, output: Any) -> Any:
+        from agentrust_sdk.client import AgentTrustClient
+        from agentrust_sdk.decorator import BlockedError, _check_decision
+
+        raw = output
+        if hasattr(output, "raw"):
+            raw = output.raw
+        payload = raw if isinstance(raw, dict) else {"result": str(raw)}
+
+        try:
+            with AgentTrustClient(base_url=self._base_url, api_key=self._api_key) as client:
+                resp = client.validate(
+                    agent_id=self._agent_id,
+                    user=self._user,
+                    input="crewai-task",
+                    output=payload,
+                    framework=self._framework,
+                )
+            _check_decision(resp, self._block_on_block, self._block_on_review)
+            self._last_result = resp
+        except BlockedError:
+            raise
+        except Exception as exc:
+            logger.warning("[AgentTrust] CrewAI callback failed (non-fatal): %s", exc)
+
+        return output
+
+    def task_callback(self, fn: Callable) -> Callable:
+        import functools
+
+        @functools.wraps(fn)
+        def wrapper(output: Any) -> Any:
+            self.on_task_complete(output)
+            return fn(output)
+
+        return wrapper
+
+    @property
+    def last_result(self) -> Any:
+        return self._last_result

agentrust_sdk/adapters/langgraph.py

@@ -0,0 +1,115 @@
+"""
+LangGraph adapter — AgentTrust validation node.
+
+Requires Team tier. Gated at import-time for clear error messaging.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _check_adapter_tier(api_key: str | None = None) -> None:
+    import os
+    env = os.environ.get("AGENTRUST_ENV", "production").lower()
+    if env in ("development", "dev", "demo", "test") or not api_key:
+        return
+    if not api_key.startswith("at_"):
+        return
+    from agentrust_sdk.auth import resolve_key
+    from agentrust_sdk.tiers import Capability, is_allowed, UPGRADE_MESSAGES
+    info = resolve_key(api_key)
+    if not is_allowed(Capability.LANGGRAPH_ADAPTER, info.tier):
+        msg = UPGRADE_MESSAGES.get(Capability.LANGGRAPH_ADAPTER, "LangGraph adapter requires Team tier.")
+        raise RuntimeError(f"[AgentTrust] {msg}")
+
+
+class AgentTrustNode:
+    """
+    Callable LangGraph node that validates state via AgentTrust.
+
+    Requires Team tier ($149/mo).
+
+    State keys:
+      output_key  → dict output to validate  (default: "output")
+      input_key   → user's request text      (default: "input")
+      user_key    → user identity string      (default: "user")
+
+    Injects ``_agentrust_result`` into the returned state.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        base_url: str = "http://localhost:8000",
+        api_key: str | None = None,
+        output_key: str = "output",
+        input_key: str = "input",
+        user_key: str = "user",
+        block_on_block: bool = True,
+        block_on_review: bool = False,
+        framework: str = "LangGraph",
+    ) -> None:
+        _check_adapter_tier(api_key)
+        self._agent_id = agent_id
+        self._base_url = base_url
+        self._api_key = api_key
+        self._output_key = output_key
+        self._input_key = input_key
+        self._user_key = user_key
+        self._block_on_block = block_on_block
+        self._block_on_review = block_on_review
+        self._framework = framework
+
+    def __call__(self, state: dict[str, Any]) -> dict[str, Any]:
+        from agentrust_sdk.client import AgentTrustClient
+        from agentrust_sdk.decorator import BlockedError, _check_decision
+
+        output = state.get(self._output_key, {})
+        if not isinstance(output, dict):
+            output = {"result": str(output)}
+
+        try:
+            with AgentTrustClient(base_url=self._base_url, api_key=self._api_key) as client:
+                resp = client.validate(
+                    agent_id=self._agent_id,
+                    user=str(state.get(self._user_key, "unknown")),
+                    input=str(state.get(self._input_key, "")),
+                    output=output,
+                    framework=self._framework,
+                )
+            _check_decision(resp, self._block_on_block, self._block_on_review)
+            return {**state, "_agentrust_result": resp.model_dump()}
+        except BlockedError:
+            raise
+        except Exception as exc:
+            logger.warning("[AgentTrust] LangGraph node failed (non-fatal): %s", exc)
+            return state
+
+    async def ainvoke(self, state: dict[str, Any]) -> dict[str, Any]:
+        from agentrust_sdk.client import AsyncAgentTrustClient
+        from agentrust_sdk.decorator import BlockedError, _check_decision
+
+        output = state.get(self._output_key, {})
+        if not isinstance(output, dict):
+            output = {"result": str(output)}
+
+        try:
+            async with AsyncAgentTrustClient(base_url=self._base_url, api_key=self._api_key) as client:
+                resp = await client.validate(
+                    agent_id=self._agent_id,
+                    user=str(state.get(self._user_key, "unknown")),
+                    input=str(state.get(self._input_key, "")),
+                    output=output,
+                    framework=self._framework,
+                )
+            _check_decision(resp, self._block_on_block, self._block_on_review)
+            return {**state, "_agentrust_result": resp.model_dump()}
+        except BlockedError:
+            raise
+        except Exception as exc:
+            logger.warning("[AgentTrust] LangGraph async node failed (non-fatal): %s", exc)
+            return state