tollgate 1.0.0__py3-none-any.whl

tollgate/__init__.py

@@ -0,0 +1,66 @@
+from .approvals import (
+    ApprovalOutcome,
+    ApprovalStore,
+    Approver,
+    AsyncQueueApprover,
+    AutoApprover,
+    CliApprover,
+    InMemoryApprovalStore,
+    compute_request_hash,
+)
+from .audit import AuditSink, JsonlAuditSink
+from .exceptions import (
+    TollgateApprovalDenied,
+    TollgateDeferred,
+    TollgateDenied,
+    TollgateError,
+)
+from .helpers import guard, wrap_tool
+from .policy import PolicyEvaluator, YamlPolicyEvaluator
+from .registry import ToolRegistry
+from .tower import ControlTower
+from .types import (
+    AgentContext,
+    AuditEvent,
+    Decision,
+    DecisionType,
+    Effect,
+    Intent,
+    NormalizedToolCall,
+    Outcome,
+    ToolRequest,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ControlTower",
+    "AgentContext",
+    "Intent",
+    "ToolRequest",
+    "NormalizedToolCall",
+    "Decision",
+    "DecisionType",
+    "Effect",
+    "AuditEvent",
+    "Outcome",
+    "ApprovalOutcome",
+    "ApprovalStore",
+    "Approver",
+    "InMemoryApprovalStore",
+    "AsyncQueueApprover",
+    "AutoApprover",
+    "CliApprover",
+    "compute_request_hash",
+    "AuditSink",
+    "JsonlAuditSink",
+    "ToolRegistry",
+    "PolicyEvaluator",
+    "YamlPolicyEvaluator",
+    "TollgateError",
+    "TollgateDenied",
+    "TollgateApprovalDenied",
+    "TollgateDeferred",
+    "wrap_tool",
+    "guard",
+]

tollgate/approvals.py

@@ -0,0 +1,227 @@
+import asyncio
+import hashlib
+import json
+import time
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any, Protocol
+
+from .types import AgentContext, ApprovalOutcome, Effect, Intent, ToolRequest
+
+
+class ApprovalStore(ABC):
+    """Interface for persistent storage of approval requests."""
+
+    @abstractmethod
+    async def create_request(
+        self,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        tool_request: ToolRequest,
+        request_hash: str,
+        reason: str,
+        expiry: float,
+    ) -> str:
+        """Create an approval request and return its ID."""
+        pass
+
+    @abstractmethod
+    async def set_decision(
+        self,
+        approval_id: str,
+        outcome: ApprovalOutcome,
+        decided_by: str,
+        decided_at: float,
+        request_hash: str,
+    ) -> None:
+        """Record a decision for an approval request."""
+        pass
+
+    @abstractmethod
+    async def get_request(self, approval_id: str) -> dict[str, Any] | None:
+        """Load an approval request by ID."""
+        pass
+
+    @abstractmethod
+    async def wait_for_decision(
+        self, approval_id: str, timeout: float
+    ) -> ApprovalOutcome:
+        """Wait for a decision on an approval request."""
+        pass
+
+
+class InMemoryApprovalStore(ApprovalStore):
+    """In-memory approval store with replay protection and expiry."""
+
+    def __init__(self):
+        self._requests: dict[str, dict[str, Any]] = {}
+        self._events: dict[str, asyncio.Event] = {}
+
+    async def create_request(
+        self, agent_ctx, intent, tool_request, request_hash, reason, expiry
+    ) -> str:
+        approval_id = str(uuid.uuid4())
+        self._requests[approval_id] = {
+            "id": approval_id,
+            "agent": agent_ctx.to_dict(),
+            "intent": intent.to_dict(),
+            "tool_request": tool_request.to_dict(),
+            "request_hash": request_hash,
+            "reason": reason,
+            "expiry": expiry,
+            "outcome": ApprovalOutcome.DEFERRED,
+        }
+        self._events[approval_id] = asyncio.Event()
+        return approval_id
+
+    async def set_decision(
+        self, approval_id, outcome, decided_by, decided_at, request_hash
+    ):
+        if approval_id in self._requests:
+            req = self._requests[approval_id]
+            # Replay protection: hash must match
+            if req["request_hash"] != request_hash:
+                raise ValueError(
+                    "Request hash mismatch. Approval bound to a different request."
+                )
+
+            req["outcome"] = outcome
+            req["decided_by"] = decided_by
+            req["decided_at"] = decided_at
+            if approval_id in self._events:
+                self._events[approval_id].set()
+
+    async def get_request(self, approval_id):
+        return self._requests.get(approval_id)
+
+    async def wait_for_decision(self, approval_id, timeout):
+        event = self._events.get(approval_id)
+        if not event:
+            return ApprovalOutcome.TIMEOUT
+
+        req = self._requests.get(approval_id)
+        if req and req["expiry"] < time.time():
+            return ApprovalOutcome.TIMEOUT
+
+        try:
+            await asyncio.wait_for(event.wait(), timeout=timeout)
+            return self._requests[approval_id]["outcome"]
+        except asyncio.TimeoutError:
+            return ApprovalOutcome.TIMEOUT
+
+
+class Approver(Protocol):
+    """Async-first approver protocol."""
+
+    async def request_approval_async(
+        self,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        tool_request: ToolRequest,
+        request_hash: str,
+        reason: str,
+    ) -> ApprovalOutcome:
+        """Request approval from a human or another system."""
+        ...
+
+
+class AsyncQueueApprover:
+    """An approver that queues requests in a store and waits for a decision."""
+
+    def __init__(
+        self,
+        store: ApprovalStore,
+        timeout: float = 3600.0,
+        default_outcome: ApprovalOutcome = ApprovalOutcome.DENIED,
+    ):
+        self.store = store
+        self.timeout = timeout
+        self.default_outcome = default_outcome
+
+    async def request_approval_async(
+        self, agent_ctx, intent, tool_request, request_hash, reason
+    ) -> ApprovalOutcome:
+        expiry = time.time() + self.timeout
+        approval_id = await self.store.create_request(
+            agent_ctx, intent, tool_request, request_hash, reason, expiry
+        )
+
+        outcome = await self.store.wait_for_decision(approval_id, self.timeout)
+        if outcome == ApprovalOutcome.TIMEOUT:
+            return self.default_outcome
+        return outcome
+
+
+class AutoApprover:
+    """Non-interactive approver for tests and examples."""
+
+    async def request_approval_async(
+        self,
+        _agent_ctx: AgentContext,
+        _intent: Intent,
+        tool_request: ToolRequest,
+        _request_hash: str,
+        _reason: str,
+    ) -> ApprovalOutcome:
+        # Decision: approve ASK only when tool_request.effect == READ
+        if tool_request.effect == Effect.READ:
+            return ApprovalOutcome.APPROVED
+        return ApprovalOutcome.DENIED
+
+
+class CliApprover:
+    """Async-wrapped CLI approver for development."""
+
+    def __init__(self, show_emojis: bool = True):
+        self.show_emojis = show_emojis
+
+    async def request_approval_async(
+        self, agent_ctx, intent, tool_request, _hash, reason
+    ) -> ApprovalOutcome:
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            self._sync_request,
+            agent_ctx,
+            intent,
+            tool_request,
+            reason,
+        )
+
+    def _sync_request(self, agent_ctx, intent, tool_request, reason) -> ApprovalOutcome:
+        prefix = "🚦 " if self.show_emojis else ""
+        print("\n" + "=" * 40)
+        print(f"{prefix}TOLLGATE APPROVAL REQUESTED")
+        print("=" * 40)
+        print(f"Reason: {reason}")
+        print(f"Agent:  {agent_ctx.agent_id} (v{agent_ctx.version})")
+        print(f"Intent: {intent.action} - {intent.reason}")
+        print(f"Tool:   {tool_request.tool}.{tool_request.action}")
+        print(f"Params: {tool_request.params}")
+        print("-" * 40)
+        choice = input("Approve this tool call? (y/N): ").strip().lower()
+        return ApprovalOutcome.APPROVED if choice == "y" else ApprovalOutcome.DENIED
+
+
+def compute_request_hash(
+    agent_ctx: AgentContext, intent: Intent, tool_request: ToolRequest
+) -> str:
+    """Compute a deterministic hash for a tool request."""
+
+    def canonicalize(d: dict[str, Any]) -> str:
+        return json.dumps(d, sort_keys=True)
+
+    payload = "|".join(
+        [
+            agent_ctx.agent_id,
+            agent_ctx.version,
+            intent.action,
+            tool_request.tool,
+            tool_request.action,
+            tool_request.effect.value,
+            tool_request.resource_type,
+            canonicalize(tool_request.params),
+            canonicalize(tool_request.metadata),
+        ]
+    )
+    return hashlib.sha256(payload.encode()).hexdigest()

tollgate/audit.py

@@ -0,0 +1,47 @@
+import json
+from pathlib import Path
+from typing import Protocol
+
+from .types import AuditEvent
+
+
+class AuditSink(Protocol):
+    """Protocol for auditing tool execution results."""
+
+    def emit(self, event: AuditEvent) -> None:
+        """Emit an audit event."""
+        ...
+
+
+class JsonlAuditSink:
+    """Audit sink that writes to a JSONL file with buffering."""
+
+    def __init__(self, log_path: str | Path):
+        """Initialize the sink and ensure the log directory exists."""
+        self.log_path = Path(log_path)
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+        self._f = None
+
+    def _get_file(self):
+        if self._f is None or self._f.closed:
+            self._f = self.log_path.open("a", encoding="utf-8", buffering=1)
+        return self._f
+
+    def emit(self, event: AuditEvent) -> None:
+        """Append an audit event to the JSONL file."""
+        f = self._get_file()
+        f.write(json.dumps(event.to_dict(), ensure_ascii=False) + "\n")
+
+    def close(self):
+        """Close the file handle."""
+        if self._f and not self._f.closed:
+            self._f.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def __del__(self):
+        self.close()

tollgate/exceptions.py

@@ -0,0 +1,28 @@
+class TollgateError(Exception):
+    """Base exception for all Tollgate errors."""
+
+    pass
+
+
+class TollgateDenied(TollgateError):  # noqa: N818
+    """Raised when a tool call is explicitly denied by policy."""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+        super().__init__(f"Tool call denied: {reason}")
+
+
+class TollgateApprovalDenied(TollgateError):  # noqa: N818
+    """Raised when a human-in-the-loop approval is denied."""
+
+    def __init__(self, reason: str = "Approval denied by human."):
+        self.reason = reason
+        super().__init__(reason)
+
+
+class TollgateDeferred(TollgateError):  # noqa: N818
+    """Raised when a tool call is deferred (e.g., waiting for async approval)."""
+
+    def __init__(self, approval_id: str):
+        self.approval_id = approval_id
+        super().__init__(f"Tool call deferred. Approval ID: {approval_id}")

tollgate/helpers.py

@@ -0,0 +1,72 @@
+import asyncio
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from .tower import ControlTower
+from .types import AgentContext, Effect, Intent, ToolRequest
+
+
+def wrap_tool(
+    tower: ControlTower,
+    tool_callable: Callable,
+    *,
+    tool: str,
+    action: str,
+    resource_type: str,
+    effect: Effect,
+):
+    """
+    Wraps a tool callable to be executed through a ControlTower.
+    Maintained for backward compatibility with v0.
+    """
+
+    @wraps(tool_callable)
+    def wrapper(
+        agent_ctx: AgentContext,
+        intent: Intent,
+        metadata: dict[str, Any] | None = None,
+        **params,
+    ) -> Any:
+        req = ToolRequest(
+            tool=tool,
+            action=action,
+            resource_type=resource_type,
+            effect=effect,
+            params=params,
+            metadata=metadata or {},
+        )
+
+        if asyncio.iscoroutinefunction(tool_callable):
+
+            async def _exec():
+                return await tool_callable(**params)
+
+            return asyncio.run(tower.execute_async(agent_ctx, intent, req, _exec))
+
+        return tower.execute(agent_ctx, intent, req, lambda: tool_callable(**params))
+
+    return wrapper
+
+
+def guard(
+    tower: ControlTower,
+    *,
+    tool: str,
+    action: str,
+    resource_type: str,
+    effect: Effect,
+):
+    """Decorator to guard a tool function with a ControlTower."""
+
+    def decorator(func: Callable):
+        return wrap_tool(
+            tower,
+            func,
+            tool=tool,
+            action=action,
+            resource_type=resource_type,
+            effect=effect,
+        )
+
+    return decorator

tollgate/integrations/mcp.py

@@ -0,0 +1,58 @@
+from typing import Any
+
+from ..registry import ToolRegistry
+from ..tower import ControlTower
+from ..types import AgentContext, Intent, ToolRequest
+
+
+class TollgateMCPClient:
+    """A wrapper for an MCP client that gates tool calls through Tollgate."""
+
+    def __init__(
+        self,
+        client: Any,
+        server_name: str,
+        tower: ControlTower,
+        registry: ToolRegistry,
+    ):
+        """
+        Initialize the TollgateMCPClient.
+
+        :param client: The underlying MCP client (must have a call_tool).
+        :param server_name: The explicit name of the MCP server.
+        :param tower: The Tollgate ControlTower instance.
+        :param registry: The ToolRegistry instance.
+        """
+        self.client = client
+        self.server_name = server_name
+        self.tower = tower
+        self.registry = registry
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        agent_ctx: AgentContext,
+        intent: Intent,
+        metadata: dict[str, Any] | None = None,
+    ) -> Any:
+        """
+        Call an MCP tool, intercepted by Tollgate.
+        """
+        tool_key = f"mcp:{self.server_name}.{tool_name}"
+        effect, resource_type, manifest_version = self.registry.resolve_tool(tool_key)
+
+        request = ToolRequest(
+            tool="mcp",
+            action=tool_name,
+            resource_type=resource_type,
+            effect=effect,
+            params=arguments,
+            metadata=metadata or {},
+            manifest_version=manifest_version,
+        )
+
+        async def _exec_async():
+            return await self.client.call_tool(tool_name, arguments)
+
+        return await self.tower.execute_async(agent_ctx, intent, request, _exec_async)

tollgate/integrations/strands.py

@@ -0,0 +1,89 @@
+import asyncio
+from typing import Any
+
+from ..registry import ToolRegistry
+from ..tower import ControlTower
+from ..types import AgentContext, Intent, ToolRequest
+
+
+class GuardedStrandsTool:
+    """A wrapper for Strands tools that enforces Tollgate gating."""
+
+    def __init__(self, tool: Any, tower: ControlTower, registry: ToolRegistry):
+        self.tool = tool
+        self.tower = tower
+        self.registry = registry
+
+        # Resolve tool name
+        if callable(tool) and hasattr(tool, "__name__"):
+            self.name = tool.__name__
+        elif hasattr(tool, "name"):
+            self.name = tool.name
+        else:
+            self.name = tool.__class__.__name__
+
+        self.description = getattr(tool, "description", f"Strands tool: {self.name}")
+
+    async def __call__(
+        self,
+        tool_input: Any,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        metadata: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> Any:
+        return await self.run_async(tool_input, agent_ctx, intent, metadata, **kwargs)
+
+    async def run_async(
+        self,
+        tool_input: Any,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        metadata: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> Any:
+        tool_key = f"strands:{self.name}"
+        effect, resource_type, manifest_version = self.registry.resolve_tool(tool_key)
+
+        params = tool_input if isinstance(tool_input, dict) else {"input": tool_input}
+        if kwargs:
+            params.update(kwargs)
+
+        request = ToolRequest(
+            tool="strands",
+            action=self.name,
+            resource_type=resource_type,
+            effect=effect,
+            params=params,
+            metadata=metadata or {},
+            manifest_version=manifest_version,
+        )
+
+        async def _exec_async():
+            # Support various calling conventions
+            if hasattr(self.tool, "ainvoke"):
+                return await self.tool.ainvoke(tool_input, **kwargs)
+            if hasattr(self.tool, "arun"):
+                return await self.tool.arun(tool_input, **kwargs)
+            if asyncio.iscoroutinefunction(self.tool):
+                return await self.tool(tool_input, **kwargs)
+
+            # Sync fallback
+            def _sync_call():
+                if hasattr(self.tool, "invoke"):
+                    return self.tool.invoke(tool_input, **kwargs)
+                if hasattr(self.tool, "run"):
+                    return self.tool.run(tool_input, **kwargs)
+                return self.tool(tool_input, **kwargs)
+
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(None, _sync_call)
+
+        return await self.tower.execute_async(agent_ctx, intent, request, _exec_async)
+
+
+def guard_tools(
+    tools: list[Any], tower: ControlTower, registry: ToolRegistry
+) -> list[GuardedStrandsTool]:
+    """Wrap a list of Strands tools with Tollgate."""
+    return [GuardedStrandsTool(t, tower, registry) for t in tools]

tollgate/interceptors/__init__.py

@@ -0,0 +1,12 @@
+from .base import TollgateInterceptor, ToolAdapter
+from .langchain import LangChainAdapter, guard_tools
+from .openai import OpenAIAdapter, OpenAIToolRunner
+
+__all__ = [
+    "ToolAdapter",
+    "TollgateInterceptor",
+    "LangChainAdapter",
+    "guard_tools",
+    "OpenAIAdapter",
+    "OpenAIToolRunner",
+]

tollgate/interceptors/base.py

@@ -0,0 +1,41 @@
+import asyncio
+from typing import Any, Protocol
+
+from ..tower import ControlTower
+from ..types import AgentContext, Intent, NormalizedToolCall
+
+
+class ToolAdapter(Protocol):
+    """Protocol for framework-specific tool adapters."""
+
+    def normalize(self, tool_call: Any) -> NormalizedToolCall:
+        """Normalize a framework-specific tool call."""
+        ...
+
+
+class TollgateInterceptor:
+    """Core interceptor for gating tool calls."""
+
+    def __init__(self, tower: ControlTower, adapter: ToolAdapter):
+        self.tower = tower
+        self.adapter = adapter
+
+    async def intercept_async(
+        self, agent_ctx: AgentContext, intent: Intent, tool_call: Any
+    ) -> Any:
+        """Intercept and gate a tool call asynchronously."""
+        normalized = self.adapter.normalize(tool_call)
+        return await self.tower.execute_async(
+            agent_ctx, intent, normalized.request, normalized.exec_async
+        )
+
+    def intercept(self, agent_ctx: AgentContext, intent: Intent, tool_call: Any) -> Any:
+        """Intercept and gate a tool call synchronously."""
+        normalized = self.adapter.normalize(tool_call)
+        # For sync, we use tower.execute which handles the loop safety check
+        return self.tower.execute(
+            agent_ctx,
+            intent,
+            normalized.request,
+            lambda: asyncio.run(normalized.exec_async()),
+        )