agentguard-python-sdk 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

agentguard/__init__.py

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

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/client.py

@@ -1,91 +1,305 @@
 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, base_url: str = "https://agentguard-backend.onrender.com"):
+    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 production client.
-        
-        Args:
-            wallet_address: The user's wallet address (Principal ID).
-            base_url: The URL of the AgentGuard Backend.
+        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 = base_url.rstrip("/")
-        self.async_client = httpx.AsyncClient(timeout=30.0)
+        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, 
-        amount_algo: float, 
-        purpose: 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.
-            amount_algo: The amount to pay in ALGO.
             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. Generate Nonce for replay protection
-        nonce = str(uuid.uuid4())
+        # 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.")
         
-        # 2. Generate Consent Proof (SHA256 of metadata)
-        consent_hash, timestamp = generate_consent_proof(
+        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=nonce
+            nonce=act_nonce,
+            microalgos=actual_microalgos,
+            timestamp=timestamp # Pass through for retry consistency
         )
         
-        # 3. Request Payment via Backend Proxy
+        # 4. Payload Construction
         payload = {
             "resource_url": resource_url,
-            "amount_algo": amount_algo,
+            "microalgos": actual_microalgos,
             "purpose": purpose,
             "principal_id": self.wallet_address,
             "consent_hash": consent_hash,
-            "nonce": nonce,
-            "timestamp": timestamp
+            "nonce": act_nonce,
+            "timestamp": act_timestamp,
+            "idempotency_key": idem_key,
+            "correlation_id": act_correlation_id
         }
         
-        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}")
+        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)
 
-    async def verify(self, tx_id: str) -> AuditProof:
+            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:
-            response = await self.async_client.get(f"{self.base_url}/verify/{tx_id}")
-            response.raise_for_status()
-            res_data = response.json()
-            
+            # 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"],
@@ -95,25 +309,90 @@ class AgentGuardClient:
                 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:
-            logger.error(f"Verification failed: {e}")
-            raise Exception(f"Verification failed: {e}")
+            if isinstance(e, AgentGuardError): raise
+            raise VerificationError(f"Independent verification failed: {str(e)}", original_exception=e)
 
-    async def register_budget(self, limit_algo: float) -> Dict[str, Any]:
+    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_algo": limit_algo
+            "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 Exception as e:
-            logger.error(f"Budget registration failed: {e}")
-            raise Exception(f"Budget registration failed: {e}")
+        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."""
@@ -124,3 +403,5 @@ class AgentGuardClient:
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         await self.close()
+
+    # Removed _log_event because it's replaced by Span system

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/consent.py

@@ -2,50 +2,69 @@ 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, data_fiduciary: str = "AgentGuard Platform") -> Dict[str, Any]:
+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.
     """
-    timestamp = int(time.time())
+    if timestamp is None:
+        timestamp = int(time.time())
     
+    # Normalize strings to NFC at the creation boundary
     consent_obj = {
-        "principal_id": principal_id,
-        "data_fiduciary": data_fiduciary,
-        "purpose": purpose,
-        "item": item,
+        "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
+        "nonce": nonce,
+        "hash_version": 2 # Current Refactor Version
     }
     
-    logger.info(f"Generated DPDP consent for principal={principal_id} at {timestamp}")
+    logger.info(f"Generated DPDP consent (v2) 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.
+    Canonical hashing implementation.
+    MUST REMAINT SYNCED with Backend and MCP Server.
     
-    Args:
-        consent: The consent dictionary.
-        
-    Returns:
-        str: SHA256 hash string.
+    Rules:
+    1. sort_keys=True
+    2. separators=(',', ':')
+    3. ensure_ascii=False
+    4. Encoding: utf-8
     """
-    # Convert consent dict to JSON string with sorted keys to ensure determinism
-    consent_json = json.dumps(consent, sort_keys=True)
-    
-    # Generate SHA256 hash
+    # 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) -> tuple[str, int]:
+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.
     """
@@ -53,6 +72,8 @@ def generate_consent_proof(principal_id: str, resource_url: str, purpose: str, n
         principal_id=principal_id,
         purpose=purpose,
         item=resource_url,
-        nonce=nonce
+        nonce=nonce,
+        microalgos=microalgos,
+        timestamp=timestamp
     )
     return hash_consent(consent), consent["timestamp"]

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/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/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.dist-info → agentguard_python_sdk-0.1.2.dist-info}/METADATA

@@ -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.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+agentguard/__init__.py,sha256=gCRF3pf7qpWf6_VVwgl2X1A4apOSCx7zqd8g2r3fe44,130
+agentguard/auth.py,sha256=PBb7l-x5MGTv_iwilK6LTi5Yhr76qcZL30p1-J80lDg,1720
+agentguard/client.py,sha256=B8ttu1_AcUFODeW27Q6jDHDyh1Yn1AdUWfBDs3Xg50w,17798
+agentguard/config.py,sha256=96xRt8FCVoRS1jVzNt4i4hzzP1NorT2NrAWPE_5XbCU,1032
+agentguard/consent.py,sha256=iTVCf4FaFlsJQF0R63HtbgYTtDUPzRCVPULz-cmX2nA,2706
+agentguard/errors.py,sha256=rEFQI4mrbccXRyjVYm_pZwHWr4aolcg8e5KMCIzrOdE,4181
+agentguard/observability.py,sha256=2xSySYDtPhtiNUKXH0zQ0N4WG7j3ssQqPtOBDK6V2EQ,1706
+agentguard/types.py,sha256=U1anjHwYfjFhbzWP-xkaLfPqCkpzJ4DtjOt5kP9bsLA,559
+agentguard_python_sdk-0.1.2.dist-info/METADATA,sha256=BO-xdHnBpkK7GoVCQnEzSObJQnHGyAsxmym8h591SVY,2503
+agentguard_python_sdk-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentguard_python_sdk-0.1.2.dist-info/top_level.txt,sha256=rEW5sAnjxXRs63ja2psmsMRMJJfi_3EAxf7crl1nHyw,11
+agentguard_python_sdk-0.1.2.dist-info/RECORD,,

agentguard_python_sdk-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-agentguard/__init__.py,sha256=P8UrlV5qCw8DCFwGmAunbItyBncuDH7UK7HzsqYMxBk,69
-agentguard/client.py,sha256=8rvSOzfrtjKNy5PibBbikX9Sm-_-OnW4OXxrFWUGRUM,4550
-agentguard/consent.py,sha256=RDefJwimc9MM14fbRrM9740yMHate7IIyJElkDoPPHE,1846
-agentguard/types.py,sha256=lJCLHl-DYYV6wDETIhj7NbE548YviUXgMp6svH5nM60,534
-agentguard_python_sdk-0.1.0.dist-info/METADATA,sha256=I67rw1MY1cM2EjF3eO48ij2lu6GVmmi8y2TEkXov2j4,2410
-agentguard_python_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-agentguard_python_sdk-0.1.0.dist-info/top_level.txt,sha256=rEW5sAnjxXRs63ja2psmsMRMJJfi_3EAxf7crl1nHyw,11
-agentguard_python_sdk-0.1.0.dist-info/RECORD,,