pyagentgate 0.1.0__tar.gz

pyagentgate-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v

pyagentgate-0.1.0/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.

pyagentgate-0.1.0/PKG-INFO

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

@@ -0,0 +1,148 @@
+# 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/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",
+]

pyagentgate-0.1.0/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,
+]