langchain-xache 0.1.0__py3-none-any.whl

xache_langchain/collective.py

@@ -0,0 +1,254 @@
+"""
+Xache Collective Intelligence for LangChain
+Share and learn from collective knowledge pools
+"""
+
+from typing import List, Optional, Dict, Any
+from langchain.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from xache import XacheClient
+
+
+class ContributeInput(BaseModel):
+    """Input for contribute tool"""
+    insight: str = Field(description="The insight or learning to contribute")
+    domain: str = Field(description="Domain/topic of the insight")
+    evidence: Optional[str] = Field(default=None, description="Supporting evidence")
+    tags: Optional[List[str]] = Field(default=None, description="Tags for categorization")
+
+
+class QueryInput(BaseModel):
+    """Input for query tool"""
+    query: str = Field(description="What to search for in the collective")
+    domain: Optional[str] = Field(default=None, description="Filter by domain")
+    limit: int = Field(default=5, description="Number of results")
+
+
+class XacheCollectiveContributeTool(BaseTool):
+    """
+    LangChain tool for contributing to Xache collective intelligence.
+
+    Use this tool when your agent learns something valuable that could
+    benefit other agents. Contributions earn reputation.
+
+    Example:
+        ```python
+        from xache_langchain import XacheCollectiveContributeTool
+
+        contribute_tool = XacheCollectiveContributeTool(
+            wallet_address="0x...",
+            private_key="0x..."
+        )
+
+        # Use in agent
+        tools = [contribute_tool, ...]
+        agent = initialize_agent(tools, llm)
+        ```
+    """
+
+    name: str = "xache_collective_contribute"
+    description: str = (
+        "Contribute an insight or learning to the collective intelligence pool. "
+        "Use this when you discover something valuable that could help other agents. "
+        "You'll earn reputation for quality contributions."
+    )
+    args_schema: type = ContributeInput
+
+    # Xache configuration
+    api_url: str = "https://api.xache.xyz"
+    wallet_address: str
+    private_key: str
+    chain: str = "base"
+
+    _client: Optional[XacheClient] = None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        chain_prefix = "sol" if self.chain == "solana" else "evm"
+        did = f"did:agent:{chain_prefix}:{self.wallet_address.lower()}"
+        self._client = XacheClient(
+            api_url=self.api_url,
+            did=did,
+            private_key=self.private_key,
+        )
+
+    def _run(
+        self,
+        insight: str,
+        domain: str,
+        evidence: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> str:
+        """Contribute to collective"""
+        import asyncio
+
+        async def _contribute():
+            async with self._client as client:
+                result = await client.collective.contribute(
+                    domain=domain,
+                    pattern=insight,
+                    evidence=evidence,
+                    tags=tags or [],
+                )
+                return result
+
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor() as pool:
+                    result = pool.submit(asyncio.run, _contribute()).result()
+            else:
+                result = loop.run_until_complete(_contribute())
+        except RuntimeError:
+            result = asyncio.run(_contribute())
+
+        heuristic_id = result.get("heuristicId", "unknown")
+        receipt_id = result.get("receiptId", "unknown")
+        return f"Contributed insight to '{domain}'. Heuristic ID: {heuristic_id}, Receipt: {receipt_id}"
+
+    async def _arun(
+        self,
+        insight: str,
+        domain: str,
+        evidence: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> str:
+        """Async contribute to collective"""
+        async with self._client as client:
+            result = await client.collective.contribute(
+                domain=domain,
+                pattern=insight,
+                evidence=evidence,
+                tags=tags or [],
+            )
+
+        heuristic_id = result.get("heuristicId", "unknown")
+        receipt_id = result.get("receiptId", "unknown")
+        return f"Contributed insight to '{domain}'. Heuristic ID: {heuristic_id}, Receipt: {receipt_id}"
+
+
+class XacheCollectiveQueryTool(BaseTool):
+    """
+    LangChain tool for querying Xache collective intelligence.
+
+    Use this tool to learn from other agents' contributions.
+
+    Example:
+        ```python
+        from xache_langchain import XacheCollectiveQueryTool
+
+        query_tool = XacheCollectiveQueryTool(
+            wallet_address="0x...",
+            private_key="0x..."
+        )
+
+        # Use in agent
+        tools = [query_tool, ...]
+        ```
+    """
+
+    name: str = "xache_collective_query"
+    description: str = (
+        "Query the collective intelligence pool to learn from other agents. "
+        "Use this when you need insights or knowledge from the community. "
+        "Returns relevant contributions from other agents."
+    )
+    args_schema: type = QueryInput
+
+    # Xache configuration
+    api_url: str = "https://api.xache.xyz"
+    wallet_address: str
+    private_key: str
+    chain: str = "base"
+
+    _client: Optional[XacheClient] = None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        chain_prefix = "sol" if self.chain == "solana" else "evm"
+        did = f"did:agent:{chain_prefix}:{self.wallet_address.lower()}"
+        self._client = XacheClient(
+            api_url=self.api_url,
+            did=did,
+            private_key=self.private_key,
+        )
+
+    def _run(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 5,
+    ) -> str:
+        """Query collective"""
+        import asyncio
+
+        async def _query():
+            async with self._client as client:
+                result = await client.collective.query(
+                    query=query,
+                    domain=domain,
+                    limit=limit,
+                )
+                return result
+
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor() as pool:
+                    result = pool.submit(asyncio.run, _query()).result()
+            else:
+                result = loop.run_until_complete(_query())
+        except RuntimeError:
+            result = asyncio.run(_query())
+
+        # Format results
+        results = result.get("results", [])
+        if not results:
+            return "No relevant insights found in the collective."
+
+        output = f"Found {len(results)} insights:\n"
+        for i, item in enumerate(results, 1):
+            output += f"\n{i}. {item.get('pattern', '')[:200]}"
+            if item.get("domain"):
+                output += f" [Domain: {item['domain']}]"
+            if item.get("relevance"):
+                output += f" (Relevance: {item['relevance']:.2f})"
+
+        return output
+
+    async def _arun(
+        self,
+        query: str,
+        domain: Optional[str] = None,
+        limit: int = 5,
+    ) -> str:
+        """Async query collective"""
+        async with self._client as client:
+            result = await client.collective.query(
+                query=query,
+                domain=domain,
+                limit=limit,
+            )
+
+        results = result.get("results", [])
+        if not results:
+            return "No relevant insights found in the collective."
+
+        output = f"Found {len(results)} insights:\n"
+        for i, item in enumerate(results, 1):
+            output += f"\n{i}. {item.get('pattern', '')[:200]}"
+            if item.get("domain"):
+                output += f" [Domain: {item['domain']}]"
+
+        return output

xache_langchain/extraction.py

@@ -0,0 +1,229 @@
+"""
+Xache Extraction for LangChain
+Automatic memory extraction from conversations
+"""
+
+import os
+from typing import List, Optional, Dict, Any
+from langchain.schema import Document
+from pydantic import BaseModel, Field
+
+from xache import XacheClient
+from ._async_utils import run_sync
+
+
+class ExtractionResult(BaseModel):
+    """Result from memory extraction"""
+    memories: List[Dict[str, Any]] = Field(default_factory=list)
+    receipt_id: Optional[str] = None
+    transaction: Optional[str] = None
+
+
+class XacheExtractor:
+    """
+    Extract memories from text using Xache's LLM-powered extraction.
+
+    Supports three modes:
+    - api-key: Use your own API key (BYOK)
+    - endpoint: Use your own LLM endpoint
+    - xache-managed: Use Xache's hosted LLM
+
+    Example:
+        ```python
+        from xache_langchain import XacheExtractor
+
+        extractor = XacheExtractor(
+            wallet_address="0x...",
+            private_key="0x...",
+            mode="xache-managed"  # or "api-key" with your key
+        )
+
+        # Extract memories from a conversation
+        result = extractor.extract(
+            trace="User asked about quantum computing. "
+                  "I explained superposition and entanglement."
+        )
+
+        print(f"Extracted {len(result.memories)} memories")
+        for mem in result.memories:
+            print(f"  - {mem['content'][:50]}...")
+        ```
+
+    With auto-store (memories saved automatically):
+        ```python
+        result = extractor.extract(
+            trace="...",
+            auto_store=True  # Extracted memories are stored
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        wallet_address: str,
+        private_key: str,
+        api_url: Optional[str] = None,
+        chain: str = "base",
+        mode: str = "xache-managed",
+        llm_api_key: Optional[str] = None,
+        llm_endpoint: Optional[str] = None,
+        llm_model: str = "claude-3-haiku-20240307",
+    ):
+        """
+        Initialize Xache extractor.
+
+        Args:
+            wallet_address: Wallet address for authentication
+            private_key: Private key for signing
+            api_url: Xache API URL (defaults to XACHE_API_URL env var or https://api.xache.xyz)
+            chain: Blockchain (base, solana)
+            mode: Extraction mode (xache-managed, api-key, endpoint)
+            llm_api_key: Your LLM API key (required for api-key mode)
+            llm_endpoint: Your LLM endpoint (required for endpoint mode)
+            llm_model: LLM model to use
+        """
+        # Validate mode-specific requirements
+        if mode == "api-key" and not llm_api_key:
+            raise ValueError("llm_api_key is required when mode is 'api-key'")
+        if mode == "endpoint" and not llm_endpoint:
+            raise ValueError("llm_endpoint is required when mode is 'endpoint'")
+
+        self.wallet_address = wallet_address
+        self.private_key = private_key
+        self.api_url = api_url or os.environ.get("XACHE_API_URL", "https://api.xache.xyz")
+        self.chain = chain
+        self.mode = mode
+        self.llm_api_key = llm_api_key
+        self.llm_endpoint = llm_endpoint
+        self.llm_model = llm_model
+
+        # 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=self.api_url,
+            did=self.did,
+            private_key=private_key,
+        )
+
+    def extract(
+        self,
+        trace: str,
+        auto_store: bool = False,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> ExtractionResult:
+        """
+        Extract memories from text.
+
+        Args:
+            trace: The text to extract memories from
+            auto_store: Automatically store extracted memories
+            context: Optional context for extraction
+
+        Returns:
+            ExtractionResult with extracted memories
+        """
+
+        async def _extract():
+            async with self._client as client:
+                # Build LLM config based on mode
+                if self.mode == "api-key":
+                    llm_config = {
+                        "type": "api-key",
+                        "apiKey": self.llm_api_key,
+                        "model": self.llm_model,
+                    }
+                elif self.mode == "endpoint":
+                    llm_config = {
+                        "type": "endpoint",
+                        "endpoint": self.llm_endpoint,
+                        "model": self.llm_model,
+                    }
+                else:
+                    llm_config = {
+                        "type": "xache-managed",
+                        "model": self.llm_model,
+                    }
+
+                result = await client.extraction.extract(
+                    trace=trace,
+                    llm_config=llm_config,
+                    options={
+                        "autoStore": auto_store,
+                        "context": context,
+                    }
+                )
+
+                return ExtractionResult(
+                    memories=result.get("memories", []),
+                    receipt_id=result.get("receiptId"),
+                    transaction=result.get("transaction"),
+                )
+
+        return run_sync(_extract())
+
+    async def aextract(
+        self,
+        trace: str,
+        auto_store: bool = False,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> ExtractionResult:
+        """Async extract memories from text"""
+        async with self._client as client:
+            if self.mode == "api-key":
+                llm_config = {
+                    "type": "api-key",
+                    "apiKey": self.llm_api_key,
+                    "model": self.llm_model,
+                }
+            elif self.mode == "endpoint":
+                llm_config = {
+                    "type": "endpoint",
+                    "endpoint": self.llm_endpoint,
+                    "model": self.llm_model,
+                }
+            else:
+                llm_config = {
+                    "type": "xache-managed",
+                    "model": self.llm_model,
+                }
+
+            result = await client.extraction.extract(
+                trace=trace,
+                llm_config=llm_config,
+                options={
+                    "autoStore": auto_store,
+                    "context": context,
+                }
+            )
+
+            return ExtractionResult(
+                memories=result.get("memories", []),
+                receipt_id=result.get("receiptId"),
+                transaction=result.get("transaction"),
+            )
+
+    def extract_from_messages(
+        self,
+        messages: List[Any],
+        auto_store: bool = False,
+    ) -> ExtractionResult:
+        """
+        Extract memories from LangChain messages.
+
+        Args:
+            messages: List of LangChain BaseMessage objects
+            auto_store: Automatically store extracted memories
+
+        Returns:
+            ExtractionResult with extracted memories
+        """
+        # Convert messages to trace format
+        trace_lines = []
+        for msg in messages:
+            role = msg.__class__.__name__.replace("Message", "")
+            trace_lines.append(f"{role}: {msg.content}")
+
+        trace = "\n".join(trace_lines)
+        return self.extract(trace, auto_store=auto_store)

xache_langchain/memory.py

@@ -0,0 +1,181 @@
+"""
+Xache Memory for LangChain
+Drop-in replacement for ConversationBufferMemory with verifiable receipts
+"""
+
+import os
+from typing import Any, Dict, List, Optional
+from langchain.memory.chat_memory import BaseChatMemory
+from langchain.schema import BaseMessage, HumanMessage, AIMessage
+from pydantic import Field
+
+from xache import XacheClient
+from ._async_utils import run_sync
+
+
+class XacheMemory(BaseChatMemory):
+    """
+    LangChain memory backed by Xache Protocol.
+
+    Provides persistent, verifiable memory with cryptographic receipts.
+    One-line replacement for ConversationBufferMemory.
+
+    Example:
+        ```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:
+        - Persistent memory across sessions
+        - Cryptographic receipts for every operation
+        - Reputation tracking for quality
+        - x402 micropayments (auto-handled)
+    """
+
+    # Xache client configuration
+    api_url: str = Field(
+        default_factory=lambda: os.environ.get("XACHE_API_URL", "https://api.xache.xyz")
+    )
+    wallet_address: str = Field(...)
+    private_key: str = Field(...)
+    chain: str = Field(default="base")
+
+    # Memory configuration
+    memory_key: str = Field(default="history")
+    return_messages: bool = Field(default=True)
+    human_prefix: str = Field(default="Human")
+    ai_prefix: str = Field(default="AI")
+
+    # Internal state
+    _client: Optional[XacheClient] = None
+    _session_id: Optional[str] = None
+
+    class Config:
+        arbitrary_types_allowed = True
+        underscore_attrs_are_private = True
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._init_client()
+
+    def _init_client(self):
+        """Initialize Xache client"""
+        chain_prefix = "sol" if self.chain == "solana" else "evm"
+        did = f"did:agent:{chain_prefix}:{self.wallet_address.lower()}"
+
+        self._client = XacheClient(
+            api_url=self.api_url,
+            did=did,
+            private_key=self.private_key,
+        )
+
+        # Generate session ID for this memory instance
+        import hashlib
+        import time
+        session_data = f"{did}:{time.time()}"
+        self._session_id = hashlib.sha256(session_data.encode()).hexdigest()[:16]
+
+    @property
+    def memory_variables(self) -> List[str]:
+        """Return memory variables"""
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """Load memory variables from Xache"""
+
+        async def _load():
+            async with self._client as client:
+                # Retrieve recent memories for this session (filtered by session context)
+                memories = await client.memory.list(
+                    limit=50,
+                    context=f"langchain:session:{self._session_id}"
+                )
+
+                messages = []
+                for mem in memories:
+                    # Parse stored message format
+                    content = mem.get("content", "")
+                    metadata = mem.get("metadata", {})
+
+                    if metadata.get("role") == "human":
+                        messages.append(HumanMessage(content=content))
+                    elif metadata.get("role") == "ai":
+                        messages.append(AIMessage(content=content))
+
+                return messages
+
+        messages = run_sync(_load())
+
+        if self.return_messages:
+            return {self.memory_key: messages}
+        else:
+            # Return as string buffer
+            buffer = ""
+            for msg in messages:
+                if isinstance(msg, HumanMessage):
+                    buffer += f"{self.human_prefix}: {msg.content}\n"
+                elif isinstance(msg, AIMessage):
+                    buffer += f"{self.ai_prefix}: {msg.content}\n"
+            return {self.memory_key: buffer.strip()}
+
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, str]) -> None:
+        """Save context to Xache memory"""
+
+        async def _save():
+            async with self._client as client:
+                # Extract input and output
+                input_key = list(inputs.keys())[0] if inputs else "input"
+                output_key = list(outputs.keys())[0] if outputs else "output"
+
+                human_input = inputs.get(input_key, "")
+                ai_output = outputs.get(output_key, "")
+
+                # Store human message with session context
+                if human_input:
+                    await client.memory.store(
+                        content=human_input,
+                        context=f"langchain:session:{self._session_id}",
+                        metadata={
+                            "role": "human",
+                            "session_id": self._session_id,
+                            "source": "langchain",
+                        }
+                    )
+
+                # Store AI message with session context
+                if ai_output:
+                    await client.memory.store(
+                        content=ai_output,
+                        context=f"langchain:session:{self._session_id}",
+                        metadata={
+                            "role": "ai",
+                            "session_id": self._session_id,
+                            "source": "langchain",
+                        }
+                    )
+
+        run_sync(_save())
+
+    def clear(self) -> None:
+        """Clear memory (marks as deleted in Xache)"""
+        # Note: Xache uses soft delete - memories are marked deleted but retained
+        # for receipt verification
+        self._session_id = None
+        self._init_client()  # Reset with new session
+
+
+class XacheConversationBufferMemory(XacheMemory):
+    """Alias for XacheMemory for familiar naming"""
+    pass