@cmdoss/memwal-sdk 0.6.0

package/src/langchain/README.md

@@ -0,0 +1,116 @@
+# LangChain Integration for Personal Data Wallet SDK
+
+This module provides standard LangChain interfaces for PDW's decentralized storage, SEAL encryption, and Sui blockchain integration.
+
+## Features
+
+- ✅ **PDWEmbeddings** - LangChain embeddings adapter using Google Gemini
+- ✅ **PDWVectorStore** - VectorStore with Walrus storage + Sui blockchain + HNSW search
+- 🚧 **createPDWRAG** - Coming soon (Simple RAG helper function)
+
+## Installation
+
+The LangChain integration is included in the main PDW SDK package:
+
+```bash
+npm install personal-data-wallet-sdk @langchain/core @langchain/google-genai
+```
+
+## Quick Start
+
+### Complete Example with PDWVectorStore
+
+```typescript
+import { PDWEmbeddings, PDWVectorStore } from 'personal-data-wallet-sdk/langchain';
+import { useCurrentAccount, useSuiClient, useSignAndExecuteTransaction } from '@mysten/dapp-kit';
+
+// Initialize embeddings
+const embeddings = new PDWEmbeddings({
+  geminiApiKey: process.env.NEXT_PUBLIC_GEMINI_API_KEY!
+});
+
+// Initialize PDW VectorStore (decentralized storage)
+const vectorStore = new PDWVectorStore(embeddings, {
+  userAddress: account.address,
+  packageId: '0x...',
+  walrusAggregator: 'https://aggregator.walrus-testnet.walrus.space',
+  geminiApiKey: process.env.NEXT_PUBLIC_GEMINI_API_KEY!
+});
+
+// Add documents (creates memories on Walrus + Sui blockchain)
+await vectorStore.addDocuments([
+  { pageContent: 'Meeting notes...', metadata: { category: 'work' } }
+], {
+  account,
+  signAndExecute,
+  client
+});
+
+// Search (HNSW vector search)
+const results = await vectorStore.similaritySearch('meetings', 5);
+
+// Use as retriever in RAG chains
+const retriever = vectorStore.asRetriever({ k: 5 });
+```
+
+## API Reference
+
+### PDWEmbeddings
+
+LangChain Embeddings adapter using PDW's EmbeddingService (Google Gemini).
+
+#### Constructor
+
+```typescript
+new PDWEmbeddings(params: {
+  geminiApiKey: string;      // Required: Your Gemini API key
+  model?: string;            // Optional: Model name (default: 'text-embedding-004')
+  dimensions?: number;       // Optional: Embedding dimensions (default: 768)
+  requestsPerMinute?: number;// Optional: Rate limit (default: 1500)
+})
+```
+
+#### Methods
+
+**`embedQuery(text: string): Promise<number[]>`**
+
+Embed a single query text. Optimized for search queries.
+
+**`embedDocuments(texts: string[]): Promise<number[][]>`**
+
+Embed multiple document texts. Uses batch processing for efficiency.
+
+**`getModelInfo(): { model: string; dimensions: number; provider: string }`**
+
+Get information about the embedding model.
+
+## Examples
+
+See the [examples directory](../../examples/langchain/) for complete examples:
+
+- `basic-embeddings.ts` - Simple embedding generation
+- More examples coming soon!
+
+## Why Use PDW with LangChain?
+
+1. **Decentralized Storage**: Store embeddings on Walrus (decentralized blob storage)
+2. **Blockchain Ownership**: Track ownership via Sui blockchain
+3. **SEAL Encryption**: Privacy-preserving encryption for sensitive data
+4. **Standard Interface**: Works with entire LangChain ecosystem
+5. **Browser Compatible**: All operations work in browser (WebAssembly HNSW)
+
+## Roadmap
+
+- ✅ PDWEmbeddings adapter
+- 🚧 PDWVectorStore (Walrus + Sui + HNSW)
+- 🚧 PDWRetriever (with SEAL decryption)
+- 🚧 createPDWRAG helper
+- 🚧 React hooks for LangChain components
+- 🚧 Advanced retrievers (MMR, compression, etc.)
+
+## Learn More
+
+- [LangChain Documentation](https://docs.langchain.com/)
+- [PDW SDK Documentation](../../README.md)
+- [Walrus Storage](https://docs.walrus.site/)
+- [Sui Blockchain](https://docs.sui.io/)

package/src/langchain/createPDWRAG.ts

@@ -0,0 +1,303 @@
+/**
+ * createPDWRAG - Simple RAG Helper for Personal Data Wallet
+ *
+ * A one-function RAG setup that combines PDWVectorStore with any LangChain LLM.
+ * Provides the quickest way to build RAG applications with decentralized storage.
+ *
+ * @example
+ * ```typescript
+ * import { createPDWRAG, PDWEmbeddings, PDWVectorStore } from 'personal-data-wallet-sdk/langchain';
+ * import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
+ *
+ * const embeddings = new PDWEmbeddings({ geminiApiKey });
+ * const vectorStore = new PDWVectorStore(embeddings, config);
+ * const llm = new ChatGoogleGenerativeAI({ apiKey: geminiApiKey });
+ *
+ * const ragChain = await createPDWRAG({
+ *   vectorStore,
+ *   llm,
+ *   systemPrompt: 'You are my personal AI assistant.'
+ * });
+ *
+ * const answer = await ragChain.invoke({ question: 'What did I do last week?' });
+ * ```
+ */
+
+import { ChatPromptTemplate } from '@langchain/core/prompts';
+import { RunnableSequence } from '@langchain/core/runnables';
+import type { Runnable } from '@langchain/core/runnables';
+import { StringOutputParser } from '@langchain/core/output_parsers';
+import { VectorStoreRetriever } from '@langchain/core/vectorstores';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { PDWVectorStore } from './PDWVectorStore';
+
+export interface PDWRAGConfig {
+  /**
+   * PDWVectorStore instance for retrieval
+   */
+  vectorStore: PDWVectorStore;
+
+  /**
+   * LangChain LLM for generation
+   * Can be any LLM: ChatGoogleGenerativeAI, ChatOpenAI, ChatAnthropic, etc.
+   */
+  llm: Runnable<any, BaseMessage>;
+
+  /**
+   * System prompt for the RAG chain
+   * @default 'You are a helpful assistant with access to a knowledge base.'
+   */
+  systemPrompt?: string;
+
+  /**
+   * Number of documents to retrieve
+   * @default 5
+   */
+  k?: number;
+
+  /**
+   * Minimum similarity threshold (0-1)
+   * @default 0.5
+   */
+  minSimilarity?: number;
+
+  /**
+   * Custom retriever (overrides vectorStore if provided)
+   */
+  retriever?: VectorStoreRetriever;
+
+  /**
+   * Custom prompt template (overrides systemPrompt)
+   */
+  promptTemplate?: ChatPromptTemplate;
+
+  /**
+   * Whether to include source documents in the output
+   * @default false
+   */
+  returnSourceDocuments?: boolean;
+
+  /**
+   * Metadata filters for retrieval
+   */
+  filter?: Record<string, any>;
+}
+
+export interface PDWRAGResult {
+  /**
+   * Generated answer from the LLM
+   */
+  answer: string;
+
+  /**
+   * Source documents used for context (if returnSourceDocuments is true)
+   */
+  sourceDocuments?: Array<{
+    content: string;
+    metadata: any;
+    similarity?: number;
+  }>;
+}
+
+/**
+ * Create a RAG chain with PDWVectorStore
+ *
+ * This helper function sets up a complete RAG pipeline:
+ * 1. Retriever: Fetches relevant documents from PDWVectorStore
+ * 2. Prompt: Formats context and question for the LLM
+ * 3. LLM: Generates answer based on context
+ * 4. Parser: Extracts text from LLM response
+ *
+ * @param config - RAG configuration
+ * @returns A runnable chain that takes { question: string } and returns answer
+ */
+export async function createPDWRAG(
+  config: PDWRAGConfig
+): Promise<RunnableSequence> {
+  const {
+    vectorStore,
+    llm,
+    systemPrompt = 'You are a helpful assistant with access to a knowledge base. Use the following context to answer questions accurately.',
+    k = 5,
+    minSimilarity = 0.5,
+    retriever: customRetriever,
+    promptTemplate,
+    filter,
+  } = config;
+
+  // Create retriever from vector store or use custom
+  const retriever = customRetriever || vectorStore.asRetriever({
+    k,
+    filter: {
+      ...filter,
+      minSimilarity,
+    },
+  });
+
+  // Create prompt template
+  const prompt = promptTemplate || ChatPromptTemplate.fromTemplate(`
+${systemPrompt}
+
+Context from your knowledge base:
+{context}
+
+Question: {question}
+
+Answer based on the context above. If the context doesn't contain relevant information, say so.
+  `);
+
+  // Build RAG chain
+  const ragChain = RunnableSequence.from([
+    {
+      context: async (input: { question: string }) => {
+        const docs = await retriever.invoke(input.question);
+        return docs.map(d => d.pageContent).join('\n\n');
+      },
+      question: (input: { question: string }) => input.question,
+    },
+    prompt,
+    llm,
+    new StringOutputParser(),
+  ]);
+
+  return ragChain;
+}
+
+/**
+ * Create a RAG chain that returns both answer and source documents
+ *
+ * @param config - RAG configuration with returnSourceDocuments enabled
+ * @returns A runnable chain that returns { answer, sourceDocuments }
+ */
+export async function createPDWRAGWithSources(
+  config: Omit<PDWRAGConfig, 'returnSourceDocuments'>
+): Promise<RunnableSequence> {
+  const {
+    vectorStore,
+    llm,
+    systemPrompt = 'You are a helpful assistant with access to a knowledge base.',
+    k = 5,
+    minSimilarity = 0.5,
+    retriever: customRetriever,
+    promptTemplate,
+    filter,
+  } = config;
+
+  // Create retriever
+  const retriever = customRetriever || vectorStore.asRetriever({
+    k,
+    filter: {
+      ...filter,
+      minSimilarity,
+    },
+  });
+
+  // Create prompt template
+  const prompt = promptTemplate || ChatPromptTemplate.fromTemplate(`
+${systemPrompt}
+
+Context:
+{context}
+
+Question: {question}
+
+Answer:
+  `);
+
+  // Build RAG chain with sources
+  const ragChain = RunnableSequence.from([
+    async (input: { question: string }) => {
+      const docs = await retriever.invoke(input.question);
+
+      return {
+        context: docs.map(d => d.pageContent).join('\n\n'),
+        question: input.question,
+        sourceDocuments: docs.map(d => ({
+          content: d.pageContent,
+          metadata: d.metadata,
+          similarity: d.metadata?.similarity,
+        })),
+      };
+    },
+    async (input: any) => {
+      const answer = await RunnableSequence.from([
+        {
+          context: () => input.context,
+          question: () => input.question,
+        },
+        prompt,
+        llm,
+        new StringOutputParser(),
+      ]).invoke(input);
+
+      return {
+        answer,
+        sourceDocuments: input.sourceDocuments,
+      };
+    },
+  ]);
+
+  return ragChain;
+}
+
+/**
+ * Create a conversational RAG chain that maintains chat history
+ *
+ * @param config - RAG configuration
+ * @returns A runnable chain that takes { question, chatHistory } and returns answer
+ */
+export async function createConversationalPDWRAG(
+  config: PDWRAGConfig
+): Promise<RunnableSequence> {
+  const {
+    vectorStore,
+    llm,
+    systemPrompt = 'You are a helpful assistant with access to a knowledge base.',
+    k = 5,
+    minSimilarity = 0.5,
+    retriever: customRetriever,
+    filter,
+  } = config;
+
+  // Create retriever
+  const retriever = customRetriever || vectorStore.asRetriever({
+    k,
+    filter: {
+      ...filter,
+      minSimilarity,
+    },
+  });
+
+  // Create conversational prompt
+  const prompt = ChatPromptTemplate.fromTemplate(`
+${systemPrompt}
+
+Chat History:
+{chatHistory}
+
+Context from knowledge base:
+{context}
+
+Current Question: {question}
+
+Answer:
+  `);
+
+  // Build conversational RAG chain
+  const ragChain = RunnableSequence.from([
+    {
+      context: async (input: { question: string; chatHistory?: string }) => {
+        const docs = await retriever.invoke(input.question);
+        return docs.map(d => d.pageContent).join('\n\n');
+      },
+      question: (input: { question: string; chatHistory?: string }) => input.question,
+      chatHistory: (input: { question: string; chatHistory?: string }) =>
+        input.chatHistory || 'No previous messages',
+    },
+    prompt,
+    llm,
+    new StringOutputParser(),
+  ]);
+
+  return ragChain;
+}

package/src/langchain/index.ts

@@ -0,0 +1,47 @@
+/**
+ * LangChain Integration for Personal Data Wallet SDK
+ *
+ * Provides standard LangChain interfaces for PDW's decentralized storage,
+ * SEAL encryption, and Sui blockchain integration.
+ *
+ * @module langchain
+ *
+ * @example
+ * ```typescript
+ * import { PDWEmbeddings, PDWVectorStore } from 'personal-data-wallet-sdk/langchain';
+ *
+ * // Initialize embeddings
+ * const embeddings = new PDWEmbeddings({
+ *   geminiApiKey: process.env.GEMINI_API_KEY!
+ * });
+ *
+ * // Initialize vector store
+ * const vectorStore = new PDWVectorStore(embeddings, {
+ *   userAddress: '0x...',
+ *   packageId: '0x...',
+ *   walrusAggregator: 'https://...'
+ * });
+ *
+ * // Use with LangChain
+ * const results = await vectorStore.similaritySearch('query', 5);
+ * ```
+ */
+
+// Embeddings
+export { PDWEmbeddings } from './PDWEmbeddings';
+export type { PDWEmbeddingsParams } from './PDWEmbeddings';
+
+// VectorStore
+export { PDWVectorStore } from './PDWVectorStore';
+export type { PDWVectorStoreConfig, PDWAddDocumentOptions } from './PDWVectorStore';
+
+// RAG Helpers
+export {
+  createPDWRAG,
+  createPDWRAGWithSources,
+  createConversationalPDWRAG
+} from './createPDWRAG';
+export type {
+  PDWRAGConfig,
+  PDWRAGResult
+} from './createPDWRAG';