@xache/langchain 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# @xache/langchain
+
+LangChain.js integration for [Xache Protocol](https://xache.xyz) - verifiable AI agent memory with cryptographic receipts, collective intelligence, and portable ERC-8004 reputation.
+
+## Installation
+
+```bash
+npm install @xache/langchain @langchain/core langchain
+```
+
+## Quick Start
+
+### One-Line Memory Replacement
+
+```typescript
+// Before (standard LangChain)
+import { BufferMemory } from 'langchain/memory';
+const memory = new BufferMemory();
+
+// After (with Xache - one line change!)
+import { XacheMemory } from '@xache/langchain';
+const memory = new XacheMemory({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+});
+
+// Everything else stays the same
+const chain = new ConversationChain({ llm, memory });
+```
+
+## Features
+
+### Memory Storage
+
+Persistent memory that survives across sessions with cryptographic receipts:
+
+```typescript
+import { XacheMemory } from '@xache/langchain';
+
+const memory = new XacheMemory({
+  walletAddress: '0xYourWallet',
+  privateKey: '0xYourPrivateKey',
+  apiUrl: 'https://api.xache.xyz', // optional
+  chain: 'base', // or 'solana'
+});
+```
+
+### Retrieval (RAG)
+
+Semantic search for retrieval-augmented generation:
+
+```typescript
+import { XacheRetriever } from '@xache/langchain';
+import { RetrievalQAChain } from 'langchain/chains';
+
+const retriever = new XacheRetriever({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+  k: 5, // number of documents
+});
+
+const qa = RetrievalQAChain.fromLLM(llm, retriever);
+```
+
+### Collective Intelligence
+
+Query and contribute to shared knowledge:
+
+```typescript
+import {
+  createCollectiveContributeTool,
+  createCollectiveQueryTool,
+} from '@xache/langchain';
+
+// Add to your agent's tools
+const contributeTool = createCollectiveContributeTool({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+});
+
+const queryTool = createCollectiveQueryTool({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+});
+
+const tools = [contributeTool, queryTool];
+```
+
+### Memory Extraction
+
+Auto-extract memories from conversations:
+
+```typescript
+import { XacheExtractor } from '@xache/langchain';
+
+const extractor = new XacheExtractor({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+  mode: 'xache-managed', // or 'api-key' with your LLM key
+});
+
+const result = await extractor.extract(
+  'User asked about quantum computing...',
+  { autoStore: true }
+);
+
+console.log(`Extracted ${result.count} memories`);
+```
+
+### Reputation
+
+Check and verify agent reputation:
+
+```typescript
+import { createReputationTool, XacheReputationChecker } from '@xache/langchain';
+
+// As a tool for your agent
+const repTool = createReputationTool({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+});
+
+// Or check other agents
+const checker = new XacheReputationChecker({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+});
+
+const otherRep = await checker.check('did:agent:evm:0xOtherAgent...');
+if (otherRep.score >= 0.5) {
+  console.log('Agent is trustworthy');
+}
+```
+
+## Chat History
+
+For more control over message history:
+
+```typescript
+import { XacheChatMessageHistory } from '@xache/langchain';
+import { BufferMemory } from 'langchain/memory';
+
+const history = new XacheChatMessageHistory({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+  sessionId: 'unique-session-id',
+});
+
+const memory = new BufferMemory({ chatHistory: 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

package/dist/index.d.mts

@@ -0,0 +1,457 @@
+import { BaseMemory, InputValues, MemoryVariables, OutputValues } from '@langchain/core/memory';
+import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
+import { BaseMessage } from '@langchain/core/messages';
+import { BaseRetriever, BaseRetrieverInput } from '@langchain/core/retrievers';
+import { Document } from '@langchain/core/documents';
+import { CallbackManagerForRetrieverRun } from '@langchain/core/callbacks/manager';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+
+/**
+ * Xache Chat Message History for LangChain.js
+ * Persistent message storage with cryptographic receipts
+ */
+
+interface XacheChatMessageHistoryConfig {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** Session ID to group messages */
+    sessionId?: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+    /** Maximum messages to load (default: 1000, set to -1 for unlimited) */
+    maxMessages?: number;
+    /** Page size for loading messages (default: 100) */
+    pageSize?: number;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Chat message history backed by Xache Protocol.
+ *
+ * Messages are stored with cryptographic receipts and can persist
+ * across sessions.
+ *
+ * @example
+ * ```typescript
+ * import { XacheChatMessageHistory } from '@xache/langchain';
+ *
+ * const history = new XacheChatMessageHistory({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   sessionId: 'unique-session-id',
+ * });
+ *
+ * await history.addUserMessage('Hello!');
+ * await history.addAIMessage('Hi there!');
+ *
+ * const messages = await history.getMessages();
+ * ```
+ */
+declare class XacheChatMessageHistory extends BaseListChatMessageHistory {
+    lc_namespace: string[];
+    private client;
+    private sessionId;
+    private messages;
+    private initialized;
+    private maxMessages;
+    private pageSize;
+    constructor(config: XacheChatMessageHistoryConfig);
+    /**
+     * Get all messages in the history
+     */
+    getMessages(): Promise<BaseMessage[]>;
+    /**
+     * Add a message to the history
+     */
+    addMessage(message: BaseMessage): Promise<void>;
+    /**
+     * Add a user message
+     */
+    addUserMessage(message: string): Promise<void>;
+    /**
+     * Add an AI message
+     */
+    addAIMessage(message: string): Promise<void>;
+    /**
+     * Clear all messages from history
+     */
+    clear(): Promise<void>;
+    /**
+     * Load messages from Xache storage with pagination support
+     */
+    private loadMessages;
+    private getMessageRole;
+}
+
+/**
+ * Xache Memory for LangChain.js
+ * Drop-in replacement for ConversationBufferMemory with verifiable receipts
+ */
+
+interface XacheMemoryConfig extends XacheChatMessageHistoryConfig {
+    /** Memory key for input (default: 'input') */
+    inputKey?: string;
+    /** Memory key for output (default: 'output') */
+    outputKey?: string;
+    /** Key for returning memory (default: 'history') */
+    memoryKey?: string;
+    /** Return messages as list vs string */
+    returnMessages?: boolean;
+}
+/**
+ * Drop-in replacement for LangChain memory with Xache storage.
+ *
+ * Provides persistent, verifiable memory that survives across sessions.
+ *
+ * @example
+ * ```typescript
+ * import { XacheMemory } from '@xache/langchain';
+ * import { ChatOpenAI } from '@langchain/openai';
+ * import { ConversationChain } from 'langchain/chains';
+ *
+ * const memory = new XacheMemory({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const chain = new ConversationChain({
+ *   llm: new ChatOpenAI(),
+ *   memory,
+ * });
+ *
+ * await chain.call({ input: 'Hello!' });
+ * ```
+ */
+declare class XacheMemory extends BaseMemory {
+    lc_namespace: string[];
+    private chatHistory;
+    private inputKey;
+    private outputKey;
+    private memoryKey;
+    private returnMessages;
+    constructor(config: XacheMemoryConfig);
+    get memoryKeys(): string[];
+    /**
+     * Load memory variables
+     */
+    loadMemoryVariables(_values: InputValues): Promise<MemoryVariables>;
+    /**
+     * Save context from this conversation to buffer
+     */
+    saveContext(inputValues: InputValues, outputValues: OutputValues): Promise<void>;
+    /**
+     * Clear memory contents
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Extended memory with conversation buffer capabilities
+ */
+declare class XacheConversationBufferMemory extends XacheMemory {
+    lc_namespace: string[];
+}
+
+/**
+ * Xache Retriever for LangChain.js
+ * Memory retrieval for RAG pipelines with verifiable receipts
+ */
+
+interface XacheRetrieverConfig extends BaseRetrieverInput {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** Number of documents to retrieve */
+    k?: number;
+    /** Filter by context */
+    context?: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+}
+/**
+ * Retriever that fetches documents from Xache memory storage.
+ *
+ * Use this for RAG pipelines with persistent, verifiable document storage.
+ *
+ * @example
+ * ```typescript
+ * import { XacheRetriever } from '@xache/langchain';
+ * import { ChatOpenAI } from '@langchain/openai';
+ * import { RetrievalQAChain } from 'langchain/chains';
+ *
+ * const retriever = new XacheRetriever({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   k: 5,
+ * });
+ *
+ * const qa = RetrievalQAChain.fromLLM(new ChatOpenAI(), retriever);
+ * const result = await qa.call({ query: 'What do you know about X?' });
+ * ```
+ */
+declare class XacheRetriever extends BaseRetriever {
+    lc_namespace: string[];
+    static lc_name(): string;
+    private client;
+    private k;
+    private filterContext?;
+    constructor(config: XacheRetrieverConfig);
+    _getRelevantDocuments(_query: string, _runManager?: CallbackManagerForRetrieverRun): Promise<Document[]>;
+}
+
+/**
+ * Xache Memory Extraction for LangChain.js
+ * Auto-extract memories from conversations
+ */
+interface ExtractedMemory {
+    /** Memory content */
+    content: string;
+    /** Suggested context/category */
+    context: string;
+    /** Suggested tags */
+    tags: string[];
+    /** Confidence score */
+    confidence: number;
+    /** Memory ID if stored */
+    memoryId?: string;
+}
+interface ExtractionResult {
+    /** Extracted memories */
+    memories: ExtractedMemory[];
+    /** Number of memories extracted */
+    count: number;
+    /** Total cost in USD */
+    cost: number;
+    /** Receipt ID for the operation */
+    receiptId?: string;
+}
+interface XacheExtractorConfig {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** Extraction mode: 'xache-managed' uses Xache's LLM, 'api-key' uses your own */
+    mode?: 'xache-managed' | 'api-key';
+    /** Your LLM API key (required if mode is 'api-key') */
+    llmApiKey?: string;
+    /** LLM provider for api-key mode */
+    llmProvider?: 'anthropic' | 'openai';
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Extract memories from conversation traces.
+ *
+ * Can auto-store extracted memories to Xache for later retrieval.
+ *
+ * @example
+ * ```typescript
+ * import { XacheExtractor } from '@xache/langchain';
+ *
+ * const extractor = new XacheExtractor({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   mode: 'xache-managed',
+ * });
+ *
+ * const result = await extractor.extract(
+ *   'User: What is the capital of France?\nAI: Paris is the capital.',
+ *   { autoStore: true }
+ * );
+ *
+ * console.log(`Extracted ${result.count} memories`);
+ * ```
+ */
+declare class XacheExtractor {
+    private client;
+    private mode;
+    private llmApiKey?;
+    private llmProvider;
+    constructor(config: XacheExtractorConfig);
+    /**
+     * Extract memories from a conversation trace
+     */
+    extract(trace: string, options?: {
+        /** Automatically store extracted memories */
+        autoStore?: boolean;
+        /** Custom instructions for extraction */
+        instructions?: string;
+        /** Minimum confidence threshold (0-1) */
+        minConfidence?: number;
+    }): Promise<ExtractionResult>;
+    /**
+     * Extract from LangChain messages
+     */
+    extractFromMessages(messages: Array<{
+        role: string;
+        content: string;
+    }>, options?: {
+        autoStore?: boolean;
+        instructions?: string;
+        minConfidence?: number;
+    }): Promise<ExtractionResult>;
+}
+
+/**
+ * Xache Collective Intelligence for LangChain.js
+ * Share and learn from collective knowledge pools
+ */
+
+interface CollectiveToolConfig {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+}
+/**
+ * Create a tool for contributing to collective intelligence.
+ *
+ * @example
+ * ```typescript
+ * import { createCollectiveContributeTool } from '@xache/langchain';
+ *
+ * const contributeTool = createCollectiveContributeTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const tools = [contributeTool, ...];
+ * ```
+ */
+declare function createCollectiveContributeTool(config: CollectiveToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for querying collective intelligence.
+ *
+ * @example
+ * ```typescript
+ * import { createCollectiveQueryTool } from '@xache/langchain';
+ *
+ * const queryTool = createCollectiveQueryTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const tools = [queryTool, ...];
+ * ```
+ */
+declare function createCollectiveQueryTool(config: CollectiveToolConfig): DynamicStructuredTool;
+/**
+ * Class-based collective contribute tool (alternative API)
+ */
+declare class XacheCollectiveContributeTool {
+    private tool;
+    constructor(config: CollectiveToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class-based collective query tool (alternative API)
+ */
+declare class XacheCollectiveQueryTool {
+    private tool;
+    constructor(config: CollectiveToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+
+/**
+ * Xache Reputation for LangChain.js
+ * Portable, verifiable agent reputation with ERC-8004 support
+ */
+
+interface ReputationToolConfig {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+}
+interface ReputationResult {
+    /** Reputation score (0-1) */
+    score: number;
+    /** Reputation level */
+    level: string;
+    /** Total contributions made */
+    totalContributions: number;
+    /** Total payments made */
+    totalPayments: number;
+    /** Whether ERC-8004 is enabled */
+    erc8004Enabled: boolean;
+    /** ERC-8004 agent ID if enabled */
+    erc8004AgentId?: string;
+}
+/**
+ * Create a tool for checking your own reputation.
+ *
+ * @example
+ * ```typescript
+ * import { createReputationTool } from '@xache/langchain';
+ *
+ * const repTool = createReputationTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const tools = [repTool, ...];
+ * ```
+ */
+declare function createReputationTool(config: ReputationToolConfig): DynamicStructuredTool;
+/**
+ * Class-based reputation tool (alternative API)
+ */
+declare class XacheReputationTool {
+    private tool;
+    constructor(config: ReputationToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Utility class for checking reputation of any agent.
+ *
+ * @example
+ * ```typescript
+ * import { XacheReputationChecker } from '@xache/langchain';
+ *
+ * const checker = new XacheReputationChecker({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const rep = await checker.check('did:agent:evm:0xOtherAgent...');
+ * if (rep.score >= 0.5) {
+ *   console.log('Agent is trustworthy');
+ * }
+ * ```
+ */
+declare class XacheReputationChecker {
+    private client;
+    constructor(config: ReputationToolConfig);
+    /**
+     * Check an agent's reputation
+     */
+    check(agentDid: string): Promise<ReputationResult>;
+    /**
+     * Check if an agent meets minimum reputation threshold
+     */
+    meetsThreshold(agentDid: string, minScore: number): Promise<boolean>;
+}
+
+export { type CollectiveToolConfig, type ExtractedMemory, type ExtractionResult, type ReputationResult, type ReputationToolConfig, XacheChatMessageHistory, type XacheChatMessageHistoryConfig, XacheCollectiveContributeTool, XacheCollectiveQueryTool, XacheConversationBufferMemory, XacheExtractor, type XacheExtractorConfig, XacheMemory, type XacheMemoryConfig, XacheReputationChecker, XacheReputationTool, XacheRetriever, type XacheRetrieverConfig, createCollectiveContributeTool, createCollectiveQueryTool, createReputationTool };