toolboundary 0.1.0__py3-none-any.whl

toolboundary/__init__.py

@@ -0,0 +1,80 @@
+"""
+ToolBoundary
+============
+Runtime boundary enforcement for AI agents -- as a library, not a service.
+
+ToolBoundary answers one question, fast and locally, every time an agent
+tries to call a tool: "is this exact call allowed, right now?" It is
+designed for the common case of one to a handful of agents built by a
+single team, where standing up a separate governance web application and
+database would be disproportionate overhead.
+
+Quickstart
+----------
+>>> from toolboundary import Boundary, ToolPermission, AutonomyLevel, AccessMode
+>>>
+>>> boundary = Boundary(
+...     agent_name="support-agent",
+...     autonomy=AutonomyLevel.LIMITED_AUTONOMOUS,
+...     permissions=[
+...         ToolPermission("read_ticket_db", access_mode=AccessMode.READ_ONLY),
+...         ToolPermission(
+...             "send_reply_email",
+...             access_mode=AccessMode.EXECUTE,
+...             max_calls_per_hour=30,
+...         ),
+...     ],
+...     blocked_operations=frozenset({"delete_ticket"}),
+...     max_actions_per_hour=100,
+...     kill_switch_env="TOOLBOUNDARY_KILL_SWITCH",
+... )
+>>>
+>>> boundary.check("read_ticket_db", access_mode=AccessMode.READ_ONLY)  # passes silently
+>>> boundary.check("delete_ticket", operation="delete_ticket")  # raises BoundaryViolation
+
+For a decorator-based approach, see `toolboundary.guarded_tool`.
+For LangChain, see `toolboundary.integrations.langchain`.
+"""
+
+from .audit import AuditEvent, AuditTrail, JSONLFileSink, LoggingSink, WebhookSink
+from .boundary import Boundary, CallContext
+from .decorators import guarded_tool
+from .enums import AccessMode, AutonomyLevel, DecisionType, ViolationReason
+from .exceptions import (
+    ApprovalRequired,
+    BoundaryViolation,
+    ConfigurationError,
+    KillSwitchActive,
+    RateLimitExceeded,
+    ToolBoundaryError,
+)
+from .permissions import ToolPermission
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # core
+    "Boundary",
+    "CallContext",
+    "ToolPermission",
+    "guarded_tool",
+    # enums
+    "AccessMode",
+    "AutonomyLevel",
+    "DecisionType",
+    "ViolationReason",
+    # exceptions
+    "ToolBoundaryError",
+    "BoundaryViolation",
+    "KillSwitchActive",
+    "RateLimitExceeded",
+    "ApprovalRequired",
+    "ConfigurationError",
+    # audit
+    "AuditTrail",
+    "AuditEvent",
+    "LoggingSink",
+    "JSONLFileSink",
+    "WebhookSink",
+]

toolboundary/_rate_limiter.py

@@ -0,0 +1,62 @@
+"""
+toolboundary._rate_limiter
+--------------------------
+Minimal in-memory sliding-window rate limiter.
+
+Private module (leading underscore): this is an internal implementation
+detail of Boundary, not part of the public API surface. Kept in-memory and
+dependency-free on purpose -- ToolBoundary must add near-zero latency and
+must not require Redis or a database to function for the common case of
+a single-process agent.
+
+For multi-process deployments, swap this out via the `store` hook in
+Boundary (see boundary.py) -- e.g. backing it with Redis INCR/EXPIRE.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+
+
+class SlidingWindowRateLimiter:
+    """Tracks timestamps of recent calls per key and enforces a max-per-window limit."""
+
+    def __init__(self) -> None:
+        self._calls: dict[str, deque[float]] = {}
+        self._lock = threading.Lock()
+
+    def check_and_record(self, key: str, max_calls: int, window_seconds: float) -> bool:
+        """
+        Returns True if the call is allowed (and records it).
+        Returns False if the call would exceed max_calls within window_seconds.
+        """
+        now = time.monotonic()
+        with self._lock:
+            window = self._calls.setdefault(key, deque())
+
+            # Drop timestamps outside the window
+            cutoff = now - window_seconds
+            while window and window[0] < cutoff:
+                window.popleft()
+
+            if len(window) >= max_calls:
+                return False
+
+            window.append(now)
+            return True
+
+    def current_count(self, key: str, window_seconds: float) -> int:
+        now = time.monotonic()
+        with self._lock:
+            window = self._calls.get(key, deque())
+            cutoff = now - window_seconds
+            return sum(1 for t in window if t >= cutoff)
+
+    def reset(self, key: str | None = None) -> None:
+        with self._lock:
+            if key is None:
+                self._calls.clear()
+            else:
+                self._calls.pop(key, None)

toolboundary/audit.py

@@ -0,0 +1,169 @@
+"""
+toolboundary.audit
+------------------
+Local-first audit trail.
+
+Design goal: ToolBoundary must never require a hosted service or database to
+produce useful audit evidence. By default every decision is emitted as a
+structured JSON line to stdlib `logging` (logger name "toolboundary.audit"),
+which the host application can route anywhere logging already goes
+(stdout, a file, Datadog, CloudWatch, etc.) with zero extra code.
+
+Optional sinks (JSONL file, HTTP webhook) are provided for teams that want
+a durable local record or want to forward events to a centralized
+governance platform (e.g. a GuardianIQ-style registry) without coupling
+ToolBoundary itself to any specific vendor.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+_logger = logging.getLogger("toolboundary.audit")
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    """
+    One record of a single ToolBoundary decision.
+
+    Field names intentionally echo the vocabulary used by enterprise AI
+    governance registries (agent_id, tool_id, access_mode, decision) so
+    that events can be reconciled with, or imported into, such a system
+    later without a translation layer.
+    """
+
+    event_id: str
+    timestamp: float
+    agent_name: str
+    tool_name: str | None
+    operation: str | None
+    access_mode: str | None
+    decision: str  # ALLOW | DENY | APPROVAL_REQUIRED
+    reason_code: str | None
+    message: str
+    correlation_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), default=str, sort_keys=True)
+
+
+class AuditSink(Protocol):
+    """Anything with an `emit(event)` method can be used as a sink."""
+
+    def emit(self, event: AuditEvent) -> None: ...
+
+
+class LoggingSink:
+    """Default sink: writes structured JSON to Python's stdlib logging."""
+
+    def __init__(self, level: int = logging.INFO) -> None:
+        self._level = level
+
+    def emit(self, event: AuditEvent) -> None:
+        level = self._level if event.decision == "ALLOW" else logging.WARNING
+        _logger.log(level, event.to_json())
+
+
+class JSONLFileSink:
+    """Appends each event as one JSON line to a local file. Thread-safe append."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+    def emit(self, event: AuditEvent) -> None:
+        with self._path.open("a", encoding="utf-8") as f:
+            f.write(event.to_json())
+            f.write("\n")
+
+
+class WebhookSink:
+    """
+    Forwards events to an HTTP endpoint (e.g. a self-hosted dashboard or a
+    governance platform's ingestion API). Uses `urllib` to avoid forcing a
+    `requests` dependency on users who don't need this sink.
+
+    Failures are swallowed (never raised) so that a network hiccup in your
+    audit pipeline can never block or crash the agent itself -- audit
+    delivery is best-effort by design; the ALLOW/DENY decision has already
+    been enforced locally before this sink is even invoked.
+    """
+
+    def __init__(
+        self, url: str, timeout: float = 2.0, headers: dict[str, str] | None = None
+    ) -> None:
+        self._url = url
+        self._timeout = timeout
+        self._headers = headers or {"Content-Type": "application/json"}
+
+    def emit(self, event: AuditEvent) -> None:
+        import urllib.request
+
+        try:
+            data = event.to_json().encode("utf-8")
+            # S310: the webhook URL is supplied by the host application at
+            # WebhookSink construction time, not by untrusted input reaching
+            # this code path -- this is a deliberate, documented HTTP POST,
+            # not an arbitrary-scheme file open.
+            req = urllib.request.Request(  # noqa: S310
+                self._url, data=data, headers=self._headers, method="POST"
+            )
+            urllib.request.urlopen(req, timeout=self._timeout)  # noqa: S310
+        except Exception:  # noqa: BLE001 - audit delivery must never raise
+            _logger.debug("toolboundary: webhook audit sink failed to deliver event", exc_info=True)
+
+
+class AuditTrail:
+    """Fans out one AuditEvent to any number of configured sinks."""
+
+    def __init__(self, sinks: list[AuditSink] | None = None) -> None:
+        self.sinks: list[AuditSink] = sinks if sinks is not None else [LoggingSink()]
+
+    def add_sink(self, sink: AuditSink) -> None:
+        self.sinks.append(sink)
+
+    def record(
+        self,
+        *,
+        agent_name: str,
+        decision: str,
+        message: str,
+        tool_name: str | None = None,
+        operation: str | None = None,
+        access_mode: str | None = None,
+        reason_code: str | None = None,
+        correlation_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> AuditEvent:
+        event = AuditEvent(
+            event_id=str(uuid.uuid4()),
+            timestamp=time.time(),
+            agent_name=agent_name,
+            tool_name=tool_name,
+            operation=operation,
+            access_mode=access_mode,
+            decision=decision,
+            reason_code=reason_code,
+            message=message,
+            correlation_id=correlation_id,
+            metadata=metadata or {},
+        )
+        for sink in self.sinks:
+            try:
+                sink.emit(event)
+            except Exception:  # noqa: BLE001
+                _logger.debug(
+                    "toolboundary: sink %r raised while emitting event", sink, exc_info=True
+                )
+        return event