Metadata-Version: 2.4
Name: agentguard-python-sdk
Version: 0.2.6
Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
Author: AgentGuard Team
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pynacl>=1.5.0
Requires-Dist: py-algorand-sdk>=2.0.0
Dynamic: license-file

# AgentGuard: Secure Payment & Consent Middleware for AI Agents

[![PyPI version](https://img.shields.io/pypi/v/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/agentguard-python-sdk.svg)](https://pypi.org/project/agentguard-python-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**AgentGuard** is a production-grade cryptographic middleware that enables AI agents to perform autonomous on-chain payments and generate verifiable consent proofs. It provides a zero-trust bridge between AI agents and the Algorand blockchain.

---

## ⚡ The Problem: Key Vulnerability in AI Agents
AI Agents often need to handle money (micropayments) and user data (consent). If you give an agent a private key, you risk:
1.  **Key Theft**: The agent's memory or logs leaking the seed.
2.  **Unintended Spending**: The agent's LLM "hallucinating" a purchase.
3.  **Non-Compliance**: No audit trail of *why* a payment was made (violating DPDP standards).

## 🛡️ The Solution: AgentGuard Architecture
AgentGuard solves this using a **Vaulted Delegation** architecture:
- **Hardened Vault (MCP)**: Your sensitive keys stay in a secure isolated server.
- **Verifiable Consent**: The SDK signs a cryptographic intent (Purpose + Amount + ID) which the Vault verifies before signing a blockchain transaction.
- **Zero-Trust**: The Backend never sees your keys; it only relays signed instructions.

---

## 📦 Installation

```bash
pip install agentguard-python-sdk
```

---

## 🚀 Quick Start (Request Signing)

AgentGuard uses **dual-identity cryptography**. Your **Signer ID** (Master Account) authenticates the request, while your **Principal ID** (Vault/LogicSig) handles the funds.

```python
import asyncio
from agentguard import AgentGuardClient

async def main():
    # Initialize client with your Signer Identity
    # Note: private_key is used ONLY for request signing, never for on-chain spend.
    async with AgentGuardClient(
        principal_id="LOGICSIG_OR_VAULT_ADDRESS",
        private_key="MASTER_ACCOUNT_SEED_B64",
        backend_url="https://agentguard-backend-9s8j.onrender.com"
    ) as client:
        
        # Access a premium resource
        # The SDK automatically handles: 402 Challenge -> Consent Signing -> Payment Relay
        receipt = await client.pay_and_fetch(
            resource_url="https://premium-intel.service/data",
            purpose="Market Analysis",
            amount_algo="0.1" # Optional: SDK can auto-probe price
        )
        
        print(f"✅ Success! Data: {receipt.data}")
        print(f"🔗 Audit Trail: {receipt.audit_url}")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🧩 Core Concepts

### 1. Identity Separation (Zero-Trust)
AgentGuard separates the **Signer** from the **Payer**:
*   **Signer (`signer_id`)**: Your Master Account. It signs the "Intent to Pay" via the SDK.
*   **Payer (`principal_id`)**: A LogicSig or Vault account. It contains the funds and has a pre-approved policy to pay only when the Master Account signs.

### 2. Purpose-Bound Consent (DPDP)
Every payment requires a `purpose` string. AgentGuard hashes this purpose into the blockchain transaction. This creates an irrefutable audit trail proving *exactly* what the user (or agent) consented to at the time of payment.

### 3. Capability Delegation (LogicSigs)
You can authorize specific amounts or windows of time for your agent:
```python
from agentguard.types import DelegatedAuthorization, AuthorizationConstraints

auth = DelegatedAuthorization(
    authorization_id="auth-uuid-123",
    principal_id="LOGICSIG_ADDRESS",
    logic_sig_b64="...",
    constraints=AuthorizationConstraints(
        max_amount_microalgos=5000000, # 5 ALGO limit
        expires_at_unix=1716300000
    )
)
await client.authorize(auth)
```

---

## 🛠️ API Reference

### `AgentGuardClient`
*   `pay_and_fetch(resource_url, purpose, ...)`: The primary method. Probes a resource, extracts the price, signs consent, performs payment via the vault, and returns the data.
*   `authorize(delegated_auth)`: Registers a LogicSig or delegated capability in the vault.
*   `verify(tx_id)`: Checks the blockchain and audit logs to verify a previous payment's validity.
*   `revoke(authorization_id)`: Immediately invalidates a delegated capability.

---

## 🔒 Security Policy
The SDK uses `ED25519` for all request signatures. All payloads are **canonicalized** (Deterministic JSON sorting + NFC normalization) before signing to prevent "In-Flight Mutation" attacks.

---

© 2026 AgentGuard Team. Built for the Algorand Advanced Agentic Coding.
