xache 5.0.0__py3-none-any.whl

xache/utils/http.py

@@ -0,0 +1,209 @@
+"""
+HTTP client utilities with retry logic
+"""
+
+import asyncio
+import json
+from typing import Dict, Optional, Any, Literal
+from dataclasses import dataclass
+
+import aiohttp
+
+from ..errors import (
+    create_error_from_response,
+    PaymentRequiredError,
+    NetworkError,
+    XacheError,
+)
+from ..types import APIResponse
+
+
+@dataclass
+class RetryConfig:
+    """Retry configuration"""
+    max_retries: int = 3
+    initial_delay: float = 1.0
+    max_delay: float = 10.0
+    backoff_multiplier: float = 2.0
+    retryable_status_codes: list = None
+
+    def __post_init__(self):
+        if self.retryable_status_codes is None:
+            self.retryable_status_codes = [408, 429, 500, 502, 503, 504]
+
+
+class HttpClient:
+    """HTTP client with retry logic"""
+
+    def __init__(
+        self,
+        timeout: int = 30,
+        retry_config: Optional[RetryConfig] = None,
+        debug: bool = False,
+    ):
+        self.timeout = timeout
+        self.retry_config = retry_config or RetryConfig()
+        self.debug = debug
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit"""
+        await self.close()
+
+    async def _ensure_session(self):
+        """Ensure aiohttp session exists"""
+        if self._session is None or self._session.closed:
+            timeout = aiohttp.ClientTimeout(total=self.timeout)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+
+    async def close(self):
+        """Close HTTP session"""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def request(
+        self,
+        method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"],
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        body: Optional[str] = None,
+    ) -> APIResponse:
+        """
+        Make HTTP request with retry logic
+
+        Args:
+            method: HTTP method
+            url: Full URL
+            headers: Request headers
+            body: Request body (JSON string)
+
+        Returns:
+            API response
+
+        Raises:
+            XacheError: API error
+            NetworkError: Network error
+        """
+        await self._ensure_session()
+
+        headers = headers or {}
+        headers["Content-Type"] = "application/json"
+
+        last_error: Optional[Exception] = None
+        attempt = 0
+
+        while attempt <= self.retry_config.max_retries:
+            try:
+                if self.debug and attempt > 0:
+                    print(f"Retry attempt {attempt}/{self.retry_config.max_retries} for {method} {url}")
+
+                response = await self._make_request(method, url, headers, body)
+                return response
+
+            except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+                last_error = e
+                attempt += 1
+
+                if attempt <= self.retry_config.max_retries:
+                    delay = self._calculate_delay(attempt)
+                    await asyncio.sleep(delay)
+                    continue
+
+            except PaymentRequiredError:
+                # Don't retry 402 errors
+                raise
+
+            except XacheError:
+                # Don't retry API errors (400, 401, 403, 404, 409, etc.)
+                raise
+
+            except Exception as e:
+                last_error = e
+                attempt += 1
+
+                if attempt <= self.retry_config.max_retries:
+                    delay = self._calculate_delay(attempt)
+                    await asyncio.sleep(delay)
+                    continue
+
+        # All retries exhausted
+        raise NetworkError(
+            f"Request failed after {self.retry_config.max_retries} retries",
+            last_error,
+        )
+
+    async def _make_request(
+        self,
+        method: str,
+        url: str,
+        headers: Dict[str, str],
+        body: Optional[str],
+    ) -> APIResponse:
+        """Make single HTTP request"""
+        async with self._session.request(
+            method,
+            url,
+            headers=headers,
+            data=body,
+        ) as response:
+            # Parse response
+            try:
+                response_json = await response.json()
+            except json.JSONDecodeError as e:
+                raise NetworkError("Failed to parse response JSON", e)
+
+            # Handle 402 Payment Required
+            if response.status == 402:
+                payment_data = response_json.get("payment", {})
+                meta = response_json.get("meta", {})
+                raise PaymentRequiredError(
+                    response_json.get("error", {}).get("message", "Payment required"),
+                    payment_data.get("challengeId", ""),
+                    payment_data.get("amount", ""),
+                    payment_data.get("chainHint", ""),
+                    payment_data.get("payTo", ""),
+                    payment_data.get("description", ""),
+                    meta.get("requestId"),
+                )
+
+            # Handle API error responses
+            if not response_json.get("success") and response_json.get("error"):
+                error = response_json["error"]
+                meta = response_json.get("meta", {})
+                raise create_error_from_response(
+                    error.get("code", "INTERNAL"),
+                    error.get("message", "Unknown error"),
+                    response.status,
+                    error.get("details"),
+                    meta.get("requestId"),
+                )
+
+            # Check if retryable status code
+            if response.status in self.retry_config.retryable_status_codes:
+                raise NetworkError(f"HTTP {response.status}: {response.reason}")
+
+            # Success response
+            return APIResponse(
+                success=response_json.get("success", True),
+                data=response_json.get("data"),
+                error=None,
+                meta=None,
+            )
+
+    def _calculate_delay(self, attempt: int) -> float:
+        """Calculate exponential backoff delay with jitter"""
+        import random
+
+        delay = min(
+            self.retry_config.initial_delay * (self.retry_config.backoff_multiplier ** (attempt - 1)),
+            self.retry_config.max_delay,
+        )
+
+        # Add jitter (±25%)
+        jitter = delay * 0.25 * (random.random() * 2 - 1)
+        return delay + jitter

xache/utils/retry.py

@@ -0,0 +1,101 @@
+"""
+Retry utility with exponential backoff
+Production-ready automatic error recovery
+"""
+
+import time
+from typing import Callable, TypeVar, List, Optional, Any
+from ..types import ErrorCode
+
+T = TypeVar('T')
+
+class RetryPolicy:
+    """Configuration for retry behavior"""
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        backoff_ms: Optional[List[int]] = None,
+        retryable_errors: Optional[List[ErrorCode]] = None,
+        timeout: int = 60000
+    ):
+        self.max_retries = max_retries
+        self.backoff_ms = backoff_ms or [1000, 2000, 4000]
+        self.retryable_errors = retryable_errors or ['RETRY_LATER', 'INTERNAL']
+        self.timeout = timeout
+
+
+def is_retryable_error(error: Exception, retryable_errors: List[ErrorCode]) -> bool:
+    """Check if error is retryable"""
+    if hasattr(error, 'code'):
+        return error.code in retryable_errors
+    return False
+
+
+def with_retry(
+    fn: Callable[[], T],
+    policy: Optional[RetryPolicy] = None,
+    debug: bool = False
+) -> T:
+    """
+    Execute function with automatic retry logic
+
+    Args:
+        fn: Function to execute
+        policy: Retry policy configuration
+        debug: Enable debug logging
+
+    Returns:
+        Result from successful function execution
+
+    Raises:
+        Last exception if all retries exhausted
+
+    Example:
+        >>> def fetch_data():
+        ...     return api.get('/data')
+        >>> result = with_retry(fetch_data, RetryPolicy(max_retries=5))
+    """
+    if policy is None:
+        policy = RetryPolicy()
+
+    start_time = time.time() * 1000  # Convert to milliseconds
+    last_error: Optional[Exception] = None
+
+    for attempt in range(policy.max_retries + 1):
+        # Check timeout
+        if (time.time() * 1000 - start_time) > policy.timeout:
+            raise TimeoutError(
+                f"Operation timed out after {policy.timeout}ms ({attempt} attempts)"
+            )
+
+        try:
+            return fn()
+        except Exception as error:
+            last_error = error
+
+            # If this is the last attempt, don't retry
+            if attempt == policy.max_retries:
+                break
+
+            # Check if error is retryable
+            if not is_retryable_error(error, policy.retryable_errors):
+                raise error
+
+            # Calculate delay
+            if attempt < len(policy.backoff_ms):
+                delay = policy.backoff_ms[attempt]
+            else:
+                delay = policy.backoff_ms[-1]
+
+            if debug:
+                print(f"Retry attempt {attempt + 1}/{policy.max_retries} after {delay}ms delay")
+
+            # Sleep for delay (convert ms to seconds)
+            time.sleep(delay / 1000)
+
+    # All retries exhausted, raise last error
+    if last_error:
+        raise last_error
+    else:
+        raise RuntimeError("Unexpected error in retry logic")

xache-5.0.0.dist-info/METADATA

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: xache
+Version: 5.0.0
+Summary: Official Python SDK for Xache Protocol
+Home-page: https://github.com/xache-ai/xache-protocol
+Author: Xache Protocol
+Author-email: Xache Protocol <dev@xache.xyz>
+License: MIT
+Project-URL: Homepage, https://xache.xyz
+Project-URL: Documentation, https://docs.xache.xyz
+Project-URL: Repository, https://github.com/oliveskin/xache
+Project-URL: Bug Reports, https://github.com/oliveskin/xache/issues
+Keywords: xache,ai,agent,memory,blockchain,decentralized
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: mnemonic>=0.20
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: bip-utils>=2.9.0
+Requires-Dist: PyNaCl>=1.5.0
+Requires-Dist: base58>=2.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pylint>=2.17.0; extra == "dev"
+Provides-Extra: encryption
+Requires-Dist: PyNaCl>=1.5.0; extra == "encryption"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Xache Protocol Python SDK
+
+Official Python SDK for [Xache Protocol](https://xache.ai) - decentralized agent memory and collective intelligence marketplace.
+
+## Features
+
+✅ **Async/Await** - Full asyncio support for concurrent operations
+✅ **Type Hints** - Complete type annotations for better IDE support
+✅ **Authentication** - Automatic request signing per protocol spec
+✅ **Payment Flow** - Built-in 402 payment handling (manual or Coinbase Commerce)
+✅ **Encryption** - Client-side encryption for memory storage
+✅ **Error Handling** - Typed exceptions with automatic retry logic
+✅ **Budget Management** - Track and control spending limits
+
+## Installation
+
+```bash
+pip install xache
+```
+
+With encryption support:
+
+```bash
+pip install xache[encryption]
+```
+
+## Quick Start
+
+```python
+import asyncio
+from xache import XacheClient
+
+async def main():
+    # Initialize client
+    async with XacheClient(
+        api_url="https://api.xache.xyz",
+        did="did:agent:evm:0xYourWalletAddress",
+        private_key="0x...",
+    ) as client:
+        # Register identity
+        identity = await client.identity.register(
+            wallet_address="0xYourWalletAddress",
+            key_type="evm",
+            chain="base",
+        )
+        print(f"DID: {identity.did}")
+
+asyncio.run(main())
+```
+
+## Usage Examples
+
+### Memory Storage
+
+```python
+# Store encrypted memory (automatic encryption + 402 payment)
+memory = await client.memory.store(
+    data={
+        "context": "user preferences",
+        "theme": "dark",
+        "language": "en",
+    },
+    storage_tier="hot",
+)
+print(f"Memory ID: {memory.memory_id}")
+
+# Retrieve memory (automatic decryption + 402 payment)
+retrieved = await client.memory.retrieve(memory_id=memory.memory_id)
+print(f"Data: {retrieved.data}")
+
+# Delete memory (free)
+await client.memory.delete(memory.memory_id)
+```
+
+### Collective Intelligence
+
+```python
+# Contribute a heuristic (automatic 402 payment)
+heuristic = await client.collective.contribute(
+    pattern="Use async/await for cleaner async code in Python",
+    domain="python",
+    tags=["async", "best-practices", "readability"],
+    context_type="code-review",
+)
+print(f"Heuristic ID: {heuristic.heuristic_id}")
+
+# Query collective (automatic 402 payment)
+results = await client.collective.query(
+    query_text="How to optimize database queries in Python",
+    domain="python",
+    limit=10,
+)
+
+for match in results.matches:
+    print(f"Pattern: {match.pattern}")
+    print(f"Score: {match.relevance_score}")
+    print(f"Royalty: ${match.royalty_amount}")
+```
+
+### Budget Management
+
+```python
+# Check budget status
+budget = await client.budget.get_status()
+print(f"Limit: ${budget.limit_cents / 100}")
+print(f"Spent: ${budget.spent_cents / 100}")
+print(f"Remaining: ${budget.remaining_cents / 100}")
+print(f"Usage: {budget.percentage_used:.1f}%")
+
+# Update budget limit
+await client.budget.update_limit(5000)  # $50/month
+
+# Check if you can afford an operation
+can_afford = await client.budget.can_afford(100)  # 100 cents = $1
+```
+
+### Receipts & Analytics
+
+```python
+# List receipts
+result = await client.receipts.list(limit=20, offset=0)
+for receipt in result["receipts"]:
+    print(f"{receipt.operation}: ${receipt.amount_usd}")
+
+# Get Merkle proof for verification
+proof = await client.receipts.get_proof("receipt_abc123")
+print(f"Merkle Root: {proof.merkle_root}")
+
+# Get usage analytics
+analytics = await client.receipts.get_analytics(
+    start_date="2024-01-01",
+    end_date="2024-01-31",
+)
+print(f"Total spent: ${analytics.total_spent}")
+```
+
+## Configuration
+
+### Basic Configuration
+
+```python
+client = XacheClient(
+    api_url="https://api.xache.xyz",
+    did="did:agent:evm:0xYourWalletAddress",
+    private_key="0x...",
+    timeout=30,  # Optional: request timeout in seconds
+    debug=False,  # Optional: enable debug logging
+)
+```
+
+### Payment Configuration
+
+#### Manual Payment (Default)
+
+```python
+client = XacheClient(
+    # ... basic config
+    payment_provider={
+        "type": "manual",
+    },
+)
+
+# When payment is required, SDK will prompt you in console
+```
+
+#### Coinbase Commerce
+
+```python
+client = XacheClient(
+    # ... basic config
+    payment_provider={
+        "type": "coinbase-commerce",
+        "api_key": "YOUR_COINBASE_API_KEY",
+    },
+)
+
+# Payments will be handled automatically via Coinbase Commerce
+```
+
+## Error Handling
+
+The SDK provides typed errors for all API error codes:
+
+```python
+from xache import (
+    XacheError,
+    UnauthenticatedError,
+    PaymentRequiredError,
+    RateLimitedError,
+    BudgetExceededError,
+    InvalidInputError,
+)
+
+try:
+    await client.memory.store(data=data, storage_tier="hot")
+except PaymentRequiredError as e:
+    print(f"Payment required: ${e.amount}")
+    print(f"Challenge ID: {e.challenge_id}")
+except RateLimitedError as e:
+    print(f"Rate limited. Retry at: {e.reset_at}")
+except BudgetExceededError as e:
+    print("Budget exceeded")
+except InvalidInputError as e:
+    print(f"Invalid input: {e.message}")
+```
+
+## Context Manager
+
+Always use the client as an async context manager to ensure proper cleanup:
+
+```python
+async with XacheClient(...) as client:
+    # Your code here
+    pass
+# HTTP session automatically closed
+```
+
+Or manually manage the lifecycle:
+
+```python
+client = XacheClient(...)
+try:
+    # Your code here
+    pass
+finally:
+    await client.close()
+```
+
+## API Reference
+
+### XacheClient
+
+Main client class for interacting with Xache Protocol.
+
+#### Properties
+
+- `client.identity` - Identity registration
+- `client.memory` - Memory storage and retrieval
+- `client.collective` - Collective intelligence marketplace
+- `client.budget` - Budget management
+- `client.receipts` - Receipt access and analytics
+
+### Types
+
+All request/response types are available:
+
+```python
+from xache import (
+    RegisterIdentityRequest,
+    RegisterIdentityResponse,
+    StoreMemoryRequest,
+    StoreMemoryResponse,
+    QueryCollectiveRequest,
+    BudgetStatus,
+    Receipt,
+)
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run type checking
+mypy xache
+
+# Format code
+black xache
+
+# Lint
+pylint xache
+```
+
+## Requirements
+
+- Python 3.8+
+- aiohttp
+- typing-extensions
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://docs.xache.ai)
+- [Protocol Specification](https://github.com/xache-ai/xache-protocol)
+- [API Reference](https://api.xache.xyz/docs)
+- [Discord](https://discord.gg/xache)

xache-5.0.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+xache/__init__.py,sha256=RFenUVyM4Mt5ycz_OvqYNg2oZVwrOF9EogK3jZ_yEpE,2989
+xache/client.py,sha256=ABjFJFnrv4KmY5ihBXK5YC8sg50s48tGdDUSKq7Vd8g,10217
+xache/errors.py,sha256=sHLjfKGw1JxN3TdV_bswG9erH2vVAOFPzvOkWb1k0EI,5007
+xache/types.py,sha256=YpepxdWdWbkCRzRWQX9wckCL1R6zjHswrWTrI3CnrB4,9479
+xache/crypto/__init__.py,sha256=uG6liKoXEY0gdRW9uh_LDNfIp-Cs5ZHE80d_FRKu9jk,308
+xache/crypto/signing.py,sha256=lUHXJ6ySp7hqx7cuX91ooRt2w6CfeHURP-RScNx0Gd8,6851
+xache/crypto/wallet.py,sha256=-VWcxZwjeK1saNgp5qJTukj62yi9BsAisYhWyNwL7qY,6983
+xache/payment/__init__.py,sha256=ggjkHACtiZwVmnt-OW4makx0RAzrNqlZNsdVgSf3VH0,90
+xache/payment/handler.py,sha256=X3RL1mvjHCn5FbloOjiNUv_CythRlJU0Vo524lx4DLg,8901
+xache/services/__init__.py,sha256=ERuZXa7R-Iv0oFBknxJiBO5nJC-oCtIut_4VITw_uOE,775
+xache/services/budget.py,sha256=6sZ3nojb888a3k774XPnJHfdkqIC2Y1BxJKt8zy76V0,10599
+xache/services/collective.py,sha256=utYLIHv3tuOYHbdYJYXqIy1hS-aYIRems744CsCUIUw,6229
+xache/services/extraction.py,sha256=5KElr4ldBR3kcOofvz4d3NwAuTvKVskZ-NTQ7BI2ChY,5317
+xache/services/facilitator.py,sha256=ikZNTqEkmcQixGSMJYGlspmbKfivMBFO3sg5Tzy7si8,9412
+xache/services/identity.py,sha256=gOs5fN9juyoBfXQVm-G4whyUMJ6Oha2VmP_i3mQw0G0,13478
+xache/services/memory.py,sha256=ng9_cwL4jE4c3gdlwQDZyqaBdQgwtqApEwj0LkZYWRY,13290
+xache/services/owner.py,sha256=2ASJFjApS3AiQEpoS2oM9M3sisi0Y6xSjmU1fwUM0rA,8912
+xache/services/receipts.py,sha256=LkVBZ-2KExWXEuA0f6GYreVPrIo_UnP1CDesSnJ9pNo,6729
+xache/services/reputation.py,sha256=dwOTSUKxOo0ajeIZwZYEpzAkmswsqGF1q6vwq9S3Jno,9733
+xache/services/royalty.py,sha256=uIf6q4BQ_VS-7alum1P7jexMzjtRUPxDIV6Lg7L1eLU,8595
+xache/services/sessions.py,sha256=9f_sLkp6QTFsP7wnZVlImFxPEkIHSitPkjR6UDSdNIk,8025
+xache/services/workspaces.py,sha256=bDu8VGXIhAX3l8Y1ReX5JH8ocNIaY3BF_Nc6QJeKlqc,13685
+xache/utils/__init__.py,sha256=8VrQm0QnyqxdplpCG7BDRiAVdBGWrjUs9ipH2zsJOBM,106
+xache/utils/cache.py,sha256=9zhE9dIXFTofj7jz1TX-FkAqmclqoYXTe4FwwGLeKT4,5479
+xache/utils/http.py,sha256=rIQCYvYrziNrNfEbOnIKbCOGGf7bcdTvZrrU_W6CcZA,6547
+xache/utils/retry.py,sha256=OJYBGozKIoteCvKw50dqd4ThhOo-WisorcKa8Tr6mnE,2860
+xache-5.0.0.dist-info/METADATA,sha256=Xk9jdBWRacl2aVkn89dGbdLr9xHNmi8FWbK-B2BHyQg,8469
+xache-5.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+xache-5.0.0.dist-info/top_level.txt,sha256=FBWE4IVb7zoLS9arsdrl97QVETlwFvYGAx6xEJZOEUU,6
+xache-5.0.0.dist-info/RECORD,,

xache-5.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xache-5.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xache