@xache/langchain 0.1.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@xache/langchain",
+  "version": "0.1.0",
+  "description": "LangChain.js integration for Xache Protocol - verifiable AI agent memory",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\""
+  },
+  "keywords": [
+    "langchain",
+    "xache",
+    "ai",
+    "agents",
+    "memory",
+    "blockchain",
+    "receipts",
+    "reputation",
+    "erc8004",
+    "x402"
+  ],
+  "author": "Xache Protocol",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oliveskin/xache"
+  },
+  "homepage": "https://xache.xyz",
+  "peerDependencies": {
+    "@langchain/core": ">=0.1.0",
+    "langchain": ">=0.1.0"
+  },
+  "dependencies": {
+    "@xache/sdk": "workspace:*",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^0.1.0",
+    "@types/node": "^20.10.0",
+    "langchain": "^0.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/chat_history.ts

@@ -0,0 +1,232 @@
+/**
+ * Xache Chat Message History for LangChain.js
+ * Persistent message storage with cryptographic receipts
+ */
+
+import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
+import {
+  BaseMessage,
+  HumanMessage,
+  AIMessage,
+  SystemMessage,
+} from '@langchain/core/messages';
+import { XacheClient, DID } from '@xache/sdk';
+import { randomUUID } from 'crypto';
+
+export 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();
+ * ```
+ */
+export class XacheChatMessageHistory extends BaseListChatMessageHistory {
+  lc_namespace = ['xache', 'chat_history'];
+
+  private client: XacheClient;
+  private sessionId: string;
+  private messages: BaseMessage[] = [];
+  private initialized = false;
+  private maxMessages: number;
+  private pageSize: number;
+
+  constructor(config: XacheChatMessageHistoryConfig) {
+    super();
+
+    const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
+    const did = `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}` as DID;
+
+    this.client = new XacheClient({
+      apiUrl: config.apiUrl || 'https://api.xache.xyz',
+      did,
+      privateKey: config.privateKey,
+      timeout: config.timeout,
+      debug: config.debug,
+    });
+
+    // Use UUID for collision-resistant session IDs
+    this.sessionId = config.sessionId || `langchain-${randomUUID()}`;
+    this.maxMessages = config.maxMessages ?? 1000;
+    this.pageSize = config.pageSize ?? 100;
+  }
+
+  /**
+   * Get all messages in the history
+   */
+  async getMessages(): Promise<BaseMessage[]> {
+    if (!this.initialized) {
+      await this.loadMessages();
+    }
+    return this.messages;
+  }
+
+  /**
+   * Add a message to the history
+   */
+  async addMessage(message: BaseMessage): Promise<void> {
+    this.messages.push(message);
+
+    const role = this.getMessageRole(message);
+    const content =
+      typeof message.content === 'string'
+        ? message.content
+        : JSON.stringify(message.content);
+
+    await this.client.memory.store({
+      data: {
+        role,
+        content,
+        sessionId: this.sessionId,
+        timestamp: Date.now(),
+      },
+      storageTier: 'hot',
+      context: `chat:${this.sessionId}`,
+      tags: ['chat', 'message', role],
+      metadata: {
+        sessionId: this.sessionId,
+        role,
+      },
+    });
+  }
+
+  /**
+   * Add a user message
+   */
+  async addUserMessage(message: string): Promise<void> {
+    await this.addMessage(new HumanMessage(message));
+  }
+
+  /**
+   * Add an AI message
+   */
+  async addAIMessage(message: string): Promise<void> {
+    await this.addMessage(new AIMessage(message));
+  }
+
+  /**
+   * Clear all messages from history
+   */
+  async clear(): Promise<void> {
+    this.messages = [];
+    // Note: Xache doesn't support deletion - messages remain for audit trail
+    // We only clear the local cache
+  }
+
+  /**
+   * Load messages from Xache storage with pagination support
+   */
+  private async loadMessages(): Promise<void> {
+    try {
+      const allMemories: Array<{ storage_key: string; created_at?: string }> = [];
+      let offset = 0;
+      const effectiveMax = this.maxMessages === -1 ? Infinity : this.maxMessages;
+
+      // Paginate through all messages
+      while (allMemories.length < effectiveMax) {
+        const result = await this.client.memory.list({
+          context: `chat:${this.sessionId}`,
+          limit: Math.min(this.pageSize, effectiveMax - allMemories.length),
+          offset,
+        });
+
+        const memories = Array.isArray(result?.memories) ? result.memories : [];
+        if (memories.length === 0) break;
+
+        allMemories.push(...memories);
+        offset += memories.length;
+
+        // If we got less than pageSize, we've reached the end
+        if (memories.length < this.pageSize) break;
+      }
+
+      // Sort by timestamp
+      const sortedMemories = [...allMemories].sort((a, b) => {
+        const tsA = new Date(a.created_at || 0).getTime();
+        const tsB = new Date(b.created_at || 0).getTime();
+        return tsA - tsB;
+      });
+
+      // For each memory, we need to retrieve the full content
+      this.messages = [];
+      for (const m of sortedMemories) {
+        try {
+          const full = await this.client.memory.retrieve({
+            storageKey: m.storage_key,
+          });
+          const data = full.data as { role?: string; content?: string };
+          if (data && data.content) {
+            switch (data.role) {
+              case 'human':
+              case 'user':
+                this.messages.push(new HumanMessage(data.content));
+                break;
+              case 'ai':
+              case 'assistant':
+                this.messages.push(new AIMessage(data.content));
+                break;
+              case 'system':
+                this.messages.push(new SystemMessage(data.content));
+                break;
+              default:
+                this.messages.push(new HumanMessage(data.content));
+            }
+          }
+        } catch (error) {
+          // Skip malformed messages but log in debug
+          console.debug?.(`[XacheChatMessageHistory] Failed to parse message: ${(error as Error).message}`);
+        }
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      // If retrieval fails (e.g., no memories yet), start fresh
+      // This is expected for new sessions
+      console.debug?.(`[XacheChatMessageHistory] No existing messages found: ${(error as Error).message}`);
+      this.messages = [];
+      this.initialized = true;
+    }
+  }
+
+  private getMessageRole(message: BaseMessage): string {
+    if (message instanceof HumanMessage) return 'human';
+    if (message instanceof AIMessage) return 'ai';
+    if (message instanceof SystemMessage) return 'system';
+    return 'unknown';
+  }
+}

package/src/collective.ts

@@ -0,0 +1,195 @@
+/**
+ * Xache Collective Intelligence for LangChain.js
+ * Share and learn from collective knowledge pools
+ */
+
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { XacheClient, DID } from '@xache/sdk';
+
+/**
+ * Generate a hash for the pattern (simple implementation)
+ */
+async function generatePatternHash(pattern: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(pattern);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+export 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 an Xache client for collective tools
+ */
+function createClient(config: CollectiveToolConfig): XacheClient {
+  const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
+  const did = `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}` as DID;
+
+  return new XacheClient({
+    apiUrl: config.apiUrl || 'https://api.xache.xyz',
+    did,
+    privateKey: config.privateKey,
+  });
+}
+
+/**
+ * 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, ...];
+ * ```
+ */
+export function createCollectiveContributeTool(
+  config: CollectiveToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_collective_contribute',
+    description:
+      '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.",
+    schema: z.object({
+      insight: z.string().describe('The insight or learning to contribute'),
+      domain: z.string().describe('Domain/topic of the insight'),
+      evidence: z.string().optional().describe('Supporting evidence'),
+      tags: z.array(z.string()).optional().describe('Tags for categorization'),
+    }),
+    func: async ({ insight, domain, evidence, tags }) => {
+      // Generate required fields for the SDK
+      const pattern = insight;
+      const patternHash = await generatePatternHash(pattern);
+      const tagsArray = tags || ['general'];
+
+      const result = await client.collective.contribute({
+        domain,
+        pattern,
+        patternHash,
+        tags: tagsArray,
+        metrics: {
+          successRate: 0.8, // Default metrics for new contributions
+          sampleSize: 1,
+          confidence: 0.7,
+        },
+        encryptedContentRef: evidence || '', // Store evidence as encrypted ref
+      });
+
+      const heuristicId = result.heuristicId || 'unknown';
+      const receiptId = result.receiptId || 'unknown';
+
+      return `Contributed insight to '${domain}'. Heuristic ID: ${heuristicId}, Receipt: ${receiptId}`;
+    },
+  });
+}
+
+/**
+ * Create a tool for querying collective intelligence.
+ *
+ * @example
+ * ```typescript
+ * import { createCollectiveQueryTool } from '@xache/langchain';
+ *
+ * const queryTool = createCollectiveQueryTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const tools = [queryTool, ...];
+ * ```
+ */
+export function createCollectiveQueryTool(
+  config: CollectiveToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_collective_query',
+    description:
+      '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.',
+    schema: z.object({
+      query: z.string().describe('What to search for in the collective'),
+      domain: z.string().optional().describe('Filter by domain'),
+      limit: z.number().optional().default(5).describe('Number of results'),
+    }),
+    func: async ({ query, domain, limit }) => {
+      const result = await client.collective.query({
+        queryText: query,
+        domain,
+        limit: limit || 5,
+      });
+
+      const results = result.matches || [];
+
+      if (results.length === 0) {
+        return 'No relevant insights found in the collective.';
+      }
+
+      let output = `Found ${results.length} insights:\n`;
+
+      results.forEach((item, i: number) => {
+        const pattern = (item.pattern || '').slice(0, 200);
+        output += `\n${i + 1}. ${pattern}`;
+        if (item.domain) {
+          output += ` [Domain: ${item.domain}]`;
+        }
+        if (item.relevanceScore) {
+          output += ` (Relevance: ${item.relevanceScore.toFixed(2)})`;
+        }
+      });
+
+      return output;
+    },
+  });
+}
+
+/**
+ * Class-based collective contribute tool (alternative API)
+ */
+export class XacheCollectiveContributeTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: CollectiveToolConfig) {
+    this.tool = createCollectiveContributeTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}
+
+/**
+ * Class-based collective query tool (alternative API)
+ */
+export class XacheCollectiveQueryTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: CollectiveToolConfig) {
+    this.tool = createCollectiveQueryTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}

package/src/extraction.ts

@@ -0,0 +1,172 @@
+/**
+ * Xache Memory Extraction for LangChain.js
+ * Auto-extract memories from conversations
+ */
+
+import { XacheClient, DID } from '@xache/sdk';
+import type { ExtractMemoriesResponse } from '@xache/sdk';
+
+export 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;
+}
+
+export 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;
+}
+
+export 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`);
+ * ```
+ */
+export class XacheExtractor {
+  private client: XacheClient;
+  private mode: 'xache-managed' | 'api-key';
+  private llmApiKey?: string;
+  private llmProvider: 'anthropic' | 'openai';
+
+  constructor(config: XacheExtractorConfig) {
+    // Validate api-key mode requires llmApiKey
+    const mode = config.mode || 'xache-managed';
+    if (mode === 'api-key' && !config.llmApiKey) {
+      throw new Error('llmApiKey is required when mode is "api-key"');
+    }
+
+    const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
+    const did = `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}` as DID;
+
+    this.client = new XacheClient({
+      apiUrl: config.apiUrl || 'https://api.xache.xyz',
+      did,
+      privateKey: config.privateKey,
+      timeout: config.timeout,
+      debug: config.debug,
+    });
+
+    this.mode = mode;
+    this.llmApiKey = config.llmApiKey;
+    this.llmProvider = config.llmProvider || 'anthropic';
+  }
+
+  /**
+   * Extract memories from a conversation trace
+   */
+  async 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> {
+    const llmConfig =
+      this.mode === 'xache-managed'
+        ? { type: 'xache-managed' as const, provider: 'anthropic' as const }
+        : {
+            type: 'api-key' as const,
+            provider: this.llmProvider || ('anthropic' as const),
+            apiKey: this.llmApiKey || '',
+          };
+
+    const result: ExtractMemoriesResponse = await this.client.extraction.extract({
+      trace,
+      llmConfig,
+      options: {
+        autoStore: options?.autoStore,
+        contextHint: options?.instructions,
+      },
+    });
+
+    const minConfidence = options?.minConfidence ?? 0;
+    const memories: ExtractedMemory[] = (result.extractions || [])
+      .filter((m) => (m.confidence || 1) >= minConfidence)
+      .map((m, index) => ({
+        content: m.reasoning || JSON.stringify(m.data) || '',
+        context: m.type || 'extracted',
+        tags: Object.keys(m.data || {}),
+        confidence: m.confidence || 1,
+        memoryId: result.stored?.[index],
+      }));
+
+    return {
+      memories,
+      count: memories.length,
+      cost: 0, // Cost is handled by x402
+      receiptId: result.metadata?.paymentReceiptId,
+    };
+  }
+
+  /**
+   * Extract from LangChain messages
+   */
+  async extractFromMessages(
+    messages: Array<{ role: string; content: string }>,
+    options?: {
+      autoStore?: boolean;
+      instructions?: string;
+      minConfidence?: number;
+    }
+  ): Promise<ExtractionResult> {
+    const trace = messages.map((m) => `${m.role}: ${m.content}`).join('\n');
+
+    return this.extract(trace, options);
+  }
+}