agentguard-python-sdk 0.1.3__tar.gz → 0.2.1__tar.gz

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentguard-python-sdk
-Version: 0.1.3
+Version: 0.2.1
 Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
 Author: AgentGuard Team
 License-Expression: MIT
@@ -32,7 +32,12 @@ from agentguard import AgentGuardClient
 
 async def main():
     # 1. Initialize the client
-    async with AgentGuardClient(wallet_address="YOUR_WALLET_ADDRESS") as client:
+    # NOTE: The backend requires a cryptographic signature on `/pay`.
+    # Provide `private_key` as a base64-encoded Algorand private key seed for request signing.
+    async with AgentGuardClient(
+        wallet_address="YOUR_WALLET_ADDRESS",
+        private_key="YOUR_PRIVATE_KEY_B64",
+    ) as client:
         
         # 2. Perform a secure payment (includes automatic DPDP consent hashing)
         receipt = await client.pay_and_fetch(

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/README.md

@@ -18,7 +18,12 @@ from agentguard import AgentGuardClient
 
 async def main():
     # 1. Initialize the client
-    async with AgentGuardClient(wallet_address="YOUR_WALLET_ADDRESS") as client:
+    # NOTE: The backend requires a cryptographic signature on `/pay`.
+    # Provide `private_key` as a base64-encoded Algorand private key seed for request signing.
+    async with AgentGuardClient(
+        wallet_address="YOUR_WALLET_ADDRESS",
+        private_key="YOUR_PRIVATE_KEY_B64",
+    ) as client:
         
         # 2. Perform a secure payment (includes automatic DPDP consent hashing)
         receipt = await client.pay_and_fetch(

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/agentguard/client.py

@@ -15,7 +15,7 @@ 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 .errors import map_backend_error, TransportError, AgentGuardError, VerificationError, PaymentError
 from .config import AgentGuardConfig
 from .observability import start_span
 
@@ -105,48 +105,63 @@ class AgentGuardClient:
         correlation_id: Optional[str] = None
     ) -> AgentGuardReceipt:
         """
-        Asynchronously perform an on-chain payment and return a typed receipt.
+        End-to-end flow for accessing resources (Probe -> Pay -> Fetch).
         
-        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. SDK sends GET resource_url with no payment.
+        2. If 200 -> return data directly, no payment.
+        3. If 402 -> extract price from headers, pay via backend, and retry with proof.
         """
-        # 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.")
+        # Step A — Probe Request
+        async with httpx.AsyncClient(timeout=self.timeout) as probe_client:
+            try:
+                probe_res = await probe_client.get(resource_url)
+                
+                if probe_res.status_code == 200:
+                    logger.info(f"Resource {resource_url} is free. Accessing directly.")
+                    return AgentGuardReceipt(
+                        tx_id=None,
+                        consent_hash=None,
+                        audit_url=None,
+                        data=probe_res.json()
+                    )
+                
+                if probe_res.status_code != 402:
+                    raise PaymentError(f"Resource server returned unexpected status: {probe_res.status_code}", "ERR_UNEXPECTED_STATUS")
+                
+                # Extract 402 headers
+                header_amount = probe_res.headers.get("X-402-Payment-Amount")
+                header_receiver = probe_res.headers.get("X-402-Receiver-Address")
+                
+                if header_amount:
+                    actual_microalgos = int(header_amount)
+                    logger.info(f"Resource requires payment: {actual_microalgos} microAlgos (per header)")
+                elif microalgos is not None:
+                    actual_microalgos = microalgos
+                elif amount_algo is not None:
+                    actual_microalgos = parse_algo_amount_to_microalgos(amount_algo)
+                else:
+                    raise ValueError("Resource requires payment but provided no price header, and no fallback amount was provided.")
+                
+            except httpx.RequestError as e:
+                raise TransportError(f"Failed to probe resource: {e}")
+            except Exception as e:
+                if isinstance(e, AgentGuardError): raise
+                raise AgentGuardError(f"Unexpected error during probe: {str(e)}", "ERR_PROBE_FAILED")
 
-        # 2. Idempotency & Replay Protection (PHASE C)
-        # We generate these early so they can be persisted across retries if needed.
+        # Step B — Payment (Using Backend Relay)
         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
+            timestamp=timestamp
         )
         
-        # 4. Payload Construction
         payload = {
             "resource_url": resource_url,
             "microalgos": actual_microalgos,
@@ -164,7 +179,6 @@ class AgentGuardClient:
             "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({
@@ -173,63 +187,57 @@ class AgentGuardClient:
                 "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
         
+        receipt = None
         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(
+                    receipt = AgentGuardReceipt(
                         tx_id=res_data["tx_id"],
                         consent_hash=res_data["consent_hash"],
                         audit_url=res_data["audit_url"],
-                        data=res_data.get("data", {})
                     )
+                    break
                 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)
-
+                    if response.status_code in [502, 503, 504, 429] and attempt < max_attempts - 1:
+                        await asyncio.sleep(base_delay * (2 ** attempt))
+                        continue
+                    raise map_backend_error(response.status_code, response.json())
             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)
+                    await asyncio.sleep(base_delay * (2 ** attempt))
                     continue
-                span.end(error="transport_failure")
-                raise TransportError(f"Could not connect to AgentGuard Backend: {e}")
+                raise TransportError(f"Backend unreachable: {e}")
+
+        if not receipt:
+            raise PaymentError("Payment failed or timed out.")
+
+        # Step C — Retry with Proof
+        async with httpx.AsyncClient(timeout=self.timeout) as fetch_client:
+            logger.info(f"Payment successful (TX: {receipt.tx_id}). Fetching data...")
+            proof_headers = {
+                "X-AgentGuard-Proof": receipt.tx_id,
+                "X-AgentGuard-Principal": self.wallet_address
+            }
+            try:
+                final_res = await fetch_client.get(resource_url, headers=proof_headers)
+                if final_res.status_code == 200:
+                    receipt.data = final_res.json()
+                    span.end()
+                    return receipt
+                else:
+                    span.end(error=f"Resource rejected proof: {final_res.status_code}")
+                    raise PaymentError(f"Proof rejected by resource server: {final_res.status_code}")
             except Exception as e:
-                attempt_span.end(error=str(e))
-                span.end(error="unexpected_sdk_error")
-                raise
+                span.end(error=str(e))
+                raise TransportError(f"Failed to fetch data with proof: {e}")
 
     async def verify(self, tx_id: str, verify_onchain: bool = False, local_proof: Optional[Dict[str, Any]] = None) -> AuditProof:
         """
@@ -265,9 +273,19 @@ class AgentGuardClient:
                 canonical_json = res_data.get("canonical_json")
                 
                 if not canonical_json and local_proof:
-                    # [Priority 8 BONUS] Reconstruct canonical JSON from raw local proof
+                    # [Priority 8 BONUS] Reconstruct canonical JSON using SHARED SCHEMA BUILDER
+                    from .consent import build_canonical_payload
                     from .auth import canonicalize_payload
-                    canonical_bytes = canonicalize_payload(local_proof)
+                    
+                    canonical_payload = build_canonical_payload(
+                        principal_id=local_proof.get("principal_id", self.wallet_address),
+                        resource_url=local_proof.get("resource_url", ""),
+                        purpose=local_proof.get("purpose", ""),
+                        microalgos=int(local_proof.get("microalgos", 0)),
+                        nonce=local_proof.get("nonce", ""),
+                        timestamp=int(local_proof.get("timestamp", 0))
+                    )
+                    canonical_bytes = canonicalize_payload(canonical_payload)
                     canonical_json = canonical_bytes.decode("utf-8")
                 
                 if not canonical_json:

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/agentguard/consent.py

@@ -8,56 +8,36 @@ from typing import Dict, Any
 # Configure logging
 logger = logging.getLogger("agentguard-sdk")
 
-def generate_consent(
+def build_canonical_payload(
     principal_id: str, 
+    resource_url: str, 
     purpose: str, 
-    item: str, 
-    nonce: str, 
     microalgos: int,
-    data_fiduciary: str = "AlgoBharat Agentic Node",
-    timestamp: int = None
+    nonce: str,
+    timestamp: int,
+    data_fiduciary: str = "AlgoBharat Agentic Node"
 ) -> 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.
+    SINGLE SOURCE OF TRUTH for the audit payload schema.
+    Guarantees deterministic parity between SDK, Backend, and recovery logic.
     """
-    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),
+    return {
         "data_fiduciary": unicodedata.normalize("NFC", data_fiduciary),
-        "purpose": unicodedata.normalize("NFC", purpose),
-        "item": unicodedata.normalize("NFC", item),
-        "microalgos": microalgos,
-        "timestamp": timestamp,
+        "hash_version": 2, # Current Refactor Version
+        "item": unicodedata.normalize("NFC", resource_url),
+        "microalgos": int(microalgos),
         "nonce": nonce,
-        "hash_version": 2 # Current Refactor Version
+        "principal_id": unicodedata.normalize("NFC", principal_id),
+        "purpose": unicodedata.normalize("NFC", purpose),
+        "timestamp": int(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:
     """
     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
+    # Convert consent dict to JSON string with strict canonical form
     consent_json = json.dumps(consent, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
     consent_hash = hashlib.sha256(consent_json.encode("utf-8")).hexdigest()
     
@@ -68,12 +48,15 @@ def generate_consent_proof(principal_id: str, resource_url: str, purpose: str, n
     """
     High-level helper to generate a consent hash and return the timestamp used.
     """
-    consent = generate_consent(
+    if timestamp is None:
+        timestamp = int(time.time())
+    
+    consent = build_canonical_payload(
         principal_id=principal_id,
+        resource_url=resource_url,
         purpose=purpose,
-        item=resource_url,
-        nonce=nonce,
         microalgos=microalgos,
+        nonce=nonce,
         timestamp=timestamp
     )
     return hash_consent(consent), consent["timestamp"]

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/agentguard/types.py

@@ -1,14 +1,14 @@
 from dataclasses import dataclass, field
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 
 @dataclass
 class AgentGuardReceipt:
     """
     Structured response for a successful AgentGuard payment.
     """
-    tx_id: str
-    consent_hash: str
-    audit_url: str
+    tx_id: Optional[str]
+    consent_hash: Optional[str]
+    audit_url: Optional[str]
     data: Dict[str, Any] = field(default_factory=dict)
 
 @dataclass

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/agentguard_python_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentguard-python-sdk
-Version: 0.1.3
+Version: 0.2.1
 Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
 Author: AgentGuard Team
 License-Expression: MIT
@@ -32,7 +32,12 @@ from agentguard import AgentGuardClient
 
 async def main():
     # 1. Initialize the client
-    async with AgentGuardClient(wallet_address="YOUR_WALLET_ADDRESS") as client:
+    # NOTE: The backend requires a cryptographic signature on `/pay`.
+    # Provide `private_key` as a base64-encoded Algorand private key seed for request signing.
+    async with AgentGuardClient(
+        wallet_address="YOUR_WALLET_ADDRESS",
+        private_key="YOUR_PRIVATE_KEY_B64",
+    ) as client:
         
         # 2. Perform a secure payment (includes automatic DPDP consent hashing)
         receipt = await client.pay_and_fetch(

{agentguard_python_sdk-0.1.3 → agentguard_python_sdk-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentguard-python-sdk"
-version = "0.1.3"
+version = "0.2.1"
 description = "A production-grade middleware for AI agents to perform on-chain payments and verifiable consent."
 readme = "README.md"
 requires-python = ">=3.9"