pyagentgate 0.1.0__py3-none-any.whl

agentgate/__init__.py

@@ -0,0 +1,53 @@
+"""AgentGate — Open-source policy engine for agentic payments."""
+
+from .decorators import GatedTransactionDenied, GatedTransactionEscalated, gated
+from .gate import EscalationHandler, Gate, LoggingEscalationHandler
+from .ledger import InMemoryLedger, LedgerBackend
+from .loader import load_policy
+from .models import (
+    AuditEntry,
+    Check,
+    CheckResult,
+    Decision,
+    EscalationRules,
+    EvaluationResult,
+    MerchantRules,
+    Policy,
+    PolicyLimits,
+    TimeRestrictions,
+    Transaction,
+    VelocityRules,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "Gate",
+    "Policy",
+    "Transaction",
+    "Decision",
+    "EvaluationResult",
+    # Policy components
+    "PolicyLimits",
+    "MerchantRules",
+    "VelocityRules",
+    "EscalationRules",
+    "TimeRestrictions",
+    # Results
+    "Check",
+    "CheckResult",
+    "AuditEntry",
+    # Escalation
+    "EscalationHandler",
+    "LoggingEscalationHandler",
+    # Ledger
+    "InMemoryLedger",
+    "LedgerBackend",
+    # Loader
+    "load_policy",
+    # Decorator
+    "gated",
+    "GatedTransactionDenied",
+    "GatedTransactionEscalated",
+]

agentgate/checks.py

@@ -0,0 +1,257 @@
+"""Individual policy checks. Each is a pure function: transaction + policy + ledger → Check."""
+
+from __future__ import annotations
+
+import fnmatch
+from datetime import datetime, timedelta, timezone
+
+from .ledger import InMemoryLedger
+from .models import Check, CheckResult, Policy, Transaction
+
+
+def check_amount_limit(tx: Transaction, policy: Policy, **_) -> Check:
+    """Check if transaction amount exceeds per-transaction limit."""
+    limit = policy.limits.per_transaction
+    if limit is None:
+        return Check("amount_limit", CheckResult.SKIP, "No per-transaction limit set")
+    if tx.amount > limit:
+        return Check(
+            "amount_limit",
+            CheckResult.FAIL,
+            f"Amount {tx.amount} exceeds limit {limit}",
+            {"amount": tx.amount, "limit": limit},
+        )
+    return Check("amount_limit", CheckResult.PASS, f"Amount {tx.amount} within limit {limit}")
+
+
+def check_daily_limit(tx: Transaction, policy: Policy, ledger: InMemoryLedger, **_) -> Check:
+    """Check if transaction would exceed daily spending limit."""
+    limit = policy.limits.daily
+    if limit is None:
+        return Check("daily_limit", CheckResult.SKIP, "No daily limit set")
+    now = datetime.now(timezone.utc)
+    start_of_day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    spent = ledger.total_since(tx.agent_id, start_of_day)
+    if spent + tx.amount > limit:
+        return Check(
+            "daily_limit",
+            CheckResult.FAIL,
+            f"Daily total {spent + tx.amount:.2f} would exceed limit {limit}",
+            {"spent_today": spent, "proposed": tx.amount, "limit": limit},
+        )
+    return Check("daily_limit", CheckResult.PASS, f"Daily spend OK ({spent + tx.amount:.2f}/{limit})")
+
+
+def check_weekly_limit(tx: Transaction, policy: Policy, ledger: InMemoryLedger, **_) -> Check:
+    """Check if transaction would exceed weekly spending limit."""
+    limit = policy.limits.weekly
+    if limit is None:
+        return Check("weekly_limit", CheckResult.SKIP, "No weekly limit set")
+    now = datetime.now(timezone.utc)
+    week_start = now - timedelta(days=now.weekday())
+    week_start = week_start.replace(hour=0, minute=0, second=0, microsecond=0)
+    spent = ledger.total_since(tx.agent_id, week_start)
+    if spent + tx.amount > limit:
+        return Check(
+            "weekly_limit",
+            CheckResult.FAIL,
+            f"Weekly total {spent + tx.amount:.2f} would exceed limit {limit}",
+            {"spent_this_week": spent, "proposed": tx.amount, "limit": limit},
+        )
+    return Check("weekly_limit", CheckResult.PASS, f"Weekly spend OK ({spent + tx.amount:.2f}/{limit})")
+
+
+def check_monthly_limit(tx: Transaction, policy: Policy, ledger: InMemoryLedger, **_) -> Check:
+    """Check if transaction would exceed monthly spending limit."""
+    limit = policy.limits.monthly
+    if limit is None:
+        return Check("monthly_limit", CheckResult.SKIP, "No monthly limit set")
+    now = datetime.now(timezone.utc)
+    month_start = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    spent = ledger.total_since(tx.agent_id, month_start)
+    if spent + tx.amount > limit:
+        return Check(
+            "monthly_limit",
+            CheckResult.FAIL,
+            f"Monthly total {spent + tx.amount:.2f} would exceed limit {limit}",
+            {"spent_this_month": spent, "proposed": tx.amount, "limit": limit},
+        )
+    return Check("monthly_limit", CheckResult.PASS, f"Monthly spend OK ({spent + tx.amount:.2f}/{limit})")
+
+
+def check_category(tx: Transaction, policy: Policy, **_) -> Check:
+    """Check if transaction category is allowed."""
+    rules = policy.merchants
+
+    # Check blocked categories first
+    if tx.category in rules.blocked_categories:
+        return Check(
+            "category",
+            CheckResult.FAIL,
+            f"Category '{tx.category}' is blocked",
+            {"category": tx.category, "blocked": rules.blocked_categories},
+        )
+
+    # If allowlist is set, category must be in it
+    if rules.allowed_categories is not None and tx.category not in rules.allowed_categories:
+        return Check(
+            "category",
+            CheckResult.FAIL,
+            f"Category '{tx.category}' not in allowed list",
+            {"category": tx.category, "allowed": rules.allowed_categories},
+        )
+
+    return Check("category", CheckResult.PASS, f"Category '{tx.category}' is allowed")
+
+
+def check_merchant(tx: Transaction, policy: Policy, **_) -> Check:
+    """Check if merchant is allowed."""
+    rules = policy.merchants
+
+    # Check blocked merchants (supports glob patterns)
+    for pattern in rules.blocked_merchants:
+        if fnmatch.fnmatch(tx.merchant.lower(), pattern.lower()):
+            return Check(
+                "merchant",
+                CheckResult.FAIL,
+                f"Merchant '{tx.merchant}' matches blocked pattern '{pattern}'",
+                {"merchant": tx.merchant, "pattern": pattern},
+            )
+
+    # If allowlist is set, merchant must be in it
+    if rules.allowed_merchants is not None:
+        matched = any(
+            fnmatch.fnmatch(tx.merchant.lower(), p.lower())
+            for p in rules.allowed_merchants
+        )
+        if not matched:
+            return Check(
+                "merchant",
+                CheckResult.FAIL,
+                f"Merchant '{tx.merchant}' not in allowed list",
+                {"merchant": tx.merchant, "allowed": rules.allowed_merchants},
+            )
+
+    return Check("merchant", CheckResult.PASS, f"Merchant '{tx.merchant}' is allowed")
+
+
+def check_velocity(tx: Transaction, policy: Policy, ledger: InMemoryLedger, **_) -> Check:
+    """Check transaction velocity (rate limiting)."""
+    rules = policy.velocity
+    now = datetime.now(timezone.utc)
+    failures = []
+
+    # Cooldown check
+    if rules.cooldown_seconds > 0:
+        last_time = ledger.last_transaction_time(tx.agent_id)
+        if last_time:
+            elapsed = (now - last_time).total_seconds()
+            if elapsed < rules.cooldown_seconds:
+                failures.append(
+                    f"Cooldown: {elapsed:.1f}s since last tx, need {rules.cooldown_seconds}s"
+                )
+
+    # Hourly rate check
+    if rules.max_per_hour is not None:
+        hour_ago = now - timedelta(hours=1)
+        count = ledger.count_since(tx.agent_id, hour_ago)
+        if count >= rules.max_per_hour:
+            failures.append(f"Hourly limit: {count} txns in last hour (max {rules.max_per_hour})")
+
+    # Daily rate check
+    if rules.max_per_day is not None:
+        start_of_day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        count = ledger.count_since(tx.agent_id, start_of_day)
+        if count >= rules.max_per_day:
+            failures.append(f"Daily limit: {count} txns today (max {rules.max_per_day})")
+
+    if failures:
+        return Check(
+            "velocity",
+            CheckResult.FAIL,
+            "; ".join(failures),
+            {"failures": failures},
+        )
+
+    return Check("velocity", CheckResult.PASS, "Velocity checks passed")
+
+
+def check_time_restrictions(tx: Transaction, policy: Policy, **_) -> Check:
+    """Check if current time is within allowed transaction window."""
+    rules = policy.time_restrictions
+    now = datetime.now(timezone.utc)
+
+    if rules.allowed_days is not None:
+        if now.weekday() not in rules.allowed_days:
+            return Check(
+                "time_restriction",
+                CheckResult.FAIL,
+                f"Day {now.strftime('%A')} not in allowed days",
+                {"day": now.weekday(), "allowed": rules.allowed_days},
+            )
+
+    if rules.allowed_hours is not None:
+        start, end = rules.allowed_hours
+        if not (start <= now.hour < end):
+            return Check(
+                "time_restriction",
+                CheckResult.FAIL,
+                f"Hour {now.hour} outside allowed range {start}-{end}",
+                {"hour": now.hour, "allowed_start": start, "allowed_end": end},
+            )
+
+    return Check("time_restriction", CheckResult.PASS, "Within allowed time window")
+
+
+def check_escalation(tx: Transaction, policy: Policy, ledger: InMemoryLedger, **_) -> Check:
+    """Check if transaction should be escalated to a human.
+    
+    Unlike other checks, FAIL here means ESCALATE, not DENY.
+    """
+    rules = policy.escalation
+    reasons = []
+
+    if rules.above_amount is not None and tx.amount > rules.above_amount:
+        reasons.append(f"Amount {tx.amount} exceeds escalation threshold {rules.above_amount}")
+
+    if rules.on_new_merchant:
+        known = ledger.get_known_merchants(tx.agent_id)
+        if tx.merchant not in known and known:  # don't escalate the very first tx
+            reasons.append(f"New merchant: {tx.merchant}")
+
+    if rules.on_new_category:
+        known = ledger.get_known_categories(tx.agent_id)
+        if tx.category not in known and known:
+            reasons.append(f"New category: {tx.category}")
+
+    if rules.on_cumulative_above is not None:
+        now = datetime.now(timezone.utc)
+        start_of_day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        total = ledger.total_since(tx.agent_id, start_of_day) + tx.amount
+        if total > rules.on_cumulative_above:
+            reasons.append(f"Cumulative total {total:.2f} exceeds escalation threshold {rules.on_cumulative_above}")
+
+    if reasons:
+        return Check(
+            "escalation",
+            CheckResult.FAIL,
+            "; ".join(reasons),
+            {"reasons": reasons},
+        )
+
+    return Check("escalation", CheckResult.PASS, "No escalation needed")
+
+
+# Registry of all checks in evaluation order.
+# Escalation is last because it only matters if everything else passes.
+ALL_CHECKS = [
+    check_amount_limit,
+    check_daily_limit,
+    check_weekly_limit,
+    check_monthly_limit,
+    check_category,
+    check_merchant,
+    check_velocity,
+    check_time_restrictions,
+    check_escalation,
+]

agentgate/decorators.py

@@ -0,0 +1,129 @@
+"""Decorators for wrapping payment functions with gate enforcement."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable
+
+from .gate import Gate
+from .models import Decision, Policy, Transaction
+
+
+class GatedTransactionDenied(Exception):
+    """Raised when a gated transaction is denied."""
+
+    def __init__(self, result):
+        self.result = result
+        reasons = "; ".join(c.message for c in result.failed_checks)
+        super().__init__(f"Transaction denied: {reasons}")
+
+
+class GatedTransactionEscalated(Exception):
+    """Raised when a gated transaction requires escalation."""
+
+    def __init__(self, result):
+        self.result = result
+        super().__init__(f"Transaction requires escalation: {', '.join(result.escalation_reasons)}")
+
+
+def gated(
+    policy: Policy | None = None,
+    gate: Gate | None = None,
+    amount_param: str = "amount",
+    merchant_param: str = "merchant",
+    category_param: str = "category",
+    agent_id: str = "default-agent",
+    reasoning_param: str | None = None,
+):
+    """Decorator that gates a payment function behind policy evaluation.
+
+    Usage:
+        @gated(policy=my_policy)
+        async def buy_item(merchant, amount, item):
+            return await stripe.checkout(...)
+
+        # Or with an existing gate:
+        @gated(gate=my_gate, amount_param="price")
+        def purchase(store, price):
+            ...
+
+    The decorated function will raise GatedTransactionDenied if the
+    transaction is denied, or GatedTransactionEscalated if it needs
+    human approval.
+    """
+    if policy is None and gate is None:
+        raise ValueError("Either policy or gate must be provided")
+
+    _gate = gate or Gate(policy=policy)
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Extract transaction params from the function call
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            amount = bound.arguments.get(amount_param, 0)
+            merchant = bound.arguments.get(merchant_param, "unknown")
+            category = bound.arguments.get(category_param, "general")
+            reasoning = ""
+            if reasoning_param:
+                reasoning = bound.arguments.get(reasoning_param, "")
+
+            tx = Transaction(
+                amount=float(amount),
+                currency="USD",
+                merchant=str(merchant),
+                category=str(category),
+                agent_id=agent_id,
+                reasoning=reasoning,
+            )
+
+            result = _gate.evaluate(tx)
+
+            if result.decision == Decision.DENY:
+                raise GatedTransactionDenied(result)
+            elif result.decision == Decision.ESCALATE:
+                raise GatedTransactionEscalated(result)
+
+            return func(*args, **kwargs)
+
+        # Async variant
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            amount = bound.arguments.get(amount_param, 0)
+            merchant = bound.arguments.get(merchant_param, "unknown")
+            category = bound.arguments.get(category_param, "general")
+            reasoning = ""
+            if reasoning_param:
+                reasoning = bound.arguments.get(reasoning_param, "")
+
+            tx = Transaction(
+                amount=float(amount),
+                currency="USD",
+                merchant=str(merchant),
+                category=str(category),
+                agent_id=agent_id,
+                reasoning=reasoning,
+            )
+
+            result = _gate.evaluate(tx)
+
+            if result.decision == Decision.DENY:
+                raise GatedTransactionDenied(result)
+            elif result.decision == Decision.ESCALATE:
+                raise GatedTransactionEscalated(result)
+
+            return await func(*args, **kwargs)
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper
+        return wrapper
+
+    return decorator

agentgate/gate.py

@@ -0,0 +1,131 @@
+"""The Gate — core evaluation engine."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Callable, Protocol
+
+from .checks import ALL_CHECKS
+from .ledger import InMemoryLedger
+from .models import (
+    AuditEntry,
+    Check,
+    CheckResult,
+    Decision,
+    EvaluationResult,
+    Policy,
+    Transaction,
+)
+
+
+class EscalationHandler(Protocol):
+    """Protocol for handling escalated transactions."""
+
+    async def escalate(
+        self, transaction: Transaction, reasons: list[str]
+    ) -> bool:
+        """Return True to approve, False to deny."""
+        ...
+
+
+class LoggingEscalationHandler:
+    """Default escalation handler — logs and denies."""
+
+    async def escalate(
+        self, transaction: Transaction, reasons: list[str]
+    ) -> bool:
+        print(f"[ESCALATION] tx={transaction.id} reasons={reasons}")
+        return False  # deny by default — safe fallback
+
+
+class Gate:
+    """Main policy evaluation engine.
+
+    Usage:
+        gate = Gate(policy=my_policy)
+        result = gate.evaluate(transaction)
+        if result.passed:
+            # proceed with payment
+        elif result.decision == Decision.ESCALATE:
+            # human review needed
+        else:
+            # denied — result.failed_checks has details
+    """
+
+    def __init__(
+        self,
+        policy: Policy,
+        ledger: InMemoryLedger | None = None,
+        escalation_handler: EscalationHandler | None = None,
+        checks: list[Callable] | None = None,
+        audit_log: list[AuditEntry] | None = None,
+    ):
+        self.policy = policy
+        self.ledger = ledger or InMemoryLedger()
+        self.escalation_handler = escalation_handler
+        self._checks = checks or ALL_CHECKS
+        self._audit_log: list[AuditEntry] = audit_log if audit_log is not None else []
+
+    def evaluate(self, tx: Transaction) -> EvaluationResult:
+        """Evaluate a transaction against the policy. Synchronous."""
+        results: list[Check] = []
+        escalation_reasons: list[str] = []
+
+        for check_fn in self._checks:
+            check = check_fn(tx=tx, policy=self.policy, ledger=self.ledger)
+            results.append(check)
+
+        # Separate hard failures from escalation
+        hard_fails = [
+            c for c in results
+            if c.result == CheckResult.FAIL and c.name != "escalation"
+        ]
+        escalation_check = next(
+            (c for c in results if c.name == "escalation"), None
+        )
+
+        # Determine decision
+        if hard_fails:
+            decision = Decision.DENY
+        elif escalation_check and escalation_check.result == CheckResult.FAIL:
+            decision = Decision.ESCALATE
+            escalation_reasons = escalation_check.details.get("reasons", [])
+        else:
+            decision = Decision.ALLOW
+
+        # Build audit entry
+        audit = AuditEntry(
+            timestamp=datetime.now(timezone.utc),
+            transaction_id=tx.id,
+            agent_id=tx.agent_id,
+            decision=decision,
+            checks_passed=[c.name for c in results if c.result == CheckResult.PASS],
+            checks_failed=[c.name for c in results if c.result == CheckResult.FAIL],
+            escalation_reasons=escalation_reasons,
+            reasoning=tx.reasoning,
+            policy_name=self.policy.name,
+            policy_version=self.policy.version,
+        )
+        self._audit_log.append(audit)
+
+        # Record in ledger if allowed
+        if decision == Decision.ALLOW:
+            self.ledger.record(tx.agent_id, tx)
+
+        result = EvaluationResult(
+            decision=decision,
+            transaction=tx,
+            checks=results,
+            escalation_reasons=escalation_reasons,
+            audit=audit,
+        )
+        return result
+
+    @property
+    def audit_log(self) -> list[AuditEntry]:
+        return list(self._audit_log)
+
+    def reset(self) -> None:
+        """Clear ledger and audit log. Useful for testing."""
+        self.ledger.clear()
+        self._audit_log.clear()

agentgate/ledger.py

@@ -0,0 +1,74 @@
+"""Transaction ledger for tracking spending history.
+
+The ledger is what makes velocity checks, daily/weekly/monthly limits,
+and "new merchant" detection possible. It's an in-memory store by default,
+with a protocol for plugging in persistent backends.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from typing import Protocol
+
+from .models import Transaction
+
+
+class LedgerBackend(Protocol):
+    """Protocol for persistent ledger backends."""
+
+    def record(self, agent_id: str, transaction: Transaction) -> None: ...
+    def get_transactions(
+        self, agent_id: str, since: datetime
+    ) -> list[Transaction]: ...
+    def get_known_merchants(self, agent_id: str) -> set[str]: ...
+    def get_known_categories(self, agent_id: str) -> set[str]: ...
+
+
+class InMemoryLedger:
+    """In-memory transaction ledger. Good for dev/testing, not production."""
+
+    def __init__(self):
+        self._transactions: dict[str, list[Transaction]] = defaultdict(list)
+        self._known_merchants: dict[str, set[str]] = defaultdict(set)
+        self._known_categories: dict[str, set[str]] = defaultdict(set)
+
+    def record(self, agent_id: str, transaction: Transaction) -> None:
+        self._transactions[agent_id].append(transaction)
+        self._known_merchants[agent_id].add(transaction.merchant)
+        self._known_categories[agent_id].add(transaction.category)
+
+    def get_transactions(
+        self, agent_id: str, since: datetime
+    ) -> list[Transaction]:
+        return [
+            tx
+            for tx in self._transactions.get(agent_id, [])
+            if tx.timestamp >= since
+        ]
+
+    def get_known_merchants(self, agent_id: str) -> set[str]:
+        return self._known_merchants.get(agent_id, set())
+
+    def get_known_categories(self, agent_id: str) -> set[str]:
+        return self._known_categories.get(agent_id, set())
+
+    def total_since(self, agent_id: str, since: datetime) -> float:
+        return sum(tx.amount for tx in self.get_transactions(agent_id, since))
+
+    def count_since(self, agent_id: str, since: datetime) -> int:
+        return len(self.get_transactions(agent_id, since))
+
+    def last_transaction_time(self, agent_id: str) -> datetime | None:
+        txs = self._transactions.get(agent_id, [])
+        return txs[-1].timestamp if txs else None
+
+    def clear(self, agent_id: str | None = None) -> None:
+        if agent_id:
+            self._transactions.pop(agent_id, None)
+            self._known_merchants.pop(agent_id, None)
+            self._known_categories.pop(agent_id, None)
+        else:
+            self._transactions.clear()
+            self._known_merchants.clear()
+            self._known_categories.clear()

agentgate/loader.py

@@ -0,0 +1,101 @@
+"""Load policies from YAML files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .models import (
+    EscalationRules,
+    MerchantRules,
+    Policy,
+    PolicyLimits,
+    TimeRestrictions,
+    VelocityRules,
+)
+
+try:
+    import yaml
+
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+
+def load_policy(source: str | Path | dict) -> Policy:
+    """Load a policy from a YAML file path, YAML string, or dict.
+
+    Args:
+        source: File path, YAML string, or already-parsed dict.
+
+    Returns:
+        A Policy instance.
+    """
+    if isinstance(source, dict):
+        data = source
+    elif isinstance(source, Path) or (
+        isinstance(source, str) and not source.strip().startswith("{")
+        and "\n" not in source
+        and Path(source).suffix in (".yaml", ".yml")
+    ):
+        if not HAS_YAML:
+            raise ImportError("PyYAML required: pip install pyyaml")
+        with open(source) as f:
+            data = yaml.safe_load(f)
+    else:
+        if not HAS_YAML:
+            raise ImportError("PyYAML required: pip install pyyaml")
+        data = yaml.safe_load(source)
+
+    return _dict_to_policy(data)
+
+
+def _dict_to_policy(data: dict[str, Any]) -> Policy:
+    """Convert a raw dict to a Policy."""
+    limits_data = data.get("limits", {})
+    limits = PolicyLimits(
+        per_transaction=limits_data.get("per_transaction"),
+        daily=limits_data.get("daily"),
+        weekly=limits_data.get("weekly"),
+        monthly=limits_data.get("monthly"),
+        currency=limits_data.get("currency", "USD"),
+    )
+
+    merch_data = data.get("merchants", {})
+    merchants = MerchantRules(
+        allowed_categories=merch_data.get("allowed_categories"),
+        blocked_categories=merch_data.get("blocked_categories", []),
+        allowed_merchants=merch_data.get("allowed_merchants"),
+        blocked_merchants=merch_data.get("blocked_merchants", []),
+    )
+
+    vel_data = data.get("velocity", {})
+    velocity = VelocityRules(
+        max_per_hour=vel_data.get("max_transactions_per_hour"),
+        max_per_day=vel_data.get("max_transactions_per_day"),
+        cooldown_seconds=vel_data.get("cooldown_seconds", 0),
+    )
+
+    esc_data = data.get("escalation", {})
+    escalation = EscalationRules(
+        above_amount=esc_data.get("above_amount"),
+        on_new_merchant=esc_data.get("on_new_merchant", False),
+        on_new_category=esc_data.get("on_new_category", False),
+        on_cumulative_above=esc_data.get("on_cumulative_above"),
+    )
+
+    time_data = data.get("time_restrictions", {})
+    time_rules = TimeRestrictions(
+        allowed_hours=tuple(time_data["allowed_hours"]) if "allowed_hours" in time_data else None,
+        allowed_days=time_data.get("allowed_days"),
+    )
+
+    return Policy(
+        name=data.get("name", "default"),
+        version=str(data.get("version", "1")),
+        limits=limits,
+        merchants=merchants,
+        velocity=velocity,
+        escalation=escalation,
+        time_restrictions=time_rules,
+    )

agentgate/models.py

@@ -0,0 +1,179 @@
+"""Core data models for AgentGate."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class Decision(str, Enum):
+    """Result of a policy evaluation."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    ESCALATE = "escalate"
+
+
+class CheckResult(str, Enum):
+    """Result of an individual policy check."""
+
+    PASS = "pass"
+    FAIL = "fail"
+    SKIP = "skip"  # check not applicable
+
+
+@dataclass(frozen=True)
+class Transaction:
+    """A proposed agent-initiated transaction."""
+
+    amount: float
+    currency: str
+    merchant: str
+    category: str
+    agent_id: str
+    reasoning: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: f"tx_{uuid.uuid4().hex[:12]}")
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def __post_init__(self):
+        if self.amount < 0:
+            raise ValueError("Transaction amount cannot be negative")
+        if not self.currency:
+            raise ValueError("Currency is required")
+        if not self.merchant:
+            raise ValueError("Merchant is required")
+
+
+@dataclass
+class PolicyLimits:
+    """Spending limits."""
+
+    per_transaction: float | None = None
+    daily: float | None = None
+    weekly: float | None = None
+    monthly: float | None = None
+    currency: str = "USD"
+
+
+@dataclass
+class MerchantRules:
+    """Merchant/category allow/block rules."""
+
+    allowed_categories: list[str] | None = None  # None = all allowed
+    blocked_categories: list[str] = field(default_factory=list)
+    allowed_merchants: list[str] | None = None  # None = all allowed
+    blocked_merchants: list[str] = field(default_factory=list)
+
+
+@dataclass
+class VelocityRules:
+    """Rate limiting for transactions."""
+
+    max_per_hour: int | None = None
+    max_per_day: int | None = None
+    cooldown_seconds: float = 0
+
+
+@dataclass
+class EscalationRules:
+    """When to escalate to a human."""
+
+    above_amount: float | None = None
+    on_new_merchant: bool = False
+    on_new_category: bool = False
+    on_cumulative_above: float | None = None  # escalate when session total exceeds
+
+
+@dataclass
+class TimeRestrictions:
+    """When the agent is allowed to transact."""
+
+    allowed_hours: tuple[int, int] | None = None  # (start, end) in 24h
+    allowed_days: list[int] | None = None  # 0=Mon, 6=Sun
+
+
+@dataclass
+class Policy:
+    """Complete policy definition for an agent."""
+
+    name: str = "default"
+    version: str = "1"
+    limits: PolicyLimits = field(default_factory=PolicyLimits)
+    merchants: MerchantRules = field(default_factory=MerchantRules)
+    velocity: VelocityRules = field(default_factory=VelocityRules)
+    escalation: EscalationRules = field(default_factory=EscalationRules)
+    time_restrictions: TimeRestrictions = field(default_factory=TimeRestrictions)
+
+    # Convenience constructor
+    @classmethod
+    def simple(
+        cls,
+        max_per_transaction: float = 50.0,
+        max_daily: float = 200.0,
+        max_monthly: float = 2000.0,
+        allowed_categories: list[str] | None = None,
+        blocked_merchants: list[str] | None = None,
+        require_escalation_above: float | None = None,
+    ) -> Policy:
+        return cls(
+            limits=PolicyLimits(
+                per_transaction=max_per_transaction,
+                daily=max_daily,
+                monthly=max_monthly,
+            ),
+            merchants=MerchantRules(
+                allowed_categories=allowed_categories,
+                blocked_merchants=blocked_merchants or [],
+            ),
+            escalation=EscalationRules(above_amount=require_escalation_above),
+        )
+
+
+@dataclass
+class Check:
+    """Result of a single policy check."""
+
+    name: str
+    result: CheckResult
+    message: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EvaluationResult:
+    """Full result of a gate evaluation."""
+
+    decision: Decision
+    transaction: Transaction
+    checks: list[Check]
+    escalation_reasons: list[str] = field(default_factory=list)
+    audit: AuditEntry | None = None
+
+    @property
+    def passed(self) -> bool:
+        return self.decision == Decision.ALLOW
+
+    @property
+    def failed_checks(self) -> list[Check]:
+        return [c for c in self.checks if c.result == CheckResult.FAIL]
+
+
+@dataclass
+class AuditEntry:
+    """Immutable record of a gate decision."""
+
+    timestamp: datetime
+    transaction_id: str
+    agent_id: str
+    decision: Decision
+    checks_passed: list[str]
+    checks_failed: list[str]
+    escalation_reasons: list[str]
+    reasoning: str
+    policy_name: str
+    policy_version: str
+    id: str = field(default_factory=lambda: f"audit_{uuid.uuid4().hex[:12]}")

pyagentgate-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: pyagentgate
+Version: 0.1.0
+Summary: Open-source policy engine for agentic payments
+Project-URL: Repository, https://github.com/Peterc3-dev/agentgate
+Author: Peter C. Clemente III
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,authorization,fintech,payments,policy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# AgentGate
+
+Open-source policy engine for agentic payments. Not a payment processor. Not a toll booth. The authorization layer between an AI agent and whatever payment API it's calling.
+
+## Why
+
+Every "agentic payments" startup is racing to insert themselves as middleware and clip 1-5 cents per transaction. AgentGate is the open alternative: a framework-agnostic policy engine that lets you define what an agent is allowed to spend, where, how much, and how often — without surrendering control to a rent-seeking intermediary.
+
+## What It Does
+
+- **Policy Schema** — Define spending rules in YAML or Python: per-transaction limits, daily/weekly/monthly caps, merchant category allowlists/blocklists, time-of-day restrictions
+- **Evaluation Engine** — Takes a proposed transaction + policy → returns `ALLOW`, `DENY`, or `ESCALATE`
+- **Human-in-the-Loop Hooks** — Pluggable escalation when transactions exceed policy bounds
+- **Audit Trail** — Structured log of every decision with agent reasoning attached
+- **Cooldown & Velocity Controls** — Prevent rapid-fire purchasing and runaway loops
+
+## What It Doesn't Do
+
+- Process payments (use Stripe, Square, PayPal, etc.)
+- Store card numbers or tokens (use your payment provider's vault)
+- Replace PCI compliance (that's between you and your provider)
+
+## Install
+
+```bash
+pip install agentgate
+```
+
+## Quick Start
+
+```python
+from agentgate import Policy, Gate, Transaction
+
+# Define a policy
+policy = Policy(
+    max_per_transaction=50.00,
+    max_daily=200.00,
+    max_monthly=2000.00,
+    allowed_categories=["groceries", "office_supplies", "saas"],
+    blocked_merchants=["casino-online.com"],
+    require_escalation_above=100.00,
+)
+
+# Create a gate
+gate = Gate(policy=policy)
+
+# Evaluate a transaction
+tx = Transaction(
+    amount=42.99,
+    currency="USD",
+    merchant="staples.com",
+    category="office_supplies",
+    agent_id="purchasing-agent-01",
+    reasoning="Need printer paper for office",
+)
+
+result = gate.evaluate(tx)
+# result.decision = Decision.ALLOW
+# result.policy_checks = [...]
+```
+
+## Policy Schema (YAML)
+
+```yaml
+version: "1"
+name: office-purchasing-agent
+limits:
+  per_transaction: 50.00
+  daily: 200.00
+  weekly: 750.00
+  monthly: 2000.00
+  currency: USD
+merchants:
+  allowed_categories:
+    - office_supplies
+    - saas
+    - groceries
+  blocked:
+    - casino-online.com
+    - gambling.*
+velocity:
+  max_transactions_per_hour: 10
+  max_transactions_per_day: 50
+  cooldown_seconds: 30
+escalation:
+  above_amount: 100.00
+  on_new_merchant: true
+  on_new_category: true
+time_restrictions:
+  allowed_hours: [9, 17]  # 9am-5pm only
+  allowed_days: [0, 1, 2, 3, 4]  # Mon-Fri
+```
+
+## Custom Escalation Handlers
+
+```python
+from agentgate import Gate, EscalationHandler
+
+class SlackEscalation(EscalationHandler):
+    async def escalate(self, transaction, reasons):
+        # Post to Slack, wait for approval
+        approved = await self.post_to_slack(transaction, reasons)
+        return approved
+
+gate = Gate(policy=policy, escalation_handler=SlackEscalation())
+```
+
+## Audit Log
+
+Every evaluation produces an `AuditEntry`:
+
+```python
+result = gate.evaluate(tx)
+print(result.audit)
+# AuditEntry(
+#   timestamp=2026-08-30T...,
+#   transaction_id="tx_abc123",
+#   agent_id="purchasing-agent-01",
+#   decision=Decision.ALLOW,
+#   checks_passed=["amount_limit", "category_allowed", "velocity_ok"],
+#   checks_failed=[],
+#   reasoning="Need printer paper for office",
+#   policy_version="1",
+# )
+```
+
+## Framework Integration
+
+AgentGate is framework-agnostic. Use it with any agent framework:
+
+```python
+# LangChain tool wrapper
+from agentgate.integrations import langchain_tool
+
+# CrewAI tool wrapper  
+from agentgate.integrations import crewai_tool
+
+# Raw function — wrap any payment call
+from agentgate import gated
+
+@gated(policy=policy)
+async def buy_item(merchant, amount, item):
+    return await stripe.checkout(...)
+```
+
+## License
+
+MIT — because the whole point is that nobody gets to gatekeep this.

pyagentgate-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agentgate/__init__.py,sha256=23XPwkDvyrOXo89VJMk3m4mQvofRnPOzcCoxoHxmdHk,1117
+agentgate/checks.py,sha256=ZTIVQuG4FdN1TkbHlRn9BiLNum5xwTPs0VwugZnxOys,9973
+agentgate/decorators.py,sha256=0Ml4z8ZBlDXIx9kcK5JZLOZ9xkAUKTFQlLBNKhrJDiM,4187
+agentgate/gate.py,sha256=VMAGNAg75GjwzxW0Qh9eRYYX1hAjEMJo2jgC1U8bWBI,4032
+agentgate/ledger.py,sha256=STf4TyfFJrO-OcRkJ_HmKEadc0KqnzrwAwlfGP_-5KI,2752
+agentgate/loader.py,sha256=7xcvF1jqsxESophjB984-ginKqbZ1GwfKUZGWsVjlTg,3036
+agentgate/models.py,sha256=KzHB_qu3Zmq9q25BFvJ79DnvxKpR5tu9aGmVPr5OKHg,4825
+pyagentgate-0.1.0.dist-info/METADATA,sha256=1XjFpMN-sKY5_e-oFgaP7JTm99QE1k1wU2ALqrlzcSY,4815
+pyagentgate-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyagentgate-0.1.0.dist-info/licenses/LICENSE,sha256=mik7Go9iYdliXSawk4ipL6BXJh0FTu5GEyJtZQFJBzA,1078
+pyagentgate-0.1.0.dist-info/RECORD,,

pyagentgate-0.1.0.dist-info/WHEEL

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

pyagentgate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter C. Clemente III
+
+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.