ghemud-agentkit 0.1.0__py3-none-any.whl

ghemud_agentkit/__init__.py

@@ -0,0 +1,156 @@
+"""Ghemud AgentKit: a secure, provider-agnostic runtime for AI agent tools.
+
+Created and maintained by Yashraj Sachin Ghemud.
+
+Quick start::
+
+    from ghemud_agentkit import ToolRegistry, ToolRuntime, tool
+
+    @tool(description="Add two integers")
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    registry = ToolRegistry()
+    registry.register(add)
+
+    runtime = ToolRuntime(registry)
+    result = await runtime.run("add", {"a": 2, "b": 3})
+    assert result.content == 5
+
+The public API is intentionally small. Everything else (policies, approvals,
+audit, models, loops) is importable from its submodule but only surfaced
+here once it is stable.
+"""
+
+from ghemud_agentkit._version import __version__, __version_info__
+from ghemud_agentkit.approvals import (
+    ApprovalDecision,
+    ApprovalManager,
+    ApprovalProvider,
+    ApprovalRequest,
+    AutoDenyProvider,
+    CallbackProvider,
+    InteractiveConsoleProvider,
+    StaticProvider,
+)
+from ghemud_agentkit.audit import AuditSink, InMemoryAuditSink, JsonlFileAuditSink
+from ghemud_agentkit.budgets import Budget, BudgetSet
+from ghemud_agentkit.capabilities import BUILTIN_CAPABILITIES, Capability
+from ghemud_agentkit.events import EventBus, EventType, InMemoryEventCollector
+from ghemud_agentkit.lifecycle import InvocationState
+from ghemud_agentkit.loop import AgentLoop, LoopConfig, LoopResult, StopReason
+from ghemud_agentkit.middleware import InvocationGate, Middleware, MiddlewareChain
+from ghemud_agentkit.models.base import (
+    ModelClient,
+    ModelMessage,
+    ModelRequest,
+    ModelResponse,
+    ModelToolCall,
+)
+from ghemud_agentkit.models.fake import ScriptedModel
+from ghemud_agentkit.permissions import (
+    ChainedPolicy,
+    DefaultPolicy,
+    Effect,
+    PermissionPolicy,
+    PermissionRequest,
+    PolicyDecision,
+    PolicyRule,
+    RuleBasedPolicy,
+    policy_from_dict,
+)
+from ghemud_agentkit.registry import CompositeToolRegistry, RegistrySnapshot, ToolRegistry
+from ghemud_agentkit.resilience import RetryPolicy
+from ghemud_agentkit.results import FailureKind, ResultStatus, ToolResult
+from ghemud_agentkit.runtime import InvocationMetadata, RuntimeConfig, ToolRuntime
+from ghemud_agentkit.sandbox import (
+    SANDBOX_TRUST_BOUNDARY,
+    SandboxExecutor,
+    SandboxRequest,
+    SandboxResult,
+    SubprocessSandboxExecutor,
+)
+from ghemud_agentkit.state import InMemoryStateStore, StateStore
+from ghemud_agentkit.tools import (
+    Example,
+    RateLimit,
+    RiskLevel,
+    SideEffects,
+    Tool,
+    ToolContext,
+    ToolSpec,
+    tool,
+)
+from ghemud_agentkit.tracing import TraceRecorder
+
+__all__ = [
+    "BUILTIN_CAPABILITIES",
+    "SANDBOX_TRUST_BOUNDARY",
+    "AgentLoop",
+    "ApprovalDecision",
+    "ApprovalManager",
+    "ApprovalProvider",
+    "ApprovalRequest",
+    "AuditSink",
+    "AutoDenyProvider",
+    "Budget",
+    "BudgetSet",
+    "CallbackProvider",
+    "Capability",
+    "ChainedPolicy",
+    "CompositeToolRegistry",
+    "DefaultPolicy",
+    "Effect",
+    "EventBus",
+    "EventType",
+    "Example",
+    "FailureKind",
+    "InMemoryAuditSink",
+    "InMemoryEventCollector",
+    "InMemoryStateStore",
+    "InteractiveConsoleProvider",
+    "InvocationGate",
+    "InvocationMetadata",
+    "InvocationState",
+    "JsonlFileAuditSink",
+    "LoopConfig",
+    "LoopResult",
+    "Middleware",
+    "MiddlewareChain",
+    "ModelClient",
+    "ModelMessage",
+    "ModelRequest",
+    "ModelResponse",
+    "ModelToolCall",
+    "PermissionPolicy",
+    "PermissionRequest",
+    "PolicyDecision",
+    "PolicyRule",
+    "RateLimit",
+    "RegistrySnapshot",
+    "ResultStatus",
+    "RetryPolicy",
+    "RiskLevel",
+    "RuleBasedPolicy",
+    "RuntimeConfig",
+    "SandboxExecutor",
+    "SandboxRequest",
+    "SandboxResult",
+    "ScriptedModel",
+    "SideEffects",
+    "StateStore",
+    "StaticProvider",
+    "StopReason",
+    "SubprocessSandboxExecutor",
+    "Tool",
+    "ToolContext",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolRuntime",
+    "ToolSpec",
+    "TraceRecorder",
+    "__version__",
+    "__version_info__",
+    "policy_from_dict",
+    "tool",
+]

ghemud_agentkit/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m ghemud_agentkit`` entry point — equivalent to the ``ghemud_agentkit`` CLI."""
+
+from ghemud_agentkit.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ghemud_agentkit/_version.py

@@ -0,0 +1,12 @@
+"""Single authoritative source for the Ghemud AgentKit package version.
+
+Every other module (and the build backend via ``[tool.hatch.version]``) reads
+the version from here so there is exactly one place to bump it.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+#: Public compatibility surface, following semver-2.0.0.
+__version_info__ = tuple(int(part) for part in __version__.split(".")[:3])

ghemud_agentkit/approvals.py

@@ -0,0 +1,498 @@
+"""Human-in-the-loop approval for risky tool invocations.
+
+Flow
+----
+1. Policy evaluates to ``approval_required``.
+2. Runtime creates an :class:`ApprovalRequest` (tool, redacted arguments,
+   capabilities, reason, invocation metadata) with a *request TTL*.
+3. An :class:`ApprovalProvider` obtains a human decision (or an automated
+   one — providers are just callables with opinions).
+4. The resulting :class:`ApprovalDecision` carries its *decision TTL*:
+   approvals are perishable. A decision that sat in a queue longer than its
+   TTL is treated as expired and the invocation is denied — approvals must
+   never silently persist forever (engineering requirement 12).
+5. Non-interactive environments use :class:`AutoDenyProvider` by default:
+   if nobody can answer, the answer is no, unless the operator explicitly
+   installs a provider that says otherwise.
+
+Every step emits an event (``approval.requested/granted/denied/expired``) so
+the audit trail answers "who approved what, when, and for which arguments".
+"""
+
+from __future__ import annotations
+
+import asyncio
+import fnmatch
+import time
+import uuid
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from ghemud_agentkit.errors import ApprovalDeniedError, ApprovalExpiredError, ApprovalTimeoutError
+from ghemud_agentkit.events import EventBus, EventType
+from ghemud_agentkit.permissions import PolicyDecision
+
+__all__ = [
+    "ApprovalDecision",
+    "ApprovalManager",
+    "ApprovalProvider",
+    "ApprovalRequest",
+    "ApprovalStatus",
+    "AutoDenyProvider",
+    "CallbackProvider",
+    "InteractiveConsoleProvider",
+    "StaticProvider",
+]
+
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    """A request for human approval of one would-be invocation."""
+
+    request_id: str
+    tool_name: str
+    arguments: Mapping[str, Any]  # already redacted
+    capabilities: frozenset[str]
+    reason: str
+    risk_level: int
+    invocation_id: str | None
+    actor_id: str | None
+    agent_id: str | None
+    created_at: float = field(default_factory=time.time)
+    request_ttl: float = 300.0  # how long the *request* may stay pending
+
+    @property
+    def expires_at(self) -> float:
+        return self.created_at + self.request_ttl
+
+    @property
+    def expired(self) -> bool:
+        return time.time() > self.expires_at
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "request_id": self.request_id,
+            "tool_name": self.tool_name,
+            "arguments": dict(self.arguments),
+            "capabilities": sorted(self.capabilities),
+            "reason": self.reason,
+            "risk_level": self.risk_level,
+            "invocation_id": self.invocation_id,
+            "actor_id": self.actor_id,
+            "agent_id": self.agent_id,
+            "created_at": self.created_at,
+            "request_ttl": self.request_ttl,
+        }
+
+
+class ApprovalStatus:
+    """Lifecycle states of an approval request."""
+
+    PENDING = "pending"
+    APPROVED = "approved"
+    DENIED = "denied"
+    EXPIRED = "expired"
+
+
+@dataclass(frozen=True)
+class ApprovalDecision:
+    """A human (or automated) decision about an approval request."""
+
+    request_id: str
+    approved: bool
+    decided_by: str
+    decided_at: float = field(default_factory=time.time)
+    reason: str = ""
+    decision_ttl: float = 60.0  # how long the *decision* stays valid
+
+    @property
+    def expires_at(self) -> float:
+        return self.decided_at + self.decision_ttl
+
+    def expired(self, *, now: float | None = None) -> bool:
+        current = now if now is not None else time.time()
+        return current > self.expires_at
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "request_id": self.request_id,
+            "approved": self.approved,
+            "decided_by": self.decided_by,
+            "decided_at": self.decided_at,
+            "reason": self.reason,
+            "decision_ttl": self.decision_ttl,
+        }
+
+
+class ApprovalProvider(Protocol):
+    """Anything that can produce approval decisions."""
+
+    async def decide(self, request: ApprovalRequest) -> ApprovalDecision:
+        """Return a decision for ``request``. Must not raise for policy
+        reasons — return ``approved=False`` instead. Infrastructure errors may
+        propagate; the runtime converts them into denials with the failure
+        reason recorded."""
+        ...
+
+
+class AutoDenyProvider:
+    """Denies everything — the safe default for non-interactive runtimes.
+
+    An unattended process has no human to ask; fabricating an "approved"
+    would defeat the entire point of approval-required. Operators who want
+    unattended approval can install :class:`StaticProvider` *explicitly*,
+    which is the documented tradeoff (engineering requirement 20).
+    """
+
+    def __init__(self, *, reason: str = "non-interactive runtime: auto-deny") -> None:
+        self.reason = reason
+
+    async def decide(self, request: ApprovalRequest) -> ApprovalDecision:
+        return ApprovalDecision(
+            request_id=request.request_id,
+            approved=False,
+            decided_by="auto-deny",
+            reason=self.reason,
+        )
+
+
+class StaticProvider:
+    """Approves (or denies) everything unconditionally.
+
+    Exists for tests and for explicitly-configured unattended runs. The
+    constructor takes the decision *once* so the audit trail records who
+    pre-authorized the blanket decision.
+    """
+
+    def __init__(self, *, approved: bool, decided_by: str = "static") -> None:
+        self.approved = approved
+        self.decided_by = decided_by
+
+    async def decide(self, request: ApprovalRequest) -> ApprovalDecision:
+        return ApprovalDecision(
+            request_id=request.request_id,
+            approved=self.approved,
+            decided_by=self.decided_by,
+            reason="static provider configuration",
+        )
+
+
+class CallbackProvider:
+    """Adapter turning any callable into a provider.
+
+    The callable receives the request and returns a boolean (or an
+    :class:`ApprovalDecision`). Useful for wiring GUI callbacks, queue
+    consumers, or test doubles without defining a class.
+    """
+
+    def __init__(
+        self,
+        callback: Callable[[ApprovalRequest], bool | ApprovalDecision | Awaitable[Any]],
+        *,
+        decided_by: str = "callback",
+    ) -> None:
+        self._callback = callback
+        self._decided_by = decided_by
+
+    async def decide(self, request: ApprovalRequest) -> ApprovalDecision:
+        outcome = self._callback(request)
+        if hasattr(outcome, "__await__"):
+            outcome = await outcome
+        if isinstance(outcome, ApprovalDecision):
+            return outcome
+        return ApprovalDecision(
+            request_id=request.request_id,
+            approved=bool(outcome),
+            decided_by=self._decided_by,
+        )
+
+
+class InteractiveConsoleProvider:
+    """Prompts a human on stdin — for CLI/debugging use only.
+
+    If stdin is not a TTY the provider auto-denies rather than hanging a
+    headless process forever (same posture as AutoDenyProvider).
+    """
+
+    def __init__(self, *, decision_ttl: float = 60.0) -> None:
+        self.decision_ttl = decision_ttl
+
+    async def decide(self, request: ApprovalRequest) -> ApprovalDecision:
+        import sys
+
+        if not sys.stdin.isatty():  # pragma: no cover - environment-dependent
+            return ApprovalDecision(
+                request_id=request.request_id,
+                approved=False,
+                decided_by="console",
+                reason="stdin is not interactive; auto-denied",
+            )
+        loop = asyncio.get_running_loop()
+        prompt = (
+            f"\n[approval] {request.tool_name} (risk={request.risk_level})\n"
+            f"  capabilities: {sorted(request.capabilities)}\n"
+            f"  arguments: {dict(request.arguments)}\n"
+            f"  reason: {request.reason}\n"
+            f"Approve? [y/N] "
+        )
+        answer = await loop.run_in_executor(None, input, prompt)
+        approved = answer.strip().lower() in {"y", "yes"}
+        return ApprovalDecision(
+            request_id=request.request_id,
+            approved=approved,
+            decided_by=f"console:{'approved' if approved else 'denied'}",
+            decision_ttl=self.decision_ttl,
+            reason="interactive console decision",
+        )
+
+
+class ApprovalManager:
+    """Creates approval requests, routes them to a provider, tracks state.
+
+    Thread-safety: the manager is asyncio-native (single event loop). The
+    registry of decisions is guarded by a plain dict + event-loop affinity;
+    cross-loop use is not supported and documented as such.
+    """
+
+    def __init__(
+        self,
+        provider: ApprovalProvider | None = None,
+        *,
+        events: EventBus | None = None,
+        default_request_ttl: float = 300.0,
+        default_decision_ttl: float = 60.0,
+    ) -> None:
+        self._provider = provider or AutoDenyProvider()
+        self._events = events
+        self._default_request_ttl = default_request_ttl
+        self._default_decision_ttl = default_decision_ttl
+        self._requests: dict[str, ApprovalRequest] = {}
+        self._decisions: dict[str, ApprovalDecision] = {}
+        self._waiters: dict[str, list[asyncio.Future[ApprovalDecision]]] = {}
+
+    def attach_events(self, events: EventBus) -> None:
+        """Route approval telemetry to an event bus (idempotent)."""
+        self._events = events
+
+    @property
+    def provider(self) -> ApprovalProvider:
+        return self._provider
+
+    def set_provider(self, provider: ApprovalProvider) -> None:
+        self._provider = provider
+
+    def create_request(
+        self,
+        *,
+        tool_name: str,
+        arguments: Mapping[str, Any],
+        capabilities: frozenset[str],
+        decision: PolicyDecision,
+        risk_level: int,
+        invocation_id: str | None = None,
+        actor_id: str | None = None,
+        agent_id: str | None = None,
+        request_ttl: float | None = None,
+    ) -> ApprovalRequest:
+        """Register a pending approval request (does not contact the provider)."""
+        request = ApprovalRequest(
+            request_id=uuid.uuid4().hex,
+            tool_name=tool_name,
+            arguments=dict(arguments),
+            capabilities=frozenset(capabilities),
+            reason=decision.reason,
+            risk_level=risk_level,
+            invocation_id=invocation_id,
+            actor_id=actor_id,
+            agent_id=agent_id,
+            request_ttl=request_ttl if request_ttl is not None else self._default_request_ttl,
+        )
+        self._requests[request.request_id] = request
+        if self._events is not None:
+            self._events.emit(
+                EventType.APPROVAL_REQUESTED,
+                invocation_id=invocation_id,
+                data={"request_id": request.request_id, "tool": tool_name},
+            )
+        return request
+
+    async def resolve(self, request: ApprovalRequest) -> ApprovalDecision:
+        """Ask the provider for a decision and record it.
+
+        Enforces the request TTL: if the provider stalls longer than the
+        request's lifetime, the outcome is an expired decision, not an
+        eternal wait.
+        """
+        provider_task = asyncio.create_task(self._provider.decide(request))
+        try:
+            decision = await asyncio.wait_for(
+                provider_task, timeout=max(0.001, request.expires_at - time.time())
+            )
+        except TimeoutError:
+            provider_task.cancel()
+            decision = ApprovalDecision(
+                request_id=request.request_id,
+                approved=False,
+                decided_by="timeout",
+                reason="approval provider did not answer within the request TTL",
+            )
+        except asyncio.CancelledError:
+            provider_task.cancel()
+            raise
+        except Exception as exc:
+            decision = ApprovalDecision(
+                request_id=request.request_id,
+                approved=False,
+                decided_by="error",
+                reason=f"approval provider failed: {exc.__class__.__name__}",
+            )
+
+        if decision.approved and request.expired:
+            decision = ApprovalDecision(
+                request_id=request.request_id,
+                approved=False,
+                decided_by="expired",
+                reason="decision arrived after the request expired",
+            )
+        self._record(request, decision)
+        return decision
+
+    def _record(self, request: ApprovalRequest, decision: ApprovalDecision) -> None:
+        self._decisions[request.request_id] = decision
+        for waiter in self._waiters.pop(request.request_id, []):
+            if not waiter.done():
+                waiter.set_result(decision)
+        if self._events is not None:
+            event_type = (
+                EventType.APPROVAL_GRANTED if decision.approved else EventType.APPROVAL_DENIED
+            )
+            self._events.emit(
+                event_type,
+                invocation_id=request.invocation_id,
+                data={
+                    "request_id": request.request_id,
+                    "tool": request.tool_name,
+                    "decided_by": decision.decided_by,
+                },
+            )
+
+    def get_decision(self, request_id: str) -> ApprovalDecision | None:
+        return self._decisions.get(request_id)
+
+    def get_request(self, request_id: str) -> ApprovalRequest | None:
+        return self._requests.get(request_id)
+
+    def validate_decision(self, decision: ApprovalDecision) -> None:
+        """Raise if a decision cannot be used to dispatch work right now.
+
+        This is the decision-TTL gate: the runtime calls it immediately
+        before transitioning to ``queued``. An approval older than its TTL
+        raises :class:`ApprovalExpiredError`, forcing re-approval.
+        """
+        if decision.expired():
+            if self._events is not None:
+                self._events.emit(
+                    EventType.APPROVAL_EXPIRED,
+                    data={
+                        "request_id": decision.request_id,
+                        "decided_at": decision.decided_at,
+                    },
+                )
+            raise ApprovalExpiredError(
+                f"approval for request {decision.request_id} expired at "
+                f"{decision.expires_at:.3f}; re-approval is required"
+            )
+        if not decision.approved:
+            raise ApprovalDeniedError(
+                f"approval request {decision.request_id} was denied by "
+                f"{decision.decided_by}: {decision.reason}",
+                capabilities=[],
+            )
+
+    async def wait_for_decision(
+        self, request: ApprovalRequest, *, timeout: float | None = None
+    ) -> ApprovalDecision:
+        """Async wait for a decision recorded via :meth:`_record`.
+
+        Used by interactive approval UIs that call ``approve()``/``deny()``
+        from other tasks.
+        """
+        existing = self._decisions.get(request.request_id)
+        if existing is not None:
+            return existing
+        waiter: asyncio.Future[ApprovalDecision] = asyncio.get_running_loop().create_future()
+        self._waiters.setdefault(request.request_id, []).append(waiter)
+        try:
+            return await asyncio.wait_for(waiter, timeout=timeout)
+        except TimeoutError as exc:
+            raise ApprovalTimeoutError(
+                f"no approval decision within {timeout}s for request {request.request_id}"
+            ) from exc
+
+    # -- programmatic decision entry points (for tests / external UIs) ------
+
+    def approve(
+        self, request_id: str, *, decided_by: str, decision_ttl: float | None = None
+    ) -> None:
+        """Record an approval programmatically (idempotent per request)."""
+        self._apply_decision(
+            request_id, approved=True, decided_by=decided_by, decision_ttl=decision_ttl
+        )
+
+    def deny(self, request_id: str, *, decided_by: str) -> None:
+        """Record a denial programmatically."""
+        self._apply_decision(request_id, approved=False, decided_by=decided_by)
+
+    def _apply_decision(
+        self,
+        request_id: str,
+        *,
+        approved: bool,
+        decided_by: str,
+        decision_ttl: float | None = None,
+    ) -> None:
+        request = self._requests.get(request_id)
+        if request is None:
+            raise KeyError(f"unknown approval request {request_id!r}")
+        if request_id in self._decisions:
+            raise ValueError(f"request {request_id!r} already has a decision")
+        if request.expired:
+            decision = ApprovalDecision(
+                request_id=request_id,
+                approved=False,
+                decided_by="expired",
+                reason="decision arrived after request expiry",
+            )
+        else:
+            decision = ApprovalDecision(
+                request_id=request_id,
+                approved=approved,
+                decided_by=decided_by,
+                decision_ttl=decision_ttl
+                if decision_ttl is not None
+                else self._default_decision_ttl,
+            )
+        self._record(request, decision)
+
+    # -- reporting -----------------------------------------------------------
+
+    def pending(self, *, tool_pattern: str | None = None) -> list[ApprovalRequest]:
+        """Requests still awaiting a decision (optionally filtered by tool)."""
+        return [
+            request
+            for request in self._requests.values()
+            if request.request_id not in self._decisions
+            and not request.expired
+            and (tool_pattern is None or fnmatch.fnmatch(request.tool_name, tool_pattern))
+        ]
+
+    def stats(self) -> dict[str, int]:
+        approved = sum(1 for d in self._decisions.values() if d.approved)
+        denied = len(self._decisions) - approved
+        return {
+            "total_requests": len(self._requests),
+            "approved": approved,
+            "denied": denied,
+            "pending": len(self.pending()),
+        }