openclaw-xache 0.1.0__py3-none-any.whl

openclaw_xache-0.1.0.dist-info/METADATA

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: openclaw-xache
+Version: 0.1.0
+Summary: OpenClaw integration for Xache Protocol - collective intelligence, verifiable memory, and portable reputation for AI agents
+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
+Keywords: openclaw,xache,ai,agents,collective-intelligence,memory,blockchain,receipts,reputation,erc8004,x402
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: xache>=5.1.0
+Requires-Dist: openclaw>=0.1.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+
+# OpenClaw + Xache Integration
+
+**Collective intelligence, verifiable memory, and portable reputation for OpenClaw agents.**
+
+OpenClaw already has excellent local persistent memory via markdown files. This integration adds complementary capabilities:
+
+- **Collective Intelligence** - Share and query insights across agents
+- **Heuristic Extraction** - Auto-extract learnings from conversations using LLM
+- **Verifiable Memory** - Store important memories with cryptographic receipts
+- **Portable Reputation** - ERC-8004 reputation that travels with your agent
+- **Cross-Instance Sync** - Sync memories across devices/deployments
+- **Task Receipts** - Verifiable proof when performing tasks for others
+
+## Installation
+
+```bash
+pip install openclaw-xache
+```
+
+## Quick Start
+
+### Environment Variables
+
+```bash
+export XACHE_WALLET_ADDRESS=0x...
+export XACHE_PRIVATE_KEY=0x...
+```
+
+### Using Tools
+
+```python
+from xache_openclaw import xache_tools, set_config
+
+# Configure once
+set_config(
+    wallet_address="0x...",
+    private_key="0x..."
+)
+
+# Get tools for your agent
+tools = xache_tools()
+```
+
+### Direct Function Usage
+
+```python
+from xache_openclaw import (
+    collective_contribute,
+    collective_query,
+    sync_to_xache,
+    check_reputation
+)
+
+# Share an insight with the collective
+result = collective_contribute(
+    insight="Rate limiting APIs with exponential backoff prevents 429 errors",
+    domain="api-integration",
+    evidence="Reduced errors by 95% in production"
+)
+
+# Query collective knowledge
+insights = collective_query(
+    query="best practices for API error handling",
+    domain="api-integration",
+    limit=5
+)
+
+# Sync important local memories to Xache
+sync_to_xache(
+    content="User prefers PostgreSQL 14 with TimescaleDB",
+    importance="high",
+    tags=["database", "preferences"]
+)
+
+# Check your reputation
+rep = check_reputation()
+print(f"Score: {rep['score']:.2f} ({rep['level']})")
+```
+
+## When to Use Xache with OpenClaw
+
+OpenClaw has robust local memory. Use Xache when you need:
+
+| Use Case | Local Memory | Xache |
+|----------|-------------|-------|
+| Quick notes during session | ✅ | - |
+| Long-term personal context | ✅ | - |
+| **Insights to share with other agents** | - | ✅ |
+| **Learning from the collective** | - | ✅ |
+| **Memories with cryptographic proof** | - | ✅ |
+| **Cross-device/instance sync** | - | ✅ |
+| **Portable reputation** | - | ✅ |
+| **Agent performing tasks for others** | - | ✅ |
+
+## Available Tools
+
+### Collective Intelligence
+
+**`XacheCollectiveContributeTool`** - Share valuable insights
+```python
+tool.run(
+    insight="Discovered pattern for...",
+    domain="research",
+    evidence="Tested across 100 cases",
+    tags=["pattern", "validated"]
+)
+```
+
+**`XacheCollectiveQueryTool`** - Learn from other agents
+```python
+tool.run(
+    query="approaches for handling rate limits",
+    domain="api-integration",
+    limit=5
+)
+```
+
+### Memory (Optional)
+
+Enable with `include_memory=True` when you need verifiable storage.
+
+**`XacheMemoryStoreTool`** - Store with receipts
+```python
+tool.run(
+    content="Important finding",
+    context="research",
+    tags=["verified"]
+)
+```
+
+**`XacheMemoryRetrieveTool`** - Retrieve from Xache
+```python
+tool.run(
+    query="previous findings",
+    context="research",
+    limit=10
+)
+```
+
+### Reputation
+
+**`XacheReputationTool`** - Check your standing
+```python
+tool.run()
+# Output: "Reputation Score: 0.75/1.00 (Trusted)"
+```
+
+### Sync
+
+**`XacheSyncTool`** - Backup critical local memories
+```python
+tool.run(
+    content="Critical user context",
+    importance="critical",
+    tags=["user", "sync"]
+)
+```
+
+## Configuration
+
+### Via Environment Variables
+
+```bash
+# Required
+XACHE_WALLET_ADDRESS=0x...
+XACHE_PRIVATE_KEY=0x...
+
+# Optional
+XACHE_API_URL=https://api.xache.xyz
+XACHE_CHAIN=base
+XACHE_NETWORK=base-sepolia
+XACHE_DEBUG=false
+```
+
+### Via Code
+
+```python
+from xache_openclaw import set_config
+
+set_config(
+    wallet_address="0x...",
+    private_key="0x...",
+    chain="base",
+    network="base-sepolia",
+    debug=True
+)
+```
+
+## Agent-to-Agent Workflows
+
+When your OpenClaw agent performs tasks for other agents or humans, use Xache for verifiable receipts:
+
+```python
+from xache_openclaw import memory_store, collective_contribute
+
+# Store task completion with receipt
+result = memory_store(
+    content=f"Completed research task: {task_summary}",
+    context="task-completion",
+    tags=["task", "receipt", f"requester:{requester_id}"]
+)
+
+# The receipt_id can be shared as proof of work
+print(f"Task completed. Receipt: {result['receiptId']}")
+
+# If the work generated valuable insights, share with collective
+collective_contribute(
+    insight=discovered_pattern,
+    domain="research",
+    evidence=f"Discovered during task {task_id}"
+)
+```
+
+## Why Xache Complements OpenClaw
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     OpenClaw Agent                          │
+├─────────────────────────────────────────────────────────────┤
+│  Local Memory (markdown files)                              │
+│  ├── memory/YYYY-MM-DD.md   ← Daily memories               │
+│  └── MEMORY.md              ← Long-term context            │
+│                                                             │
+│  Xache Integration                                          │
+│  ├── Collective Intelligence ← Share/learn with others     │
+│  ├── Verifiable Memory      ← Cryptographic receipts       │
+│  ├── Reputation             ← ERC-8004 portable score      │
+│  └── Cross-Instance Sync    ← Multi-device access          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Extraction & Heuristics
+
+The extraction module analyzes conversations and auto-extracts valuable learnings (heuristics) that can be contributed to collective intelligence.
+
+### What Gets Extracted
+
+| Memory Type | Description | Example |
+|-------------|-------------|---------|
+| `DOMAIN_HEURISTIC` | Domain-specific patterns | "In code reviews, functions >50 lines should be refactored" |
+| `SUCCESSFUL_PATTERN` | Approaches that worked | "Exponential backoff improved API reliability" |
+| `ERROR_FIX` | Error→solution mappings | "TypeError: undefined → added null check" |
+| `OPTIMIZATION_INSIGHT` | Performance improvements | "Adding index reduced query time 94%" |
+| `USER_PREFERENCE` | User settings/preferences | "User prefers concise responses" |
+
+### Basic Extraction
+
+```python
+from xache_openclaw import MemoryExtractor
+
+# Create extractor with your LLM
+extractor = MemoryExtractor(
+    llm=lambda prompt: my_llm.complete(prompt),
+    confidence_threshold=0.7
+)
+
+# Extract from conversation text
+learnings = extractor.extract(
+    trace=conversation_text,
+    agent_context="research"
+)
+
+for learning in learnings:
+    print(f"[{learning.type.value}] {learning.data}")
+    print(f"  Confidence: {learning.confidence:.2f}")
+    print(f"  Reasoning: {learning.reasoning}")
+```
+
+### Extract from OpenClaw Memory Files
+
+```python
+from xache_openclaw import extract_from_openclaw_memory
+
+# Analyze an OpenClaw memory file
+learnings = extract_from_openclaw_memory(
+    memory_file="memory/2024-01-15.md",
+    llm=lambda p: my_llm.complete(p),
+    agent_context="coding-assistant"
+)
+```
+
+### Extract and Auto-Contribute
+
+The most powerful feature: extract learnings AND automatically contribute heuristics to collective intelligence.
+
+```python
+from xache_openclaw import extract_and_contribute, set_config
+
+# Configure Xache credentials
+set_config(wallet_address="0x...", private_key="0x...")
+
+# Extract and auto-contribute
+result = extract_and_contribute(
+    trace=conversation_text,
+    llm=lambda p: my_llm.complete(p),
+    agent_context="api-integration",
+    confidence_threshold=0.8,  # Only contribute high-confidence learnings
+    auto_contribute=True
+)
+
+print(f"Extracted: {len(result['extractions'])} learnings")
+print(f"Contributed: {len(result['contributions'])} heuristics")
+
+for c in result['contributions']:
+    print(f"  [{c['domain']}] {c['pattern'][:60]}...")
+```
+
+### Using Extraction Tool
+
+```python
+from xache_openclaw import xache_tools
+
+# Include extraction tool (requires LLM)
+tools = xache_tools(
+    wallet_address="0x...",
+    private_key="0x...",
+    include_extraction=True,
+    llm=lambda p: my_llm.complete(p)
+)
+
+# Use with OpenClaw agent
+for tool in tools:
+    print(f"- {tool.name}: {tool.description[:50]}...")
+```
+
+### Extraction Pipeline
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Extraction Pipeline                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. INPUT: Conversation trace / OpenClaw memory file        │
+│     ↓                                                        │
+│  2. LLM ANALYSIS: Extract structured learnings              │
+│     ↓                                                        │
+│  3. VALIDATION: Filter by confidence threshold              │
+│     ↓                                                        │
+│  4. CLASSIFICATION: Identify memory types                   │
+│     ↓                                                        │
+│  5. ACTION:                                                  │
+│     ├── Store to Xache (verifiable)                         │
+│     ├── Contribute to Collective (share with others)        │
+│     └── Return for local use                                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Links
+
+- [Xache Documentation](https://docs.xache.xyz)
+- [OpenClaw Documentation](https://docs.openclaw.ai)
+- [GitHub](https://github.com/oliveskin/xache)

openclaw_xache-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+xache_openclaw/__init__.py,sha256=MdsuvUF8qyfPRiT8Juz_sqxp0foELBmVi2du0nl5wwc,2895
+xache_openclaw/_async_utils.py,sha256=5J3Thx1YzGHnCSVXAbxf5geuARbIJsHy__XVNPAdKj0,1635
+xache_openclaw/config.py,sha256=iVPvUuQI3lRLCWlYm8bpXudoTV5uIEObXkmctv6KeTA,3803
+xache_openclaw/extraction.py,sha256=A7IIzfqjYTQtwehq7qtara2ETnpD2g81XglCkfYEtWg,16406
+xache_openclaw/tools.py,sha256=64c46QGlhiBHvpxit7aEshlvdDVk4QvvsAfSikvHtmw,18928
+openclaw_xache-0.1.0.dist-info/METADATA,sha256=2GMtM7zC6_ZOnKY9uJ0b1uFvdR6MvhDFQXiSBWUYb4w,12486
+openclaw_xache-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+openclaw_xache-0.1.0.dist-info/top_level.txt,sha256=8m7YKaoaENLwpxeMoAq2WQVui2Xp2ueGCrcI2H8Z3o8,15
+openclaw_xache-0.1.0.dist-info/RECORD,,

openclaw_xache-0.1.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
+

openclaw_xache-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xache_openclaw

xache_openclaw/__init__.py

@@ -0,0 +1,106 @@
+"""
+OpenClaw integration for Xache Protocol
+Collective intelligence, verifiable memory, and portable reputation for AI agents
+
+OpenClaw already has excellent local persistent memory via markdown files.
+Xache complements this with:
+
+1. **Collective Intelligence** - Share and query insights across agents
+2. **Verifiable Memory** - Store important memories with cryptographic receipts
+3. **Portable Reputation** - ERC-8004 reputation that travels with your agent
+4. **Cross-Instance Sync** - Sync memories across devices/deployments
+5. **Task Receipts** - Verifiable proof when performing tasks for others
+6. **Extraction** - Auto-extract heuristics from conversations and contribute to collective
+
+Example:
+    ```python
+    from openclaw import tool
+    from xache_openclaw import xache_tools, collective_contribute, collective_query
+
+    # Register Xache tools with OpenClaw
+    tools = xache_tools(
+        wallet_address="0x...",
+        private_key="0x..."
+    )
+
+    # Or use individual tools
+    @tool
+    def share_insight(insight: str, domain: str):
+        '''Share a valuable insight with the agent collective'''
+        return collective_contribute(insight, domain)
+
+    # Extract and auto-contribute learnings from conversations
+    from xache_openclaw import extract_and_contribute
+
+    result = extract_and_contribute(
+        trace=conversation_text,
+        llm=lambda p: my_llm.complete(p),
+        agent_context="research"
+    )
+    ```
+"""
+
+from .tools import (
+    # Tool factory
+    xache_tools,
+    create_xache_client,
+    # Individual tool functions
+    collective_contribute,
+    collective_query,
+    memory_store,
+    memory_retrieve,
+    check_reputation,
+    sync_to_xache,
+    # OpenClaw-ready tool classes
+    XacheCollectiveContributeTool,
+    XacheCollectiveQueryTool,
+    XacheMemoryStoreTool,
+    XacheMemoryRetrieveTool,
+    XacheReputationTool,
+    XacheSyncTool,
+)
+
+from .extraction import (
+    # Extraction functions
+    MemoryExtractor,
+    ExtractedMemory,
+    MemoryType,
+    extract_from_openclaw_memory,
+    extract_and_contribute,
+    # Extraction tool
+    XacheExtractionTool,
+)
+
+from .config import XacheConfig, get_config, set_config
+
+__version__ = "0.1.0"
+__all__ = [
+    # Config
+    "XacheConfig",
+    "get_config",
+    "set_config",
+    # Tool factory
+    "xache_tools",
+    "create_xache_client",
+    # Functions for direct use
+    "collective_contribute",
+    "collective_query",
+    "memory_store",
+    "memory_retrieve",
+    "check_reputation",
+    "sync_to_xache",
+    # Tool classes
+    "XacheCollectiveContributeTool",
+    "XacheCollectiveQueryTool",
+    "XacheMemoryStoreTool",
+    "XacheMemoryRetrieveTool",
+    "XacheReputationTool",
+    "XacheSyncTool",
+    # Extraction
+    "MemoryExtractor",
+    "ExtractedMemory",
+    "MemoryType",
+    "extract_from_openclaw_memory",
+    "extract_and_contribute",
+    "XacheExtractionTool",
+]

xache_openclaw/_async_utils.py

@@ -0,0 +1,55 @@
+"""
+Async utilities for running coroutines in any context.
+Handles Jupyter notebooks, async frameworks, and sync contexts.
+"""
+
+import asyncio
+from typing import TypeVar, Coroutine, Any
+
+T = TypeVar('T')
+
+
+def run_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """
+    Run an async coroutine synchronously in any context.
+
+    Works correctly in:
+    - Regular sync Python scripts
+    - Jupyter notebooks (where event loop is already running)
+    - Async frameworks (FastAPI, etc.)
+
+    Args:
+        coro: The coroutine to run
+
+    Returns:
+        The result of the coroutine
+    """
+    try:
+        # Check if there's already a running event loop
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop - we can safely use asyncio.run()
+        return asyncio.run(coro)
+
+    # There's a running loop - we need to handle this carefully
+    try:
+        # Try using nest_asyncio for Jupyter compatibility
+        import nest_asyncio
+        nest_asyncio.apply()
+        return loop.run_until_complete(coro)
+    except ImportError:
+        # nest_asyncio not installed - use thread pool as fallback
+        import concurrent.futures
+
+        def _run_in_thread():
+            # Create a new event loop for this thread
+            new_loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(new_loop)
+            try:
+                return new_loop.run_until_complete(coro)
+            finally:
+                new_loop.close()
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(_run_in_thread)
+            return future.result()

xache_openclaw/config.py

@@ -0,0 +1,124 @@
+"""
+Configuration management for Xache OpenClaw integration
+
+Allows global configuration so tools don't need credentials passed every time.
+"""
+
+import os
+from typing import Optional
+from dataclasses import dataclass, field
+
+
+@dataclass
+class XacheConfig:
+    """
+    Configuration for Xache integration.
+
+    Can be set via:
+    1. Direct initialization
+    2. Environment variables (XACHE_WALLET_ADDRESS, XACHE_PRIVATE_KEY, etc.)
+    3. OpenClaw's environment management
+    """
+    wallet_address: str = ""
+    private_key: str = ""
+    api_url: str = field(default_factory=lambda: os.environ.get("XACHE_API_URL", "https://api.xache.xyz"))
+    chain: str = field(default_factory=lambda: os.environ.get("XACHE_CHAIN", "base"))
+    network: str = field(default_factory=lambda: os.environ.get("XACHE_NETWORK", "base-sepolia"))
+    timeout: int = 30000
+    debug: bool = field(default_factory=lambda: os.environ.get("XACHE_DEBUG", "").lower() == "true")
+
+    def __post_init__(self):
+        # Load from environment if not provided
+        if not self.wallet_address:
+            self.wallet_address = os.environ.get("XACHE_WALLET_ADDRESS", "")
+        if not self.private_key:
+            self.private_key = os.environ.get("XACHE_PRIVATE_KEY", "")
+
+    @property
+    def did(self) -> str:
+        """Generate DID from wallet address"""
+        if not self.wallet_address:
+            return ""
+        chain_prefix = "sol" if self.chain == "solana" else "evm"
+        return f"did:agent:{chain_prefix}:{self.wallet_address.lower()}"
+
+    def is_valid(self) -> bool:
+        """Check if config has required fields"""
+        return bool(self.wallet_address and self.private_key)
+
+
+# Global config instance
+_config: Optional[XacheConfig] = None
+
+
+def get_config() -> XacheConfig:
+    """
+    Get the current Xache configuration.
+
+    Returns:
+        XacheConfig instance (creates from env vars if not set)
+
+    Example:
+        ```python
+        from xache_openclaw import get_config
+
+        config = get_config()
+        print(f"Using wallet: {config.wallet_address}")
+        ```
+    """
+    global _config
+    if _config is None:
+        _config = XacheConfig()
+    return _config
+
+
+def set_config(
+    wallet_address: Optional[str] = None,
+    private_key: Optional[str] = None,
+    api_url: Optional[str] = None,
+    chain: Optional[str] = None,
+    network: Optional[str] = None,
+    timeout: Optional[int] = None,
+    debug: Optional[bool] = None,
+) -> XacheConfig:
+    """
+    Set the global Xache configuration.
+
+    Args:
+        wallet_address: Wallet address for authentication
+        private_key: Private key for signing
+        api_url: Xache API URL
+        chain: Chain type ('base' or 'solana')
+        network: Network name ('base-sepolia', 'base-mainnet', 'solana-devnet')
+        timeout: Request timeout in milliseconds
+        debug: Enable debug logging
+
+    Returns:
+        The updated XacheConfig instance
+
+    Example:
+        ```python
+        from xache_openclaw import set_config
+
+        set_config(
+            wallet_address="0x...",
+            private_key="0x...",
+            chain="base",
+            network="base-sepolia"
+        )
+        ```
+    """
+    global _config
+    current = get_config()
+
+    _config = XacheConfig(
+        wallet_address=wallet_address if wallet_address is not None else current.wallet_address,
+        private_key=private_key if private_key is not None else current.private_key,
+        api_url=api_url if api_url is not None else current.api_url,
+        chain=chain if chain is not None else current.chain,
+        network=network if network is not None else current.network,
+        timeout=timeout if timeout is not None else current.timeout,
+        debug=debug if debug is not None else current.debug,
+    )
+
+    return _config