@retrivora-ai/rag-engine 1.9.0 → 1.9.1

package/src/hooks/useRagChat.ts

@@ -128,10 +128,36 @@ export function useRagChat(
         let sources: VectorMatch[] = [];
         let uiTransformation: unknown = null;
         let trace: ObservabilityTrace | undefined;
-        // Buffer for partial SSE frames that arrive split across reads
         let buffer = '';
 
-        // Add a placeholder assistant message that we will update incrementally
+        // ── RAF-based render batching ─────────────────────────────────────
+        // Accumulate text chunks in a ref and flush to React state at ~60fps
+        // instead of calling setMessages on every SSE frame. This eliminates
+        // O(N) ReactMarkdown re-parses where N = number of token chunks.
+        let pendingFlush = false;
+        const pendingContentRef = { current: '' };
+
+        const flushTextUpdate = (msgId: string) => {
+          pendingFlush = false;
+          const snapshot = pendingContentRef.current;
+          setMessages((prev) =>
+            prev.map((msg) =>
+              msg.id === msgId
+                ? { ...msg, content: snapshot }
+                : msg
+            )
+          );
+        };
+
+        const scheduleFlush = (msgId: string) => {
+          if (!pendingFlush) {
+            pendingFlush = true;
+            requestAnimationFrame(() => flushTextUpdate(msgId));
+          }
+        };
+        // ─────────────────────────────────────────────────────────────────
+
+        // Add a placeholder assistant message
         const assistantMessageId = `assistant_${Date.now()}`;
         setMessages((prev) => [
           ...prev,
@@ -149,40 +175,50 @@ export function useRagChat(
 
           buffer += decoder.decode(value, { stream: true });
 
-          // Only process complete frames (ending with \n\n)
           const lastBoundary = buffer.lastIndexOf('\n\n');
-          if (lastBoundary === -1) continue; // Wait for more data
+          if (lastBoundary === -1) continue;
 
           const complete = buffer.slice(0, lastBoundary + 2);
           buffer = buffer.slice(lastBoundary + 2);
 
+          let hasNonTextFrame = false;
+
           for (const frame of parseSseChunk(complete)) {
             if (frame.type === 'text' && frame.text) {
               assistantContent += frame.text;
+              pendingContentRef.current = assistantContent;
+              // Schedule a batched RAF flush instead of immediate setMessages
+              scheduleFlush(assistantMessageId);
             } else if (frame.type === 'metadata') {
               sources = frame.sources ?? [];
+              hasNonTextFrame = true;
             } else if (frame.type === 'ui_transformation') {
               uiTransformation = frame.data;
+              hasNonTextFrame = true;
             } else if (frame.type === 'observability') {
               trace = (frame as SseObservabilityFrame).data;
+              hasNonTextFrame = true;
             } else if (frame.type === 'error') {
               setError(frame.error || 'Stream error');
             }
           }
 
-          // Update the assistant message with accumulated content
-          setMessages((prev) =>
-            prev.map((msg) =>
-              msg.id === assistantMessageId
-                ? { 
-                    ...msg, 
-                    content: assistantContent, 
-                    sources: sources.length > 0 ? sources : msg.sources,
-                    uiTransformation: uiTransformation || (msg as RagMessage).uiTransformation
-                  }
-                : msg
-            )
-          );
+          // Flush non-text metadata immediately (sources, UI transform, trace)
+          if (hasNonTextFrame) {
+            pendingFlush = false; // cancel pending text flush — we'll do a full update
+            setMessages((prev) =>
+              prev.map((msg) =>
+                msg.id === assistantMessageId
+                  ? {
+                      ...msg,
+                      content: assistantContent,
+                      sources: sources.length > 0 ? sources : msg.sources,
+                      uiTransformation: uiTransformation || (msg as RagMessage).uiTransformation,
+                    }
+                  : msg
+              )
+            );
+          }
         }
 
         // Process any remaining buffered data

package/src/llm/providers/UniversalLLMAdapter.ts

@@ -25,6 +25,9 @@ export class UniversalLLMAdapter implements ILLMProvider {
   private readonly systemPrompt: string;
   private readonly maxTokens: number;
   private readonly temperature: number;
+  private readonly baseUrl: string;
+  private readonly apiKey?: string;
+  private readonly resolvedHeaders: Record<string, string>;
 
   constructor(config: LLMConfig | EmbeddingConfig) {
     this.model = config.model;
@@ -46,19 +49,22 @@ export class UniversalLLMAdapter implements ILLMProvider {
     this.systemPrompt = llmConfig.systemPrompt ?? 'You are a helpful AI assistant. Use the provided context to answer the user.';
     this.maxTokens = llmConfig.maxTokens ?? 1024;
     this.temperature = llmConfig.temperature ?? 0;
+    this.apiKey = config.apiKey;
 
-    const baseUrl = llmConfig.baseUrl ?? this.opts.baseUrl;
-    if (!baseUrl) {
+    this.baseUrl = llmConfig.baseUrl ?? this.opts.baseUrl ?? '';
+    if (!this.baseUrl) {
       throw new Error('[UniversalLLMAdapter] baseUrl is required in config or config.options');
     }
 
+    this.resolvedHeaders = {
+      'Content-Type': 'application/json',
+      ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+      ...(this.opts.headers || {}),
+    };
+
     this.http = axios.create({
-      baseURL: baseUrl,
-      headers: {
-        'Content-Type': 'application/json',
-        ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
-        ...(this.opts.headers || {}),
-      },
+      baseURL: this.baseUrl,
+      headers: this.resolvedHeaders,
       timeout: this.opts.timeout ?? 60_000,
     });
   }
@@ -73,7 +79,6 @@ export class UniversalLLMAdapter implements ILLMProvider {
 
     let payload: unknown;
     if (this.opts.chatPayloadTemplate) {
-      // The user wants to map messages and parameters to their unique JSON shape
       payload = buildPayload(this.opts.chatPayloadTemplate, {
         model: this.model,
         messages: formattedMessages,
@@ -81,7 +86,6 @@ export class UniversalLLMAdapter implements ILLMProvider {
         temperature: this.temperature,
       });
     } else {
-      // Fallback to OpenAI standard which covers 90% of open-source models (vLLM, LMStudio, Ollama, etc.)
       payload = {
         model: this.model,
         messages: formattedMessages,
@@ -102,6 +106,102 @@ export class UniversalLLMAdapter implements ILLMProvider {
     return String(result);
   }
 
+  /**
+   * Streaming chat using native fetch + ReadableStream.
+   * Parses OpenAI-compatible SSE frames: `data: {...}\n\n`
+   * Works with vLLM, LMStudio, Together AI, Fireworks, and any OpenAI-compatible API.
+   */
+  async *chatStream(messages: ChatMessage[], context?: string): AsyncIterable<string> {
+    const path = this.opts.chatPath ?? '/chat/completions';
+    const url = `${this.baseUrl.replace(/\/$/, '')}${path}`;
+    // Delta extract path — same root as chat but with delta instead of message
+    const extractPath = (this.opts.responseExtractPath ?? 'choices[0].message.content')
+      .replace('message.content', 'delta.content');
+
+    const formattedMessages = [
+      { role: 'system', content: `${this.systemPrompt}\n\nContext:\n${context ?? 'None'}` },
+      ...messages,
+    ];
+
+    let payload: unknown;
+    if (this.opts.chatPayloadTemplate) {
+      payload = buildPayload(this.opts.chatPayloadTemplate, {
+        model: this.model,
+        messages: formattedMessages,
+        maxTokens: this.maxTokens,
+        temperature: this.temperature,
+      });
+      // Inject stream: true into the payload if it's an object
+      if (typeof payload === 'object' && payload !== null) {
+        (payload as Record<string, unknown>).stream = true;
+      }
+    } else {
+      payload = {
+        model: this.model,
+        messages: formattedMessages,
+        max_tokens: this.maxTokens,
+        temperature: this.temperature,
+        stream: true,
+      };
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: this.resolvedHeaders,
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => response.statusText);
+      throw new Error(`[UniversalLLMAdapter] Streaming request failed (${response.status}): ${errorText}`);
+    }
+
+    if (!response.body) {
+      throw new Error('[UniversalLLMAdapter] Response body is null — server did not send a streaming response.');
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buffer = '';
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed === 'data: [DONE]') continue;
+          if (!trimmed.startsWith('data:')) continue;
+
+          try {
+            const json = JSON.parse(trimmed.slice(5).trim());
+            const text = resolvePath(json, extractPath);
+            if (text && typeof text === 'string') yield text;
+          } catch {
+            // Malformed SSE line — skip
+          }
+        }
+      }
+
+      // Flush remaining buffer
+      if (buffer.trim() && buffer.trim() !== 'data: [DONE]') {
+        const jsonStr = buffer.replace(/^data:\s*/, '').trim();
+        try {
+          const json = JSON.parse(jsonStr);
+          const text = resolvePath(json, extractPath);
+          if (text && typeof text === 'string') yield text;
+        } catch { /* ignore final partial line */ }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
   async embed(text: string): Promise<number[]> {
     const path = this.opts.embedPath ?? '/embeddings';
 
@@ -112,7 +212,6 @@ export class UniversalLLMAdapter implements ILLMProvider {
         input: text,
       });
     } else {
-      // OpenAI standard fallback
       payload = {
         model: this.model,
         input: text,
@@ -133,8 +232,6 @@ export class UniversalLLMAdapter implements ILLMProvider {
 
   async batchEmbed(texts: string[]): Promise<number[][]> {
     const vectors: number[][] = [];
-    // Sequential fallback if the provider doesn't have a specific batch template
-    // In production, we should add a batchEmbedPayloadTemplate to UniversalLLMOptions
     for (const text of texts) {
       vectors.push(await this.embed(text));
     }

package/src/providers/vectordb/ChromaDBProvider.ts

@@ -70,12 +70,23 @@ export class ChromaDBProvider extends BaseVectorProvider {
     await this.http.post(`/api/v1/collections/${this.collectionId}/add`, payload);
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   async query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]> {
+    const sanitizedFilter = this.sanitizeFilter(_filter);
+    const whereClauses: Record<string, unknown>[] = [];
+    if (namespace) whereClauses.push({ namespace: { $eq: namespace } });
+    Object.entries(sanitizedFilter).forEach(([key, value]) => {
+      if (key === 'namespace') return;
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        whereClauses.push({ [key]: { $eq: value } });
+      }
+    });
+
     const payload = {
       query_embeddings: [vector],
       n_results: topK,
-      where: namespace ? { namespace: { $eq: namespace } } : undefined,
+      where: whereClauses.length > 1
+        ? { $and: whereClauses }
+        : whereClauses[0],
     };
     const { data } = await this.http.post(`/api/v1/collections/${this.collectionId}/query`, payload);
 

package/src/providers/vectordb/MilvusProvider.ts

@@ -68,13 +68,29 @@ export class MilvusProvider extends BaseVectorProvider {
     await this.http.post('/v1/vector/upsert', payload);
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   async query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]> {
+    const sanitizedFilter = this.sanitizeFilter(_filter);
+
+    // Build Milvus boolean expression from filter fields.
+    // Namespace filtering is expressed as a field equality check.
+    const filterParts: string[] = [];
+    if (namespace) {
+      filterParts.push(`namespace == "${namespace}"`);
+    }
+    for (const [key, value] of Object.entries(sanitizedFilter)) {
+      if (key === 'queryText' || key === 'keywords') continue;
+      if (typeof value === 'string') {
+        filterParts.push(`metadata["${key}"] == "${value.replace(/"/g, '\\"')}"`);
+      } else if (typeof value === 'number') {
+        filterParts.push(`metadata["${key}"] == ${value}`);
+      }
+    }
+
     const payload = {
       collectionName: this.indexName,
       vector: vector,
       limit: topK,
-      filter: namespace ? `namespace == "${namespace}"` : undefined,
+      filter: filterParts.length > 0 ? filterParts.join(' && ') : undefined,
       outputFields: ['content', 'metadata'],
       searchParams: {
         nprobe: (this.config.options.nprobe as number) || 16,

package/src/providers/vectordb/MultiTablePostgresProvider.ts

@@ -235,12 +235,9 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
     console.log(`[MultiTablePostgresProvider] --- Starting Multi-Table Search ---`);
 
     const queryText = _filter?.queryText as string | undefined;
-    const entityHints = Array.isArray(_filter?.__entityHints)
-      ? (_filter.__entityHints as unknown[])
-        .filter((hint): hint is { value: string; field?: string } =>
-          typeof hint === 'object' && hint !== null && typeof (hint as Record<string, unknown>).value === 'string'
-        )
-        .map((hint) => hint.value.trim().toLowerCase())
+    const entityHints = Array.isArray(_filter?.keywords)
+      ? (_filter.keywords as string[])
+        .map((k) => k.trim().toLowerCase())
         .filter(Boolean)
       : [];
 
@@ -252,15 +249,17 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
       if (entityHints.length > 0) {
         // Use extracted entities as high-signal keywords
         return entityHints
-          .map(h => h.includes(' ') ? `"${h}"` : h) // Wrap multi-word hints in quotes
+          .map(h => h.replace(/\s+/g, ' & ')) // Replace spaces with & for valid tsquery
           .join(' & ');
       }
 
       if (queryText) {
         // Fallback to cleaned raw text if no high-signal hints were extracted
+        // Added 'get', 'details', 'information', 'info' to stop words
         return queryText
           .toLowerCase()
-          .replace(/\b(show|me|the|product[s]?|item[s]?|card[s]?|of|category|find|list|browse|what|are|display|all|under|for|in|with|about)\b/g, '')
+          .replace(/\b(show|me|the|product[s]?|item[s]?|card[s]?|organization[s]?|comp(?:any|anies)|of|category|find|list|browse|what|are|display|all|whose|that|which|have|has|having|greater|than|more|less|equal|equals|above|below|over|under|at|least|most|for|in|with|about|get|details|information|info)\b/g, '')
+          .replace(/\b\d+(?:\.\d+)?\b/g, '')
           .trim()
           .replace(/\s+/g, ' & ');
       }
@@ -268,13 +267,14 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
     };
 
     const dynamicKeywordQuery = getDynamicKeywordQuery();
+    const tableLimit = Math.max(topK, 50);
 
     const queryPromises = this.tables.map(async (table) => {
       try {
         let sqlQuery = '';
         let params: unknown[] = [];
 
-        if (queryText) {
+        if (queryText && dynamicKeywordQuery) {
           const hasEntityHints = entityHints.length > 0;
           const exactNameScoreExpr = hasEntityHints
             ? `+ (
@@ -295,17 +295,17 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
              ((1 - (embedding <=> $1::vector)) + (COALESCE(ts_rank(to_tsvector('english', (to_jsonb(t) - 'embedding')::text), to_tsquery('english', $2)), 0) * 2.0) ${exactNameScoreExpr}) AS hybrid_score
             FROM "${table}" t
             ORDER BY hybrid_score DESC
-            LIMIT 50
+            LIMIT ${tableLimit}
           `;
           params = [vectorLiteral, dynamicKeywordQuery];
         } else {
           // Fallback to Vector-only Search
           sqlQuery = `
             SELECT *, 
-             (1 - (embedding <=> $1::vector)) AS hybrid_score
+            (1 - (embedding <=> $1::vector)) AS hybrid_score
             FROM "${table}" t
             ORDER BY hybrid_score DESC
-            LIMIT 50
+            LIMIT ${tableLimit}
           `;
           params = [vectorLiteral];
         }

package/src/providers/vectordb/PostgreSQLProvider.ts

@@ -170,7 +170,7 @@ export class PostgreSQLProvider extends BaseVectorProvider {
       const filterConditions = Object.entries(publicFilter)
         .map(([key, val]) => {
           const paramIdx = params.length + 1;
-          params.push(JSON.stringify(val));
+          params.push(String(val));
           return `metadata->>'${key}' = $${paramIdx}`;
         })
         .join(' AND ');

package/src/providers/vectordb/QdrantProvider.ts

@@ -211,7 +211,7 @@ export class QdrantProvider extends BaseVectorProvider {
       limit: topK,
       with_payload: true,
       params: {
-        hnsw_ef: (this.config.options.efSearch as number) || Math.max(topK * 20, 128),
+        hnsw_ef: ((this.config.options as Record<string, unknown>)?.efSearch as number | undefined) || Math.max(topK * 20, 128),
         exact: false
       },
       filter: must.length > 0 ? { must } : undefined,

package/src/providers/vectordb/RedisProvider.ts

@@ -90,16 +90,15 @@ export class RedisProvider extends BaseVectorProvider {
   }
 
   /**
-   * Redis is TCP-based and has no HTTP health endpoint.
-   * Returns true; actual connectivity is validated on the first operation.
+   * Check reachability via a PING command.
+   * Returns false on connection failure so health checks surface real problems.
    */
   async ping(): Promise<boolean> {
     try {
       await this.http.post('/', ['PING']);
       return true;
     } catch {
-      // If REST ping fails, assume connectivity will be validated on first use
-      return true;
+      return false;
     }
   }
 

package/src/providers/vectordb/WeaviateProvider.ts

@@ -40,6 +40,7 @@ export class WeaviateProvider extends BaseVectorProvider {
   }
 
   async upsert(doc: UpsertDocument, namespace?: string): Promise<void> {
+    const primitiveMetadata = this.extractPrimitiveMetadata(doc.metadata);
     const payload = {
       class: this.indexName,
       id: doc.id,
@@ -47,6 +48,7 @@ export class WeaviateProvider extends BaseVectorProvider {
       properties: {
         content: doc.content,
         metadata: JSON.stringify(doc.metadata || {}),
+        ...primitiveMetadata,
         namespace: namespace || '',
       },
     };
@@ -62,6 +64,7 @@ export class WeaviateProvider extends BaseVectorProvider {
         properties: {
           content: doc.content,
           metadata: JSON.stringify(doc.metadata || {}),
+          ...this.extractPrimitiveMetadata(doc.metadata),
           namespace: namespace || '',
         },
       })),
@@ -70,12 +73,14 @@ export class WeaviateProvider extends BaseVectorProvider {
   }
 
   async query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]> {
+    // IMPORTANT: read queryText BEFORE calling sanitizeFilter() because sanitizeFilter strips it.
+    const queryText = _filter?.queryText as string | undefined;
     const sanitizedFilter = this.sanitizeFilter(_filter);
-    const queryText = sanitizedFilter.queryText as string;
 
-    const searchParams = queryText 
+    const searchParams = queryText
       ? `hybrid: { query: ${JSON.stringify(queryText)}, alpha: 0.5 }`
       : `nearVector: { vector: ${JSON.stringify(vector)} }`;
+    const where = this.buildWhereFilter(namespace, sanitizedFilter);
 
     const graphqlQuery = {
       query: `
@@ -84,7 +89,7 @@ export class WeaviateProvider extends BaseVectorProvider {
             ${this.indexName}(
               ${searchParams}
               limit: ${topK}
-              ${namespace ? `where: { path: ["namespace"], operator: Equal, valueString: "${namespace}" }` : ''}
+              ${where ? `where: ${where}` : ''}
             ) {
               content
               metadata
@@ -132,4 +137,37 @@ export class WeaviateProvider extends BaseVectorProvider {
   }
 
   async disconnect(): Promise<void> {}
+
+  private extractPrimitiveMetadata(metadata?: Record<string, unknown>): Record<string, string | number | boolean> {
+    const result: Record<string, string | number | boolean> = {};
+    Object.entries(metadata || {}).forEach(([key, value]) => {
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        result[key] = value;
+      }
+    });
+    return result;
+  }
+
+  private buildWhereFilter(namespace?: string, filter?: Record<string, unknown>): string | undefined {
+    const operands: string[] = [];
+    if (namespace) operands.push(this.weaviateOperand('namespace', namespace));
+
+    Object.entries(filter || {}).forEach(([key, value]) => {
+      if (key === 'namespace') return;
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        operands.push(this.weaviateOperand(key, value));
+      }
+    });
+
+    if (operands.length === 0) return undefined;
+    if (operands.length === 1) return operands[0];
+    return `{ operator: And, operands: [${operands.join(', ')}] }`;
+  }
+
+  private weaviateOperand(key: string, value: string | number | boolean): string {
+    const path = `path: [${JSON.stringify(key)}], operator: Equal`;
+    if (typeof value === 'number') return `{ ${path}, valueNumber: ${value} }`;
+    if (typeof value === 'boolean') return `{ ${path}, valueBoolean: ${value} }`;
+    return `{ ${path}, valueString: ${JSON.stringify(value)} }`;
+  }
 }

package/src/types/index.ts

@@ -125,7 +125,12 @@ export type VisualizationType =
   | 'pie_chart'
   | 'bar_chart'
   | 'line_chart'
+  | 'histogram'
+  | 'horizontal_bar'
+  | 'scatter_plot'
   | 'radar_chart'
+  | 'metric_card'
+  | 'geo_map'
   | 'table'
   | 'product_carousel'
   | 'carousel'
@@ -173,6 +178,27 @@ export interface LineChartDataPoint {
   [key: string]: unknown;
 }
 
+/**
+ * Scatter plot data point
+ */
+export interface ScatterPlotDataPoint {
+  x: number;
+  y: number;
+  label?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * KPI / metric card representation
+ */
+export interface MetricCardData {
+  label: string;
+  value: number;
+  operation?: 'sum' | 'average' | 'count' | 'min' | 'max' | 'median';
+  unit?: string;
+  details?: Record<string, string | number | boolean>;
+}
+
 /**
  * Table representation
  */

package/src/utils/ProductExtractor.ts

@@ -199,11 +199,13 @@ export function extractProductsFromSources(sources: VectorMatch[] | undefined, i
     .filter(s => {
       const m = s.metadata ?? {};
       const keys = Object.keys(m).map(k => k.toLowerCase());
-      const hasProductKey = keys.some(k =>
-        ['price', 'image', 'img', 'thumbnail', 'images', 'brand', 'product', 'sku', 'category', 'model', 'cost'].includes(k)
+      const hasStrongProductKey = keys.some(k =>
+        ['price', 'image', 'img', 'thumbnail', 'images', 'product', 'sku', 'cost'].includes(k)
       );
+      const hasProductIdentity = keys.some(k => ['brand', 'model'].includes(k)) &&
+        keys.some(k => ['name', 'title', 'product_name', 'product'].includes(k));
       const hasPricePattern = /\$\s*\d+/.test(s.content);
-      return hasProductKey || hasPricePattern || m.type === 'product';
+      return hasStrongProductKey || hasProductIdentity || hasPricePattern || m.type === 'product';
     })
     .map(s => {
       const m = (s.metadata ?? {}) as Record<string, unknown>;