agec 0.1.0__py3-none-any.whl

agec/__init__.py

@@ -0,0 +1,44 @@
+"""AGEC — Authorized Governance Execution Context.
+
+A pre-execution governance layer for AI agents. Every agent action is
+validated for intent, semantic context, execution path, and data
+processing permissions before the tool call is allowed to run.
+
+Quick start::
+
+    from agec import guard
+
+    @guard(
+        intent="send_email",
+        purpose="customer_support",
+        allowed_tools=["gmail.send"],
+    )
+    def send_email() -> str:
+        return "Email sent."
+"""
+
+from .audit import AuditEvent, AuditLog
+from .core import AGEC, AGECStatus, AGECTransitionError, DataPermissions, ExecutionPath, Intent
+from .guard import AGECBlockedError, guard
+from .policies import DEFAULT_LEGAL_BASES, Policy
+from .validator import AGECValidator, ValidationResult, validate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AGEC",
+    "AGECStatus",
+    "AGECTransitionError",
+    "AGECBlockedError",
+    "AGECValidator",
+    "AuditEvent",
+    "AuditLog",
+    "DEFAULT_LEGAL_BASES",
+    "DataPermissions",
+    "ExecutionPath",
+    "Intent",
+    "Policy",
+    "ValidationResult",
+    "guard",
+    "validate",
+]

agec/audit.py

@@ -0,0 +1,114 @@
+"""Audit logging for AGEC governance decisions.
+
+Records every validation allow/deny event with a timestamp and
+structured metadata. Events can be persisted to and loaded from
+JSON files for replay and compliance auditing.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class AuditEvent:
+    """A single governance decision recorded by AGEC.
+
+    Attributes:
+        agec_id: UUID of the AGEC context that produced this event.
+        event_type: Dot-separated event type, e.g. ``validation.allowed``.
+        message: Human-readable description of the outcome.
+        metadata: Arbitrary structured data attached to the event.
+        timestamp: ISO-8601 UTC timestamp of when the event was recorded.
+    """
+
+    agec_id: str
+    event_type: str
+    message: str
+    metadata: dict[str, Any]
+    timestamp: str
+
+
+class AuditLog:
+    """Append-only log of :class:`AuditEvent` records.
+
+    Events are stored in memory and can optionally be persisted to a
+    newline-delimited JSON file (one JSON object per line) for replay
+    and compliance use-cases.
+
+    Example::
+
+        log = AuditLog()
+        log.record("abc-123", "validation.allowed", "Passed.", {"intent": "send_email"})
+        log.save_json("audit.jsonl")
+        restored = AuditLog.load_json("audit.jsonl")
+    """
+
+    def __init__(self) -> None:
+        self.events: list[AuditEvent] = []
+
+    def record(
+        self,
+        agec_id: str,
+        event_type: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Append a new event to the log.
+
+        Args:
+            agec_id: UUID of the originating AGEC context.
+            event_type: Dot-separated event identifier.
+            message: Human-readable outcome description.
+            metadata: Optional structured data to attach.
+        """
+        self.events.append(
+            AuditEvent(
+                agec_id=agec_id,
+                event_type=event_type,
+                message=message,
+                metadata=metadata or {},
+                timestamp=datetime.now(timezone.utc).isoformat(),
+            )
+        )
+
+    def to_list(self) -> list[dict[str, Any]]:
+        """Return all events as a list of plain dicts."""
+        return [asdict(event) for event in self.events]
+
+    def save_json(self, path: str | Path, *, append: bool = False) -> None:
+        """Persist events to a newline-delimited JSON file.
+
+        Args:
+            path: File path to write to.
+            append: If ``True``, append to an existing file instead of
+                overwriting it. Useful for long-running processes.
+        """
+        mode = "a" if append else "w"
+        with open(path, mode, encoding="utf-8") as fh:
+            for event in self.events:
+                fh.write(json.dumps(asdict(event), ensure_ascii=False) + "\n")
+
+    @classmethod
+    def load_json(cls, path: str | Path) -> "AuditLog":
+        """Load events from a previously saved newline-delimited JSON file.
+
+        Args:
+            path: File path to read from.
+
+        Returns:
+            A new :class:`AuditLog` pre-populated with the stored events.
+        """
+        log = cls()
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                data = json.loads(line)
+                log.events.append(AuditEvent(**data))
+        return log

agec/core.py

@@ -0,0 +1,195 @@
+"""Core AGEC data models and lifecycle state machine.
+
+AGEC (Authorized Governance Execution Context) is the central object
+passed through the governance pipeline. It captures intent, execution
+path, data permissions, and lifecycle state for a single agent action
+request.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class AGECStatus(str, Enum):
+    """Lifecycle states for an :class:`AGEC` context.
+
+    The valid transition graph is::
+
+        INACTIVE → AWAITING_VALIDATION → ACTIVE → EXECUTING → COMPLETED
+                                      ↘ SUSPENDED
+                                      ↘ CANCELLED   (expired)
+    """
+
+    INACTIVE = "inactive"
+    AWAITING_VALIDATION = "awaiting_validation"
+    ACTIVE = "active"
+    EXECUTING = "executing"
+    COMPLETED = "completed"
+    SUSPENDED = "suspended"
+    CANCELLED = "cancelled"
+
+
+# Allowed (from_state, to_state) transitions.
+_ALLOWED_TRANSITIONS: frozenset[tuple[AGECStatus, AGECStatus]] = frozenset(
+    {
+        (AGECStatus.INACTIVE, AGECStatus.AWAITING_VALIDATION),
+        (AGECStatus.AWAITING_VALIDATION, AGECStatus.ACTIVE),
+        (AGECStatus.AWAITING_VALIDATION, AGECStatus.SUSPENDED),
+        (AGECStatus.AWAITING_VALIDATION, AGECStatus.CANCELLED),
+        (AGECStatus.ACTIVE, AGECStatus.EXECUTING),
+        (AGECStatus.ACTIVE, AGECStatus.SUSPENDED),
+        (AGECStatus.ACTIVE, AGECStatus.CANCELLED),
+        (AGECStatus.EXECUTING, AGECStatus.COMPLETED),
+        (AGECStatus.EXECUTING, AGECStatus.SUSPENDED),
+    }
+)
+
+
+class AGECTransitionError(RuntimeError):
+    """Raised when an illegal status transition is attempted."""
+
+
+@dataclass
+class Intent:
+    """Represents the declared intent of an agent action.
+
+    Attributes:
+        type: Intent identifier, e.g. ``"send_email"``.
+        source: Origin of the intent (default ``"user"``).
+        confidence: Model-assigned confidence score in ``[0.0, 1.0]``.
+    """
+
+    type: str
+    source: str = "user"
+    confidence: float = 1.0
+
+
+@dataclass
+class ExecutionPath:
+    """Ordered sequence of tools that will be invoked.
+
+    Attributes:
+        path_id: Human-readable identifier for this path.
+        steps: Ordered list of tool identifiers to be executed.
+    """
+
+    path_id: str
+    steps: list[str]
+
+    def deterministic_hash(self) -> str:
+        """Return a SHA-256 hex digest of the ordered tool list.
+
+        The hash is deterministic for the same sequence of steps and
+        can be stored in audit logs for replay verification.
+        """
+        raw = "|".join(self.steps)
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+@dataclass
+class DataPermissions:
+    """Data processing permissions attached to an agent action.
+
+    Attributes:
+        purpose: Processing purpose, e.g. ``"customer_support"``.
+        legal_basis: GDPR-aligned legal basis for processing.
+        allowed_operations: Operations permitted under this context.
+        data_categories: Categories of personal data involved.
+        retention_seconds: Optional maximum retention window in seconds.
+    """
+
+    purpose: str
+    legal_basis: str
+    allowed_operations: list[str]
+    data_categories: list[str] = field(default_factory=list)
+    retention_seconds: int | None = None
+
+
+@dataclass
+class AGEC:
+    """Authorized Governance Execution Context.
+
+    The central governance object for a single agent action request.
+    It captures intent, execution path, data permissions, and lifecycle
+    state, and enforces valid status transitions.
+
+    Args:
+        intent: The declared intent of the action.
+        context: Arbitrary key-value context (e.g. user_id, session_id).
+        execution_path: Ordered list of tools to be called.
+        data_permissions: Data processing permissions for this action.
+        agec_id: Auto-generated UUID; can be overridden for testing.
+        created_at: Unix timestamp of creation; auto-set.
+        ttl_seconds: Time-to-live in seconds (default 300).
+        status: Initial lifecycle state.
+    """
+
+    intent: Intent
+    context: dict[str, Any]
+    execution_path: ExecutionPath
+    data_permissions: DataPermissions
+    agec_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: float = field(default_factory=time.time)
+    ttl_seconds: int = 300
+    status: AGECStatus = AGECStatus.AWAITING_VALIDATION
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _transition(self, target: AGECStatus) -> None:
+        """Perform a guarded status transition.
+
+        Args:
+            target: Desired next state.
+
+        Raises:
+            AGECTransitionError: If the transition is not permitted.
+        """
+        if (self.status, target) not in _ALLOWED_TRANSITIONS:
+            raise AGECTransitionError(
+                f"Invalid AGEC transition: {self.status.value!r} → {target.value!r}"
+            )
+        self.status = target
+
+    # ------------------------------------------------------------------
+    # Lifecycle API
+    # ------------------------------------------------------------------
+
+    def is_expired(self) -> bool:
+        """Return ``True`` if the TTL has elapsed since creation."""
+        return time.time() > self.created_at + self.ttl_seconds
+
+    def activate(self) -> None:
+        """Transition to :attr:`AGECStatus.ACTIVE` after validation."""
+        self._transition(AGECStatus.ACTIVE)
+
+    def suspend(self) -> None:
+        """Transition to :attr:`AGECStatus.SUSPENDED` on policy failure."""
+        self._transition(AGECStatus.SUSPENDED)
+
+    def cancel(self) -> None:
+        """Transition to :attr:`AGECStatus.CANCELLED` (e.g. on expiry)."""
+        self._transition(AGECStatus.CANCELLED)
+
+    def start_execution(self) -> None:
+        """Transition to :attr:`AGECStatus.EXECUTING`.
+
+        Raises:
+            AGECTransitionError: If the context is not yet active.
+        """
+        self._transition(AGECStatus.EXECUTING)
+
+    def complete(self) -> None:
+        """Transition to :attr:`AGECStatus.COMPLETED`.
+
+        Raises:
+            AGECTransitionError: If the context is not executing.
+        """
+        self._transition(AGECStatus.COMPLETED)

agec/guard.py

@@ -0,0 +1,129 @@
+"""Pre-execution governance decorator for AI agent actions.
+
+Usage::
+
+    from agec import guard
+
+    @guard(
+        intent="send_email",
+        purpose="customer_support",
+        allowed_tools=["gmail.send"],
+        legal_basis="consent",
+    )
+    def send_email() -> str:
+        return "Email sent."
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+from .core import AGEC, AGECTransitionError, DataPermissions, ExecutionPath, Intent
+from .policies import Policy
+from .validator import AGECValidator
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class AGECBlockedError(PermissionError):
+    """Raised when the AGEC validator denies execution.
+
+    Attributes:
+        reason: Human-readable denial reason from the validator.
+        agec: The :class:`~agec.core.AGEC` context that was denied.
+    """
+
+    def __init__(self, reason: str, agec: AGEC) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.agec = agec
+
+
+def guard(
+    *,
+    intent: str,
+    purpose: str,
+    allowed_tools: list[str],
+    legal_basis: str = "consent",
+    data_categories: list[str] | None = None,
+    minimum_intent_confidence: float = 0.7,
+    intent_confidence: float = 1.0,
+) -> Callable[[F], F]:
+    """Decorator that enforces AGEC governance before function execution.
+
+    The :class:`~agec.policies.Policy` and
+    :class:`~agec.validator.AGECValidator` are created **once** at
+    decoration time to avoid per-call overhead. A fresh
+    :class:`~agec.core.AGEC` context is created on every invocation to
+    ensure independent TTL and audit tracking per call.
+
+    Args:
+        intent: Intent type string, e.g. ``"send_email"``.
+        purpose: Data processing purpose, e.g. ``"customer_support"``.
+        allowed_tools: List of tool identifiers permitted by this action.
+        legal_basis: GDPR legal basis (default ``"consent"``).
+        data_categories: Optional list of personal data categories.
+        minimum_intent_confidence: Minimum acceptable confidence score
+            (default ``0.7``).
+        intent_confidence: Confidence score to assign to this intent
+            (default ``1.0``).
+
+    Returns:
+        A decorator that wraps the target function with AGEC governance.
+
+    Raises:
+        AGECBlockedError: If the validator denies execution.
+
+    Example::
+
+        @guard(intent="send_email", purpose="support",
+               allowed_tools=["gmail.send"])
+        def send_email() -> str:
+            return "Email sent."
+    """
+    # Build policy once at decoration time — not per call.
+    _policy = Policy(
+        allowed_intents=[intent],
+        allowed_tools=allowed_tools,
+        allowed_purposes=[purpose],
+        allowed_legal_bases=[legal_basis],
+        minimum_intent_confidence=minimum_intent_confidence,
+    )
+    _validator = AGECValidator(_policy)
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Fresh AGEC context per call (independent TTL & audit ID).
+            agec = AGEC(
+                intent=Intent(type=intent, confidence=intent_confidence),
+                context={"function": func.__name__},
+                execution_path=ExecutionPath(
+                    path_id=f"{func.__name__}_path",
+                    steps=allowed_tools,
+                ),
+                data_permissions=DataPermissions(
+                    purpose=purpose,
+                    legal_basis=legal_basis,
+                    allowed_operations=["execute"],
+                    data_categories=data_categories or [],
+                ),
+            )
+            result = _validator.validate(agec)
+            if not result.allowed:
+                raise AGECBlockedError(result.reason, agec)
+
+            agec.start_execution()
+            try:
+                return func(*args, **kwargs)
+            finally:
+                try:
+                    agec.complete()
+                except AGECTransitionError:
+                    pass  # Guard should not raise on cleanup.
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

agec/policies.py

@@ -0,0 +1,79 @@
+"""AGEC policy definitions and built-in legal basis vocabulary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+DEFAULT_LEGAL_BASES: list[str] = [
+    "consent",
+    "contract",
+    "legal_obligation",
+    "vital_interest",
+    "public_task",
+    "legitimate_interest",
+]
+"""GDPR Article 6 legal bases supported by AGEC out of the box."""
+
+
+@dataclass
+class Policy:
+    """Declares what an agent is allowed to do.
+
+    A :class:`Policy` is the authoritative source of truth for a single
+    governance context. It specifies which intents, tools, purposes, and
+    legal bases are permitted, and optionally blocks certain data
+    categories.
+
+    Args:
+        allowed_intents: Intent types the agent may declare.
+        allowed_tools: Tool identifiers the agent may invoke.
+        allowed_purposes: Data processing purposes that are permitted.
+        allowed_legal_bases: GDPR legal bases accepted for this policy.
+        blocked_data_categories: Data categories explicitly disallowed.
+            ``None`` means no categories are blocked.
+        minimum_intent_confidence: Minimum confidence score required for
+            an intent to be accepted (default ``0.7``).
+
+    Example::
+
+        policy = Policy(
+            allowed_intents=["send_email"],
+            allowed_tools=["gmail.send"],
+            allowed_purposes=["customer_support"],
+            allowed_legal_bases=["consent"],
+        )
+    """
+
+    allowed_intents: list[str]
+    allowed_tools: list[str]
+    allowed_purposes: list[str]
+    allowed_legal_bases: list[str]
+    blocked_data_categories: list[str] | None = None
+    minimum_intent_confidence: float = 0.7
+
+    def is_intent_allowed(self, intent: str) -> bool:
+        """Return ``True`` if *intent* is in :attr:`allowed_intents`."""
+        return intent in self.allowed_intents
+
+    def is_tool_allowed(self, tool: str) -> bool:
+        """Return ``True`` if *tool* is in :attr:`allowed_tools`."""
+        return tool in self.allowed_tools
+
+    def is_purpose_allowed(self, purpose: str) -> bool:
+        """Return ``True`` if *purpose* is in :attr:`allowed_purposes`."""
+        return purpose in self.allowed_purposes
+
+    def is_legal_basis_allowed(self, legal_basis: str) -> bool:
+        """Return ``True`` if *legal_basis* is in :attr:`allowed_legal_bases`."""
+        return legal_basis in self.allowed_legal_bases
+
+    def has_blocked_data_category(self, categories: list[str]) -> bool:
+        """Return ``True`` if any category in *categories* is blocked.
+
+        Args:
+            categories: Data categories to check against the block list.
+        """
+        if not self.blocked_data_categories:
+            return False
+        return any(category in self.blocked_data_categories for category in categories)

agec/validator.py

@@ -0,0 +1,145 @@
+"""AGEC validation engine.
+
+Runs a deterministic, ordered series of policy checks against an
+:class:`~agec.core.AGEC` context and records every decision in an
+:class:`~agec.audit.AuditLog`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .audit import AuditLog
+from .core import AGEC
+from .policies import Policy
+
+
+@dataclass
+class ValidationResult:
+    """Outcome of a single validation run.
+
+    Attributes:
+        allowed: ``True`` if all policy checks passed.
+        reason: Human-readable explanation of the outcome.
+    """
+
+    allowed: bool
+    reason: str
+
+
+class AGECValidator:
+    """Validates an :class:`~agec.core.AGEC` context against a :class:`~agec.policies.Policy`.
+
+    Checks are evaluated in this order:
+
+    1. Expiry (TTL)
+    2. Intent allowlist
+    3. Intent confidence threshold
+    4. Execution path non-empty
+    5. Tool allowlist (per step)
+    6. Purpose allowlist
+    7. Legal basis allowlist
+    8. Blocked data categories
+
+    Every outcome — allow or deny — is recorded in the
+    :class:`~agec.audit.AuditLog`.
+
+    Args:
+        policy: The :class:`~agec.policies.Policy` to validate against.
+        audit_log: Optional existing :class:`~agec.audit.AuditLog` to
+            append events to. A new log is created if omitted.
+    """
+
+    def __init__(self, policy: Policy, audit_log: AuditLog | None = None) -> None:
+        self.policy = policy
+        self.audit_log = audit_log or AuditLog()
+
+    def validate(self, agec: AGEC) -> ValidationResult:
+        """Run all policy checks against *agec*.
+
+        Args:
+            agec: The governance context to validate.
+
+        Returns:
+            A :class:`ValidationResult` indicating allow or deny.
+        """
+        if agec.is_expired():
+            agec.cancel()
+            return self._deny(agec, "AGEC expired.")
+
+        if not self.policy.is_intent_allowed(agec.intent.type):
+            agec.suspend()
+            return self._deny(agec, f"Intent not allowed: {agec.intent.type}")
+
+        if agec.intent.confidence < self.policy.minimum_intent_confidence:
+            agec.suspend()
+            return self._deny(agec, "Intent confidence below threshold.")
+
+        if not agec.execution_path.steps:
+            agec.suspend()
+            return self._deny(agec, "Execution path is empty.")
+
+        for tool in agec.execution_path.steps:
+            if not self.policy.is_tool_allowed(tool):
+                agec.suspend()
+                return self._deny(agec, f"Tool not allowed: {tool}")
+
+        if not self.policy.is_purpose_allowed(agec.data_permissions.purpose):
+            agec.suspend()
+            return self._deny(
+                agec,
+                f"Purpose not allowed: {agec.data_permissions.purpose}",
+            )
+
+        if not self.policy.is_legal_basis_allowed(agec.data_permissions.legal_basis):
+            agec.suspend()
+            return self._deny(
+                agec,
+                f"Legal basis not allowed: {agec.data_permissions.legal_basis}",
+            )
+
+        if self.policy.has_blocked_data_category(agec.data_permissions.data_categories):
+            agec.suspend()
+            return self._deny(agec, "Blocked data category detected.")
+
+        agec.activate()
+        self.audit_log.record(
+            agec.agec_id,
+            "validation.allowed",
+            "AGEC validation passed.",
+            {
+                "intent": agec.intent.type,
+                "path_hash": agec.execution_path.deterministic_hash(),
+            },
+        )
+        return ValidationResult(True, "AGEC validation passed.")
+
+    def _deny(self, agec: AGEC, reason: str) -> ValidationResult:
+        """Record a denial event and return a denied :class:`ValidationResult`."""
+        self.audit_log.record(
+            agec.agec_id,
+            "validation.denied",
+            reason,
+            {
+                "intent": agec.intent.type,
+                "status": agec.status.value,
+            },
+        )
+        return ValidationResult(False, reason)
+
+
+def validate(agec: AGEC, policy: Policy) -> ValidationResult:
+    """Convenience function: validate *agec* against *policy*.
+
+    Creates a throw-away :class:`AGECValidator` with a fresh
+    :class:`~agec.audit.AuditLog`. Prefer constructing a validator
+    directly when you need to inspect audit events afterward.
+
+    Args:
+        agec: The governance context to validate.
+        policy: The policy to validate against.
+
+    Returns:
+        A :class:`ValidationResult`.
+    """
+    return AGECValidator(policy).validate(agec)

agec-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: agec
+Version: 0.1.0
+Summary: Authorized Governance Execution Context for AI agents
+Author-email: Onur Esmercan <onuresmercan@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/onur-esmercan/agec
+Project-URL: Repository, https://github.com/onur-esmercan/agec
+Keywords: ai-agents,authorization,governance,audit,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == "openai"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# AGEC
+
+Pre-execution governance layer for AI agents.
+
+Every AI agent action should be authorized before execution. AGEC validates
+intent, semantic context, execution path, and data processing permissions
+before any tool call is executed. It provides deterministic authorization,
+replayable decisions, and auditability for autonomous AI agents.
+
+---
+
+## Installation
+
+```bash
+pip install agec
+```
+
+## Quick Start
+
+```python
+from agec import guard, AGECBlockedError
+
+@guard(
+    intent="send_email",
+    purpose="customer_support",
+    allowed_tools=["gmail.send"],
+    legal_basis="consent",
+)
+def send_email() -> str:
+    return "Email sent."
+
+
+@guard(
+    intent="transfer_money",
+    purpose="unknown",
+    allowed_tools=["bank.transfer"],
+    intent_confidence=0.48,         # below the 0.7 threshold
+)
+def unsafe_transfer() -> str:
+    return "Transferred $1M."
+
+
+print(send_email())                 # → Email sent.
+
+try:
+    unsafe_transfer()
+except AGECBlockedError as exc:
+    print("AGEC BLOCKED EXECUTION")
+    print(f"Reason:   {exc.reason}")
+    print(f"Audit ID: {exc.agec.agec_id}")
+```
+
+If validation fails, execution is blocked **before** the wrapped function runs.
+
+---
+
+## Why AGEC?
+
+Traditional authorization systems answer:
+
+```text
+Can this identity access this resource?
+```
+
+AGEC answers a different question:
+
+```text
+Should this exact action execute right now?
+```
+
+AGEC introduces a mandatory governance layer between agent planning and tool
+execution — combining intent validation, policy enforcement, and tamper-evident
+audit logging in a single decorator.
+
+---
+
+## What AGEC Validates
+
+| Check | What it enforces |
+|---|---|
+| **Intent** | Declared intent must be in the policy allowlist |
+| **Confidence** | Intent confidence must meet the minimum threshold |
+| **Execution path** | Every tool step must be explicitly permitted |
+| **Purpose** | Data processing purpose must be allowed |
+| **Legal basis** | GDPR-aligned legal basis must be declared and allowed |
+| **Data categories** | Blocked data categories are rejected before execution |
+| **Expiry (TTL)** | Stale contexts are cancelled automatically |
+
+---
+
+## Architecture
+
+```text
+User
+  │
+AI Agent (planning)
+  │
+AGEC  ◄─── Policy + Validator
+  │              │
+  │         AuditLog ──► audit.jsonl (optional)
+  │
+Tool Execution
+```
+
+---
+
+## Lower-Level API
+
+```python
+from agec import AGEC, Intent, ExecutionPath, DataPermissions, Policy, AGECValidator
+
+policy = Policy(
+    allowed_intents=["send_email"],
+    allowed_tools=["gmail.send"],
+    allowed_purposes=["customer_support"],
+    allowed_legal_bases=["consent", "contract"],
+)
+
+agec = AGEC(
+    intent=Intent(type="send_email", confidence=0.95),
+    context={"user_id": "123"},
+    execution_path=ExecutionPath(path_id="email_path", steps=["gmail.send"]),
+    data_permissions=DataPermissions(
+        purpose="customer_support",
+        legal_basis="consent",
+        allowed_operations=["send"],
+        data_categories=["email"],
+    ),
+)
+
+validator = AGECValidator(policy)
+result = validator.validate(agec)
+
+print(result.allowed)   # True
+print(result.reason)    # AGEC validation passed.
+print(agec.status)      # AGECStatus.ACTIVE
+```
+
+### Persisting the Audit Log
+
+```python
+from agec import AuditLog
+
+log = AuditLog()
+# ... pass log to AGECValidator(policy, audit_log=log) ...
+
+# Save all recorded events to disk
+log.save_json("audit.jsonl")
+
+# Reload later for replay or compliance review
+restored = AuditLog.load_json("audit.jsonl")
+```
+
+---
+
+## Roadmap
+
+- [ ] OpenAI Agents SDK adapter
+- [ ] LangGraph adapter
+- [ ] CrewAI adapter
+- [ ] AutoGen adapter
+- [ ] CLI demo runner
+- [ ] Policy manifest (YAML/JSON) support
+- [x] Replayable audit log (JSON persistence)
+- [x] Deterministic execution path hashing
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+Apache-2.0

agec-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agec/__init__.py,sha256=C5DN-LzjHnjsCkzjUk9S3AOYgZlsjtRZThAoE4ZeghI,1100
+agec/audit.py,sha256=QYyiN0oYEvSk8qNt3_2H3WHB6VGDpBRhy0i1wG_WYUM,3590
+agec/core.py,sha256=cS5OQnDc7z92NdHSJVSdHv0BK_9d5y8heJAZONclOZs,6367
+agec/guard.py,sha256=LITzbl_nSnmv3_fRxkcpn18QfRBLZY67_Kcr4dh-Uk4,4188
+agec/policies.py,sha256=lAzINAqLM0kNg4L9Ak8M_-l6AiMCTQrHoCvN4_hdbeA,2787
+agec/validator.py,sha256=r3EwzPE1TdQOS2dqz1V1rzSQamCafaucIj0DN6H8VnE,4573
+agec-0.1.0.dist-info/METADATA,sha256=43_dPbmBz1FgWOl6Y1ofE8XfxyzN2_ADxoJyroJwQD0,5221
+agec-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agec-0.1.0.dist-info/top_level.txt,sha256=2_EJnPlPTZR-mRreLfAW-uqn5Ak4HtxG9vi-il5-kdc,5
+agec-0.1.0.dist-info/RECORD,,

agec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agec-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agec