tollgate 1.0.0__py3-none-any.whl

tollgate/interceptors/langchain.py

@@ -0,0 +1,91 @@
+from typing import Any
+
+from ..registry import ToolRegistry
+from ..tower import ControlTower
+from ..types import NormalizedToolCall, ToolRequest
+from .base import TollgateInterceptor
+
+
+class LangChainAdapter:
+    """Adapter for LangChain tools."""
+
+    def __init__(self, registry: ToolRegistry):
+        self.registry = registry
+
+    def normalize(self, tool_call: Any) -> NormalizedToolCall:
+        # tool_call is expected to be (tool, tool_input) or (tool, tool_input, kwargs)
+        if len(tool_call) == 3:
+            tool, tool_input, kwargs = tool_call
+        else:
+            tool, tool_input = tool_call
+            kwargs = {}
+
+        tool_name = getattr(tool, "name", str(tool))
+        registry_key = f"langchain:{tool_name}"
+
+        effect, resource_type, manifest_version = self.registry.resolve_tool(
+            registry_key
+        )
+
+        metadata = kwargs.get("metadata", {})
+
+        params = tool_input if isinstance(tool_input, dict) else {"input": tool_input}
+
+        request = ToolRequest(
+            tool="langchain",
+            action=tool_name,
+            resource_type=resource_type,
+            effect=effect,
+            params=params,
+            metadata=metadata,
+            manifest_version=manifest_version,
+        )
+
+        async def _exec_async():
+            if hasattr(tool, "ainvoke"):
+                return await tool.ainvoke(tool_input)
+            return await tool.arun(tool_input)
+
+        def _exec_sync():
+            if hasattr(tool, "invoke"):
+                return tool.invoke(tool_input)
+            return tool.run(tool_input)
+
+        return NormalizedToolCall(
+            request=request, exec_async=_exec_async, exec_sync=_exec_sync
+        )
+
+
+class GuardedLangChainTool:
+    """A wrapper for LangChain tools that enforces Tollgate gating."""
+
+    def __init__(self, tool: Any, interceptor: TollgateInterceptor):
+        self.tool = tool
+        self.interceptor = interceptor
+        self.name = tool.name
+        self.description = tool.description
+
+    async def ainvoke(self, tool_input, agent_ctx=None, intent=None, **kwargs):
+        if agent_ctx is None or intent is None:
+            return await self.tool.ainvoke(tool_input, **kwargs)
+
+        return await self.interceptor.intercept_async(
+            agent_ctx, intent, (self.tool, tool_input, kwargs)
+        )
+
+    def invoke(self, tool_input, agent_ctx=None, intent=None, **kwargs):
+        if agent_ctx is None or intent is None:
+            return self.tool.invoke(tool_input, **kwargs)
+
+        return self.interceptor.intercept(
+            agent_ctx, intent, (self.tool, tool_input, kwargs)
+        )
+
+
+def guard_tools(
+    tools: list[Any], tower: ControlTower, registry: ToolRegistry
+) -> list[Any]:
+    """Wrap a list of LangChain tools with Tollgate."""
+    adapter = LangChainAdapter(registry)
+    interceptor = TollgateInterceptor(tower, adapter)
+    return [GuardedLangChainTool(t, interceptor) for t in tools]

tollgate/interceptors/openai.py

@@ -0,0 +1,87 @@
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any
+
+from ..registry import ToolRegistry
+from ..tower import ControlTower
+from ..types import AgentContext, Intent, NormalizedToolCall, ToolRequest
+from .base import TollgateInterceptor
+
+
+class OpenAIAdapter:
+    """Adapter for OpenAI function/tool calls."""
+
+    def __init__(self, registry: ToolRegistry, tool_map: dict[str, Callable]):
+        self.registry = registry
+        self.tool_map = tool_map
+
+    def normalize(self, tool_call: Any) -> NormalizedToolCall:
+        # tool_call is expected to be a dict with 'name' and 'arguments'
+        # OR (tool_call_dict, kwargs)
+        if isinstance(tool_call, tuple) and len(tool_call) == 2:
+            tc_dict, kwargs = tool_call
+        else:
+            tc_dict = tool_call
+            kwargs = {}
+
+        tool_name = tc_dict.get("function", {}).get("name") or tc_dict.get("name")
+        args_str = tc_dict.get("function", {}).get("arguments") or tc_dict.get(
+            "arguments"
+        )
+        args = json.loads(args_str) if isinstance(args_str, str) else args_str
+
+        registry_key = f"openai:{tool_name}"
+        effect, resource_type, manifest_version = self.registry.resolve_tool(
+            registry_key
+        )
+
+        metadata = kwargs.get("metadata", {})
+
+        request = ToolRequest(
+            tool="openai",
+            action=tool_name,
+            resource_type=resource_type,
+            effect=effect,
+            params=args,
+            metadata=metadata,
+            manifest_version=manifest_version,
+        )
+
+        func = self.tool_map[tool_name]
+
+        async def _exec_async():
+            if asyncio.iscoroutinefunction(func):
+                return await func(**args)
+            return func(**args)
+
+        def _exec_sync():
+            return func(**args)
+
+        return NormalizedToolCall(
+            request=request, exec_async=_exec_async, exec_sync=_exec_sync
+        )
+
+
+class OpenAIToolRunner:
+    """Helper to run OpenAI tool calls through Tollgate."""
+
+    def __init__(self, tower: ControlTower, registry: ToolRegistry):
+        self.tower = tower
+        self.registry = registry
+
+    async def run_async(
+        self,
+        tool_calls: list[Any],
+        tool_map: dict[str, Callable],
+        agent_ctx: AgentContext,
+        intent: Intent,
+    ) -> list[Any]:
+        adapter = OpenAIAdapter(self.registry, tool_map)
+        interceptor = TollgateInterceptor(self.tower, adapter)
+
+        results = []
+        for tc in tool_calls:
+            result = await interceptor.intercept_async(agent_ctx, intent, tc)
+            results.append(result)
+        return results

tollgate/policy.py

@@ -0,0 +1,152 @@
+import hashlib
+from pathlib import Path
+from typing import Any, Protocol
+
+import yaml
+
+from .types import AgentContext, Decision, DecisionType, Effect, Intent, ToolRequest
+
+
+class PolicyEvaluator(Protocol):
+    """Protocol for policy evaluation."""
+
+    def evaluate(
+        self, agent_ctx: AgentContext, intent: Intent, tool_request: ToolRequest
+    ) -> Decision:
+        """Evaluate a tool request against the policy."""
+        ...
+
+
+class YamlPolicyEvaluator:
+    """YAML-based policy evaluator with safe defaults."""
+
+    def __init__(
+        self,
+        policy_path: str | Path,
+        default_if_unknown: DecisionType = DecisionType.DENY,
+    ):
+        """Load and validate policy from YAML file."""
+        self.path = Path(policy_path)
+        with self.path.open("r") as f:
+            content = f.read()
+            self.data = yaml.safe_load(content)
+            self.version = self.data.get(
+                "version", hashlib.sha256(content.encode()).hexdigest()[:8]
+            )
+
+        self.rules = self.data.get("rules", [])
+        self.default_if_unknown = default_if_unknown
+        self._validate_rules()
+
+    def _validate_rules(self):
+        """Basic validation of rule structure."""
+        for i, rule in enumerate(self.rules):
+            if "decision" not in rule:
+                raise ValueError(f"Rule at index {i} is missing 'decision' key")
+            try:
+                DecisionType(rule["decision"])
+            except ValueError:
+                raise ValueError(
+                    f"Invalid decision '{rule['decision']}' in rule at index {i}"
+                ) from None
+
+    def evaluate(
+        self, agent_ctx: AgentContext, intent: Intent, tool_request: ToolRequest
+    ) -> Decision:
+        """Evaluate a tool request against loaded rules."""
+        # Principle 2: Safe Defaults for unknown effect/resource
+        if tool_request.effect == Effect.UNKNOWN:
+            return Decision(
+                decision=self.default_if_unknown,
+                reason="Unknown tool effect. Safe default applied.",
+                policy_version=self.version,
+            )
+
+        for rule in self.rules:
+            if self._matches(rule, agent_ctx, intent, tool_request):
+                # Principle 3: Trusted Attributes
+                # If ALLOW, ensure effect and resource_type are from registry (trusted)
+                decision = DecisionType(rule["decision"])
+                if decision == DecisionType.ALLOW and not tool_request.manifest_version:
+                    return Decision(
+                        decision=DecisionType.ASK,
+                        reason=(
+                            "ALLOW decision requires trusted tool metadata "
+                            "from registry."
+                        ),
+                        policy_version=self.version,
+                    )
+
+                return Decision(
+                    decision=decision,
+                    reason=rule.get("reason", "Rule matched"),
+                    policy_id=rule.get("id"),
+                    policy_version=self.version,
+                    metadata=rule.get("metadata", {}),
+                )
+
+        return Decision(
+            decision=DecisionType.DENY,
+            reason="No matching policy rule found. Defaulting to DENY.",
+            policy_version=self.version,
+        )
+
+    def _matches(
+        self,
+        rule: dict,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        req: ToolRequest,
+    ) -> bool:
+        # Match tool, action, resource_type, effect
+        if "tool" in rule and rule["tool"] != req.tool:
+            return False
+        if "action" in rule and rule["action"] != req.action:
+            return False
+        if "resource_type" in rule and rule["resource_type"] != req.resource_type:
+            return False
+        if "effect" in rule and rule["effect"] != req.effect.value:
+            return False
+
+        # Match Agent Context
+        if "agent" in rule:
+            for key, expected_val in rule["agent"].items():
+                if getattr(agent_ctx, key, None) != expected_val:
+                    return False
+
+        # Match Intent
+        if "intent" in rule:
+            for key, expected_val in rule["intent"].items():
+                if getattr(intent, key, None) != expected_val:
+                    return False
+
+        # Match metadata conditions (Untrusted)
+        if "when" in rule:
+            for key, condition in rule["when"].items():
+                val = req.metadata.get(key)
+                if not self._check_condition(val, condition):
+                    return False
+
+        return True
+
+    def _check_condition(self, val: Any, condition: Any) -> bool:
+        """Check a single condition against a value."""
+        if isinstance(condition, dict):
+            for op, target in condition.items():
+                if val is None and op in (">", ">=", "<", "<="):
+                    return False
+
+                if op == "==" and val != target:
+                    return False
+                if op == "!=" and val == target:
+                    return False
+                if op == ">" and not (val > target):
+                    return False
+                if op == ">=" and not (val >= target):
+                    return False
+                if op == "<" and not (val < target):
+                    return False
+                if op == "<=" and not (val <= target):
+                    return False
+            return True
+        return val == condition

tollgate/registry.py

@@ -0,0 +1,58 @@
+import hashlib
+from pathlib import Path
+
+import yaml
+
+from .types import Effect
+
+
+class ToolRegistry:
+    """A registry of trusted tool metadata."""
+
+    def __init__(self, manifest_path: str | Path):
+        self.path = Path(manifest_path)
+        if not self.path.exists():
+            raise FileNotFoundError(f"Manifest file not found: {manifest_path}")
+
+        with self.path.open("r") as f:
+            content = f.read()
+            self.data = yaml.safe_load(content)
+            if not self.data:
+                self.data = {}
+            # Use content hash as manifest version if not provided
+            self.version = str(
+                self.data.get(
+                    "version", hashlib.sha256(content.encode()).hexdigest()[:8]
+                )
+            )
+        self.tools = self.data.get("tools", {})
+        self._validate_manifest()
+
+    def _validate_manifest(self):
+        """Basic validation of manifest structure."""
+        if not isinstance(self.tools, dict):
+            raise ValueError("Manifest 'tools' must be a dictionary.")
+
+        for key, entry in self.tools.items():
+            if not isinstance(entry, dict):
+                raise ValueError(f"Tool entry '{key}' must be a dictionary.")
+            if "effect" in entry:
+                try:
+                    Effect(entry["effect"])
+                except ValueError as e:
+                    raise ValueError(
+                        f"Invalid effect '{entry['effect']}' for tool '{key}'."
+                    ) from e
+
+    def resolve_tool(self, tool_key: str) -> tuple[Effect, str, str | None]:
+        """
+        Resolve tool key to (effect, resource_type, manifest_version).
+        Returns (UNKNOWN, "unknown", None) if not found.
+        """
+        meta = self.tools.get(tool_key)
+        if not meta:
+            return Effect.UNKNOWN, "unknown", None
+
+        effect = Effect(meta.get("effect", "unknown"))
+        resource_type = meta.get("resource_type", "unknown")
+        return effect, resource_type, self.version

tollgate/tower.py

@@ -0,0 +1,224 @@
+import asyncio
+import uuid
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from .approvals import Approver, compute_request_hash
+from .audit import AuditSink
+from .exceptions import (
+    TollgateApprovalDenied,
+    TollgateDeferred,
+    TollgateDenied,
+)
+from .policy import PolicyEvaluator
+from .types import (
+    AgentContext,
+    ApprovalOutcome,
+    AuditEvent,
+    Decision,
+    DecisionType,
+    Intent,
+    Outcome,
+    ToolRequest,
+)
+
+
+class ControlTower:
+    """Async-first control tower for tool execution enforcement."""
+
+    def __init__(
+        self,
+        policy: PolicyEvaluator,
+        approver: Approver,
+        audit: AuditSink,
+        redact_fn: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+    ):
+        self.policy = policy
+        self.approver = approver
+        self.audit = audit
+        self.redact_fn = redact_fn or self._default_redact
+
+    @staticmethod
+    def _default_redact(params: dict[str, Any]) -> dict[str, Any]:
+        """Redact sensitive keys by default."""
+        sensitive_keys = {
+            "password",
+            "token",
+            "secret",
+            "authorization",
+            "api_key",
+            "key",
+        }
+        return {
+            k: ("[REDACTED]" if k.lower() in sensitive_keys else v)
+            for k, v in params.items()
+        }
+
+    async def execute_async(
+        self,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        tool_request: ToolRequest,
+        exec_async: Callable[[], Awaitable[Any]],
+    ) -> Any:
+        """
+        Evaluate and execute a tool call asynchronously.
+        """
+        correlation_id = str(uuid.uuid4())
+        request_hash = compute_request_hash(agent_ctx, intent, tool_request)
+
+        # 1. Evaluate Policy
+        decision = self.policy.evaluate(agent_ctx, intent, tool_request)
+
+        # 2. Handle DENY
+        if decision.decision == DecisionType.DENY:
+            self._log(
+                correlation_id,
+                request_hash,
+                agent_ctx,
+                intent,
+                tool_request,
+                decision,
+                Outcome.BLOCKED,
+            )
+            raise TollgateDenied(decision.reason)
+
+        # 3. Handle ASK
+        if decision.decision == DecisionType.ASK:
+            outcome = await self.approver.request_approval_async(
+                agent_ctx, intent, tool_request, request_hash, decision.reason
+            )
+
+            if outcome == ApprovalOutcome.DEFERRED:
+                # Audit the deferral
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,  # Deferral is a temporary block
+                )
+                raise TollgateDeferred("pending")
+
+            if outcome != ApprovalOutcome.APPROVED:
+                final_outcome = (
+                    Outcome.TIMEOUT
+                    if outcome == ApprovalOutcome.TIMEOUT
+                    else Outcome.APPROVAL_DENIED
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    final_outcome,
+                )
+                raise TollgateApprovalDenied(f"Approval failed: {outcome.value}")
+
+        # 4. Execute tool
+        result = None
+        outcome = Outcome.EXECUTED
+        try:
+            result = await exec_async()
+        except Exception as e:
+            outcome = Outcome.FAILED
+            result_summary = f"{type(e).__name__}: {str(e)}"
+            self._log(
+                correlation_id,
+                request_hash,
+                agent_ctx,
+                intent,
+                tool_request,
+                decision,
+                outcome,
+                result_summary=result_summary,
+            )
+            raise
+
+        # 5. Final Audit
+        result_summary = self._truncate_result(result)
+        self._log(
+            correlation_id,
+            request_hash,
+            agent_ctx,
+            intent,
+            tool_request,
+            decision,
+            outcome,
+            result_summary=result_summary,
+        )
+
+        return result
+
+    def execute(
+        self,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        tool_request: ToolRequest,
+        exec_sync: Callable[[], Any],
+    ) -> Any:
+        """Sync wrapper for execute_async. Safe only if no event loop is running."""
+        try:
+            loop = asyncio.get_running_loop()
+            if loop.is_running():
+                raise RuntimeError(
+                    "execute() called from within a running event loop. "
+                    "Use execute_async() instead."
+                )
+        except RuntimeError:
+            pass
+
+        async def _exec():
+            return exec_sync()
+
+        return asyncio.run(self.execute_async(agent_ctx, intent, tool_request, _exec))
+
+    def _log(
+        self,
+        correlation_id: str,
+        request_hash: str,
+        agent: AgentContext,
+        intent: Intent,
+        req: ToolRequest,
+        decision: Decision,
+        outcome: Outcome,
+        approval_id: str | None = None,
+        result_summary: str | None = None,
+    ):
+        # Redact params before logging
+        redacted_req = ToolRequest(
+            tool=req.tool,
+            action=req.action,
+            resource_type=req.resource_type,
+            effect=req.effect,
+            params=self.redact_fn(req.params),
+            metadata=req.metadata,
+            manifest_version=req.manifest_version,
+        )
+
+        event = AuditEvent(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            correlation_id=correlation_id,
+            request_hash=request_hash,
+            agent=agent,
+            intent=intent,
+            tool_request=redacted_req,
+            decision=decision,
+            outcome=outcome,
+            approval_id=approval_id,
+            result_summary=result_summary,
+            policy_version=decision.policy_version,
+            manifest_version=req.manifest_version,
+        )
+        self.audit.emit(event)
+
+    def _truncate_result(self, result: Any, max_chars: int = 200) -> str | None:
+        if result is None:
+            return None
+        s = str(result)
+        return s[:max_chars] + "..." if len(s) > max_chars else s