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

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
 
@@ -55,11 +55,12 @@ def parse_algo_amount_to_microalgos(amount: str) -> int:
 class AgentGuardClient:
     def __init__(
         self, 
-        wallet_address: str, 
+        wallet_address: Optional[str] = None, 
         config: Optional[AgentGuardConfig] = None, 
         private_key: str = None,
         backend_url: Optional[str] = None,
-        indexer_url: Optional[str] = None
+        indexer_url: Optional[str] = None,
+        principal_id: Optional[str] = None
     ):
         """
         Initialize the AgentGuard client with a structured config object or direct overrides.
@@ -72,7 +73,11 @@ class AgentGuardClient:
         if indexer_url:
             self.config.indexer_url = indexer_url
 
-        self.wallet_address = wallet_address
+        # Support principal_id as an alias for wallet_address
+        self.wallet_address = wallet_address or principal_id
+        if not self.wallet_address:
+            raise ValueError("Either wallet_address or principal_id must be provided.")
+            
         self.base_url = self.config.backend_url.rstrip("/")
         self.private_key = private_key
         
@@ -100,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,
@@ -159,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({
@@ -168,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:
         """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentguard-python-sdk
-Version: 0.1.2
+Version: 0.2.0
 Summary: A production-grade middleware for AI agents to perform on-chain payments and verifiable consent.
 Author: AgentGuard Team
 License-Expression: MIT
@@ -8,6 +8,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pynacl>=1.5.0
 Requires-Dist: py-algorand-sdk>=2.0.0
 

{agentguard_python_sdk-0.1.2.dist-info → agentguard_python_sdk-0.2.0.dist-info}/RECORD

@@ -1,12 +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/client.py,sha256=iQW4rseOh2LaRf4SIN4TsBEFepcy4gC7DyLNe4LAmbw,18443
 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/types.py,sha256=HpxtMCzV6x-TIsv99gurLwd53DqtC-ul_IMKPuzps2Y,599
+agentguard_python_sdk-0.2.0.dist-info/METADATA,sha256=T6mwNf3cIpwXBtJVWOgRBeT1IImBMn5CI14uJHA71_I,2544
+agentguard_python_sdk-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentguard_python_sdk-0.2.0.dist-info/top_level.txt,sha256=rEW5sAnjxXRs63ja2psmsMRMJJfi_3EAxf7crl1nHyw,11
+agentguard_python_sdk-0.2.0.dist-info/RECORD,,