@snap-agent/rag-ecommerce 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ViloTech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,279 @@
+# @snap-agent/rag-ecommerce
+
+E-commerce RAG plugin for SnapAgent SDK - Sophisticated product search and recommendations with vector embeddings.
+
+## Features
+
+- **Vector Search** - MongoDB Atlas with Voyage AI embeddings
+- **Smart Attribute Extraction** - AI-powered query understanding
+- **Soft Rescoring** - Attribute matching + business metrics
+- **Optional Reranking** - Voyage reranker for precision
+- **Built-in Caching** - 50-80% cost & latency reduction
+- **Multilingual** - Spanish and English support
+- **Fully Configurable** - Tune every aspect  
+
+## Installation
+
+```bash
+npm install @snap-agent/rag-ecommerce @snap-agent/core
+```
+
+## Quick Start
+
+```typescript
+import { createClient, MongoDBStorage } from '@snap-agent/core';
+import { EcommerceRAGPlugin } from '@snap-agent/rag-ecommerce';
+
+const client = createClient({
+  storage: new MongoDBStorage(process.env.MONGODB_URI!),
+  providers: {
+    openai: { apiKey: process.env.OPENAI_API_KEY! },
+  },
+});
+
+const agent = await client.createAgent({
+  name: 'Shopping Assistant',
+  instructions: 'You are a helpful shopping assistant.',
+  model: 'gpt-4o',
+  userId: 'user-123',
+  plugins: [
+    new EcommerceRAGPlugin({
+      mongoUri: process.env.MONGODB_URI!,
+      openaiApiKey: process.env.OPENAI_API_KEY!,
+      voyageApiKey: process.env.VOYAGE_API_KEY!,
+      tenantId: 'my-store',
+    }),
+  ],
+});
+
+const thread = await client.createThread({
+  agentId: agent.id,
+  userId: 'user-123',
+});
+
+const response = await client.chat({
+  threadId: thread.id,
+  message: 'I want red sneakers under $100',
+  useRAG: true,
+});
+```
+
+## How It Works
+
+### 1. Query Understanding
+```
+User: "red nike running shoes under $100"
+↓
+Attribute Extraction (OpenAI):
+{
+  color: "red",
+  brand: "nike",
+  category: "running shoes",
+  priceMax: 100
+}
+```
+
+### 2. Vector Search
+```
+Query → Embedding (Voyage) → MongoDB Atlas Vector Search
+↓
+Returns: Top 50 semantically similar products
+```
+
+### 3. Soft Rescoring
+```
+Base score + Attribute matches + Business metrics
+- Color match: +0.15
+- Brand match: +0.08
+- Popularity: +0.05
+- CTR: +0.10
+↓
+Re-ranked by combined score
+```
+
+### 4. Optional Reranking
+```
+Top 50 → Voyage Reranker → Top 10 most relevant
+```
+
+### 5. Context Injection
+```
+Top 8 products → Formatted context → Injected into LLM prompt
+```
+
+## Configuration
+
+### Basic
+```typescript
+new EcommerceRAGPlugin({
+  mongoUri: process.env.MONGODB_URI!,
+  openaiApiKey: process.env.OPENAI_API_KEY!,
+  voyageApiKey: process.env.VOYAGE_API_KEY!,
+  tenantId: 'my-store',
+})
+```
+
+### Advanced
+```typescript
+new EcommerceRAGPlugin({
+  // Required
+  mongoUri: process.env.MONGODB_URI!,
+  openaiApiKey: process.env.OPENAI_API_KEY!,
+  voyageApiKey: process.env.VOYAGE_API_KEY!,
+  tenantId: 'my-store',
+  
+  // Customize attributes
+  attributeList: ['category', 'color', 'brand', 'price', 'size', 'style'],
+  
+  // Tune scoring weights
+  rescoringWeights: {
+    color: 0.20,
+    brand: 0.15,
+    category: 0.10,
+    popularity: 0.15,
+  },
+  
+  // Enable reranking
+  enableReranking: true,
+  rerankTopK: 5,
+  
+  // Cache configuration
+  cache: {
+    embeddings: { enabled: true, ttl: 3600000, maxSize: 2000 },
+    attributes: { enabled: true, ttl: 1800000, maxSize: 1000 },
+  },
+  
+  // Context
+  contextProductCount: 10,
+  language: 'en',
+  includeOutOfStock: false,
+})
+```
+
+## Caching
+
+Built-in intelligent caching for dramatic performance improvements:
+
+```typescript
+const stats = plugin.getCacheStats();
+console.log(stats);
+// {
+//   embeddings: { hits: 1250, misses: 320, hitRate: '0.80' },
+//   attributes: { hits: 890, misses: 210, hitRate: '0.81' }
+// }
+```
+
+**Benefits:**
+- 50-80% cost reduction
+- 5-10x faster for repeat queries
+- Automatic cleanup
+- Zero configuration required
+
+See [CACHING.md](./CACHING.md) for details.
+
+## Database Schema
+
+### Products Collection
+```typescript
+{
+  tenantId: string,
+  agentId?: string,
+  sku: string,
+  title: string,
+  description?: string,
+  embedding: number[], // 1024-dim vector
+  attributes: {
+    category?: string,
+    brand?: string,
+    color?: string,
+    material?: string,
+    size?: string[],
+    price?: number,
+    gender?: 'M' | 'F' | 'Unisex',
+  },
+  inStock?: boolean,
+  metrics?: {
+    popularity?: number,
+    ctr?: number,
+    sales?: number,
+  }
+}
+```
+
+### Required Indexes
+```javascript
+// Vector search index
+db.products.createSearchIndex({
+  name: "product_vector_index",
+  type: "vectorSearch",
+  definition: {
+    fields: [{
+      type: "vector",
+      path: "embedding",
+      numDimensions: 1024,
+      similarity: "cosine"
+    }]
+  }
+});
+```
+
+## Environment Variables
+
+```bash
+MONGODB_URI=mongodb+srv://...
+OPENAI_API_KEY=sk-...
+VOYAGE_API_KEY=pa-...
+```
+
+## Performance
+
+| Metric | Without RAG | With RAG | With RAG + Cache |
+|--------|------------|----------|------------------|
+| Latency | 200ms | 600ms | 180ms |
+| Cost/query | $0.0005 | $0.0008 | $0.0003 |
+| Relevance | Low | High | High |
+
+## Examples
+
+See [example-cache.ts](./example-cache.ts) for a complete working example with cache monitoring.
+
+## API Reference
+
+### Methods
+
+#### `retrieveContext(message, options)`
+Main retrieval method (called by SDK automatically)
+
+**Returns:**
+```typescript
+{
+  content: string,           // Formatted product list
+  sources: [...],           // Top products with scores
+  metadata: {
+    productCount: number,
+    extractedAttributes: {...},
+    topProducts: [...]
+  }
+}
+```
+
+#### `getCacheStats()`
+Get cache performance statistics
+
+#### `clearCache()`
+Clear all caches
+
+#### `disconnect()`
+Cleanup MongoDB connection
+
+## License
+
+MIT © ViloTech
+
+## Support
+
+- [ViloTech]("https://vilotech.co")
+- [Documentation](../../sdk/README.md)
+- [GitHub Issues](https://github.com/vilotech/snap-agent/issues)
+- [SnapAgent SDK](https://github.com/vilotech/snap-agent)
+

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+import { RAGPlugin, RAGContext, RAGDocument, IngestOptions, IngestResult, BulkOperation, BulkResult } from '@snap-agent/core';
+
+interface URLSource {
+    url: string;
+    type: 'json' | 'csv' | 'xml' | 'api';
+    auth?: {
+        type: 'bearer' | 'basic' | 'api-key' | 'custom';
+        token?: string;
+        username?: string;
+        password?: string;
+        header?: string;
+        key?: string;
+        headers?: Record<string, string>;
+    };
+    transform?: {
+        documentPath?: string;
+        fieldMapping?: {
+            id?: string;
+            content?: string;
+            [key: string]: string | undefined;
+        };
+    };
+    headers?: Record<string, string>;
+    timeout?: number;
+    metadata?: Record<string, any>;
+}
+interface URLIngestResult extends IngestResult {
+    sourceUrl: string;
+    fetchedAt: Date;
+    documentsFetched: number;
+}
+interface EcommerceRAGConfig {
+    mongoUri: string;
+    dbName?: string;
+    collection?: string;
+    openaiApiKey: string;
+    voyageApiKey: string;
+    embeddingModel?: string;
+    tenantId: string;
+    attributeList?: string[];
+    enableAttributeExtraction?: boolean;
+    numCandidates?: number;
+    limit?: number;
+    vectorIndexName?: string;
+    rescoringWeights?: {
+        color?: number;
+        size?: number;
+        material?: number;
+        category?: number;
+        brand?: number;
+        popularity?: number;
+        ctr?: number;
+        sales?: number;
+    };
+    enableReranking?: boolean;
+    rerankTopK?: number;
+    contextProductCount?: number;
+    language?: 'es' | 'en';
+    includeOutOfStock?: boolean;
+    cache?: {
+        embeddings?: {
+            enabled?: boolean;
+            ttl?: number;
+            maxSize?: number;
+        };
+        attributes?: {
+            enabled?: boolean;
+            ttl?: number;
+            maxSize?: number;
+        };
+    };
+    priority?: number;
+}
+interface ProductDoc {
+    _id?: any;
+    tenantId: string;
+    agentId?: string;
+    sku: string;
+    title: string;
+    description?: string;
+    embedding: number[];
+    attributes: {
+        category?: string;
+        brand?: string;
+        color?: string;
+        material?: string;
+        size?: string[];
+        gender?: 'M' | 'F' | 'Unisex';
+        season?: string;
+        price?: number;
+        [key: string]: any;
+    };
+    inStock?: boolean;
+    metrics?: {
+        popularity?: number;
+        ctr?: number;
+        sales?: number;
+    };
+    vectorSearchScore?: number;
+}
+interface QueryAttrs {
+    category?: string;
+    color?: string;
+    gender?: string;
+    brand?: string;
+    material?: string;
+    size?: string;
+    season?: string;
+    priceMin?: number;
+    priceMax?: number;
+    [key: string]: any;
+}
+declare class EcommerceRAGPlugin implements RAGPlugin {
+    name: string;
+    type: "rag";
+    priority: number;
+    private config;
+    private client;
+    private db;
+    private openai;
+    private embeddingCache;
+    private attributeCache;
+    private cacheStats;
+    private cleanupInterval?;
+    constructor(config: EcommerceRAGConfig);
+    private ensureConnection;
+    /**
+     * Main retrieval method - called by the SDK
+     */
+    retrieveContext(message: string, options: {
+        agentId: string;
+        threadId?: string;
+        filters?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<RAGContext>;
+    /**
+     * Format context for LLM
+     */
+    formatContext(context: RAGContext): string;
+    /**
+     * Embed text using Voyage with caching
+     */
+    private embedText;
+    /**
+     * Extract attributes from user message using OpenAI with caching
+     */
+    private extractAttributes;
+    /**
+     * MongoDB Atlas Vector Search
+     */
+    private vectorSearch;
+    /**
+     * Soft rescore based on attributes and metrics
+     */
+    private softRescore;
+    /**
+     * Optional Voyage reranking
+     */
+    private rerank;
+    /**
+     * Build context string for LLM
+     */
+    private buildContextString;
+    /**
+     * Start periodic cache cleanup (remove expired entries)
+     */
+    private startCacheCleanup;
+    /**
+     * Clean up expired cache entries
+     */
+    private cleanupExpiredCache;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        embeddings: {
+            size: number;
+            maxSize: number;
+            hits: number;
+            misses: number;
+            hitRate: string;
+        };
+        attributes: {
+            size: number;
+            maxSize: number;
+            hits: number;
+            misses: number;
+            hitRate: string;
+        };
+    };
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get MongoDB collection
+     */
+    private getCollection;
+    /**
+     * Generate embedding for a single text
+     */
+    private generateEmbedding;
+    /**
+     * Ingest products into the RAG system
+     * Converts RAGDocuments to ProductDocs and indexes them with embeddings
+     */
+    ingest(documents: RAGDocument[], options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Update a single product
+     */
+    update(id: string, document: Partial<RAGDocument>, options?: IngestOptions): Promise<void>;
+    /**
+     * Delete product(s) by SKU
+     */
+    delete(ids: string | string[], options?: IngestOptions): Promise<number>;
+    /**
+     * Bulk operations for efficient batch processing
+     */
+    bulk(operations: BulkOperation[], options?: IngestOptions): Promise<BulkResult>;
+    /**
+     * Generate embeddings for a batch of texts
+     */
+    private generateEmbeddingsBatch;
+    /**
+     * Ingest documents from URL source (CSV, JSON, XML, API)
+     */
+    ingestFromUrl(source: URLSource, options?: IngestOptions): Promise<URLIngestResult>;
+    /**
+     * Handle webhook payload for real-time updates
+     */
+    handleWebhook(payload: any, source: string, options?: IngestOptions): Promise<IngestResult>;
+    private buildAuthHeaders;
+    private transformJsonToDocuments;
+    private transformCsvToDocuments;
+    private transformXmlToDocuments;
+    private extractByPath;
+    private extractField;
+    private parseShopifyWebhook;
+    private parseWooCommerceWebhook;
+    /**
+     * Cleanup resources and close connections
+     */
+    disconnect(): Promise<void>;
+}
+
+export { type EcommerceRAGConfig, EcommerceRAGPlugin, type ProductDoc, type QueryAttrs, type URLIngestResult, type URLSource };