aegize 0.2.0__py3-none-any.whl

aegize/__init__.py

@@ -0,0 +1,59 @@
+"""Aegize: infrastructure for autonomous AI agents.
+
+Aegize provides the runtime governance layer between an agent and its tools:
+identity, policy, permissions, approval workflows, and audit. Every tool call
+carries an identity, is evaluated against policy, and is written to an
+append-only audit log before it is allowed to run.
+"""
+
+from __future__ import annotations
+
+from .action import RISK_LEVELS, ToolAction
+from .audit import AuditLog
+from .context import (
+    GuardContext,
+    clear_default_context,
+    get_default_context,
+    set_default_context,
+)
+from .decorators import GuardedFunction, GuardSpec, guard, guarded_tool
+from .exceptions import (
+    AegizeError,
+    ApprovalRequired,
+    PolicyDenied,
+    PolicyLoadError,
+)
+from .guarded_tool import GuardedTool
+from .identity import AgentIdentity
+from .policy import Decision, PermissionPolicy, PolicyResult
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    # primitives
+    "AgentIdentity",
+    "ToolAction",
+    "RISK_LEVELS",
+    # policy
+    "PermissionPolicy",
+    "PolicyResult",
+    "Decision",
+    # enforcement + audit
+    "GuardedTool",
+    "AuditLog",
+    # ergonomics (v0.2)
+    "guarded_tool",
+    "guard",
+    "GuardedFunction",
+    "GuardSpec",
+    "GuardContext",
+    "set_default_context",
+    "get_default_context",
+    "clear_default_context",
+    # exceptions
+    "AegizeError",
+    "PolicyDenied",
+    "ApprovalRequired",
+    "PolicyLoadError",
+]

aegize/_time.py

@@ -0,0 +1,10 @@
+"""Internal time helpers, kept in one place so timestamps stay consistent."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def utcnow() -> datetime:
+    """Return a timezone-aware UTC timestamp."""
+    return datetime.now(timezone.utc)

aegize/action.py

@@ -0,0 +1,52 @@
+"""Tool action primitive."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+from ._time import utcnow
+
+RISK_LEVELS = ("low", "medium", "high", "critical")
+
+# Numeric ordering so that risk levels can be compared (e.g. risk_level_max).
+RISK_ORDER: dict[str, int] = {level: i for i, level in enumerate(RISK_LEVELS)}
+
+
+@dataclass
+class ToolAction:
+    """A single attempted tool call, evaluated against policy and audited.
+
+    ``ToolAction`` is normally constructed for you by :class:`GuardedTool`, but
+    it is a plain dataclass so it can be built and inspected directly in tests
+    or custom integrations.
+    """
+
+    agent_id: str
+    tool_name: str
+    operation: str
+    input_summary: str = ""
+    risk_level: str = "low"
+    action_id: str = field(default_factory=lambda: str(uuid4()))
+    timestamp: datetime = field(default_factory=utcnow)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.risk_level not in RISK_LEVELS:
+            raise ValueError(
+                f"risk_level must be one of {RISK_LEVELS}, got {self.risk_level!r}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "action_id": self.action_id,
+            "agent_id": self.agent_id,
+            "tool_name": self.tool_name,
+            "operation": self.operation,
+            "input_summary": self.input_summary,
+            "risk_level": self.risk_level,
+            "timestamp": self.timestamp.isoformat(),
+            "metadata": dict(self.metadata),
+        }

aegize/audit.py

@@ -0,0 +1,83 @@
+"""Append-only JSONL audit log.
+
+Every attempted action produces at least one audit record. Allowed actions
+produce two: one when the action is authorized (before execution) and one for
+the execution result (success or failure). The log is append-only and one JSON
+object per line, so it is trivial to tail, grep, or ship to a SIEM.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from ._time import utcnow
+from .action import ToolAction
+
+# Canonical event names written to the audit log.
+EVENT_ALLOWED = "allowed"
+EVENT_DENIED = "denied"
+EVENT_APPROVAL_REQUIRED = "approval_required"
+EVENT_EXECUTION_SUCCEEDED = "execution_succeeded"
+EVENT_EXECUTION_FAILED = "execution_failed"
+
+
+class AuditLog:
+    """Writes audit records to a JSONL file (one JSON object per line)."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        parent = self.path.parent
+        if parent and not parent.exists():
+            os.makedirs(parent, exist_ok=True)
+
+    def record(
+        self,
+        action: ToolAction,
+        event: str,
+        *,
+        reason: str | None = None,
+        error: str | None = None,
+        result_summary: str | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Append one audit entry and return the written record."""
+        entry: dict[str, Any] = {
+            "timestamp": utcnow().isoformat(),
+            "event": event,
+            "action_id": action.action_id,
+            "agent_id": action.agent_id,
+            "tool_name": action.tool_name,
+            "operation": action.operation,
+            "risk_level": action.risk_level,
+            "input_summary": action.input_summary,
+        }
+        if reason is not None:
+            entry["reason"] = reason
+        if error is not None:
+            entry["error"] = error
+        if result_summary is not None:
+            entry["result_summary"] = result_summary
+        if extra:
+            entry.update(extra)
+        self._write(entry)
+        return entry
+
+    def _write(self, entry: dict[str, Any]) -> None:
+        line = json.dumps(entry, default=str, ensure_ascii=False)
+        with open(self.path, "a", encoding="utf-8") as handle:
+            handle.write(line + "\n")
+
+    def read_all(self) -> list[dict[str, Any]]:
+        """Read every record back. Convenience for tests and small tools."""
+        if not self.path.exists():
+            return []
+        records: list[dict[str, Any]] = []
+        with open(self.path, encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if line:
+                    records.append(json.loads(line))
+        return records

aegize/context.py

@@ -0,0 +1,74 @@
+"""GuardContext: bundles the agent, policy, and audit log together.
+
+A ``GuardContext`` is the "who + rules + ledger" needed to enforce any tool
+call. It lets you stop threading ``agent`` / ``policy`` / ``audit_log`` through
+every :class:`GuardedTool` or decorated function.
+
+It can also be installed as the *default* context — either explicitly via
+:meth:`GuardContext.activate` or temporarily with a ``with`` block — so that
+``@guarded_tool``-decorated functions can be called directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .audit import AuditLog
+from .identity import AgentIdentity
+from .policy import PermissionPolicy
+
+# Explicitly-installed default (via activate()), plus a stack for `with` blocks.
+_default_context: GuardContext | None = None
+_context_stack: list[GuardContext] = []
+
+
+@dataclass
+class GuardContext:
+    """The agent, policy, and audit log required to guard a tool call."""
+
+    agent: AgentIdentity
+    policy: PermissionPolicy
+    audit_log: AuditLog
+
+    def guard(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Bind a ``@guarded_tool``-decorated function to this context.
+
+        Returns a plain callable (signature-preserving) suitable for handing to
+        a tool registry, e.g. ``server.add_tool(ctx.guard(send_email))``.
+        """
+        from .decorators import guard
+
+        return guard(fn, context=self)
+
+    def activate(self) -> GuardContext:
+        """Install this context as the process-wide default. Returns self."""
+        set_default_context(self)
+        return self
+
+    def __enter__(self) -> GuardContext:
+        _context_stack.append(self)
+        return self
+
+    def __exit__(self, *exc: Any) -> bool:
+        if _context_stack and _context_stack[-1] is self:
+            _context_stack.pop()
+        return False
+
+
+def set_default_context(context: GuardContext | None) -> None:
+    """Install (or clear, with ``None``) the process-wide default context."""
+    global _default_context
+    _default_context = context
+
+
+def get_default_context() -> GuardContext | None:
+    """Return the active context: the innermost ``with`` block, else the default."""
+    if _context_stack:
+        return _context_stack[-1]
+    return _default_context
+
+
+def clear_default_context() -> None:
+    """Remove the process-wide default context."""
+    set_default_context(None)

aegize/decorators.py

@@ -0,0 +1,139 @@
+"""The ``@guarded_tool`` decorator and the ``guard()`` adapter.
+
+These are pure ergonomics on top of :class:`GuardedTool`. Decorate a function
+once with its policy coordinates, then bind it to a :class:`GuardContext` when
+you have one::
+
+    @guarded_tool(tool_name="email", operation="send", risk_level="high")
+    def send_email(to: str, body: str) -> str:
+        ...
+
+    # later, with a context in hand:
+    server.add_tool(guard(send_email, context=ctx))
+
+The object returned by ``guard()`` is a signature-preserving callable, so tool
+registries (including MCP servers) that introspect ``__name__`` and the function
+signature keep working.
+"""
+
+from __future__ import annotations
+
+import functools
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .context import GuardContext, get_default_context
+from .exceptions import AegizeError
+from .guarded_tool import GuardedTool
+
+
+@dataclass
+class GuardSpec:
+    """The policy coordinates captured by ``@guarded_tool`` at decoration time."""
+
+    tool_name: str
+    operation: str
+    risk_level: str = "low"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class GuardedFunction:
+    """A function tagged with a :class:`GuardSpec` by ``@guarded_tool``.
+
+    Calling it directly enforces policy using the active default context (set
+    via ``with context:`` or :meth:`GuardContext.activate`). To bind it to a
+    specific context explicitly, use :func:`guard` or :meth:`bind`.
+    """
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        spec: GuardSpec,
+        context: GuardContext | None = None,
+    ) -> None:
+        functools.update_wrapper(self, func)
+        self.__wrapped__ = func
+        self.spec = spec
+        self.context = context
+
+    def bind(self, context: GuardContext) -> GuardedTool:
+        """Build a :class:`GuardedTool` for this function bound to ``context``."""
+        return GuardedTool(
+            tool_name=self.spec.tool_name,
+            operation=self.spec.operation,
+            func=self.__wrapped__,
+            agent=context.agent,
+            policy=context.policy,
+            audit_log=context.audit_log,
+            risk_level=self.spec.risk_level,
+            metadata=self.spec.metadata,
+        )
+
+    def _resolve_context(self) -> GuardContext:
+        context = self.context or get_default_context()
+        if context is None:
+            raise AegizeError(
+                "no GuardContext is active for this guarded tool; bind one with "
+                "guard(fn, context=...), enter a `with context:` block, or install "
+                "a default via context.activate()"
+            )
+        return context
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.bind(self._resolve_context())(*args, **kwargs)
+
+
+def guarded_tool(
+    *,
+    tool_name: str,
+    operation: str,
+    risk_level: str = "low",
+    metadata: dict[str, Any] | None = None,
+) -> Callable[[Callable[..., Any]], GuardedFunction]:
+    """Decorator that tags a function with its Aegize policy coordinates."""
+
+    def decorator(func: Callable[..., Any]) -> GuardedFunction:
+        spec = GuardSpec(
+            tool_name=tool_name,
+            operation=operation,
+            risk_level=risk_level,
+            metadata=dict(metadata or {}),
+        )
+        return GuardedFunction(func, spec)
+
+    return decorator
+
+
+def guard(
+    fn: Callable[..., Any],
+    *,
+    context: GuardContext | None = None,
+) -> Callable[..., Any]:
+    """Bind a ``@guarded_tool`` function to a context, returning a callable.
+
+    The returned callable preserves the original function's name, docstring, and
+    signature, so it is a drop-in replacement that tool registries can introspect.
+    """
+    if not isinstance(fn, GuardedFunction):
+        raise TypeError(
+            "guard() expects a function decorated with @guarded_tool; "
+            f"got {type(fn).__name__}"
+        )
+
+    resolved = context or fn.context or get_default_context()
+    if resolved is None:
+        raise AegizeError(
+            "guard() requires a GuardContext; pass context=... or install a "
+            "default via context.activate()"
+        )
+
+    guarded = fn.bind(resolved)
+
+    @functools.wraps(fn.__wrapped__)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return guarded(*args, **kwargs)
+
+    # Expose the underlying objects for introspection / advanced use.
+    wrapper.guarded_tool = guarded  # type: ignore[attr-defined]
+    wrapper.guard_spec = fn.spec  # type: ignore[attr-defined]
+    return wrapper

aegize/exceptions.py

@@ -0,0 +1,51 @@
+"""Exception hierarchy for Aegize.
+
+All Aegize errors derive from :class:`AegizeError`, so callers can catch
+the whole family with a single ``except`` clause while still being able to
+distinguish a hard policy denial from an approval gate.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .action import ToolAction
+
+
+class AegizeError(Exception):
+    """Base class for every error raised by Aegize."""
+
+
+class PolicyLoadError(AegizeError):
+    """Raised when a policy file cannot be read, parsed, or validated."""
+
+
+class _DecisionError(AegizeError):
+    """Shared base for errors that carry the offending action and a reason."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        reason: str | None = None,
+        action: ToolAction | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.action = action
+
+
+class PolicyDenied(_DecisionError):
+    """Raised when policy explicitly (or by default-deny) blocks an action.
+
+    The underlying tool function is never executed.
+    """
+
+
+class ApprovalRequired(_DecisionError):
+    """Raised when an action needs human approval before it may run.
+
+    The underlying tool function is never executed. A human (or an out-of-band
+    approval workflow) must authorize the action and re-issue it.
+    """

aegize/guarded_tool.py

@@ -0,0 +1,160 @@
+"""GuardedTool: the enforcement point that wraps any callable."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .action import ToolAction
+from .audit import (
+    EVENT_ALLOWED,
+    EVENT_APPROVAL_REQUIRED,
+    EVENT_DENIED,
+    EVENT_EXECUTION_FAILED,
+    EVENT_EXECUTION_SUCCEEDED,
+    AuditLog,
+)
+from .exceptions import ApprovalRequired, PolicyDenied
+from .identity import AgentIdentity
+from .policy import Decision, PermissionPolicy
+
+_SUMMARY_LIMIT = 200
+
+# Reserved keyword for attaching per-call metadata. It is stripped from the
+# arguments before the wrapped function is invoked, so the function never sees
+# it. Used to drive path allowlists and to enrich audit records at call time.
+GUARD_METADATA_KWARG = "guard_metadata"
+
+# Internal bookkeeping keys that should not be echoed back into the audit log.
+_INTERNAL_METADATA_KEYS = frozenset({"candidate_paths"})
+
+
+def _truncate(text: str, limit: int = _SUMMARY_LIMIT) -> str:
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3] + "..."
+
+
+def _summarize_inputs(args: tuple, kwargs: dict[str, Any]) -> str:
+    parts: list[str] = [repr(a) for a in args]
+    parts += [f"{k}={v!r}" for k, v in kwargs.items()]
+    return _truncate(", ".join(parts))
+
+
+def _string_inputs(args: tuple, kwargs: dict[str, Any]) -> list[str]:
+    """Strings from the call that may represent paths (for path allowlists)."""
+    candidates = [a for a in args if isinstance(a, str)]
+    candidates += [v for v in kwargs.values() if isinstance(v, str)]
+    return candidates
+
+
+class GuardedTool:
+    """Wrap a callable so every invocation is permissioned, gated, and audited.
+
+    The wrapper is itself callable, so a ``GuardedTool`` is a drop-in
+    replacement for the function it guards::
+
+        safe_search = GuardedTool(
+            tool_name="web_search",
+            operation="search",
+            func=web_search,
+            agent=agent,
+            policy=policy,
+            audit_log=audit,
+            risk_level="low",
+        )
+        result = safe_search("AI safety companies")
+
+    Order of operations on every call:
+
+    1. Build a :class:`ToolAction` describing the attempt.
+    2. Evaluate it against the :class:`PermissionPolicy`.
+    3. Audit the decision **before** any execution.
+    4. Deny -> raise :class:`PolicyDenied` (function never runs).
+       Approval -> raise :class:`ApprovalRequired` (function never runs).
+       Allow -> run the function, then audit success or failure.
+    """
+
+    def __init__(
+        self,
+        *,
+        tool_name: str,
+        operation: str,
+        func: Callable[..., Any],
+        agent: AgentIdentity,
+        policy: PermissionPolicy,
+        audit_log: AuditLog,
+        risk_level: str = "low",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.operation = operation
+        self.func = func
+        self.agent = agent
+        self.policy = policy
+        self.audit_log = audit_log
+        self.risk_level = risk_level
+        self.metadata = dict(metadata or {})
+
+    def build_action(
+        self,
+        args: tuple,
+        kwargs: dict[str, Any],
+        *,
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> ToolAction:
+        metadata = dict(self.metadata)
+        if extra_metadata:
+            metadata.update(extra_metadata)
+        metadata.setdefault("environment", self.agent.environment)
+        # Surface string arguments so path allowlists can be enforced.
+        candidates = list(metadata.get("candidate_paths") or [])
+        candidates += _string_inputs(args, kwargs)
+        metadata["candidate_paths"] = candidates
+        return ToolAction(
+            agent_id=self.agent.agent_id,
+            tool_name=self.tool_name,
+            operation=self.operation,
+            input_summary=_summarize_inputs(args, kwargs),
+            risk_level=self.risk_level,
+            metadata=metadata,
+        )
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        call_metadata = kwargs.pop(GUARD_METADATA_KWARG, None)
+        action = self.build_action(args, kwargs, extra_metadata=call_metadata)
+        audit_extra = {"metadata": self._audit_metadata(action)}
+        result = self.policy.evaluate(action)
+
+        if result.decision is Decision.DENY:
+            # Audit the denial before refusing. Function never runs.
+            self.audit_log.record(action, EVENT_DENIED, reason=result.reason, extra=audit_extra)
+            raise PolicyDenied(result.reason, reason=result.reason, action=action)
+
+        if result.decision is Decision.REQUIRE_APPROVAL:
+            # Audit the gate before refusing. Function never runs.
+            self.audit_log.record(
+                action, EVENT_APPROVAL_REQUIRED, reason=result.reason, extra=audit_extra
+            )
+            raise ApprovalRequired(result.reason, reason=result.reason, action=action)
+
+        # Allowed: audit the authorization *before* executing the function.
+        self.audit_log.record(action, EVENT_ALLOWED, reason=result.reason, extra=audit_extra)
+        try:
+            value = self.func(*args, **kwargs)
+        except Exception as exc:
+            self.audit_log.record(
+                action, EVENT_EXECUTION_FAILED, error=repr(exc), extra=audit_extra
+            )
+            raise
+        self.audit_log.record(
+            action,
+            EVENT_EXECUTION_SUCCEEDED,
+            result_summary=_truncate(repr(value)),
+            extra=audit_extra,
+        )
+        return value
+
+    @staticmethod
+    def _audit_metadata(action: ToolAction) -> dict[str, Any]:
+        """User-facing metadata for the audit log (internal keys stripped)."""
+        return {k: v for k, v in action.metadata.items() if k not in _INTERNAL_METADATA_KEYS}

aegize/identity.py

@@ -0,0 +1,47 @@
+"""Agent identity primitive."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from ._time import utcnow
+
+Environment = str  # one of: "dev", "staging", "prod"
+
+VALID_ENVIRONMENTS = ("dev", "staging", "prod")
+
+
+@dataclass
+class AgentIdentity:
+    """Represents a single AI agent that wants to use tools.
+
+    Every guarded tool call is attributed to one ``AgentIdentity``. The
+    ``agent_id`` is the stable key that policies are written against.
+    """
+
+    agent_id: str
+    name: str
+    owner: str
+    environment: Environment = "dev"
+    created_at: datetime = field(default_factory=utcnow)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.agent_id:
+            raise ValueError("agent_id must be a non-empty string")
+        if self.environment not in VALID_ENVIRONMENTS:
+            raise ValueError(
+                f"environment must be one of {VALID_ENVIRONMENTS}, got {self.environment!r}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "name": self.name,
+            "owner": self.owner,
+            "environment": self.environment,
+            "created_at": self.created_at.isoformat(),
+            "metadata": dict(self.metadata),
+        }

aegize/policy.py

@@ -0,0 +1,209 @@
+"""YAML-backed policy engine.
+
+Design goals:
+
+* **Default deny.** No matching ``allow`` rule means the action is denied.
+* **Deny wins.** An explicit ``deny`` rule overrides ``require_approval`` and
+  ``allow`` for the same tool/operation.
+* **Readable rules.** Policies are plain YAML so they can live in version
+  control and be reviewed like any other code.
+
+Evaluation order for a given action:
+
+1. ``deny``             -> :data:`Decision.DENY`
+2. ``require_approval`` -> :data:`Decision.REQUIRE_APPROVAL`
+3. ``allow``            -> :data:`Decision.ALLOW`
+4. otherwise            -> default-deny
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from .action import RISK_ORDER, ToolAction
+from .exceptions import PolicyLoadError
+
+
+class Decision(str, Enum):
+    """The three possible policy outcomes."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    REQUIRE_APPROVAL = "require_approval"
+
+
+@dataclass
+class PolicyResult:
+    """Outcome of evaluating a :class:`ToolAction` against a policy."""
+
+    decision: Decision
+    reason: str
+    matched_rule: dict[str, Any] | None = None
+
+    @property
+    def allowed(self) -> bool:
+        return self.decision is Decision.ALLOW
+
+
+def _normalize_path(value: str) -> str:
+    """Normalize a path for glob comparison (forward slashes, no leading ``./``)."""
+    norm = value.replace("\\", "/")
+    while norm.startswith("./"):
+        norm = norm[2:]
+    return norm
+
+
+def _path_matches(path: str, pattern: str) -> bool:
+    """Return True if ``path`` matches the glob ``pattern``.
+
+    ``**`` is treated like ``*`` (it matches across directory separators), which
+    is sufficient for v0.1 allowlists such as ``./safe_data/**``.
+    """
+    return fnmatch.fnmatch(_normalize_path(path), _normalize_path(pattern))
+
+
+def _tool_and_operation_match(rule: dict[str, Any], action: ToolAction) -> bool:
+    """Match a rule on tool name and (optionally) operation.
+
+    A rule with no ``operations`` list matches every operation for that tool.
+    """
+    if rule.get("tool") != action.tool_name:
+        return False
+    operations = rule.get("operations")
+    if operations is None:
+        return True
+    return action.operation in operations
+
+
+def _candidate_paths(action: ToolAction) -> list[str]:
+    """Collect strings from the action that could represent a filesystem path."""
+    candidates: list[str] = []
+    explicit = action.metadata.get("path")
+    if isinstance(explicit, str):
+        candidates.append(explicit)
+    for value in action.metadata.get("candidate_paths") or []:
+        if isinstance(value, str):
+            candidates.append(value)
+    return candidates
+
+
+def _path_rule_satisfied(rule: dict[str, Any], action: ToolAction) -> bool:
+    """If a rule constrains paths, at least one candidate path must match."""
+    patterns = rule.get("paths")
+    if patterns is None:
+        return True
+    candidates = _candidate_paths(action)
+    if not candidates:
+        return False
+    return any(_path_matches(c, p) for c in candidates for p in patterns)
+
+
+def _risk_rule_satisfied(rule: dict[str, Any], action: ToolAction) -> bool:
+    """If a rule sets ``risk_level_max``, the action's risk must not exceed it."""
+    rmax = rule.get("risk_level_max")
+    if rmax is None:
+        return True
+    if rmax not in RISK_ORDER:
+        raise PolicyLoadError(f"invalid risk_level_max in policy: {rmax!r}")
+    return RISK_ORDER[action.risk_level] <= RISK_ORDER[rmax]
+
+
+class PermissionPolicy:
+    """Evaluates :class:`ToolAction` objects against a set of per-agent rules."""
+
+    def __init__(self, agents: dict[str, Any], *, source: str | None = None) -> None:
+        self._agents = agents or {}
+        self.source = source
+
+    # -- construction ----------------------------------------------------
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], *, source: str | None = None) -> PermissionPolicy:
+        if not isinstance(data, dict):
+            raise PolicyLoadError("policy root must be a mapping")
+        agents = data.get("agents")
+        if agents is None:
+            raise PolicyLoadError("policy is missing the top-level 'agents' key")
+        if not isinstance(agents, dict):
+            raise PolicyLoadError("'agents' must be a mapping of agent_id -> rules")
+        return cls(agents, source=source)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> PermissionPolicy:
+        try:
+            import yaml
+        except ImportError as exc:  # pragma: no cover - dependency guard
+            raise PolicyLoadError("PyYAML is required to load policies from YAML") from exc
+
+        path = Path(path)
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise PolicyLoadError(f"could not read policy file: {path}") from exc
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise PolicyLoadError(f"could not parse policy YAML: {path}") from exc
+        if data is None:
+            raise PolicyLoadError(f"policy file is empty: {path}")
+        return cls.from_dict(data, source=str(path))
+
+    # -- evaluation ------------------------------------------------------
+
+    def evaluate(self, action: ToolAction) -> PolicyResult:
+        """Evaluate an action and return a :class:`PolicyResult`.
+
+        Unknown agents and tools, and any action with no matching ``allow``
+        rule, resolve to :data:`Decision.DENY`.
+        """
+        agent_rules = self._agents.get(action.agent_id)
+        if agent_rules is None:
+            return PolicyResult(
+                Decision.DENY,
+                reason=f"unknown agent '{action.agent_id}' (default deny)",
+            )
+
+        # 1. Explicit deny wins outright.
+        for rule in agent_rules.get("deny", []) or []:
+            if _tool_and_operation_match(rule, action):
+                return PolicyResult(
+                    Decision.DENY,
+                    reason=f"denied by rule for tool '{action.tool_name}'",
+                    matched_rule=rule,
+                )
+
+        # 2. Approval gate.
+        for rule in agent_rules.get("require_approval", []) or []:
+            if _tool_and_operation_match(rule, action):
+                return PolicyResult(
+                    Decision.REQUIRE_APPROVAL,
+                    reason=f"approval required for tool '{action.tool_name}'",
+                    matched_rule=rule,
+                )
+
+        # 3. Allow (subject to risk and path constraints).
+        for rule in agent_rules.get("allow", []) or []:
+            if not _tool_and_operation_match(rule, action):
+                continue
+            if not _risk_rule_satisfied(rule, action):
+                continue
+            if not _path_rule_satisfied(rule, action):
+                continue
+            return PolicyResult(
+                Decision.ALLOW,
+                reason=f"allowed by rule for tool '{action.tool_name}'",
+                matched_rule=rule,
+            )
+
+        # 4. Default deny.
+        return PolicyResult(
+            Decision.DENY,
+            reason=(
+                f"no matching allow rule for tool '{action.tool_name}' "
+                f"operation '{action.operation}' (default deny)"
+            ),
+        )

aegize-0.2.0.dist-info/METADATA

@@ -0,0 +1,414 @@
+Metadata-Version: 2.4
+Name: aegize
+Version: 0.2.0
+Summary: Infrastructure for autonomous AI agents: identity, policy, permissions, approval workflows, and audit.
+Project-URL: Homepage, https://aegize.com
+Project-URL: Repository, https://github.com/gggaswint/aegize
+Project-URL: Documentation, https://github.com/gggaswint/aegize#readme
+Project-URL: Issues, https://github.com/gggaswint/aegize/issues
+Author-email: Geoffrey Gaswint <ggaswint@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,approval,audit,governance,identity,infrastructure,llm,permissions,policy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gggaswint/aegize/main/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/gggaswint/aegize/main/assets/logo-light.png" alt="Aegize" width="150">
+  </picture>
+</p>
+
+# Aegize
+
+Infrastructure for autonomous AI agents.
+
+**[Website](https://aegize.com)** • **[GitHub](https://github.com/gggaswint/aegize)**
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776ab?style=flat-square)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-3fb950?style=flat-square)](./LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-d29922?style=flat-square)](#roadmap)
+[![Version](https://img.shields.io/badge/version-0.2.0-5b9dff?style=flat-square)](#roadmap)
+
+Aegize is the runtime layer between autonomous AI agents and the tools they use.
+
+It provides identity, policy enforcement, permissions, approval workflows, audit
+logging, observability, and runtime governance for every AI action.
+
+> Every agent action must have identity, permission, policy enforcement, and audit.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gggaswint/aegize/main/assets/demo.gif" alt="Aegize demo: an agent makes three tool calls — web search allowed, email approval required, shell command denied — each governed and audited by Aegize" width="1000">
+</p>
+
+## Architecture
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gggaswint/aegize/main/assets/architecture.svg" alt="How Aegize fits into an AI agent stack: AI frameworks send tool calls into the Aegize runtime (identity, policy engine, permissions, approval workflows, audit logging, observability); only allowed actions reach tools. Every AI action passes through Aegize before reaching the outside world." width="900">
+</p>
+
+---
+
+## See it in action
+
+One agent attempts three tool calls. Aegize **allows** the web search,
+**holds the email for approval**, **blocks the shell command**, and writes an
+audit record for every attempt.
+
+```text
+$ python examples/demo_story.py
+
+[1] web_search.search   query='AI safety companies'
+    ALLOWED  -> results for 'AI safety companies'
+
+[2] email.send          to='ceo@example.com'
+    APPROVAL REQUIRED  -> held for human review (not executed)
+               reason: approval required for tool 'email'
+
+[3] shell.execute       cmd='rm -rf /var/data'
+    DENIED  -> blocked before execution
+               reason: denied by rule for tool 'shell'
+
+Audit trail:
+    allowed              web_search   search
+    execution_succeeded  web_search   search
+    approval_required    email        send
+    denied               shell        execute
+
+3 actions attempted · 1 allowed · 1 awaiting approval · 1 denied · 4 audit records written
+```
+
+The gated and denied calls never reach the underlying functions. See
+[Demo](#demo) to run it yourself.
+
+## Why Aegize?
+
+AI systems are moving from answering questions to taking actions — running
+shells, sending email, moving money, calling internal APIs. A model that only
+returns text is easy to contain. An agent that *acts* is not: it needs an
+identity, scoped permissions, approvals for high-impact operations, and a record
+of everything it did.
+
+That governance layer is usually missing today, and the model's own judgment
+stands in for it. Aegize is the runtime infrastructure that fills the gap, so
+organizations can let agents take actions without giving up control or
+visibility. Security is one capability this provides; operability, reviewability,
+and confidence in deployment are the rest.
+
+## Project Vision
+
+> Every meaningful AI action should pass through trusted runtime infrastructure
+> before reaching the outside world.
+
+## What Aegize provides
+
+- **`AgentIdentity`** — a durable identity for each agent (owner, environment,
+  metadata).
+- **`PermissionPolicy`** — a YAML policy engine that returns `allow`, `deny`, or
+  `require_approval`.
+- **`GuardedTool` / `@guarded_tool`** — the enforcement point: wrap any callable
+  so it is identified, permissioned, gated, and audited.
+- **`AuditLog`** — an append-only JSONL record of every attempt and outcome.
+- **Typed, dependency-light, and easy to extend.** One runtime dependency
+  (PyYAML).
+
+## Install
+
+```bash
+pip install aegize
+```
+
+Or from source (for development):
+
+```bash
+git clone https://github.com/gggaswint/aegize.git
+cd aegize
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from aegize import AgentIdentity, PermissionPolicy, GuardedTool, AuditLog
+
+agent = AgentIdentity(
+    agent_id="research_bot",
+    name="Research Bot",
+    owner="Geoffrey",
+    environment="dev",
+)
+
+policy = PermissionPolicy.from_yaml("aegize.yaml")
+audit = AuditLog("audit.jsonl")
+
+def web_search(query: str) -> str:
+    return f"searched: {query}"
+
+safe_web_search = GuardedTool(
+    tool_name="web_search",
+    operation="search",
+    func=web_search,
+    agent=agent,
+    policy=policy,
+    audit_log=audit,
+    risk_level="low",
+)
+
+result = safe_web_search("AI safety companies")
+```
+
+If the policy allows the action, the function runs and two audit records are
+written (authorization + result). If not, Aegize raises `PolicyDenied` or
+`ApprovalRequired` and the function never executes.
+
+```python
+from aegize import PolicyDenied, ApprovalRequired
+
+try:
+    safe_web_search("AI safety companies")
+except ApprovalRequired as exc:
+    # route to a human approval workflow
+    ...
+except PolicyDenied as exc:
+    # blocked outright
+    ...
+```
+
+## Decorator quickstart (v0.2)
+
+You don't have to wrap every function by hand. Declare a tool once with
+`@guarded_tool`, bundle your agent/policy/audit into a `GuardContext`, and bind
+them together when you have a context.
+
+```python
+from aegize import (
+    AgentIdentity, PermissionPolicy, AuditLog,
+    GuardContext, guarded_tool, guard, ApprovalRequired,
+)
+
+@guarded_tool(tool_name="email", operation="send", risk_level="high")
+def send_email(to: str, body: str) -> str:
+    ...  # your real implementation
+
+ctx = GuardContext(
+    agent=AgentIdentity(agent_id="research_bot", name="Research Bot", owner="Geoffrey"),
+    policy=PermissionPolicy.from_yaml("aegize.yaml"),
+    audit_log=AuditLog("audit.jsonl"),
+)
+
+# Bind to a context -> a plain, signature-preserving callable you can register.
+guarded_send = guard(send_email, context=ctx)
+# e.g. server.add_tool(guarded_send)   # MCP / any tool registry
+
+try:
+    guarded_send("ceo@example.com", "Q3 numbers")
+except ApprovalRequired:
+    ...  # gated for human approval; send_email never ran
+```
+
+`guard()` returns a callable that preserves the original `__name__`,
+docstring, and signature, so tool registries (including MCP servers) that
+introspect functions keep working.
+
+**Default context.** Inside a `with ctx:` block (or after `ctx.activate()`),
+decorated tools can be called directly:
+
+```python
+with ctx:
+    send_email("ceo@example.com", "Q3 numbers")  # uses the active context
+```
+
+**Per-call metadata.** Pass `guard_metadata=` to any guarded call to attach
+context for policy decisions (e.g. a path for an allowlist) and the audit log.
+It is stripped before your function runs:
+
+```python
+guarded_read("report", guard_metadata={"path": "./safe_data/report.txt"})
+```
+
+Both styles are fully supported — use `GuardedTool(...)` directly when you want
+explicit objects, or the decorator when you want ergonomics. They share the same
+enforcement and audit code.
+
+## Policy YAML
+
+Policies are per-agent. Each agent has `allow`, `require_approval`, and `deny`
+sections. Evaluation order is **deny → require_approval → allow → default-deny**,
+so an explicit `deny` always wins and anything unlisted is denied.
+
+```yaml
+agents:
+  research_bot:
+    allow:
+      - tool: web_search
+        operations: ["search"]
+        risk_level_max: medium      # block this rule above 'medium' risk
+      - tool: file_reader
+        operations: ["read"]
+        paths:
+          - "./safe_data/**"        # only inside the allowlisted path
+
+    require_approval:
+      - tool: email
+        operations: ["send"]
+      - tool: shell
+        operations: ["execute"]
+
+    deny:
+      - tool: payments
+        operations: ["charge"]
+      - tool: shell
+        operations: ["rm", "delete"]
+```
+
+Rule fields:
+
+| Field            | Applies to              | Meaning                                                            |
+| ---------------- | ----------------------- | ----------------------------------------------------------------- |
+| `tool`           | all                     | Tool name to match.                                               |
+| `operations`     | all                     | Operations the rule covers. Omit to match every operation.        |
+| `risk_level_max` | `allow`                 | Highest risk this rule permits (`low`…`critical`).                |
+| `paths`          | `allow`                 | Glob allowlist; a string argument must match one of these.        |
+
+> **Path matching:** when a rule has `paths`, Aegize checks the string
+> arguments of the call (and `metadata["path"]`) against the glob patterns. A
+> call with no matching path is denied.
+
+## Audit log
+
+Every attempt is appended to a JSONL file — one self-contained JSON object per
+line, easy to tail, `grep`, or ship to a SIEM. A single allowed call:
+
+```json
+{"timestamp": "2026-06-27T18:00:00+00:00", "event": "allowed", "agent_id": "research_bot", "tool_name": "web_search", "operation": "search", "risk_level": "low", "input_summary": "'AI safety companies'", "reason": "allowed by rule for tool 'web_search'"}
+{"timestamp": "2026-06-27T18:00:00+00:00", "event": "execution_succeeded", "agent_id": "research_bot", "tool_name": "web_search", "operation": "search", "risk_level": "low", "result_summary": "'searched: AI safety companies'"}
+```
+
+Events: `allowed`, `denied`, `approval_required`, `execution_succeeded`,
+`execution_failed`. The authorization decision is always written **before** the
+function runs; the result is written after. Reading the log back is one call:
+
+```python
+for record in audit.read_all():
+    print(record["event"], record["tool_name"], record["operation"])
+```
+
+## Demo
+
+The 60-second story — one agent, three tool calls, three outcomes, all audited:
+
+```bash
+python examples/demo_story.py
+```
+
+It runs the [`See it in action`](#see-it-in-action) flow above against
+[`examples/demo_policy.yaml`](./examples/demo_policy.yaml) and prints the path to
+the audit log it wrote.
+
+## Examples
+
+More runnable scripts live in [`examples/`](./examples):
+
+```bash
+python examples/basic_allow.py      # allowed web_search runs
+python examples/denied_shell.py     # denied shell command is blocked
+python examples/approval_email.py   # email send raises ApprovalRequired
+python examples/decorator_usage.py  # @guarded_tool + GuardContext (v0.2)
+python examples/demo_story.py       # the full allow / approve / deny story
+```
+
+## Enforcement guarantees
+
+- **Default deny.** No matching `allow` rule means the action is denied.
+- **Deny wins.** An explicit `deny` overrides `require_approval` and `allow`.
+- **Gated actions never execute.** `deny` and `require_approval` raise before
+  the wrapped function is called.
+- **Audit-first.** The decision is recorded before any execution is attempted;
+  the result is recorded after.
+
+## Project documents
+
+The operating documents for Aegize — useful for contributors and for
+understanding where the project is headed.
+
+**Direction**
+
+- [Vision](./docs/vision.md) — the thesis, the problem, and the long-term ambition.
+- [Roadmap](./docs/roadmap.md) — from the current SDK to runtime governance.
+- [Architecture](./docs/architecture.md) — primitives, runtime flow, and trust model.
+
+**Operating**
+
+- [Principles](./docs/principles.md) — the engineering and product tie-breakers.
+- [Anti-goals](./docs/anti-goals.md) — what Aegize is deliberately not.
+- [Brand](./docs/brand.md) — positioning, messaging, and visual language.
+
+**Process & record**
+
+- [Decisions](./docs/decisions.md) — the record of why things are the way they are.
+- [Open questions](./docs/questions.md) — unresolved product and architecture questions.
+- [RFCs](./rfcs/README.md) — how significant changes are proposed and recorded.
+- [Launch checklist](./docs/launch-checklist.md) — what's done and what's left to launch.
+- [Next steps](./docs/next-steps.md) — the focused two-week execution plan.
+- [CLAUDE.md](./CLAUDE.md) — operating instructions for AI coding sessions.
+
+## Roadmap
+
+- ~~`@guarded_tool` decorator + `GuardContext` ergonomics.~~ ✅ v0.2
+- Policy schema validation and a `aegize lint` CLI.
+- First-class adapters for popular agent frameworks (a thin MCP registration
+  helper on top of the v0.2 `guard()` callable).
+- Pluggable approval backends (Slack, webhook, queue) for `require_approval`.
+- Pluggable audit sinks (stdout, syslog, S3, SIEM) beyond local JSONL.
+- Per-environment policy overlays (`dev` / `staging` / `prod`).
+- Rate limits and budget/quota controls per agent and tool.
+- Signed, tamper-evident audit logs.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest          # run the test suite
+ruff check .    # lint
+```
+
+CI runs the same `pytest` + `ruff` checks on every push and pull request across
+Python 3.9–3.12.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev
+setup, the project's scope and design principles, and the bar for a mergeable
+change.
+
+> **Before making major changes, read [CLAUDE.md](./CLAUDE.md) and the project
+> documents in [`docs/`](./docs).** They are the source of truth for Aegize's
+> direction, positioning, and design. (`python scripts/context_check.py` confirms
+> they're present.)
+
+## Reporting vulnerabilities
+
+Aegize governs what agents are allowed to do, so we treat weaknesses in it
+seriously. Please report vulnerabilities privately — see
+[SECURITY.md](./SECURITY.md). Do not open a public issue for a suspected
+vulnerability.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

aegize-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+aegize/__init__.py,sha256=Bx37v6_UqNEJTiEQQhbapvqOdSwBsj09pfG26seM540,1445
+aegize/_time.py,sha256=SWzO6a_wFobnUcNNt-G83xC8tL198twEGinmLTV9whg,270
+aegize/action.py,sha256=PrER3F5wNDgMchwi6auyjkFU5XETlGf3g7RgbyhiJfs,1650
+aegize/audit.py,sha256=-ySHTlsie2poXqkXc-rkEFuAfOidSLCSHYPnRv8T3tQ,2764
+aegize/context.py,sha256=U7eYRHGFog6SPWk6Eu-08LI7Rny99mx-5DSDq469JsA,2412
+aegize/decorators.py,sha256=YNoLyKswX2ilNNcg05Y-WhVb8f6Ls-0HkX73rNzPjuU,4566
+aegize/exceptions.py,sha256=6ZQNLQiO0wrVfR3vGwf_VQLZ6Koa8m94vAS0b3JusFs,1407
+aegize/guarded_tool.py,sha256=EYlKXf8QcIBvuDvQM1QjLP40uiqTtDFtBP8eRh69GmE,5791
+aegize/identity.py,sha256=iYlm4RS5jVLqWeQsc-1e4FW65obFv8d1DCeOdO4RPcE,1386
+aegize/policy.py,sha256=z4Yubn2xqXFJmQsL8ngR4fS4Ja0EH2Kb07DfqO2LHk8,7342
+aegize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aegize-0.2.0.dist-info/METADATA,sha256=I0R3nteMbeO2RYdvOD1mxew81XLZor2KLTdavFCoOKU,15404
+aegize-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+aegize-0.2.0.dist-info/licenses/LICENSE,sha256=-TosaVc9rSOwa4-p2Td4X3C5lMxLaJM8Cff0X-Rlb7M,1065
+aegize-0.2.0.dist-info/RECORD,,

aegize-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

aegize-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoffrey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.