@xache/langchain 0.1.0

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @xache/langchain
+ * LangChain.js integration for Xache Protocol
+ *
+ * Drop-in memory, retrieval, and collective intelligence with verifiable receipts.
+ *
+ * @example
+ * ```typescript
+ * // One-line memory replacement
+ * import { XacheMemory } from '@xache/langchain';
+ *
+ * const memory = new XacheMemory({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * // Use with any LangChain chain
+ * const chain = new ConversationChain({ llm, memory });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Memory
+export { XacheMemory, XacheConversationBufferMemory } from './memory';
+export type { XacheMemoryConfig } from './memory';
+
+// Chat History
+export { XacheChatMessageHistory } from './chat_history';
+export type { XacheChatMessageHistoryConfig } from './chat_history';
+
+// Retrieval
+export { XacheRetriever } from './retriever';
+export type { XacheRetrieverConfig } from './retriever';
+
+// Extraction
+export { XacheExtractor } from './extraction';
+export type {
+  XacheExtractorConfig,
+  ExtractedMemory,
+  ExtractionResult,
+} from './extraction';
+
+// Collective Intelligence
+export {
+  createCollectiveContributeTool,
+  createCollectiveQueryTool,
+  XacheCollectiveContributeTool,
+  XacheCollectiveQueryTool,
+} from './collective';
+export type { CollectiveToolConfig } from './collective';
+
+// Reputation
+export {
+  createReputationTool,
+  XacheReputationTool,
+  XacheReputationChecker,
+} from './reputation';
+export type { ReputationToolConfig, ReputationResult } from './reputation';

package/src/memory.ts

@@ -0,0 +1,121 @@
+/**
+ * Xache Memory for LangChain.js
+ * Drop-in replacement for ConversationBufferMemory with verifiable receipts
+ */
+
+import { BaseMemory, InputValues, OutputValues, MemoryVariables } from '@langchain/core/memory';
+import { XacheChatMessageHistory, XacheChatMessageHistoryConfig } from './chat_history';
+
+export 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!' });
+ * ```
+ */
+export class XacheMemory extends BaseMemory {
+  lc_namespace = ['xache', 'memory'];
+
+  private chatHistory: XacheChatMessageHistory;
+  private inputKey: string;
+  private outputKey: string;
+  private memoryKey: string;
+  private returnMessages: boolean;
+
+  constructor(config: XacheMemoryConfig) {
+    super();
+    this.chatHistory = new XacheChatMessageHistory(config);
+    this.inputKey = config.inputKey || 'input';
+    this.outputKey = config.outputKey || 'output';
+    this.memoryKey = config.memoryKey || 'history';
+    this.returnMessages = config.returnMessages ?? false;
+  }
+
+  get memoryKeys(): string[] {
+    return [this.memoryKey];
+  }
+
+  /**
+   * Load memory variables
+   */
+  async loadMemoryVariables(_values: InputValues): Promise<MemoryVariables> {
+    const messages = await this.chatHistory.getMessages();
+
+    if (this.returnMessages) {
+      return { [this.memoryKey]: messages };
+    }
+
+    // Convert to string format
+    const history = messages
+      .map((m) => {
+        const role = m._getType() === 'human' ? 'Human' : 'AI';
+        const content =
+          typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        return `${role}: ${content}`;
+      })
+      .join('\n');
+
+    return { [this.memoryKey]: history };
+  }
+
+  /**
+   * Save context from this conversation to buffer
+   */
+  async saveContext(
+    inputValues: InputValues,
+    outputValues: OutputValues
+  ): Promise<void> {
+    const input = inputValues[this.inputKey];
+    const output = outputValues[this.outputKey];
+
+    if (input) {
+      await this.chatHistory.addUserMessage(String(input));
+    }
+
+    if (output) {
+      await this.chatHistory.addAIMessage(String(output));
+    }
+  }
+
+  /**
+   * Clear memory contents
+   */
+  async clear(): Promise<void> {
+    await this.chatHistory.clear();
+  }
+}
+
+/**
+ * Extended memory with conversation buffer capabilities
+ */
+export class XacheConversationBufferMemory extends XacheMemory {
+  lc_namespace = ['xache', 'memory', 'buffer'];
+}

package/src/reputation.ts

@@ -0,0 +1,195 @@
+/**
+ * Xache Reputation for LangChain.js
+ * Portable, verifiable agent reputation with ERC-8004 support
+ */
+
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { XacheClient, DID } from '@xache/sdk';
+
+export 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';
+}
+
+export 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;
+}
+
+/**
+ * Get reputation level from score
+ */
+function getLevel(score: number): string {
+  if (score >= 0.9) return 'Elite';
+  if (score >= 0.7) return 'Trusted';
+  if (score >= 0.5) return 'Established';
+  if (score >= 0.3) return 'Developing';
+  return 'New';
+}
+
+/**
+ * Create an Xache client for reputation tools
+ */
+function createClient(config: ReputationToolConfig): 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 checking your own reputation.
+ *
+ * @example
+ * ```typescript
+ * import { createReputationTool } from '@xache/langchain';
+ *
+ * const repTool = createReputationTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ * });
+ *
+ * const tools = [repTool, ...];
+ * ```
+ */
+export function createReputationTool(
+  config: ReputationToolConfig
+): DynamicStructuredTool {
+  const client = createClient(config);
+
+  return new DynamicStructuredTool({
+    name: 'xache_check_reputation',
+    description:
+      'Check your current reputation score and status. ' +
+      'Returns your score (0-1), level, and ERC-8004 on-chain status. ' +
+      'Higher reputation means lower costs and more trust from other agents.',
+    schema: z.object({}),
+    func: async () => {
+      const result = await client.reputation.getReputation();
+
+      // Overall score is 0-100, normalize to 0-1
+      const score = (result.overall || 0) / 100;
+      const level = getLevel(score);
+
+      let output = `Reputation Score: ${score.toFixed(2)}/1.00 (${level})\n`;
+      output += `Memory Quality: ${result.memoryQuality || 0}/100\n`;
+      output += `Contribution Success: ${result.contribSuccess || 0}/100\n`;
+      output += `Economic Value: ${result.economicValue || 0}/100\n`;
+
+      // Check ERC-8004 status separately
+      try {
+        const erc8004Status = await client.reputation.getERC8004Status();
+        if (erc8004Status.enabled) {
+          output += `ERC-8004 Status: Enabled\n`;
+          output += 'Your reputation is verifiable on-chain!';
+        } else {
+          output += 'ERC-8004 Status: Not enabled\n';
+          output += 'Enable ERC-8004 to make your reputation portable and verifiable.';
+        }
+      } catch {
+        output += 'ERC-8004 Status: Unknown';
+      }
+
+      return output;
+    },
+  });
+}
+
+/**
+ * Class-based reputation tool (alternative API)
+ */
+export class XacheReputationTool {
+  private tool: DynamicStructuredTool;
+
+  constructor(config: ReputationToolConfig) {
+    this.tool = createReputationTool(config);
+  }
+
+  asTool(): DynamicStructuredTool {
+    return this.tool;
+  }
+}
+
+/**
+ * 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');
+ * }
+ * ```
+ */
+export class XacheReputationChecker {
+  private client: XacheClient;
+
+  constructor(config: ReputationToolConfig) {
+    this.client = createClient(config);
+  }
+
+  /**
+   * Check an agent's reputation
+   */
+  async check(agentDid: string): Promise<ReputationResult> {
+    const result = await this.client.reputation.getReputation(agentDid as DID);
+
+    // Overall score is 0-100, normalize to 0-1
+    const score = (result.overall || 0) / 100;
+
+    // Try to get ERC-8004 status
+    let erc8004Enabled = false;
+    let erc8004AgentId: string | undefined;
+    try {
+      const erc8004Status = await this.client.reputation.getERC8004Status();
+      erc8004Enabled = erc8004Status.enabled;
+    } catch {
+      // ERC-8004 status not available
+    }
+
+    return {
+      score,
+      level: getLevel(score),
+      totalContributions: 0, // Not available in current API
+      totalPayments: 0, // Not available in current API
+      erc8004Enabled,
+      erc8004AgentId,
+    };
+  }
+
+  /**
+   * Check if an agent meets minimum reputation threshold
+   */
+  async meetsThreshold(agentDid: string, minScore: number): Promise<boolean> {
+    const result = await this.check(agentDid);
+    return result.score >= minScore;
+  }
+}

package/src/retriever.ts

@@ -0,0 +1,100 @@
+/**
+ * Xache Retriever for LangChain.js
+ * Memory retrieval for RAG pipelines with verifiable receipts
+ */
+
+import { BaseRetriever, BaseRetrieverInput } from '@langchain/core/retrievers';
+import { Document } from '@langchain/core/documents';
+import { CallbackManagerForRetrieverRun } from '@langchain/core/callbacks/manager';
+import { XacheClient, DID } from '@xache/sdk';
+
+export 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?' });
+ * ```
+ */
+export class XacheRetriever extends BaseRetriever {
+  lc_namespace = ['xache', 'retriever'];
+
+  static lc_name() {
+    return 'XacheRetriever';
+  }
+
+  private client: XacheClient;
+  private k: number;
+  private filterContext?: string;
+
+  constructor(config: XacheRetrieverConfig) {
+    super(config);
+
+    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,
+    });
+
+    this.k = config.k ?? 5;
+    this.filterContext = config.context;
+  }
+
+  async _getRelevantDocuments(
+    _query: string,
+    _runManager?: CallbackManagerForRetrieverRun
+  ): Promise<Document[]> {
+    // Use list method to get memories filtered by context
+    const result = await this.client.memory.list({
+      context: this.filterContext,
+      limit: this.k,
+    });
+
+    const memories = result.memories || [];
+
+    return memories.map(
+      (m) =>
+        new Document({
+          pageContent: m.context || '',
+          metadata: {
+            storageKey: m.storage_key,
+            context: m.context,
+            tier: m.storage_tier,
+            createdAt: m.created_at,
+            size: m.size_bytes,
+          },
+        })
+    );
+  }
+}