@retrivora-ai/rag-engine 1.8.1 → 1.8.2

package/src/hooks/useRagChat.ts

@@ -19,16 +19,17 @@
  */
 
 import { useState, useCallback, useRef, useEffect } from 'react';
-import { VectorMatch, RagMessage, UseRagChatOptions, UseRagChatReturn } from '../types';
+import { VectorMatch, RagMessage, UseRagChatOptions, UseRagChatReturn, ObservabilityTrace } from '../types';
 import { useStoredMessages } from './useStoredMessages';
 
 // ─── SSE Frame Parser ──────────────────────────────────────────────────────────
 
-interface SseTextFrame  { type: 'text';     text: string }
-interface SseMetaFrame  { type: 'metadata'; sources?: VectorMatch[] }
-interface SseErrorFrame { type: 'error';    error: string }
-interface SseUiFrame    { type: 'ui_transformation'; data: unknown }
-type SseFrame = SseTextFrame | SseMetaFrame | SseErrorFrame | SseUiFrame;
+interface SseTextFrame         { type: 'text';             text: string }
+interface SseMetaFrame         { type: 'metadata';         sources?: VectorMatch[] }
+interface SseErrorFrame        { type: 'error';            error: string }
+interface SseUiFrame           { type: 'ui_transformation'; data: unknown }
+interface SseObservabilityFrame { type: 'observability';   data: ObservabilityTrace }
+type SseFrame = SseTextFrame | SseMetaFrame | SseErrorFrame | SseUiFrame | SseObservabilityFrame;
 
 /**
  * Parse all complete SSE frames from a raw chunk string.
@@ -126,6 +127,7 @@ export function useRagChat(
         let assistantContent = '';
         let sources: VectorMatch[] = [];
         let uiTransformation: unknown = null;
+        let trace: ObservabilityTrace | undefined;
         // Buffer for partial SSE frames that arrive split across reads
         let buffer = '';
 
@@ -161,6 +163,8 @@ export function useRagChat(
               sources = frame.sources ?? [];
             } else if (frame.type === 'ui_transformation') {
               uiTransformation = frame.data;
+            } else if (frame.type === 'observability') {
+              trace = (frame as SseObservabilityFrame).data;
             } else if (frame.type === 'error') {
               setError(frame.error || 'Stream error');
             }
@@ -186,18 +190,24 @@ export function useRagChat(
           for (const frame of parseSseChunk(buffer)) {
             if (frame.type === 'text' && frame.text) assistantContent += frame.text;
             else if (frame.type === 'metadata') sources = frame.sources ?? [];
+            else if (frame.type === 'observability') trace = (frame as SseObservabilityFrame).data;
           }
         }
 
-        const finalAssistantMessage: RagMessage = {
+        // Final message with all accumulated data
+        const finalMsg: RagMessage = {
           id: assistantMessageId,
           role: 'assistant',
           content: assistantContent,
           sources: sources.length > 0 ? sources : undefined,
-          uiTransformation: uiTransformation || undefined,
+          uiTransformation: uiTransformation ?? undefined,
+          trace,
           createdAt: new Date().toISOString(),
         };
-        onReply?.(finalAssistantMessage);
+        setMessages((prev) =>
+          prev.map((msg) => (msg.id === assistantMessageId ? finalMsg : msg))
+        );
+        onReply?.(finalMsg);
       } catch (err) {
         const msg = err instanceof Error ? err.message : 'Something went wrong. Please try again.';
         setError(msg);

package/src/index.ts

@@ -9,11 +9,15 @@ export { ChatWindow } from './components/ChatWindow';
 export { DocumentUpload } from './components/DocumentUpload';
 export { MessageBubble } from './components/MessageBubble';
 export { SourceCard } from './components/SourceCard';
+export { ObservabilityPanel } from './components/ObservabilityPanel';
 export { ConfigProvider, useConfig } from './components/ConfigProvider';
 
 // ── Headless Hooks ────────────────────────────────────────────
 export { useRagChat } from './hooks/useRagChat';
 
+// ── Utils ─────────────────────────────────────────────────────
+export { addSynonyms } from './utils/synonyms';
+
 // ── Types (Interfaces/Types only, no Node.js deps) ─────────────
 export type { RagConfig, VectorDBConfig, VectorDBProvider, LLMConfig, LLMProvider, EmbeddingConfig, EmbeddingProvider, UIConfig, RAGConfig } from './config/RagConfig';
 export type { ILLMProvider, EmbedOptions } from './llm/ILLMProvider';
@@ -35,5 +39,9 @@ export type {
   ProductCardProps,
   ProductCarouselProps,
   DocumentUploadProps,
-  SourceCardProps
+  SourceCardProps,
+  ObservabilityTrace,
+  LatencyBreakdown,
+  TokenUsage,
+  RetrievedChunk
 } from './types';

package/src/providers/vectordb/MultiTablePostgresProvider.ts

@@ -21,6 +21,7 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
   private readonly connectionString: string;
   private tables: string[];
   private searchFields: string[];
+  private readonly uploadTable: string;
 
   constructor(config: VectorDBConfig) {
     super(config);
@@ -31,22 +32,8 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
     this.connectionString = opts.connectionString as string;
     this.dimensions = (opts.dimensions as number) ?? 768;
 
-    // Tables can come from options.tables (custom key) or be derived from VECTOR_DB_TABLES env var
-    const rawTables: string | string[] =
-      (opts.tables as string | string[]) ??
-      process.env.VECTOR_DB_TABLES ??
-      '';
-
-    this.tables = typeof rawTables === 'string'
-      ? rawTables.split(',').map((t) => t.trim()).filter(Boolean)
-      : rawTables;
-
-    if (this.tables.length === 0) {
-      console.warn(
-        '[MultiTablePostgresProvider] No tables configured. ' +
-        'Set VECTOR_DB_TABLES as a comma-separated list of table names or pass options.tables.'
-      );
-    }
+    // The provider will dynamically discover tables during initialize().
+    this.tables = [];
 
     // Exact match fields can come from options.searchFields or be derived from VECTOR_DB_SEARCH_FIELDS env var
     const rawSearchFields: string | string[] =
@@ -57,6 +44,8 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
     this.searchFields = typeof rawSearchFields === 'string'
       ? rawSearchFields.split(',').map((f) => f.trim()).filter(Boolean)
       : rawSearchFields;
+
+    this.uploadTable = (opts.uploadTable as string) || 'document_chunks';
   }
 
   async initialize(): Promise<void> {
@@ -65,6 +54,24 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
     // Dynamically discover all tables that have an 'embedding' column
     const client: PoolClient = await this.pool.connect();
     try {
+      await client.query('CREATE EXTENSION IF NOT EXISTS vector');
+      
+      // Ensure the upload table exists
+      await client.query(`
+        CREATE TABLE IF NOT EXISTS ${this.uploadTable} (
+          id          TEXT PRIMARY KEY,
+          namespace   TEXT NOT NULL DEFAULT '',
+          content     TEXT NOT NULL,
+          metadata    JSONB,
+          embedding   VECTOR(${this.dimensions})
+        )
+      `);
+      await client.query(`
+        CREATE INDEX IF NOT EXISTS ${this.uploadTable}_embedding_idx
+        ON ${this.uploadTable}
+        USING hnsw (embedding vector_cosine_ops)
+      `);
+
       const res = await client.query(`
         SELECT table_name 
         FROM information_schema.columns 
@@ -72,21 +79,8 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
         AND table_schema = 'public'
       `);
 
-      const discoveredTables = res.rows.map(r => r.table_name);
-
-      if (this.tables.length === 0) {
-        // No static tables configured, use everything discovered
-        this.tables = discoveredTables;
-      } else {
-        // Filter configured tables to ensure they actually exist with embeddings
-        const staticTables = [...this.tables];
-        this.tables = staticTables.filter(t => discoveredTables.includes(t));
-
-        if (this.tables.length < staticTables.length) {
-          const missing = staticTables.filter(t => !discoveredTables.includes(t));
-          console.warn(`[MultiTablePostgresProvider] Some configured tables were skipped (missing 'embedding' column): ${missing.join(', ')}`);
-        }
-      }
+      // Dynamically use all tables that have an embedding column
+      this.tables = res.rows.map(r => r.table_name);
 
       if (this.tables.length === 0) {
         console.warn('[MultiTablePostgresProvider] No tables with "embedding" columns found in the database.');
@@ -101,23 +95,125 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
   }
 
   /**
-   * Upsert is not supported for MultiTablePostgresProvider as it's designed for 
-   * searching across pre-existing tables with varying schemas.
+   * Upsert a document by dynamically provisioning a table and columns.
    */
-  async upsert(_doc: UpsertDocument, _namespace?: string): Promise<void> { // eslint-disable-line @typescript-eslint/no-unused-vars
-    throw new Error(
-      '[MultiTablePostgresProvider] upsert() is not supported in multi-table mode. ' +
-      'Please use the standard PostgreSQLProvider for single-table managed indices.'
-    );
+  async upsert(doc: UpsertDocument, namespace = ''): Promise<void> {
+    await this.batchUpsert([doc], namespace);
   }
 
   /**
-   * Batch upsert is not supported for MultiTablePostgresProvider.
+   * Batch upsert documents by dynamically provisioning tables and columns based on CSV headers.
    */
-  async batchUpsert(_docs: UpsertDocument[], _namespace?: string): Promise<void> { // eslint-disable-line @typescript-eslint/no-unused-vars
-    throw new Error(
-      '[MultiTablePostgresProvider] batchUpsert() is not supported in multi-table mode.'
-    );
+  async batchUpsert(docs: UpsertDocument[], namespace = ''): Promise<void> {
+    if (docs.length === 0) return;
+
+    // Group docs by fileName to support dynamic table creation per CSV
+    const docsByFile: Record<string, UpsertDocument[]> = {};
+    for (const doc of docs) {
+      const fileName = (doc.metadata?.fileName as string) || this.uploadTable;
+      if (!docsByFile[fileName]) docsByFile[fileName] = [];
+      docsByFile[fileName].push(doc);
+    }
+
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+      
+      for (const [fileName, fileDocs] of Object.entries(docsByFile)) {
+        // Sanitize table name (e.g., "jewelery.csv" -> "jewelery")
+        let tableName = fileName;
+        if (tableName.toLowerCase().endsWith('.csv')) {
+           tableName = tableName.slice(0, -4);
+        }
+        tableName = tableName.replace(/[^a-z0-9_]/gi, '_').toLowerCase() || this.uploadTable;
+        
+        // Extract headers from the first doc's metadata
+        const firstMeta = fileDocs[0].metadata || {};
+        const systemKeys = ['fileName', 'fileSize', 'fileType', 'uploadedAt', 'dimension', 'chunkIndex', 'id', 'namespace', 'content', 'metadata', 'embedding'];
+        const csvHeaders = Object.keys(firstMeta).filter(k => !systemKeys.includes(k) && !systemKeys.includes(k.toLowerCase()));
+        
+        // 1. Create Table Dynamically
+        const columnDefs = csvHeaders.map(h => `"${h}" TEXT`).join(',\n          ');
+        const createTableSql = `
+          CREATE TABLE IF NOT EXISTS "${tableName}" (
+            id          TEXT PRIMARY KEY,
+            ${columnDefs ? columnDefs + ',' : ''}
+            namespace   TEXT NOT NULL DEFAULT '',
+            content     TEXT NOT NULL,
+            metadata    JSONB,
+            embedding   VECTOR(${this.dimensions})
+          )
+        `;
+        await client.query(createTableSql);
+        
+        // Create Index
+        await client.query(`
+          CREATE INDEX IF NOT EXISTS "${tableName}_embedding_idx"
+          ON "${tableName}"
+          USING hnsw (embedding vector_cosine_ops)
+        `);
+        
+        // Ensure this new table is added to our search scope
+        if (!this.tables.includes(tableName)) {
+          this.tables.push(tableName);
+        }
+        
+        // 2. Insert Data
+        const BATCH_SIZE = 50;
+        for (let i = 0; i < fileDocs.length; i += BATCH_SIZE) {
+          const batch = fileDocs.slice(i, i + BATCH_SIZE);
+          const values: unknown[] = [];
+          
+          const headerColumns = csvHeaders.map(h => `"${h}"`).join(', ');
+          const allColumns = `id, ${headerColumns ? headerColumns + ', ' : ''}namespace, content, metadata, embedding`;
+          
+          const valuePlaceholders = batch.map((doc, idx) => {
+            const offset = idx * (5 + csvHeaders.length);
+            
+            values.push(doc.id);
+            // Push header values
+            for (const h of csvHeaders) {
+              values.push(String(doc.metadata?.[h] || ''));
+            }
+            
+            values.push(namespace, doc.content, JSON.stringify(doc.metadata ?? {}), `[${doc.vector.join(',')}]`);
+            
+            const docPlaceholders = [];
+            for (let j = 1; j <= 5 + csvHeaders.length; j++) {
+              if (j === 5 + csvHeaders.length) {
+                docPlaceholders.push(`$${offset + j}::vector`);
+              } else {
+                docPlaceholders.push(`$${offset + j}`);
+              }
+            }
+            
+            return `(${docPlaceholders.join(', ')})`;
+          }).join(', ');
+          
+          const conflictUpdates = csvHeaders.map(h => `"${h}" = EXCLUDED."${h}"`).join(',\n              ');
+          
+          const query = `
+            INSERT INTO "${tableName}" (${allColumns})
+            VALUES ${valuePlaceholders}
+            ON CONFLICT (id) DO UPDATE
+              SET ${conflictUpdates ? conflictUpdates + ',' : ''}
+                  namespace = EXCLUDED.namespace,
+                  content   = EXCLUDED.content,
+                  metadata  = EXCLUDED.metadata,
+                  embedding = EXCLUDED.embedding
+          `;
+          
+          await client.query(query, values);
+        }
+      }
+      
+      await client.query('COMMIT');
+    } catch (error) {
+      await client.query('ROLLBACK');
+      throw error;
+    } finally {
+      client.release();
+    }
   }
 
   /**
@@ -258,30 +354,20 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
       allResults.push(...tableResults);
     }
 
-    // 1. Group results by table to ensure we take the top ones from each
-    const resultsByTable: Record<string, VectorMatch[]> = {};
-    for (const res of allResults) {
-      const table = res.metadata?.source_table as string;
-      if (!resultsByTable[table]) resultsByTable[table] = [];
-      resultsByTable[table].push(res);
-    }
-
-    // 2. Take top 3 from EACH table guaranteed, then fill the rest with overall best
-    const balancedResults: VectorMatch[] = [];
-    const tables = Object.keys(resultsByTable);
+    // 1. Sort all results globally by semantic similarity score
+    allResults.sort((a, b) => b.score - a.score);
 
-    // First, ensure every table's best match is included
-    for (const table of tables) {
-      balancedResults.push(...resultsByTable[table].slice(0, 3));
-    }
+    if (allResults.length === 0) return [];
 
-    // 3. Sort the balanced list by score
-    const finalSorted = balancedResults.sort((a, b) => b.score - a.score);
+    // 2. Identify the "Active Table Context" from the absolute highest scoring match
+    const bestMatchTable = allResults[0].metadata?.source_table as string;
+    
+    // 3. Filter out all results that don't belong to the active table to prevent cross-contamination
+    const finalSorted = allResults.filter(res => res.metadata?.source_table === bestMatchTable);
 
-    if (finalSorted.length > 0) {
-      console.log(`[MultiTablePostgresProvider] --- Search Complete ---`);
-      console.log(`[MultiTablePostgresProvider] Final top match from "${finalSorted[0].metadata?.source_table ?? 'unknown'}" with score ${finalSorted[0].score.toFixed(4)}`);
-    }
+    console.log(`[MultiTablePostgresProvider] --- Search Complete ---`);
+    console.log(`[MultiTablePostgresProvider] Final top match from "${bestMatchTable}" with score ${finalSorted[0].score.toFixed(4)}`);
+    console.log(`[MultiTablePostgresProvider] Restricting recommendations strictly to table: "${bestMatchTable}"`);
 
     return finalSorted.slice(0, Math.max(topK, 15));
   }

package/src/types/chat.ts

@@ -11,6 +11,8 @@ export interface RagMessage extends ChatMessage {
   id: string;
   sources?: VectorMatch[];
   uiTransformation?: unknown;
+  /** Full observability trace emitted by the backend. Only present on assistant messages. */
+  trace?: import('./index').ObservabilityTrace;
   createdAt: string;
 }
 

package/src/types/index.ts

@@ -1,3 +1,53 @@
+// ─── Observability ────────────────────────────────────────────────────────────
+
+/** Per-stage latency breakdown for a single RAG request. */
+export interface LatencyBreakdown {
+  embedMs: number;
+  retrieveMs: number;
+  rerankMs?: number;
+  generateMs: number;
+  totalMs: number;
+}
+
+/** Token usage reported by the LLM (or estimated when the provider doesn't expose it). */
+export interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  /** Rough cost in USD — estimated from token counts and model pricing. */
+  estimatedCostUsd?: number;
+}
+
+/** A single retrieved chunk annotated with its retrieval context. */
+export interface RetrievedChunk {
+  id: string | number;
+  score: number;
+  content: string;
+  metadata: Record<string, unknown>;
+  namespace: string;
+}
+
+/**
+ * Full observability trace for one RAG request.
+ * Emitted by the backend as an SSE frame and stored on each RagMessage.
+ */
+export interface ObservabilityTrace {
+  requestId: string;
+  query: string;
+  rewrittenQuery?: string;
+  systemPrompt: string;
+  userPrompt: string;
+  chunks: RetrievedChunk[];
+  latency: LatencyBreakdown;
+  tokens?: TokenUsage;
+  /** 0 = fully grounded, 1 = likely hallucinated. */
+  hallucinationScore?: number;
+  hallucinationReason?: string;
+  timestamp: string;
+}
+
+// ─── Vector / RAG ─────────────────────────────────────────────────────────────
+
 export interface VectorMatch {
   id: string | number;
   score: number;
@@ -23,6 +73,8 @@ export interface ChatResponse {
   sources: VectorMatch[];
   graphData?: GraphSearchResult;
   ui_transformation?: unknown;
+  /** Observability trace — populated by the instrumented Pipeline. */
+  trace?: ObservabilityTrace;
 }
 
 export interface GraphNode {

package/src/types/props.ts

@@ -74,9 +74,17 @@ export interface SourceCardProps {
 export interface ClientConfig {
   projectId: string;
   ui: Required<UIConfig>;
+  embedding?: {
+    model?: string;
+    dimensions?: number;
+  };
 }
 
 export interface ConfigProviderProps {
-  config?: { projectId?: string; ui?: Partial<UIConfig> };
+  config?: { 
+    projectId?: string; 
+    ui?: Partial<UIConfig>;
+    embedding?: { model?: string; dimensions?: number }
+  };
   children: ReactNode;
 }