@snap-agent/rag-ecommerce 0.1.0

package/dist/index.d.ts

@@ -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 };