agec 0.1.0__tar.gz

agec-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,179 @@
+# 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/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "agec"
+version = "0.1.0"
+description = "Authorized Governance Execution Context for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+  { name = "Onur Esmercan", email = "onuresmercan@gmail.com" }
+]
+keywords = ["ai-agents", "authorization", "governance", "audit", "security"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai-agents>=0.1"]
+langchain = ["langchain-core>=0.2"]
+dev = ["pytest>=8.0", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/onur-esmercan/agec"
+Repository = "https://github.com/onur-esmercan/agec"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["agec"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 80

agec-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agec-0.1.0/src/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-0.1.0/src/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