agentguard-python-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

{agentguard_python_sdk-0.1.0 → agentguard_python_sdk-0.1.2}/PKG-INFO

@@ -1,13 +1,15 @@
 Metadata-Version: 2.4
 Name: agentguard-python-sdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
 Author: AgentGuard Team
-License: MIT
+License-Expression: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: py-algorand-sdk>=2.0.0
 
 # AgentGuard SDK
 
@@ -18,7 +20,7 @@ By isolating private keys in a hardened **MCP Server (Vault)** and using the **A
 ## Installation
 
 ```bash
-pip install agentguard
+pip install agentguard-python-sdk
 ```
 
 ## Quick Start (3-Line Usage)
@@ -34,7 +36,7 @@ async def main():
         # 2. Perform a secure payment (includes automatic DPDP consent hashing)
         receipt = await client.pay_and_fetch(
             resource_url="https://api.stock.com/reliance",
-            amount_algo=0.05,
+            amount_algo="0.05",
             purpose="Financial Analysis"
         )
         print(f"Payment Successful! TX ID: {receipt.tx_id}")

{agentguard_python_sdk-0.1.0 → agentguard_python_sdk-0.1.2}/README.md

@@ -1,54 +1,54 @@
-# AgentGuard SDK
-
-AgentGuard is a production-grade middleware that enables AI agents to perform on-chain payments and generate verifiable consent proofs in compliance with DPDP (Digital Personal Data Protection) standards.
-
-By isolating private keys in a hardened **MCP Server (Vault)** and using the **AgentGuard Backend (Dispatcher)** as a secure proxy, the SDK allows developers to add monetization and compliance to their agents with zero blockchain complexity.
-
-## Installation
-
-```bash
-pip install agentguard
-```
-
-## Quick Start (3-Line Usage)
-
-```python
-import asyncio
-from agentguard import AgentGuardClient
-
-async def main():
-    # 1. Initialize the client
-    async with AgentGuardClient(wallet_address="YOUR_WALLET_ADDRESS") as client:
-        
-        # 2. Perform a secure payment (includes automatic DPDP consent hashing)
-        receipt = await client.pay_and_fetch(
-            resource_url="https://api.stock.com/reliance",
-            amount_algo=0.05,
-            purpose="Financial Analysis"
-        )
-        print(f"Payment Successful! TX ID: {receipt.tx_id}")
-
-        # 3. Verify compliance audit trail
-        proof = await client.verify(receipt.tx_id)
-        print(f"On-Chain Verified: {proof.verified}")
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Architecture
-
-1.  **SDK**: Generates UUID nonces and SHA256 consent hashes.
-2.  **Backend**: Proxies requests to the internal vault and maintains audit records.
-3.  **MCP Server (Vault)**: A hardened, isolated environment that signs transactions using Algorand.
-4.  **Algorand Blockchain**: Provides the irrefutable proof-of-consent and payment settlement.
-
-## Features
-
-- **Async First**: Built on `httpx` for high-performance agentic loops.
-- **Zero-Trust**: Private keys never leave the vault.
-- **DPDP Compliant**: Automatic cryptographic logging of purpose-bound consent.
-- **Simple Audit**: Direct links to blockchain explorers for every transaction.
-
----
-© 2026 AgentGuard Team. Built for the Algorand Ecosystem.
+# AgentGuard SDK
+
+AgentGuard is a production-grade middleware that enables AI agents to perform on-chain payments and generate verifiable consent proofs in compliance with DPDP (Digital Personal Data Protection) standards.
+
+By isolating private keys in a hardened **MCP Server (Vault)** and using the **AgentGuard Backend (Dispatcher)** as a secure proxy, the SDK allows developers to add monetization and compliance to their agents with zero blockchain complexity.
+
+## Installation
+
+```bash
+pip install agentguard-python-sdk
+```
+
+## Quick Start (3-Line Usage)
+
+```python
+import asyncio
+from agentguard import AgentGuardClient
+
+async def main():
+    # 1. Initialize the client
+    async with AgentGuardClient(wallet_address="YOUR_WALLET_ADDRESS") as client:
+        
+        # 2. Perform a secure payment (includes automatic DPDP consent hashing)
+        receipt = await client.pay_and_fetch(
+            resource_url="https://api.stock.com/reliance",
+            amount_algo="0.05",
+            purpose="Financial Analysis"
+        )
+        print(f"Payment Successful! TX ID: {receipt.tx_id}")
+
+        # 3. Verify compliance audit trail
+        proof = await client.verify(receipt.tx_id)
+        print(f"On-Chain Verified: {proof.verified}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Architecture
+
+1.  **SDK**: Generates UUID nonces and SHA256 consent hashes.
+2.  **Backend**: Proxies requests to the internal vault and maintains audit records.
+3.  **MCP Server (Vault)**: A hardened, isolated environment that signs transactions using Algorand.
+4.  **Algorand Blockchain**: Provides the irrefutable proof-of-consent and payment settlement.
+
+## Features
+
+- **Async First**: Built on `httpx` for high-performance agentic loops.
+- **Zero-Trust**: Private keys never leave the vault.
+- **DPDP Compliant**: Automatic cryptographic logging of purpose-bound consent.
+- **Simple Audit**: Direct links to blockchain explorers for every transaction.
+
+---
+© 2026 AgentGuard Team. Built for the Algorand Ecosystem.

agentguard_python_sdk-0.1.2/agentguard/__init__.py

@@ -0,0 +1,4 @@
+from .client import AgentGuardClient
+from .config import AgentGuardConfig
+
+__all__ = ["AgentGuardClient", "AgentGuardConfig"]

agentguard_python_sdk-0.1.2/agentguard/auth.py

@@ -0,0 +1,54 @@
+import json
+import unicodedata
+import hashlib
+import base64
+import time
+from typing import Dict, Any
+import nacl.signing
+import nacl.encoding
+
+def canonicalize_payload(payload: Dict[str, Any]) -> bytes:
+    """
+    Deterministic canonicalization (Priority 5).
+    1. NFC Normalize all strings recursively.
+    2. Sort keys.
+    3. No whitespace (separators=(',', ':')).
+    4. UTF-8 encoding.
+    """
+    def normalize_rec(obj):
+        if isinstance(obj, str):
+            return unicodedata.normalize("NFC", obj)
+        if isinstance(obj, dict):
+            return {normalize_rec(k): normalize_rec(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [normalize_rec(i) for i in obj]
+        return obj
+
+    norm_payload = normalize_rec(payload)
+    canonical_str = json.dumps(
+        norm_payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False
+    )
+    return canonical_str.encode("utf-8")
+
+def sign_request(payload: Dict[str, Any], private_key_b64: str) -> str:
+    """
+    Signs a canonical payload using ED25519.
+    Expects private_key_b64 (32-byte seed or 64-byte expanded key in b64).
+    """
+    # Decoding private key
+    # Most Algorand private keys are the 32-byte seed. 
+    # NaCl signing keys are initialized from the 32-byte seed.
+    seed = base64.b64decode(private_key_b64)
+    if len(seed) > 32:
+        seed = seed[:32] # Algorand SK is often seed + pubkey
+        
+    signing_key = nacl.signing.SigningKey(seed)
+    
+    canonical_bytes = canonicalize_payload(payload)
+    signature = signing_key.sign(canonical_bytes)
+    
+    # Return detached signature in base64
+    return base64.b64encode(signature.signature).decode("utf-8")

agentguard_python_sdk-0.1.2/agentguard/client.py

@@ -0,0 +1,407 @@
+import httpx
+import uuid
+import logging
+import re
+import warnings
+import asyncio
+import random
+import time
+import json
+import hashlib
+import base64
+import urllib.parse
+from decimal import Decimal, InvalidOperation
+from typing import Optional, Dict, Any
+from .consent import generate_consent_proof
+from . import auth
+from .types import AgentGuardReceipt, AuditProof
+from .errors import map_backend_error, TransportError, AgentGuardError, VerificationError
+from .config import AgentGuardConfig
+from .observability import start_span
+
+logger = logging.getLogger("agentguard-sdk")
+
+def parse_algo_amount_to_microalgos(amount: str) -> int:
+    """
+    Parses a string ALGO amount into integer microAlgos.
+    
+    STRICTLY rejects:
+    - Non-string inputs
+    - Scientific notation (e.g. 1e-6)
+    - Negative values
+    - More than 6 decimal places
+    - Unnecessary leading zeros (e.g. 00.1)
+    
+    ARCHITECTURAL BOUNDARY:
+    - Decimal is used ONLY here for the one-time string-to-int conversion.
+    - The rest of the system MUST use integer microalgos.
+    """
+    if not isinstance(amount, str):
+        raise ValueError(f"Amount must be a string (e.g. '0.25'), got {type(amount).__name__}")
+    
+    # Strict Regex: (0 OR [1-9] followed by digits) followed optionally by a decimal and up to 6 digits
+    # Blocks: '00.1', '.5', '1e-1', '01'
+    if not re.match(r"^(0|[1-9]\d*)(\.\d{1,6})?$", amount):
+        raise ValueError(f"Invalid ALGO format: '{amount}'. Use '0.05' not '00.05' or '1e-2'.")
+    
+    try:
+        # Atomic conversion at the trust boundary
+        d_amount = Decimal(amount)
+        microalgos = int(d_amount * Decimal("1000000"))
+        return microalgos
+    except (InvalidOperation, ValueError) as e:
+        raise ValueError(f"Conversion failed: {e}")
+
+class AgentGuardClient:
+    def __init__(
+        self, 
+        wallet_address: str, 
+        config: Optional[AgentGuardConfig] = None, 
+        private_key: str = None,
+        backend_url: Optional[str] = None,
+        indexer_url: Optional[str] = None
+    ):
+        """
+        Initialize the AgentGuard client with a structured config object or direct overrides.
+        """
+        self.config = config or AgentGuardConfig()
+        
+        # Apply direct overrides if provided
+        if backend_url:
+            self.config.backend_url = backend_url
+        if indexer_url:
+            self.config.indexer_url = indexer_url
+
+        self.wallet_address = wallet_address
+        self.base_url = self.config.backend_url.rstrip("/")
+        self.private_key = private_key
+        
+        # Priority 6: Segmented Timeouts injected from Config
+        self.timeout = httpx.Timeout(
+            connect=self.config.timeout_connect,
+            read=self.config.timeout_read,
+            write=self.config.timeout_write,
+            pool=self.config.timeout_pool
+        )
+        self.async_client = httpx.AsyncClient(timeout=self.timeout)
+        
+        # Configure logging based on config
+        logging.getLogger("agentguard-sdk").setLevel(self.config.logging_level)
+
+    async def pay_and_fetch(
+        self, 
+        resource_url: str, 
+        purpose: str,
+        amount_algo: Optional[str] = None, 
+        microalgos: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+        nonce: Optional[str] = None,
+        timestamp: Optional[int] = None,
+        correlation_id: Optional[str] = None
+    ) -> AgentGuardReceipt:
+        """
+        Asynchronously perform an on-chain payment and return a typed receipt.
+        
+        Args:
+            resource_url: The URL/ID of the resource being accessed.
+            purpose: The purpose of the data processing.
+            amount_algo: The amount in ALGO as a string (e.g. '0.05').
+            microalgos: Alternatively, the exact amount in microAlgos (int).
+            
+        Returns:
+            AgentGuardReceipt: A structured receipt with transaction details.
+        """
+        # 1. Determine and Validate Amount
+        if amount_algo is not None and microalgos is not None:
+            raise ValueError("Provide either amount_algo or microalgos, not both.")
+        
+        if amount_algo is not None:
+            actual_microalgos = parse_algo_amount_to_microalgos(amount_algo)
+        elif microalgos is not None:
+            if not isinstance(microalgos, int) or microalgos < 0:
+                raise ValueError(f"microalgos must be a non-negative integer, got {microalgos}")
+            actual_microalgos = microalgos
+        else:
+            raise ValueError("Either amount_algo or microalgos must be provided.")
+
+        # 2. Idempotency & Replay Protection (PHASE C)
+        # We generate these early so they can be persisted across retries if needed.
+        idem_key = idempotency_key or str(uuid.uuid4())
+        act_nonce = nonce or str(uuid.uuid4())
+        act_correlation_id = correlation_id or str(idem_key)
+        
+        # 3. Generate Consent Proof (SHA256 of metadata including microalgos)
+        # If timestamp is provided (from a previous retry), we reuse it.
+        consent_hash, act_timestamp = generate_consent_proof(
+            principal_id=self.wallet_address,
+            resource_url=resource_url,
+            purpose=purpose,
+            nonce=act_nonce,
+            microalgos=actual_microalgos,
+            timestamp=timestamp # Pass through for retry consistency
+        )
+        
+        # 4. Payload Construction
+        payload = {
+            "resource_url": resource_url,
+            "microalgos": actual_microalgos,
+            "purpose": purpose,
+            "principal_id": self.wallet_address,
+            "consent_hash": consent_hash,
+            "nonce": act_nonce,
+            "timestamp": act_timestamp,
+            "idempotency_key": idem_key,
+            "correlation_id": act_correlation_id
+        }
+        
+        headers = {
+            "X-Idempotency-Key": idem_key,
+            "X-Correlation-ID": act_correlation_id
+        }
+        
+        # 5. Cryptographic Signing (Priority 5)
+        if self.private_key:
+            signature = auth.sign_request(payload, self.private_key)
+            headers.update({
+                "X-AgentGuard-Signature": signature,
+                "X-AgentGuard-Timestamp": str(act_timestamp),
+                "X-AgentGuard-Key-Id": self.wallet_address,
+                "X-AgentGuard-Nonce": act_nonce
+            })
+            # Priority 6: Signing verified via Span attributes if needed
+
+        # 6. Request with Retries
+        span = start_span("sdk.pay_request", act_correlation_id)
+        span.set_attribute("wallet", self.wallet_address)
+        span.set_attribute("microalgos", actual_microalgos)
+        span.set_attribute("idempotency_key", idem_key)
+
+        max_attempts = self.config.max_retries
+        base_delay = self.config.retry_base_delay
+        
+        for attempt in range(max_attempts):
+            attempt_span = start_span(f"sdk.request_attempt_{attempt + 1}", act_correlation_id, parent_id=span.span_id)
+            try:
+                response = await self.async_client.post(f"{self.base_url}/pay", json=payload, headers=headers)
+                
+                if response.status_code == 200:
+                    res_data = response.json()
+                    attempt_span.end()
+                    span.set_attribute("tx_id", res_data["tx_id"])
+                    span.end()
+                    return AgentGuardReceipt(
+                        tx_id=res_data["tx_id"],
+                        consent_hash=res_data["consent_hash"],
+                        audit_url=res_data["audit_url"],
+                        data=res_data.get("data", {})
+                    )
+                else:
+                    try:
+                        error_data = response.json()
+                    except:
+                        error_data = {"message": response.text}
+                    
+                    attempt_span.end(error=f"http_{response.status_code}: {error_data.get('message')}")
+                    
+                    # Transient errors -> retry
+                    if response.status_code in [502, 503, 504, 429]:
+                        if attempt < max_attempts - 1:
+                            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
+                            await asyncio.sleep(delay)
+                            continue
+                    
+                    span.end(error=f"backend_rejection_{response.status_code}")
+                    raise map_backend_error(response.status_code, error_data)
+
+            except httpx.RequestError as e:
+                attempt_span.end(error=str(e))
+                if attempt < max_attempts - 1:
+                    delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
+                    await asyncio.sleep(delay)
+                    continue
+                span.end(error="transport_failure")
+                raise TransportError(f"Could not connect to AgentGuard Backend: {e}")
+            except Exception as e:
+                attempt_span.end(error=str(e))
+                span.end(error="unexpected_sdk_error")
+                raise
+
+    async def verify(self, tx_id: str, verify_onchain: bool = False, local_proof: Optional[Dict[str, Any]] = None) -> AuditProof:
+        """
+        Asynchronously verify a transaction against the blockchain audit trail.
+        
+        If verify_onchain is True, the SDK performs an independent check against the 
+        Algorand indexer and re-computes the proof hash locally.
+        
+        If local_proof is provided, the SDK uses it to recompute the hash even if the 
+        backend has no record of the transaction (Split-Brain Recovery).
+        """
+        try:
+            # 1. Fetch Backend's Assertion (Metadata + Proof)
+            res_data = {}
+            backend_failed = False
+            try:
+                response = await self.async_client.get(f"{self.base_url}/verify/{tx_id}")
+                response.raise_for_status()
+                res_data = response.json()
+            except Exception as e:
+                if not verify_onchain:
+                    # In legacy mode, we must have the backend response
+                    raise
+                logger.warning(f"Backend lookup for {tx_id} failed: {e}. Attempting independent recovery.")
+                backend_failed = True
+
+            # 2. Independent Logic
+            if verify_onchain:
+                logger.info(f"PERFORMING INDEPENDENT ON-CHAIN VERIFICATION FOR {tx_id}")
+                
+                # A. Recompute Hash locally
+                # Content source: Backend provided proof OR user provided local_proof
+                canonical_json = res_data.get("canonical_json")
+                
+                if not canonical_json and local_proof:
+                    # [Priority 8 BONUS] Reconstruct canonical JSON from raw local proof
+                    from .auth import canonicalize_payload
+                    canonical_bytes = canonicalize_payload(local_proof)
+                    canonical_json = canonical_bytes.decode("utf-8")
+                
+                if not canonical_json:
+                    reason = "Backend missing proof" if not backend_failed else "Backend unreachable"
+                    raise VerificationError(f"{reason} and no local_proof provided for recovery.")
+                
+                local_hash = hashlib.sha256(canonical_json.encode("utf-8")).hexdigest()
+                
+                # B. Interrogate Blockchain directly
+                on_chain_hash = await self._fetch_on_chain_proof(tx_id)
+                
+                # C. Compare
+                if local_hash != on_chain_hash:
+                    # [SECURITY BOUNDARY] The Backend is lying.
+                    logger.error(f"TRUSTLESS VERIFICATION FAILED: Local Hash {local_hash} != On-chain Hash {on_chain_hash}")
+                    return AuditProof(
+                        verified=False,
+                        tx_id=tx_id,
+                        principal_id=res_data.get("principal_id", "N/A"),
+                        consent_hash=local_hash,
+                        on_chain_hash=on_chain_hash,
+                        explorer_url=self.config.backend_url, # Placeholder
+                        message="CRITICAL FAILURE: Local proof does not match blockchain evidence."
+                    )
+                
+                logger.info("TRUSTLESS VERIFICATION SUCCESS: Blockchain evidence matches backend assertion.")
+                return AuditProof(
+                    verified=True,
+                    tx_id=tx_id,
+                    principal_id=res_data.get("principal_id", "N/A"),
+                    consent_hash=local_hash,
+                    on_chain_hash=on_chain_hash,
+                    explorer_url=res_data.get("explorer_url", ""),
+                    message="Trustless independent verification successful."
+                )
+
+            # Legacy/Backend-trusting behavior
+            return AuditProof(
+                verified=res_data["verified"],
+                tx_id=res_data["tx_id"],
+                principal_id=res_data["principal_id"],
+                consent_hash=res_data["consent_hash"],
+                on_chain_hash=res_data["on_chain_hash"],
+                explorer_url=res_data["explorer_url"],
+                message=res_data["message"]
+            )
+        except httpx.HTTPStatusError as e:
+            try:
+                error_data = e.response.json()
+            except Exception:
+                error_data = {"message": e.response.text, "code": "ERR_UNKNOWN"}
+            raise map_backend_error(e.response.status_code, error_data, original_exception=e) from e
+        except httpx.RequestError as e:
+            raise TransportError(f"Verification transport failed: {e}", original_exception=e) from e
+        except Exception as e:
+            if isinstance(e, AgentGuardError): raise
+            raise VerificationError(f"Independent verification failed: {str(e)}", original_exception=e)
+
+    async def _fetch_on_chain_proof(self, tx_id: str) -> str:
+        """
+        Directly queries the Algorand Indexer to extract the proof hash.
+        Supports atomic group detection.
+        """
+        indexer_url = self.config.indexer_url.rstrip("/")
+        try:
+            # 1. Fetch TX
+            resp = await self.async_client.get(f"{indexer_url}/transactions/{tx_id}")
+            resp.raise_for_status()
+            tx_data = resp.json().get("transaction", {})
+            
+            # 2. Extract proof or hunt in group
+            relevant_txn = tx_data
+            group_id = tx_data.get("group")
+            
+            if group_id and not tx_data.get("application-transaction"):
+                # If this was one part of a group (like the payment part), find the App call
+                import urllib.parse
+                safe_group = urllib.parse.quote(group_id)
+                g_resp = await self.async_client.get(f"{indexer_url}/transactions?group-id={safe_group}")
+                if g_resp.status_code == 200:
+                    group_txns = g_resp.json().get("transactions", [])
+                    for g_tx in group_txns:
+                        if g_tx.get("application-transaction"):
+                            relevant_txn = g_tx
+                            break
+            
+            app_txn = relevant_txn.get("application-transaction", {})
+            args = app_txn.get("application-args", [])
+            
+            if not args:
+                raise VerificationError("Blockchain record found but no AppArgs proof exists.")
+                
+            # Decode proof (Arg 0 is Sha256 hex as base64-encoded bytes on wire)
+            on_chain_hash_hex = base64.b64decode(args[0]).decode("utf-8")
+            return on_chain_hash_hex
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise VerificationError(f"Transaction {tx_id} not found on blockchain indexer.")
+            raise TransportError(f"Indexer connection failed: {e.response.status_code}")
+        except Exception as e:
+            raise VerificationError(f"Failed to extract blockchain proof: {str(e)}")
+
+    async def register_budget(self, limit_algo: Optional[str] = None, limit_microalgos: Optional[int] = None) -> Dict[str, Any]:
+        """
+        Convenience method to register/update the user's budget.
+        """
+        if limit_algo is not None:
+            actual_limit = parse_algo_amount_to_microalgos(limit_algo)
+        elif limit_microalgos is not None:
+            actual_limit = limit_microalgos
+        else:
+            raise ValueError("Either limit_algo or limit_microalgos must be provided.")
+
+        payload = {
+            "wallet_address": self.wallet_address,
+            "budget_microalgos": actual_limit
+        }
+        try:
+            response = await self.async_client.post(f"{self.base_url}/user/register", json=payload)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            try:
+                error_data = e.response.json()
+            except Exception:
+                error_data = {"message": e.response.text, "code": "ERR_UNKNOWN"}
+            raise map_backend_error(e.response.status_code, error_data, original_exception=e) from e
+        except httpx.RequestError as e:
+            raise TransportError(f"Budget registration transport failed: {e}", original_exception=e) from e
+
+    async def close(self):
+        """Close the underlying HTTP client."""
+        await self.async_client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    # Removed _log_event because it's replaced by Span system

agentguard_python_sdk-0.1.2/agentguard/config.py

@@ -0,0 +1,34 @@
+from pydantic_settings import BaseSettings
+from pydantic import Field
+from typing import Optional
+
+class AgentGuardConfig(BaseSettings):
+    """
+    Typed configuration for the AgentGuard SDK.
+    Supports environment variable overrides with AGENTGUARD_ prefix.
+    """
+    environment: str = Field("testnet", pattern="^(local|development|testnet|production)$")
+    backend_url: str = Field("https://agentguard-backend.onrender.com")
+    
+    # Transport Policy
+    timeout_connect: float = 5.0
+    timeout_read: float = 30.0
+    timeout_write: float = 10.0
+    timeout_pool: float = 5.0
+    
+    # Retry Policy
+    max_retries: int = 3
+    retry_base_delay: float = 1.0
+    
+    # Observability
+    logging_level: str = "INFO"
+    tracing_enabled: bool = True
+    
+    # [Priority 8] Trustless Verification
+    indexer_url: str = Field("https://testnet-idx.algonode.cloud/v2")
+    verify_timeout: float = 30.0
+    verify_max_retries: int = 3
+    
+    class Config:
+        env_prefix = "AGENTGUARD_"
+        case_sensitive = False

agentguard_python_sdk-0.1.2/agentguard/consent.py

@@ -0,0 +1,79 @@
+import time
+import json
+import hashlib
+import logging
+import unicodedata
+from typing import Dict, Any
+
+# Configure logging
+logger = logging.getLogger("agentguard-sdk")
+
+def generate_consent(
+    principal_id: str, 
+    purpose: str, 
+    item: str, 
+    nonce: str, 
+    microalgos: int,
+    data_fiduciary: str = "AlgoBharat Agentic Node",
+    timestamp: int = None
+) -> Dict[str, Any]:
+    """
+    Creates a user consent object dictionary containing DPDP compliant fields.
+    Includes microalgos (int) and hash_version for future-proofing.
+    
+    Representation Rule:
+    - Internal: microalgos (int) is the single source of truth.
+    - Strings: All metadata is normalized to NFC.
+    """
+    if timestamp is None:
+        timestamp = int(time.time())
+    
+    # Normalize strings to NFC at the creation boundary
+    consent_obj = {
+        "principal_id": unicodedata.normalize("NFC", principal_id),
+        "data_fiduciary": unicodedata.normalize("NFC", data_fiduciary),
+        "purpose": unicodedata.normalize("NFC", purpose),
+        "item": unicodedata.normalize("NFC", item),
+        "microalgos": microalgos,
+        "timestamp": timestamp,
+        "nonce": nonce,
+        "hash_version": 2 # Current Refactor Version
+    }
+    
+    logger.info(f"Generated DPDP consent (v2) for principal={principal_id} at {timestamp}")
+    return consent_obj
+
+def hash_consent(consent: Dict[str, Any]) -> str:
+    """
+    Canonical hashing implementation.
+    MUST REMAINT SYNCED with Backend and MCP Server.
+    
+    Rules:
+    1. sort_keys=True
+    2. separators=(',', ':')
+    3. ensure_ascii=False
+    4. Encoding: utf-8
+    """
+    # Convert consent dict to JSON string with strict canonical form:
+    # - Sorted keys
+    # - No spaces (separators=(",", ":"))
+    # Use separators=(",", ":") and ensure_ascii=False for identical bytes across boundaries
+    consent_json = json.dumps(consent, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    consent_hash = hashlib.sha256(consent_json.encode("utf-8")).hexdigest()
+    
+    logger.info(f"Consent hash generated: {consent_hash}")
+    return consent_hash
+
+def generate_consent_proof(principal_id: str, resource_url: str, purpose: str, nonce: str, microalgos: int, timestamp: int = None) -> tuple[str, int]:
+    """
+    High-level helper to generate a consent hash and return the timestamp used.
+    """
+    consent = generate_consent(
+        principal_id=principal_id,
+        purpose=purpose,
+        item=resource_url,
+        nonce=nonce,
+        microalgos=microalgos,
+        timestamp=timestamp
+    )
+    return hash_consent(consent), consent["timestamp"]

agentguard_python_sdk-0.1.2/agentguard/errors.py

@@ -0,0 +1,83 @@
+class AgentGuardError(Exception):
+    """Base exception for all AgentGuard SDK errors."""
+    def __init__(self, message: str, code: str, retryable: bool = False, original_exception=None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.retryable = retryable
+        self.original_exception = original_exception
+
+class ValidationError(AgentGuardError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_VALIDATION_FAILURE", False, original_exception)
+
+class TransportError(AgentGuardError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_TRANSPORT_FAILURE", True, original_exception)
+
+# Specific errors based on Backend contract
+class AuthenticationError(AgentGuardError):
+    def __init__(self, message: str, code: str = "ERR_AUTH_FAILURE", retryable: bool = False, original_exception=None):
+        super().__init__(message, code, retryable, original_exception)
+
+class InvalidSignatureError(AuthenticationError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_INVALID_SIGNATURE", False, original_exception)
+
+class ExpiredSignatureError(AuthenticationError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_EXPIRED_SIGNATURE", False, original_exception)
+
+class PaymentError(AgentGuardError):
+    def __init__(self, message: str, code: str = "ERR_PAYMENT_FAILURE", retryable: bool = False, original_exception=None):
+        super().__init__(message, code, retryable, original_exception)
+
+class ReplayAttackError(PaymentError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_REPLAY_ATTACK", False, original_exception)
+
+class DuplicatePaymentError(PaymentError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_DUPLICATE_PAYMENT", False, original_exception)
+
+class BudgetExceededError(PaymentError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_BUDGET_EXCEEDED", False, original_exception)
+
+class VerificationError(AgentGuardError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_VERIFICATION_FAILURE", False, original_exception)
+
+class UnknownExecutionStateError(PaymentError):
+    def __init__(self, message: str, original_exception=None):
+        super().__init__(message, "ERR_UNKNOWN_EXECUTION_STATE", False, original_exception)
+
+def map_backend_error(status_code: int, error_data: dict, original_exception=None) -> AgentGuardError:
+    """Maps the standardized backend JSONError payload to SDK exceptions."""
+    if not isinstance(error_data, dict):
+        return TransportError(f"Unexpected response format from backend: {error_data}", original_exception)
+
+    code = error_data.get("code", "ERR_UNKNOWN")
+    message = error_data.get("message", "Unknown error occurred")
+    retryable = error_data.get("retryable", False)
+
+    if code == "ERR_VALIDATION_FAILURE":
+        return ValidationError(message, original_exception)
+    elif code == "ERR_REPLAY_ATTACK":
+        return ReplayAttackError(message, original_exception)
+    elif code == "ERR_DUPLICATE_PAYMENT":
+        return DuplicatePaymentError(message, original_exception)
+    elif code == "ERR_BUDGET_EXCEEDED":
+        return BudgetExceededError(message, original_exception)
+    elif code == "ERR_UNKNOWN_EXECUTION_STATE":
+        return UnknownExecutionStateError(message, original_exception)
+    elif code == "ERR_AUTH_FAILURE":
+        return AuthenticationError(message, code, retryable, original_exception)
+    elif code == "ERR_INVALID_SIGNATURE":
+        return InvalidSignatureError(message, original_exception)
+    elif code == "ERR_EXPIRED_SIGNATURE":
+        return ExpiredSignatureError(message, original_exception)
+    elif "ERR_PAYMENT" in code:
+        return PaymentError(message, code, retryable, original_exception)
+    else:
+        return AgentGuardError(message, code, retryable, original_exception)

agentguard_python_sdk-0.1.2/agentguard/observability.py

@@ -0,0 +1,52 @@
+import time
+import json
+import uuid
+import logging
+from datetime import datetime
+from typing import Optional, Dict, Any
+
+# [PRIORITY 9] SDK OBSERVABILITY CORE
+
+class Span:
+    def __init__(self, name: str, trace_id: str, parent_id: Optional[str] = None):
+        self.name = name
+        self.trace_id = trace_id
+        self.span_id = str(uuid.uuid4())[:8]
+        self.parent_id = parent_id
+        self.start_time = time.time()
+        self.metadata = {}
+
+    def set_attribute(self, key: str, value: Any):
+        self.metadata[key] = value
+
+    def end(self, error: Optional[str] = None):
+        duration = (time.time() - self.start_time) * 1000
+        log_data = {
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "level": "INFO" if not error else "ERROR",
+            "service": "agentguard-sdk",
+            "event": "span_end",
+            "span_name": self.name,
+            "span_id": self.span_id,
+            "parent_id": self.parent_id,
+            "trace_id": self.trace_id,
+            "duration_ms": duration,
+            "error": error,
+            "metadata": self.metadata
+        }
+        logging.getLogger("agentguard-sdk").info(json.dumps(log_data))
+
+def start_span(name: str, trace_id: str, parent_id: Optional[str] = None) -> Span:
+    span = Span(name, trace_id, parent_id)
+    log_data = {
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "level": "INFO",
+        "service": "agentguard-sdk",
+        "event": "span_start",
+        "span_name": name,
+        "span_id": span.span_id,
+        "parent_id": parent_id,
+        "trace_id": trace_id
+    }
+    logging.getLogger("agentguard-sdk").info(json.dumps(log_data))
+    return span

{agentguard_python_sdk-0.1.0 → agentguard_python_sdk-0.1.2}/agentguard/types.py

@@ -1,25 +1,25 @@
-from dataclasses import dataclass, field
-from typing import Dict, Any
-
-@dataclass
-class AgentGuardReceipt:
-    """
-    Structured response for a successful AgentGuard payment.
-    """
-    tx_id: str
-    consent_hash: str
-    audit_url: str
-    data: Dict[str, Any] = field(default_factory=dict)
-
-@dataclass
-class AuditProof:
-    """
-    Structured response for a DPDP compliance audit.
-    """
-    verified: bool
-    tx_id: str
-    principal_id: str
-    consent_hash: str
-    on_chain_hash: str
-    explorer_url: str
-    message: str
+from dataclasses import dataclass, field
+from typing import Dict, Any
+
+@dataclass
+class AgentGuardReceipt:
+    """
+    Structured response for a successful AgentGuard payment.
+    """
+    tx_id: str
+    consent_hash: str
+    audit_url: str
+    data: Dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class AuditProof:
+    """
+    Structured response for a DPDP compliance audit.
+    """
+    verified: bool
+    tx_id: str
+    principal_id: str
+    consent_hash: str
+    on_chain_hash: str
+    explorer_url: str
+    message: str

{agentguard_python_sdk-0.1.0 → agentguard_python_sdk-0.1.2}/agentguard_python_sdk.egg-info/PKG-INFO

@@ -1,13 +1,15 @@
 Metadata-Version: 2.4
 Name: agentguard-python-sdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
 Author: AgentGuard Team
-License: MIT
+License-Expression: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: py-algorand-sdk>=2.0.0
 
 # AgentGuard SDK
 
@@ -18,7 +20,7 @@ By isolating private keys in a hardened **MCP Server (Vault)** and using the **A
 ## Installation
 
 ```bash
-pip install agentguard
+pip install agentguard-python-sdk
 ```
 
 ## Quick Start (3-Line Usage)
@@ -34,7 +36,7 @@ async def main():
         # 2. Perform a secure payment (includes automatic DPDP consent hashing)
         receipt = await client.pay_and_fetch(
             resource_url="https://api.stock.com/reliance",
-            amount_algo=0.05,
+            amount_algo="0.05",
             purpose="Financial Analysis"
         )
         print(f"Payment Successful! TX ID: {receipt.tx_id}")

{agentguard_python_sdk-0.1.0 → agentguard_python_sdk-0.1.2}/agentguard_python_sdk.egg-info/SOURCES.txt

@@ -1,8 +1,12 @@
 README.md
 pyproject.toml
 agentguard/__init__.py
+agentguard/auth.py
 agentguard/client.py
+agentguard/config.py
 agentguard/consent.py
+agentguard/errors.py
+agentguard/observability.py
 agentguard/types.py
 agentguard_python_sdk.egg-info/PKG-INFO
 agentguard_python_sdk.egg-info/SOURCES.txt

agentguard_python_sdk-0.1.2/agentguard_python_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.27.0
+pydantic>=2.0.0
+pynacl>=1.5.0
+py-algorand-sdk>=2.0.0

{agentguard_python_sdk-0.1.0 → agentguard_python_sdk-0.1.2}/pyproject.toml

@@ -1,22 +1,24 @@
-[build-system]
-requires = ["setuptools>=61.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "agentguard-python-sdk"
-version = "0.1.0"
-description = "A production-grade middleware for AI agents to perform on-chain payments and verifiable consent."
-readme = "README.md"
-requires-python = ">=3.9"
-license = {text = "MIT"}
-authors = [
-    {name = "AgentGuard Team"}
-]
-dependencies = [
-    "httpx>=0.27.0",
-    "pydantic>=2.0.0"
-]
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["agentguard*"]
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentguard-python-sdk"
+version = "0.1.2"
+description = "A production-grade middleware for AI agents to perform on-chain payments and verifiable consent."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    {name = "AgentGuard Team"}
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "pynacl>=1.5.0",
+    "py-algorand-sdk>=2.0.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["agentguard*"]

agentguard_python_sdk-0.1.0/agentguard/__init__.py

@@ -1,3 +0,0 @@
-from .client import AgentGuardClient
-
-__all__ = ["AgentGuardClient"]

agentguard_python_sdk-0.1.0/agentguard/client.py

@@ -1,126 +0,0 @@
-import httpx
-import uuid
-import logging
-from typing import Optional, Dict, Any
-from .consent import generate_consent_proof
-from .types import AgentGuardReceipt, AuditProof
-
-logger = logging.getLogger("agentguard-sdk")
-
-class AgentGuardClient:
-    def __init__(self, wallet_address: str, base_url: str = "https://agentguard-backend.onrender.com"):
-        """
-        Initialize the AgentGuard production client.
-        
-        Args:
-            wallet_address: The user's wallet address (Principal ID).
-            base_url: The URL of the AgentGuard Backend.
-        """
-        self.wallet_address = wallet_address
-        self.base_url = base_url.rstrip("/")
-        self.async_client = httpx.AsyncClient(timeout=30.0)
-
-    async def pay_and_fetch(
-        self, 
-        resource_url: str, 
-        amount_algo: float, 
-        purpose: str
-    ) -> AgentGuardReceipt:
-        """
-        Asynchronously perform an on-chain payment and return a typed receipt.
-        
-        Args:
-            resource_url: The URL/ID of the resource being accessed.
-            amount_algo: The amount to pay in ALGO.
-            purpose: The purpose of the data processing.
-            
-        Returns:
-            AgentGuardReceipt: A structured receipt with transaction details.
-        """
-        # 1. Generate Nonce for replay protection
-        nonce = str(uuid.uuid4())
-        
-        # 2. Generate Consent Proof (SHA256 of metadata)
-        consent_hash, timestamp = generate_consent_proof(
-            principal_id=self.wallet_address,
-            resource_url=resource_url,
-            purpose=purpose,
-            nonce=nonce
-        )
-        
-        # 3. Request Payment via Backend Proxy
-        payload = {
-            "resource_url": resource_url,
-            "amount_algo": amount_algo,
-            "purpose": purpose,
-            "principal_id": self.wallet_address,
-            "consent_hash": consent_hash,
-            "nonce": nonce,
-            "timestamp": timestamp
-        }
-        
-        try:
-            response = await self.async_client.post(f"{self.base_url}/pay", json=payload)
-            response.raise_for_status()
-            res_data = response.json()
-            
-            return AgentGuardReceipt(
-                tx_id=res_data["tx_id"],
-                consent_hash=res_data["consent_hash"],
-                audit_url=res_data["audit_url"],
-                data=res_data.get("data", {})
-            )
-        except httpx.HTTPStatusError as e:
-            logger.error(f"Payment failed: {e.response.text}")
-            raise Exception(f"Payment failed: {e.response.text}")
-        except Exception as e:
-            logger.error(f"Connection failed: {e}")
-            raise Exception(f"Could not connect to AgentGuard Backend: {e}")
-
-    async def verify(self, tx_id: str) -> AuditProof:
-        """
-        Asynchronously verify a transaction against the blockchain audit trail.
-        """
-        try:
-            response = await self.async_client.get(f"{self.base_url}/verify/{tx_id}")
-            response.raise_for_status()
-            res_data = response.json()
-            
-            return AuditProof(
-                verified=res_data["verified"],
-                tx_id=res_data["tx_id"],
-                principal_id=res_data["principal_id"],
-                consent_hash=res_data["consent_hash"],
-                on_chain_hash=res_data["on_chain_hash"],
-                explorer_url=res_data["explorer_url"],
-                message=res_data["message"]
-            )
-        except Exception as e:
-            logger.error(f"Verification failed: {e}")
-            raise Exception(f"Verification failed: {e}")
-
-    async def register_budget(self, limit_algo: float) -> Dict[str, Any]:
-        """
-        Convenience method to register/update the user's budget.
-        """
-        payload = {
-            "wallet_address": self.wallet_address,
-            "budget_algo": limit_algo
-        }
-        try:
-            response = await self.async_client.post(f"{self.base_url}/user/register", json=payload)
-            response.raise_for_status()
-            return response.json()
-        except Exception as e:
-            logger.error(f"Budget registration failed: {e}")
-            raise Exception(f"Budget registration failed: {e}")
-
-    async def close(self):
-        """Close the underlying HTTP client."""
-        await self.async_client.aclose()
-
-    async def __aenter__(self):
-        return self
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        await self.close()

agentguard_python_sdk-0.1.0/agentguard/consent.py

@@ -1,58 +0,0 @@
-import time
-import json
-import hashlib
-import logging
-from typing import Dict, Any
-
-# Configure logging
-logger = logging.getLogger("agentguard-sdk")
-
-def generate_consent(principal_id: str, purpose: str, item: str, nonce: str, data_fiduciary: str = "AgentGuard Platform") -> Dict[str, Any]:
-    """
-    Creates a user consent object dictionary containing DPDP compliant fields.
-    """
-    timestamp = int(time.time())
-    
-    consent_obj = {
-        "principal_id": principal_id,
-        "data_fiduciary": data_fiduciary,
-        "purpose": purpose,
-        "item": item,
-        "timestamp": timestamp,
-        "nonce": nonce
-    }
-    
-    logger.info(f"Generated DPDP consent for principal={principal_id} at {timestamp}")
-    return consent_obj
-
-def hash_consent(consent: Dict[str, Any]) -> str:
-    """
-    Converts a consent dictionary into a sorted JSON string
-    and generates a SHA256 hash of it for on-chain logging.
-    
-    Args:
-        consent: The consent dictionary.
-        
-    Returns:
-        str: SHA256 hash string.
-    """
-    # Convert consent dict to JSON string with sorted keys to ensure determinism
-    consent_json = json.dumps(consent, sort_keys=True)
-    
-    # Generate SHA256 hash
-    consent_hash = hashlib.sha256(consent_json.encode("utf-8")).hexdigest()
-    
-    logger.info(f"Consent hash generated: {consent_hash}")
-    return consent_hash
-
-def generate_consent_proof(principal_id: str, resource_url: str, purpose: str, nonce: str) -> tuple[str, int]:
-    """
-    High-level helper to generate a consent hash and return the timestamp used.
-    """
-    consent = generate_consent(
-        principal_id=principal_id,
-        purpose=purpose,
-        item=resource_url,
-        nonce=nonce
-    )
-    return hash_consent(consent), consent["timestamp"]

agentguard_python_sdk-0.1.0/agentguard_python_sdk.egg-info/requires.txt

@@ -1,2 +0,0 @@
-httpx>=0.27.0
-pydantic>=2.0.0