openclaw-xache 0.1.0__tar.gz

openclaw_xache-0.1.0/PKG-INFO

@@ -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)