xache 5.0.0__tar.gz

xache-5.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,293 @@
+# 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/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xache"
+version = "5.0.0"
+description = "Official Python SDK for Xache Protocol"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Xache Protocol", email = "dev@xache.xyz"}
+]
+keywords = ["xache", "ai", "agent", "memory", "blockchain", "decentralized"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+    "typing-extensions>=4.0.0",
+    "mnemonic>=0.20",
+    "eth-account>=0.10.0",
+    "bip-utils>=2.9.0",
+    "PyNaCl>=1.5.0",
+    "base58>=2.1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "mypy>=1.0.0",
+    "pylint>=2.17.0",
+]
+encryption = [
+    "PyNaCl>=1.5.0",
+]
+
+[project.urls]
+Homepage = "https://xache.xyz"
+Documentation = "https://docs.xache.xyz"
+Repository = "https://github.com/oliveskin/xache"
+"Bug Reports" = "https://github.com/oliveskin/xache/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.black]
+line-length = 100
+target-version = ['py38', 'py39', 'py310', 'py311']

xache-5.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+