@retrivora-ai/rag-engine 1.8.1 → 1.8.3

package/src/handlers/index.ts

@@ -30,6 +30,11 @@ function sseUIFrame(uiTransformation: unknown): string {
   return `data: ${JSON.stringify({ type: 'ui_transformation', data: uiTransformation })}\n\n`;
 }
 
+/** Encode the observability trace as an SSE frame. */
+function sseObservabilityFrame(trace: unknown): string {
+  return `data: ${JSON.stringify({ type: 'observability', data: trace })}\n\n`;
+}
+
 /** Encode a stream error as an SSE frame. */
 function sseErrorFrame(message: string): string {
   return `data: ${JSON.stringify({ type: 'error', error: message })}\n\n`;
@@ -153,12 +158,14 @@ export function createStreamHandler(configOrPlugin?: Partial<RagConfig> | Vector
               enqueue(sseMetaFrame(chunk));
 
               // ── LLM-driven visualization decision ─────────────────────────
-              // Sends question + RAG context to the LLM and asks it to choose
-              // the best visualization format (bar_chart, pie_chart, table…).
-              // Falls back to keyword heuristic if the LLM call fails.
               const responseChunk = chunk as ChatResponse;
               const sources = responseChunk?.sources || [];
 
+              // Emit observability trace if present
+              if (responseChunk?.trace) {
+                enqueue(sseObservabilityFrame(responseChunk.trace));
+              }
+
               if (sources.length > 0) {
                 try {
                   const llmProvider = plugin.getLLMProvider?.();
@@ -172,7 +179,6 @@ export function createStreamHandler(configOrPlugin?: Partial<RagConfig> | Vector
                   }
                 } catch (transformError) {
                   console.warn('[createStreamHandler] UI transformation warning:', transformError);
-                  // Last-resort fallback: heuristic transform
                   try {
                     const fallback = UITransformer.transform(message, sources, plugin.getConfig());
                     if (fallback) enqueue(sseUIFrame(fallback));
@@ -265,15 +271,68 @@ export function createUploadHandler(configOrPlugin?: Partial<RagConfig> | Vector
       const formData = await req.formData();
       const files = formData.getAll('files') as File[];
       const namespace = (formData.get('namespace') as string) || undefined;
+      const dimensionRaw = formData.get('dimension');
+      const dimension = dimensionRaw ? parseInt(dimensionRaw as string, 10) : undefined;
 
       if (!files || files.length === 0) {
         return NextResponse.json({ error: 'No files provided' }, { status: 400 });
       }
 
-      const documents = await Promise.all(
-        files.map(async (file) => {
+      const documents: { docId: string; content: string; metadata?: Record<string, unknown> }[] = [];
+
+      for (const file of files) {
+        if (file.name.toLowerCase().endsWith('.csv') || file.type === 'text/csv') {
+          const text = await file.text();
+          const Papa = await import('papaparse');
+          const parsed = Papa.default.parse(text, { header: true, skipEmptyLines: true });
+          
+          if (parsed.data && parsed.data.length > 0) {
+            let i = 0;
+            let lastRowData: Record<string, string> | null = null;
+            
+            for (const row of parsed.data) {
+              i++;
+              const rowData = row as Record<string, string>;
+              
+              // Dynamically determine the grouping key (typically the first column like ID or Handle)
+              const groupingKey = Object.keys(rowData)[0];
+              
+              // Forward-fill ALL empty columns for variants belonging to the same group
+              if (lastRowData && groupingKey && rowData[groupingKey] && rowData[groupingKey] === lastRowData[groupingKey]) {
+                for (const key of Object.keys(rowData)) {
+                  // Forward-fill if the current row lacks the field but the previous row has it
+                  if (!rowData[key] && lastRowData[key]) {
+                    rowData[key] = lastRowData[key];
+                  }
+                }
+              }
+              // Save a copy of the filled rowData for the next iteration
+              lastRowData = { ...rowData };
+              
+              const contentParts: string[] = [];
+              for (const [key, val] of Object.entries(rowData)) {
+                if (key && val) {
+                  contentParts.push(`${key}: ${val}`);
+                }
+              }
+              
+              documents.push({
+                docId: `${file.name}-row-${i}`,
+                content: contentParts.join(', '),
+                metadata: {
+                  fileName: file.name,
+                  fileSize: file.size,
+                  fileType: file.type,
+                  uploadedAt: new Date().toISOString(),
+                  ...(dimension ? { dimension } : {}),
+                  ...rowData
+                }
+              });
+            }
+          }
+        } else {
           const content = await DocumentParser.parse(file, file.name, file.type);
-          return {
+          documents.push({
             docId: file.name,
             content,
             metadata: {
@@ -281,10 +340,11 @@ export function createUploadHandler(configOrPlugin?: Partial<RagConfig> | Vector
               fileSize: file.size,
               fileType: file.type,
               uploadedAt: new Date().toISOString(),
+              ...(dimension ? { dimension } : {}),
             },
-          };
-        })
-      );
+          });
+        }
+      }
 
       const results = await plugin.ingest(documents, namespace);
       return NextResponse.json({ message: 'Upload successful', results });
@@ -325,5 +385,5 @@ export function createSuggestionsHandler(configOrPlugin?: Partial<RagConfig> | V
   };
 }
 
-// Re-export SSE helper so host apps can use it in custom handlers
-export { sseFrame, sseTextFrame, sseMetaFrame, sseErrorFrame, sseUIFrame };
+// Re-export SSE helpers so host apps can use them in custom handlers
+export { sseFrame, sseTextFrame, sseMetaFrame, sseErrorFrame, sseUIFrame, sseObservabilityFrame };

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/rag/Reranker.ts

@@ -1,18 +1,111 @@
 import { VectorMatch } from '../types';
+import { ILLMProvider } from '../llm/ILLMProvider';
 
 export class Reranker {
   /**
-   * Re-ranks matches based on a secondary relevance score.
-   * In a production environment, this would call a Cross-Encoder model.
-   * Here we implement a placeholder that filters by score and limits count.
+   * Re-ranks matches based on a secondary relevance score using an LLM.
    */
   async rerank(
     matches: VectorMatch[], 
     query: string, 
-    limit: number = 5
+    limit: number = 5,
+    llm?: ILLMProvider
   ): Promise<VectorMatch[]> {
-    // Current implementation: sort by original score and apply a strict threshold
-    // and semantic match filtering (placeholder)
+    if (!llm || matches.length <= 1) {
+      // Fallback to deterministic keyword-based re-ranking for production speed
+      const keywords = query.toLowerCase()
+        .replace(/[^\w\s]/g, '')
+        .split(/\s+/)
+        .filter(w => w.length > 2); // Filter out short words/stop words
+
+      if (keywords.length === 0) {
+        return matches
+          .sort((a, b) => b.score - a.score)
+          .slice(0, limit);
+      }
+
+      const scoredMatches = matches.map(match => {
+        const contentLower = match.content.toLowerCase();
+        let keywordScore = 0;
+        
+        keywords.forEach(keyword => {
+          if (contentLower.includes(keyword)) {
+            keywordScore += 1;
+          }
+        });
+
+        // Normalize keyword score (fraction of keywords found)
+        const normalizedKeywordScore = keywordScore / keywords.length;
+
+        // Combine scores: Vector score (usually 0-1) + Keyword score weighted
+        // We give a significant weight to keyword matches to surface specific results
+        const combinedScore = match.score + (normalizedKeywordScore * 0.5);
+
+        return {
+          ...match,
+          score: combinedScore
+        };
+      });
+
+      return scoredMatches
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    }
+
+    try {
+      // Take top 10 matches to avoid large context and high latency
+      const topN = matches.slice(0, 10);
+      
+      const prompt = `You are a relevance ranking expert.
+Given the following user query and a list of retrieved document chunks, rank the chunks by relevance to the query.
+Return the result as a comma-separated list of document indices in order of relevance, from most relevant to least relevant.
+Use the indices provided in brackets like [0], [1], etc.
+Only return the indices (e.g., "2,0,1"), nothing else. Do not include brackets in the output.
+
+Query: "${query}"
+
+Documents:
+${topN.map((m, i) => `[${i}] ${m.content.replace(/\n/g, ' ')}`).join('\n')}`;
+
+      const response = await llm.chat(
+        [{ role: 'user', content: prompt }],
+        '',
+        { temperature: 0, maxTokens: 50 }
+      );
+
+      const cleanedResponse = response.trim().replace(/[\[\]\s]/g, '');
+      const rankedIndices = cleanedResponse.split(',').map(Number).filter(n => !isNaN(n));
+
+      if (rankedIndices.length > 0) {
+        const rankedMatches: VectorMatch[] = [];
+        const usedIndices = new Set<number>();
+
+        // Add matches in the order specified by the LLM
+        for (const index of rankedIndices) {
+          if (index >= 0 && index < topN.length && !usedIndices.has(index)) {
+            rankedMatches.push(topN[index]);
+            usedIndices.add(index);
+          }
+        }
+
+        // Add any remaining matches that the LLM might have missed
+        for (let i = 0; i < topN.length; i++) {
+          if (!usedIndices.has(i)) {
+            rankedMatches.push(topN[i]);
+          }
+        }
+
+        // Add back the rest of the matches that weren't in the top N
+        const rest = matches.slice(10);
+        rankedMatches.push(...rest);
+
+        return rankedMatches.slice(0, limit);
+      }
+    } catch (error) {
+      console.warn('[Reranker] LLM re-ranking failed, falling back to score-based sorting:', error);
+    }
+
+    // Fallback if LLM fails or returns invalid response
     return matches
       .sort((a, b) => b.score - a.score)
       .slice(0, limit);

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