weaver-kernel 0.3.0__py3-none-any.whl

agent_kernel/__init__.py

@@ -0,0 +1,139 @@
+"""agent-kernel: capability-based security kernel for AI agents.
+
+Public API
+----------
+
+Core classes::
+
+    from agent_kernel import Kernel, CapabilityRegistry
+    from agent_kernel import Capability, Principal
+    from agent_kernel import SafetyClass, SensitivityTag
+
+Token management::
+
+    from agent_kernel import HMACTokenProvider, CapabilityToken
+
+Policy::
+
+    from agent_kernel import DefaultPolicyEngine
+
+Firewall::
+
+    from agent_kernel import Firewall, Budgets
+
+Handles & traces::
+
+    from agent_kernel import HandleStore, TraceStore
+
+Errors::
+
+    from agent_kernel import (
+        AgentKernelError,
+        TokenExpired, TokenInvalid, TokenScopeError,
+        PolicyDenied, DriverError, FirewallError,
+        CapabilityNotFound, HandleNotFound, HandleExpired,
+    )
+"""
+
+from .drivers.base import Driver, ExecutionContext
+from .drivers.http import HTTPDriver
+from .drivers.memory import InMemoryDriver, make_billing_driver
+from .enums import SafetyClass, SensitivityTag
+from .errors import (
+    AgentKernelError,
+    CapabilityAlreadyRegistered,
+    CapabilityNotFound,
+    DriverError,
+    FirewallError,
+    HandleExpired,
+    HandleNotFound,
+    PolicyDenied,
+    TokenExpired,
+    TokenInvalid,
+    TokenRevoked,
+    TokenScopeError,
+)
+from .firewall.budgets import Budgets
+from .firewall.transform import Firewall
+from .handles import HandleStore
+from .kernel import Kernel
+from .models import (
+    ActionTrace,
+    Capability,
+    CapabilityGrant,
+    CapabilityRequest,
+    Frame,
+    Handle,
+    ImplementationRef,
+    PolicyDecision,
+    Principal,
+    Provenance,
+    RawResult,
+    ResponseMode,
+    RoutePlan,
+)
+from .policy import DefaultPolicyEngine
+from .registry import CapabilityRegistry
+from .router import StaticRouter
+from .tokens import CapabilityToken, HMACTokenProvider
+from .trace import TraceStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # version
+    "__version__",
+    # kernel
+    "Kernel",
+    # registry
+    "CapabilityRegistry",
+    # models
+    "Capability",
+    "CapabilityGrant",
+    "CapabilityRequest",
+    "CapabilityToken",
+    "Frame",
+    "Handle",
+    "ImplementationRef",
+    "PolicyDecision",
+    "Principal",
+    "Provenance",
+    "RawResult",
+    "ResponseMode",
+    "RoutePlan",
+    "ActionTrace",
+    # enums
+    "SafetyClass",
+    "SensitivityTag",
+    # errors
+    "AgentKernelError",
+    "CapabilityAlreadyRegistered",
+    "CapabilityNotFound",
+    "DriverError",
+    "FirewallError",
+    "HandleExpired",
+    "HandleNotFound",
+    "PolicyDenied",
+    "TokenExpired",
+    "TokenInvalid",
+    "TokenRevoked",
+    "TokenScopeError",
+    # policy
+    "DefaultPolicyEngine",
+    # tokens
+    "HMACTokenProvider",
+    # router
+    "StaticRouter",
+    # drivers
+    "Driver",
+    "ExecutionContext",
+    "InMemoryDriver",
+    "HTTPDriver",
+    "make_billing_driver",
+    # firewall
+    "Firewall",
+    "Budgets",
+    # stores
+    "HandleStore",
+    "TraceStore",
+]

agent_kernel/drivers/__init__.py

@@ -0,0 +1,7 @@
+"""Driver sub-package exports."""
+
+from .base import Driver, ExecutionContext
+from .http import HTTPDriver
+from .memory import InMemoryDriver
+
+__all__ = ["Driver", "ExecutionContext", "HTTPDriver", "InMemoryDriver"]

agent_kernel/drivers/base.py

@@ -0,0 +1,42 @@
+"""Base driver protocol and execution context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from ..models import RawResult
+
+
+@dataclass(slots=True)
+class ExecutionContext:
+    """Runtime context passed to a driver when executing a capability."""
+
+    capability_id: str
+    principal_id: str
+    args: dict[str, Any] = field(default_factory=dict)
+    constraints: dict[str, Any] = field(default_factory=dict)
+    action_id: str = ""
+
+
+class Driver(Protocol):
+    """Interface for capability execution drivers."""
+
+    @property
+    def driver_id(self) -> str:
+        """Unique identifier for this driver instance."""
+        ...
+
+    async def execute(self, ctx: ExecutionContext) -> RawResult:
+        """Execute a capability and return a raw result.
+
+        Args:
+            ctx: Execution context including capability ID, args, and constraints.
+
+        Returns:
+            The unfiltered :class:`RawResult` from the underlying system.
+
+        Raises:
+            DriverError: If execution fails.
+        """
+        ...

agent_kernel/drivers/http.py

@@ -0,0 +1,125 @@
+"""HTTPDriver: execute capabilities against HTTP APIs using httpx."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from ..errors import DriverError
+from ..models import RawResult
+from .base import ExecutionContext
+
+
+@dataclass
+class HTTPEndpoint:
+    """Describes an HTTP endpoint for a capability operation."""
+
+    url: str
+    method: str = "GET"
+    headers: dict[str, str] = field(default_factory=dict)
+    timeout: float | None = None
+    """Per-endpoint timeout in seconds. Falls back to the driver's ``default_timeout``."""
+
+
+class HTTPDriver:
+    """A driver that invokes capabilities via HTTP using :mod:`httpx`.
+
+    Each operation must be registered with an :class:`HTTPEndpoint`.
+    The driver performs *synchronous* execution inside an async method by
+    using ``httpx.AsyncClient`` for proper async support.
+    """
+
+    def __init__(
+        self,
+        driver_id: str = "http",
+        *,
+        base_headers: dict[str, str] | None = None,
+        default_timeout: float = 30.0,
+    ) -> None:
+        self._driver_id = driver_id
+        self._endpoints: dict[str, HTTPEndpoint] = {}
+        self._base_headers = base_headers or {}
+        self._default_timeout = default_timeout
+
+    @property
+    def driver_id(self) -> str:
+        """Unique identifier for this driver."""
+        return self._driver_id
+
+    def register_endpoint(self, operation: str, endpoint: HTTPEndpoint) -> None:
+        """Register an HTTP endpoint for an operation.
+
+        Args:
+            operation: The operation name to handle.
+            endpoint: The :class:`HTTPEndpoint` configuration.
+        """
+        self._endpoints[operation] = endpoint
+
+    async def execute(self, ctx: ExecutionContext) -> RawResult:
+        """Execute an HTTP request for the given context.
+
+        The operation is resolved from ``ctx.args.get("operation")`` first,
+        then falls back to ``ctx.capability_id``.
+
+        Args:
+            ctx: The execution context.
+
+        Returns:
+            :class:`RawResult` containing the parsed JSON response.
+
+        Raises:
+            DriverError: If the endpoint is not registered or the request fails.
+        """
+        operation = str(ctx.args.get("operation", ctx.capability_id))
+        endpoint = self._endpoints.get(operation)
+        if endpoint is None:
+            raise DriverError(
+                f"HTTPDriver '{self._driver_id}' has no endpoint for operation='{operation}'."
+            )
+
+        headers = {**self._base_headers, **endpoint.headers}
+        params: dict[str, Any] = {}
+        json_body: dict[str, Any] | None = None
+
+        if endpoint.method.upper() == "GET":
+            params = {k: v for k, v in ctx.args.items() if k != "operation"}
+        else:
+            json_body = {k: v for k, v in ctx.args.items() if k != "operation"}
+
+        effective_timeout = (
+            endpoint.timeout if endpoint.timeout is not None else self._default_timeout
+        )
+
+        try:
+            async with httpx.AsyncClient(headers=headers, timeout=effective_timeout) as client:
+                if endpoint.method.upper() == "GET":
+                    response = await client.get(endpoint.url, params=params)
+                elif endpoint.method.upper() == "POST":
+                    response = await client.post(endpoint.url, json=json_body)
+                elif endpoint.method.upper() == "PUT":
+                    response = await client.put(endpoint.url, json=json_body)
+                elif endpoint.method.upper() == "DELETE":
+                    response = await client.delete(endpoint.url, params=params)
+                else:
+                    response = await client.request(
+                        endpoint.method.upper(), endpoint.url, json=json_body
+                    )
+                response.raise_for_status()
+                data: Any = response.json()
+        except httpx.HTTPStatusError as exc:
+            raise DriverError(
+                f"HTTPDriver '{self._driver_id}': HTTP {exc.response.status_code} "
+                f"from {endpoint.url}: {exc.response.text[:200]}"
+            ) from exc
+        except httpx.RequestError as exc:
+            raise DriverError(
+                f"HTTPDriver '{self._driver_id}': Request to {endpoint.url} failed: {exc}"
+            ) from exc
+
+        return RawResult(
+            capability_id=ctx.capability_id,
+            data=data,
+            metadata={"status_code": response.status_code, "url": endpoint.url},
+        )

agent_kernel/drivers/memory.py

@@ -0,0 +1,171 @@
+"""In-memory driver for testing and local demos."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from typing import Any
+
+from ..errors import DriverError
+from ..models import RawResult
+from .base import ExecutionContext
+
+Handler = Callable[[ExecutionContext], Any]
+
+
+class InMemoryDriver:
+    """A driver that executes capabilities using registered Python callables.
+
+    This driver is primarily intended for unit tests, demos, and
+    local development where no external API is available.
+    """
+
+    def __init__(self, driver_id: str = "memory") -> None:
+        self._driver_id = driver_id
+        self._handlers: dict[str, Handler] = {}
+
+    @property
+    def driver_id(self) -> str:
+        """Unique identifier for this driver."""
+        return self._driver_id
+
+    def register_handler(self, operation: str, handler: Handler) -> None:
+        """Register a Python callable as the handler for an operation.
+
+        Args:
+            operation: The operation name (must match ``ImplementationRef.operation``).
+            handler: A callable ``(ExecutionContext) -> Any`` that performs the operation.
+        """
+        self._handlers[operation] = handler
+
+    async def execute(self, ctx: ExecutionContext) -> RawResult:
+        """Execute a capability via its registered handler.
+
+        The operation is looked up from ``ctx.args.get("operation")`` first,
+        then falls back to ``ctx.capability_id``.
+
+        Args:
+            ctx: The execution context.
+
+        Returns:
+            :class:`RawResult` wrapping the handler's return value.
+
+        Raises:
+            DriverError: If no handler is registered or the handler raises.
+        """
+        operation = str(ctx.args.get("operation", ctx.capability_id))
+        handler = self._handlers.get(operation)
+        if handler is None:
+            raise DriverError(
+                f"InMemoryDriver '{self._driver_id}' has no handler for "
+                f"operation='{operation}'. Register one with register_handler()."
+            )
+        try:
+            data = handler(ctx)
+        except Exception as exc:
+            raise DriverError(f"Handler for operation='{operation}' raised: {exc}") from exc
+        return RawResult(capability_id=ctx.capability_id, data=data)
+
+
+# ── Billing dataset factory ───────────────────────────────────────────────────
+
+
+def _make_billing_dataset(n: int = 200) -> list[dict[str, Any]]:
+    """Generate a deterministic synthetic billing dataset.
+
+    Uses :class:`random.Random` seeded with ``42`` so the output is always
+    the same regardless of global random state.
+
+    Args:
+        n: Number of invoice records to generate.
+
+    Returns:
+        A list of invoice dicts.
+    """
+    rng = random.Random(42)
+    statuses = ["paid", "unpaid", "overdue"]
+    currencies = ["USD", "EUR", "GBP"]
+    first_names = ["Alice", "Bob", "Carol", "Dave", "Eve", "Frank", "Grace", "Hiro"]
+    last_names = ["Smith", "Jones", "Lee", "Brown", "Taylor", "Wilson", "Davis"]
+
+    records: list[dict[str, Any]] = []
+    for i in range(1, n + 1):
+        fname = rng.choice(first_names)
+        lname = rng.choice(last_names)
+        name = f"{fname} {lname}"
+        email = f"{fname.lower()}.{lname.lower()}{i}@example.com"
+        phone = f"+1-555-{rng.randint(1000, 9999)}"
+        amount = round(rng.uniform(10.0, 5000.0), 2)
+        currency = rng.choice(currencies)
+        status = rng.choice(statuses)
+        year = rng.randint(2023, 2024)
+        month = rng.randint(1, 12)
+        day = rng.randint(1, 28)
+        date_str = f"{year}-{month:02d}-{day:02d}"
+        line_items = [
+            {
+                "description": f"Item {j}",
+                "qty": rng.randint(1, 5),
+                "unit_price": round(rng.uniform(5.0, 500.0), 2),
+            }
+            for j in range(1, rng.randint(1, 4) + 1)
+        ]
+        records.append(
+            {
+                "id": f"INV-{i:04d}",
+                "customer_name": name,
+                "email": email,
+                "phone": phone,
+                "amount": amount,
+                "currency": currency,
+                "status": status,
+                "date": date_str,
+                "line_items": line_items,
+            }
+        )
+    return records
+
+
+BILLING_DATASET: list[dict[str, Any]] = _make_billing_dataset()
+
+
+def make_billing_driver() -> InMemoryDriver:
+    """Return an :class:`InMemoryDriver` pre-loaded with billing operations.
+
+    Operations:
+        - ``list_invoices`` — returns all invoices (filtered by ``status`` if provided).
+        - ``get_invoice`` — returns a single invoice by ``id``.
+        - ``summarize_spend`` — returns total spend per currency/status.
+
+    Returns:
+        A fully configured :class:`InMemoryDriver`.
+    """
+    driver = InMemoryDriver(driver_id="billing")
+
+    def list_invoices(ctx: ExecutionContext) -> list[dict[str, Any]]:
+        status_filter = ctx.args.get("status")
+        data = BILLING_DATASET
+        if status_filter:
+            data = [r for r in data if r["status"] == status_filter]
+        return data
+
+    def get_invoice(ctx: ExecutionContext) -> dict[str, Any] | None:
+        invoice_id = ctx.args.get("id")
+        for record in BILLING_DATASET:
+            if record["id"] == invoice_id:
+                return record
+        return None
+
+    def summarize_spend(ctx: ExecutionContext) -> dict[str, Any]:
+        totals: dict[str, dict[str, float]] = {}
+        for record in BILLING_DATASET:
+            cur = record["currency"]
+            sta = record["status"]
+            totals.setdefault(cur, {}).setdefault(sta, 0.0)
+            totals[cur][sta] = round(totals[cur][sta] + record["amount"], 2)
+        return {"totals": totals, "invoice_count": len(BILLING_DATASET)}
+
+    driver.register_handler("list_invoices", list_invoices)
+    driver.register_handler("get_invoice", get_invoice)
+    driver.register_handler("summarize_spend", summarize_spend)
+    return driver

agent_kernel/enums.py

@@ -0,0 +1,32 @@
+"""Enumerations for SafetyClass and SensitivityTag."""
+
+from enum import Enum
+
+
+class SafetyClass(str, Enum):
+    """Classifies the danger level of a capability's side-effects."""
+
+    READ = "READ"
+    """No side-effects; safe to retry."""
+
+    WRITE = "WRITE"
+    """Mutates state; requires justification and writer/admin role."""
+
+    DESTRUCTIVE = "DESTRUCTIVE"
+    """Irreversible; requires admin role."""
+
+
+class SensitivityTag(str, Enum):
+    """Tags data sensitivity requirements on a capability."""
+
+    NONE = "NONE"
+    """No special sensitivity."""
+
+    PII = "PII"
+    """Personally identifiable information (name, email, phone, SSN)."""
+
+    PCI = "PCI"
+    """Payment card industry data (card numbers, CVV)."""
+
+    SECRETS = "SECRETS"
+    """Credentials, API keys, tokens."""

agent_kernel/errors.py

@@ -0,0 +1,67 @@
+"""Custom exception hierarchy for agent-kernel."""
+
+
+class AgentKernelError(Exception):
+    """Base class for all agent-kernel errors."""
+
+
+# ── Token errors ──────────────────────────────────────────────────────────────
+
+
+class TokenExpired(AgentKernelError):
+    """Raised when a token's ``expires_at`` is in the past."""
+
+
+class TokenInvalid(AgentKernelError):
+    """Raised when a token's HMAC signature does not verify."""
+
+
+class TokenScopeError(AgentKernelError):
+    """Raised when a token is used by the wrong principal or for the wrong capability."""
+
+
+class TokenRevoked(AgentKernelError):
+    """Raised when a revoked token is presented for verification."""
+
+
+# ── Policy errors ─────────────────────────────────────────────────────────────
+
+
+class PolicyDenied(AgentKernelError):
+    """Raised when the policy engine rejects a capability request."""
+
+
+# ── Driver errors ─────────────────────────────────────────────────────────────
+
+
+class DriverError(AgentKernelError):
+    """Raised when a driver fails to execute a capability."""
+
+
+# ── Firewall errors ───────────────────────────────────────────────────────────
+
+
+class FirewallError(AgentKernelError):
+    """Raised when the context firewall cannot transform a raw result."""
+
+
+# ── Registry / lookup errors ──────────────────────────────────────────────────
+
+
+class CapabilityAlreadyRegistered(AgentKernelError):
+    """Raised when a capability with the same ID is already registered."""
+
+
+class CapabilityNotFound(AgentKernelError):
+    """Raised when a capability ID is not found in the registry."""
+
+
+# ── Handle errors ─────────────────────────────────────────────────────────────
+
+
+class HandleNotFound(AgentKernelError):
+    """Raised when a handle ID is not found in the handle store."""
+
+
+class HandleExpired(AgentKernelError):
+    """Raised when a handle's TTL has elapsed."""

agent_kernel/firewall/__init__.py

@@ -0,0 +1,8 @@
+"""Firewall sub-package exports."""
+
+from .budgets import Budgets
+from .redaction import redact
+from .summarize import summarize
+from .transform import Firewall
+
+__all__ = ["Budgets", "Firewall", "redact", "summarize"]

agent_kernel/firewall/budgets.py

@@ -0,0 +1,26 @@
+"""Budgets dataclass for the context firewall.
+
+Canonical definition of :class:`Budgets`.  Re-exported via
+``agent_kernel.firewall`` and the top-level ``agent_kernel`` package.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Budgets:
+    """Budget constraints enforced by the context firewall.
+
+    Attributes:
+        max_rows: Maximum number of rows to include in a table preview.
+        max_fields: Maximum number of fields per row.
+        max_chars: Maximum total characters in the frame output.
+        max_depth: Maximum nesting depth when traversing dict/list values.
+    """
+
+    max_rows: int = 50
+    max_fields: int = 20
+    max_chars: int = 4000
+    max_depth: int = 3