langchain-xache 0.1.0__py3-none-any.whl

langchain_xache-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: langchain-xache
+Version: 0.1.0
+Summary: LangChain integration for Xache Protocol - verifiable AI agent memory
+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: langchain,ai,agents,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>=0.1.0
+Requires-Dist: langchain>=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"
+
+# langchain-xache
+
+LangChain integration for [Xache Protocol](https://xache.xyz) - verifiable AI agent memory with cryptographic receipts, collective intelligence, and portable ERC-8004 reputation.
+
+## Installation
+
+```bash
+pip install langchain-xache
+```
+
+## Quick Start
+
+### One-Line Memory Replacement
+
+```python
+# Before (standard LangChain)
+from langchain.memory import ConversationBufferMemory
+memory = ConversationBufferMemory()
+
+# After (with Xache - one line change!)
+from xache_langchain import XacheMemory
+memory = XacheMemory(
+    wallet_address="0x...",
+    private_key="0x..."
+)
+
+# Everything else stays the same
+agent = initialize_agent(tools, llm, memory=memory)
+```
+
+## Features
+
+### Memory Storage
+Persistent memory that survives across sessions with cryptographic receipts:
+
+```python
+from xache_langchain import XacheMemory
+
+memory = XacheMemory(
+    wallet_address="0xYourWallet",
+    private_key="0xYourPrivateKey",
+    api_url="https://api.xache.xyz",  # optional
+    chain="base"  # or "solana"
+)
+```
+
+### Retrieval (RAG)
+Semantic search for retrieval-augmented generation:
+
+```python
+from xache_langchain import XacheRetriever
+from langchain.chains import RetrievalQA
+
+retriever = XacheRetriever(
+    wallet_address="0x...",
+    private_key="0x...",
+    k=5  # number of documents
+)
+
+qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
+```
+
+### Collective Intelligence
+Query and contribute to shared knowledge:
+
+```python
+from xache_langchain import XacheCollectiveContributeTool, XacheCollectiveQueryTool
+
+# Add to your agent's tools
+contribute = XacheCollectiveContributeTool(
+    wallet_address="0x...",
+    private_key="0x..."
+)
+
+query = XacheCollectiveQueryTool(
+    wallet_address="0x...",
+    private_key="0x..."
+)
+
+tools = [contribute, query, ...]
+```
+
+### Memory Extraction
+Auto-extract memories from conversations:
+
+```python
+from xache_langchain import XacheExtractor
+
+extractor = XacheExtractor(
+    wallet_address="0x...",
+    private_key="0x...",
+    mode="xache-managed"  # or "api-key" with your LLM key
+)
+
+result = extractor.extract(
+    trace="User asked about quantum computing...",
+    auto_store=True  # automatically store extracted memories
+)
+
+print(f"Extracted {len(result.memories)} memories")
+```
+
+### Reputation
+Check and verify agent reputation:
+
+```python
+from xache_langchain import XacheReputationTool, XacheReputationChecker
+
+# As a tool for your agent
+rep_tool = XacheReputationTool(
+    wallet_address="0x...",
+    private_key="0x..."
+)
+
+# Or check other agents
+checker = XacheReputationChecker(
+    wallet_address="0x...",
+    private_key="0x..."
+)
+
+other_rep = checker.check("did:agent:evm:0xOtherAgent...")
+if other_rep.score >= 0.5:
+    print("Agent is trustworthy")
+```
+
+## Chat History
+
+For more control over message history:
+
+```python
+from xache_langchain import XacheChatMessageHistory
+from langchain.memory import ConversationBufferMemory
+
+history = XacheChatMessageHistory(
+    wallet_address="0x...",
+    private_key="0x...",
+    session_id="unique-session-id"
+)
+
+memory = ConversationBufferMemory(chat_memory=history)
+```
+
+## Pricing
+
+All operations use x402 micropayments (auto-handled):
+
+| Operation | Price |
+|-----------|-------|
+| Memory Store | $0.002 |
+| Memory Retrieve | $0.003 |
+| Collective Contribute | $0.002 |
+| Collective Query | $0.011 |
+| Extraction (managed) | $0.011 |
+
+## ERC-8004 Portable Reputation
+
+Xache supports [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) for portable, on-chain reputation. Enable it to make your agent's reputation verifiable across platforms.
+
+## Resources
+
+- [Documentation](https://docs.xache.xyz)
+- [API Reference](https://docs.xache.xyz/api)
+- [GitHub](https://github.com/oliveskin/xache)
+- [Discord](https://discord.gg/xache)
+
+## License
+
+MIT

langchain_xache-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+xache_langchain/__init__.py,sha256=OYzpiCnA75ToCTVmQcqut7kGygD9lQhjrUTiFZU5S88,1560
+xache_langchain/_async_utils.py,sha256=Srhe4rJ1S4W6E0sDfgsTqMdfMFr0Je9scJ3cFNa8fWA,1699
+xache_langchain/chat_history.py,sha256=MS6w8fyowWlLvvtZ0RBQWNygBytM3cnasZ6C0KwL4sE,6730
+xache_langchain/collective.py,sha256=OyZKvfOx20ETK236P36fqAZ6ahLyos6FYs81IOKjti0,8092
+xache_langchain/extraction.py,sha256=tFJtL3Sk1XK7UUSmlLw3eMsPA9Lh5kI-G8EhQ1Uiuf0,7407
+xache_langchain/memory.py,sha256=71hxXcUtsyaAo67_xBmjel43EvhgDiCENcD6AvJxMBo,6196
+xache_langchain/reputation.py,sha256=b1GVceH1QPqB7rjvTj295QllxiJ5W0rQ5rUoKJ5Np7A,7389
+xache_langchain/retriever.py,sha256=qw7CSP7zR6g7mn9DUYHbId9S9K564kKXqKR1WnnHkP0,7607
+langchain_xache-0.1.0.dist-info/METADATA,sha256=YXS1nXk1NsOstVUNgauJtq-Z_laum0LNEpy7_-U7Q-w,5308
+langchain_xache-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+langchain_xache-0.1.0.dist-info/top_level.txt,sha256=in69PSq9agqGIAyShkm5ZVg9n0ks76QlD1tGaws9efA,16
+langchain_xache-0.1.0.dist-info/RECORD,,

langchain_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
+

langchain_xache-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xache_langchain

xache_langchain/__init__.py

@@ -0,0 +1,59 @@
+"""
+LangChain integration for Xache Protocol
+Drop-in memory, retrieval, and collective intelligence with verifiable receipts
+
+Example:
+    ```python
+    # One-line memory replacement
+    from xache_langchain import XacheMemory
+
+    memory = XacheMemory(
+        wallet_address="0x...",
+        private_key="0x..."
+    )
+
+    # Everything else stays the same
+    agent = initialize_agent(tools, llm, memory=memory)
+    ```
+
+All Xache features:
+    - Memory: Persistent, verifiable memory storage
+    - Retrieval: Semantic search for RAG pipelines
+    - Collective: Share and learn from agent community
+    - Extraction: Auto-extract memories from conversations
+    - Reputation: Portable ERC-8004 on-chain reputation
+"""
+
+from .memory import XacheMemory, XacheConversationBufferMemory
+from .chat_history import XacheChatMessageHistory
+from .retriever import XacheRetriever
+from .extraction import XacheExtractor, ExtractionResult
+from .collective import (
+    XacheCollectiveContributeTool,
+    XacheCollectiveQueryTool,
+)
+from .reputation import (
+    XacheReputationTool,
+    XacheReputationChecker,
+    ReputationResult,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    # Memory
+    "XacheMemory",
+    "XacheConversationBufferMemory",
+    "XacheChatMessageHistory",
+    # Retrieval
+    "XacheRetriever",
+    # Extraction
+    "XacheExtractor",
+    "ExtractionResult",
+    # Collective Intelligence
+    "XacheCollectiveContributeTool",
+    "XacheCollectiveQueryTool",
+    # Reputation
+    "XacheReputationTool",
+    "XacheReputationChecker",
+    "ReputationResult",
+]

xache_langchain/_async_utils.py

@@ -0,0 +1,56 @@
+"""
+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
+    # This happens in Jupyter notebooks, async frameworks, etc.
+    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_langchain/chat_history.py

@@ -0,0 +1,194 @@
+"""
+Xache Chat Message History for LangChain
+Persistent chat history with verifiable receipts
+"""
+
+import os
+from typing import List, Optional
+from langchain.schema import BaseMessage, HumanMessage, AIMessage, SystemMessage
+from langchain.memory.chat_message_histories.base import BaseChatMessageHistory
+
+from xache import XacheClient
+from ._async_utils import run_sync
+
+
+class XacheChatMessageHistory(BaseChatMessageHistory):
+    """
+    Chat message history backed by Xache Protocol.
+
+    Stores chat messages with cryptographic receipts and optional
+    reputation tracking.
+
+    Example:
+        ```python
+        from xache_langchain import XacheChatMessageHistory
+        from langchain.memory import ConversationBufferMemory
+
+        history = XacheChatMessageHistory(
+            wallet_address="0x...",
+            private_key="0x...",
+            session_id="unique-session-id"
+        )
+
+        memory = ConversationBufferMemory(chat_memory=history)
+        ```
+    """
+
+    def __init__(
+        self,
+        wallet_address: str,
+        private_key: str,
+        session_id: str,
+        api_url: Optional[str] = None,
+        chain: str = "base",
+    ):
+        """
+        Initialize Xache chat history.
+
+        Args:
+            wallet_address: Wallet address for authentication
+            private_key: Private key for signing
+            session_id: Unique session identifier
+            api_url: Xache API URL
+            chain: Blockchain (base, solana)
+        """
+        self.wallet_address = wallet_address
+        self.private_key = private_key
+        self.session_id = session_id
+        self.api_url = api_url or os.environ.get("XACHE_API_URL", "https://api.xache.xyz")
+        self.chain = chain
+
+        # Build DID
+        chain_prefix = "sol" if chain == "solana" else "evm"
+        self.did = f"did:agent:{chain_prefix}:{wallet_address.lower()}"
+
+        self._client = XacheClient(
+            api_url=api_url,
+            did=self.did,
+            private_key=private_key,
+        )
+
+    @property
+    def messages(self) -> List[BaseMessage]:
+        """Retrieve all messages from Xache"""
+
+        async def _get_messages():
+            async with self._client as client:
+                # Retrieve memories for this session (filtered by context)
+                memories = await client.memory.list(
+                    limit=1000,
+                    context=f"chat:session:{self.session_id}"
+                )
+
+                messages = []
+                result_memories = memories.get("memories", []) if isinstance(memories, dict) else memories
+                for mem in sorted(result_memories, key=lambda x: x.get("created_at", "")):
+                    content = mem.get("content", "")
+                    metadata = mem.get("metadata", {})
+                    role = metadata.get("role", "human")
+
+                    if role == "human":
+                        messages.append(HumanMessage(content=content))
+                    elif role == "ai":
+                        messages.append(AIMessage(content=content))
+                    elif role == "system":
+                        messages.append(SystemMessage(content=content))
+
+                return messages
+
+        return run_sync(_get_messages())
+
+    def add_message(self, message: BaseMessage) -> None:
+        """Add a message to the history"""
+
+        # Determine role from message type
+        if isinstance(message, HumanMessage):
+            role = "human"
+        elif isinstance(message, AIMessage):
+            role = "ai"
+        elif isinstance(message, SystemMessage):
+            role = "system"
+        else:
+            role = "unknown"
+
+        async def _add():
+            async with self._client as client:
+                await client.memory.store(
+                    content=message.content,
+                    context=f"chat:session:{self.session_id}",
+                    metadata={
+                        "role": role,
+                        "session_id": self.session_id,
+                        "source": "langchain",
+                        "message_type": message.__class__.__name__,
+                    }
+                )
+
+        run_sync(_add())
+
+    def add_user_message(self, message: str) -> None:
+        """Add a user message"""
+        self.add_message(HumanMessage(content=message))
+
+    def add_ai_message(self, message: str) -> None:
+        """Add an AI message"""
+        self.add_message(AIMessage(content=message))
+
+    def clear(self) -> None:
+        """Clear message history (soft delete) using bulk deletion"""
+        self.bulk_delete()
+
+    def bulk_delete(self, storage_keys: Optional[List[str]] = None) -> dict:
+        """
+        Delete multiple messages from history.
+
+        Args:
+            storage_keys: List of storage keys to delete. If None, deletes all messages
+                         in this session.
+
+        Returns:
+            dict with 'deleted' count and 'errors' list
+        """
+        import asyncio
+
+        async def _bulk_delete():
+            async with self._client as client:
+                # Get storage keys if not provided
+                keys_to_delete = storage_keys
+                if keys_to_delete is None:
+                    result = await client.memory.list(
+                        limit=1000,
+                        context=f"chat:session:{self.session_id}"
+                    )
+                    memories = result.get("memories", []) if isinstance(result, dict) else result
+                    keys_to_delete = [
+                        mem.get("storage_key") for mem in memories
+                        if mem.get("storage_key")
+                    ]
+
+                if not keys_to_delete:
+                    return {"deleted": 0, "errors": []}
+
+                # Delete in parallel using asyncio.gather with return_exceptions
+                async def safe_delete(key):
+                    try:
+                        await client.memory.delete(key)
+                        return {"key": key, "success": True}
+                    except Exception as e:
+                        return {"key": key, "success": False, "error": str(e)}
+
+                results = await asyncio.gather(
+                    *[safe_delete(key) for key in keys_to_delete],
+                    return_exceptions=True
+                )
+
+                deleted = sum(1 for r in results if isinstance(r, dict) and r.get("success"))
+                errors = [
+                    r for r in results
+                    if isinstance(r, dict) and not r.get("success")
+                    or isinstance(r, Exception)
+                ]
+
+                return {"deleted": deleted, "errors": errors}
+
+        return run_sync(_bulk_delete())