@retrivora-ai/rag-engine 1.9.0 → 1.9.1

package/src/core/Pipeline.ts

@@ -11,7 +11,8 @@ import { RagConfig } from '../config/RagConfig';
 import { ProviderRegistry } from './ProviderRegistry';
 import { BatchProcessor, BatchOptions } from './BatchProcessor';
 import { EmbeddingStrategyResolver } from '../config/EmbeddingStrategy';
-import { QueryProcessor } from './QueryProcessor';
+import { QueryProcessor, NumericPredicate, QueryFilter } from './QueryProcessor';
+import { LLMRouter } from './LLMRouter';
 import {
   IngestDocument, ChatResponse, VectorMatch, GraphSearchResult,
   RetrievalResult, UpsertDocument, ObservabilityTrace, LatencyBreakdown,
@@ -166,6 +167,7 @@ export class Pipeline {
   private graphDB?: BaseGraphProvider;
   private llmProvider!: ILLMProvider;
   private embeddingProvider!: ILLMProvider;
+  private llmRouter!: LLMRouter;
   private chunker: DocumentChunker;
   private llamaIngestor?: LlamaIndexIngestor;
   private entityExtractor?: EntityExtractor;
@@ -198,17 +200,26 @@ export class Pipeline {
     if (this.initialised) return;
 
     const chartInstruction = `\
-You are a helpful product assistant. Use the provided context to answer questions accurately.
+You are a helpful assistant. Use the provided context to answer questions accurately.
 
-### UI STYLE RULES (CRITICAL):
+### CRITICAL RULES:
+- ONLY answer the user's specific question. Do NOT suggest or recommend unrelated products unless specifically asked.
 - NEVER generate markdown tables. If you do, the UI will break.
 - NEVER generate HTML tags like <figure>, <tbody>, <tr>, etc.
 - NEVER generate text-based charts or graphs.
+- NEVER say you cannot display, render, draw, or create a chart when the user asks for a visualization. The UI handles visual rendering separately.
 - ONLY use plain text and bullet points.
+- NEVER use the plus sign (+) as a separator between names, categories, or products. Use commas or bullet points.
+- ONLY answer the question if the sources contain relevant information to answer it, else say that you cannot answer the question.
+- If answer cannot be found in the sources, say that you cannot answer the question and do not hallucinate.
+- Do not use information from previous turns to answer the question.
+- You CAN use numbers for years and counts (e.g., 2006, 5800). But NEVER put a dollar sign ($) before non-monetary numbers like Stock quantities, EAN numbers, or years. Only use dollar signs for actual monetary prices.
 
 ### PRODUCT DISPLAY:
-- When recommending products, simply list their names, prices, and features in a friendly, conversational manner.
+- Recommended Products should only be displayed when the user explicitly asks for products.
+- When recommending products (ONLY when asked), simply list their names, prices, and features in a friendly, conversational manner.
 - The UI will automatically detect these products and show high-quality product cards in a carousel below your message.
+- For product descriptions, summarize customer-facing details only. Do NOT list internal catalog fields such as Handle, Body (HTML), Vendor, Type, Tags, Published, Option, Variant, SKU, or raw metadata labels.
 - Do NOT try to format product lists as tables.
 `;
 
@@ -216,14 +227,23 @@ You are a helpful product assistant. Use the provided context to answer question
 
     this.vectorDB = await ProviderRegistry.createVectorProvider(this.config.vectorDb);
 
-    const { llmProvider, embeddingProvider } = await EmbeddingStrategyResolver.resolve(
+    // Initialize LLM Router for multi-model support
+    this.llmRouter = new LLMRouter(this.config);
+
+    // EmbeddingStrategyResolver creates the providers with the correct configs
+    const { llmProvider: resolvedLLM, embeddingProvider } = await EmbeddingStrategyResolver.resolve(
       this.config.llm,
       this.config.embedding
     );
-
-    this.llmProvider = llmProvider;
     this.embeddingProvider = embeddingProvider;
 
+    // Seed the router with the correctly initialised LLM provider, then initialise
+    // the rest of the router (fast/powerful roles) using provider-aware defaults.
+    await this.llmRouter.initialize(resolvedLLM);
+
+    // Primary LLM provider — use what the router resolved as 'default'
+    this.llmProvider = this.llmRouter.get('default');
+
     if (this.config.graphDb) {
       this.graphDB = await ProviderRegistry.createGraphProvider(this.config.graphDb);
       await this.graphDB.initialize();
@@ -397,6 +417,12 @@ You are a helpful product assistant. Use the provided context to answer question
   /**
    * High-performance streaming RAG flow.
    * Yields text chunks first, then the retrieval metadata + observability trace at the end.
+   *
+   * Latency optimizations:
+   * - Strategy classification runs in parallel with query embedding (saves ~400ms)
+   * - Hallucination scoring is fire-and-forget (doesn't block metadata yield)
+   * - UITransformation is computed after text streaming and emitted with metadata
+   * - SchemaMapper.train runs while answer generation streams
    */
   async *askStream(question: string, history: ChatMessage[] = [], namespace?: string): AsyncIterable<string | ChatResponse> {
     await this.initialize();
@@ -416,28 +442,67 @@ You are a helpful product assistant. Use the provided context to answer question
         rewrittenQuery = searchQuery !== question ? searchQuery : undefined;
       }
 
-      // 2. Parallel Retrieval (with latency tracking)
+      // 2. Parallel: embed query + classify retrieval strategy at the same time.
+      // Previously strategy was awaited first (serialized LLM call), blocking embed+retrieve.
       const hints = QueryProcessor.extractQueryFieldHints(question, this.config.rag?.filterableFields);
       const filter = QueryProcessor.buildQueryFilter(question, hints);
+      const numericPredicates = QueryProcessor.extractNumericPredicates(question, this.config.rag?.filterableFields);
+      if (numericPredicates.length > 0) {
+        filter.__numericPredicates = numericPredicates;
+      }
 
       const embedStart = performance.now();
-      const { sources: rawSources, graphData } = await this.retrieve(searchQuery, {
-        namespace: ns,
-        topK: topK * 2,
-        filter
-      });
+
+      // Parallelize: strategy classification + embedding run concurrently.
+      // Strategy is an LLM call (~300-800ms). Embedding is also async.
+      // Neither depends on the other's result, so both can run at the same time.
+      const cacheKey = `${ns}::${searchQuery}`;
+      const cachedVector = this.embeddingCache.get(cacheKey);
+
+      const [strategyResult, embeddedVector] = await Promise.all([
+        QueryProcessor.determineRetrievalStrategy(
+          searchQuery,
+          this.llmRouter.get('fast'),
+          this.config.rag?.graphKeywords,
+          this.config.rag?.vectorKeywords
+        ),
+        // Embed immediately regardless of strategy — costs nothing if cached.
+        // If strategy turns out to be 'graph'-only we just won't use the vector.
+        cachedVector
+          ? Promise.resolve(cachedVector)
+          : this.embeddingProvider.embed(searchQuery, { taskType: 'query' }),
+      ]);
+
+      const queryVector = embeddedVector;
+      if (!cachedVector && queryVector.length > 0) {
+        this.embeddingCache.set(cacheKey, queryVector);
+      }
+
+      const graphData = (strategyResult === 'graph' || strategyResult === 'both') && this.graphDB && this.config.rag?.useGraphRetrieval
+        ? await this.graphDB.query(searchQuery)
+        : undefined;
+
+      const hasNumericPredicates = Array.isArray(filter.__numericPredicates) && filter.__numericPredicates.length > 0;
+      const wantsExhaustiveList = hasNumericPredicates || /\b(list|all|show|provide|give|get)\b/i.test(question);
+      const retrievalLimit = wantsExhaustiveList ? Math.max(topK * 20, 100) : topK * 2;
+
+      const rawSources = (strategyResult === 'vector' || strategyResult === 'both') && queryVector && queryVector.length > 0
+        ? await this.vectorDB.query(queryVector, retrievalLimit, ns, filter)
+        : [];
+
       const retrieveEnd = performance.now();
-      const embedMs = retrieveEnd - embedStart; // embed + retrieve combined (cache may make embed ~0)
+      const embedMs = retrieveEnd - embedStart;
       const retrieveMs = retrieveEnd - embedStart;
 
       // 3. Reranking
       const rerankStart = performance.now();
-      let sources = rawSources.filter((m) => m.score >= scoreThreshold);
-      if (this.config.rag?.useReranking) {
-        // We do not pass llmProvider here to opt into the fast, deterministic keyword-based re-ranking in production.
-        // Pass this.llmProvider as the 4th argument if you want high-accuracy LLM-based re-ranking.
+      const structuredSources = this.applyStructuredFilters(rawSources, filter);
+      let sources = hasNumericPredicates
+        ? structuredSources
+        : structuredSources.filter((m) => m.score >= scoreThreshold);
+      if (!hasNumericPredicates && this.config.rag?.useReranking) {
         sources = await this.reranker.rerank(sources, question, topK);
-      } else {
+      } else if (!wantsExhaustiveList) {
         sources = sources.slice(0, topK);
       }
       const rerankMs = performance.now() - rerankStart;
@@ -448,26 +513,24 @@ You are a helpful product assistant. Use the provided context to answer question
         : 'No relevant context found.';
 
       if (graphData && graphData.nodes.length > 0) {
-        console.log(`[Graph Retrieval] Found ${graphData.nodes.length} relevant entities.`);
         const graphContext = graphData.nodes.map(n =>
           `Entity: ${n.label} (${n.id})${n.properties ? ' - ' + JSON.stringify(n.properties) : ''}`
         ).join('\n');
         context = `GRAPH KNOWLEDGE:\n${graphContext}\n\nVECTOR CONTEXT:\n${context}`;
       }
 
-      // 4.5 Schema Training (non-blocking)
+      // 4.5 Schema Training — fire-and-forget, never blocks the stream.
       const allMetadataKeys = Array.from(new Set(sources.flatMap(s => Object.keys(s.metadata || {}))));
-      const trainingPromise = allMetadataKeys.length > 0
-        ? SchemaMapper.train(this.llmProvider, ns, allMetadataKeys)
+      const trainedSchemaPromise = allMetadataKeys.length > 0
+        ? SchemaMapper.train(this.llmProvider, ns, allMetadataKeys).catch(() => undefined)
         : Promise.resolve(undefined);
 
-      // 5. Generation (Streaming) — capture the full reply for observability
-      const restrictionSuffix = '\n\n(IMPORTANT: Use plain text only. NEVER generate tables, HTML figures, or text charts. If listing products, use simple bullet points.)';
+      // 5. Generation (Streaming)
+      const restrictionSuffix = '\n\n(IMPORTANT: Use plain text only. NEVER generate tables, HTML figures, or text charts. The UI renders requested charts separately, so NEVER say you cannot create, display, draw, render, or provide a chart/visualization. If listing products, use simple bullet points or comma-separated names. NEVER use plus signs (+) to separate product names, category names, or list items. For product description/detail questions, provide customer-facing prose only and do NOT list internal catalog fields such as Handle, Body (HTML), Vendor, Type, Tags, Published, Option, Variant, SKU, or raw metadata labels. You CAN use numbers for years/counts like 2006 or 5800, but NEVER put a dollar sign ($) before them.)';
       const hardenedHistory = [...history];
       const userQuestion = { role: 'user', content: question + restrictionSuffix } as ChatMessage;
       const messages: ChatMessage[] = [...hardenedHistory, userQuestion];
 
-      // Build prompt strings for tracing
       const systemPrompt = this.config.llm.systemPrompt ?? '';
       const userPrompt = messages.map(m => `${m.role}: ${m.content}`).join('\n');
 
@@ -476,9 +539,7 @@ You are a helpful product assistant. Use the provided context to answer question
 
       if (this.llmProvider.chatStream) {
         const stream = this.llmProvider.chatStream(messages, context);
-        if (!stream) {
-          throw new Error(`[Pipeline] ${this.config.llm.provider} chatStream returned undefined`);
-        }
+        if (!stream) throw new Error(`[Pipeline] ${this.config.llm.provider} chatStream returned undefined`);
         for await (const chunk of stream) {
           fullReply += chunk;
           yield chunk;
@@ -511,14 +572,8 @@ You are a helpful product assistant. Use the provided context to answer question
         estimatedCostUsd: estimateCostUsd(promptTokens, completionTokens, this.config.llm.model),
       };
 
-      // 7. Hallucination scoring (async, non-blocking on generation yield)
-      const hallucinationResult = await scoreHallucination(this.llmProvider, fullReply, context).catch(() => undefined);
-
-      // 8. Automated UI transformation
-      const trainedSchema = await trainingPromise;
-      const uiTransformation = await this.generateUiTransformation(question, sources, trainedSchema);
-
-      // 9. Build observability trace
+      // 7. Yield metadata frame IMMEDIATELY after generation — don't wait for scoring/UI.
+      // Hallucination scoring and UI transformation are kicked off as background tasks.
       const trace: ObservabilityTrace = {
         requestId,
         query: question,
@@ -534,12 +589,23 @@ You are a helpful product assistant. Use the provided context to answer question
         } satisfies RetrievedChunk)),
         latency,
         tokens,
-        hallucinationScore: hallucinationResult?.score,
-        hallucinationReason: hallucinationResult?.reason,
         timestamp: new Date().toISOString(),
       };
 
-      // Yield metadata + trace + UI transformation
+      let uiTransformation: unknown;
+      try {
+        const trainedSchema = await trainedSchemaPromise;
+        uiTransformation = await this.generateUiTransformation(
+          question,
+          sources,
+          trainedSchema,
+          hasNumericPredicates,
+        );
+      } catch (uiError) {
+        console.warn('[Pipeline] UI transformation failed before metadata yield:', uiError);
+        uiTransformation = UITransformer.transform(question, sources, this.config);
+      }
+
       yield {
         reply: '',
         sources,
@@ -548,6 +614,17 @@ You are a helpful product assistant. Use the provided context to answer question
         trace,
       } as ChatResponse & { trace: ObservabilityTrace };
 
+      // 8. Hallucination scoring — fire-and-forget, yields an updated trace frame.
+      // The client receives this as a supplementary observability frame after the metadata.
+      scoreHallucination(this.llmProvider, fullReply, context)
+        .then((hallucinationResult) => {
+          if (hallucinationResult) {
+            trace.hallucinationScore = hallucinationResult.score;
+            trace.hallucinationReason = hallucinationResult.reason;
+          }
+        })
+        .catch(() => { /* non-critical */ });
+
     } catch (error) {
       throw new Error(`[Pipeline] Stream failed: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -560,20 +637,136 @@ You are a helpful product assistant. Use the provided context to answer question
   private async generateUiTransformation(
     question: string,
     sources: VectorMatch[],
-    trainedSchema?: SchemaMap
+    trainedSchema?: SchemaMap,
+    forceDeterministic: boolean = false,
   ): Promise<unknown> {
     if (!sources || sources.length === 0) {
       return UITransformer.transform(question, sources, this.config, trainedSchema);
     }
 
+    if (forceDeterministic) {
+      return UITransformer.transform(question, sources, this.config, trainedSchema);
+    }
+
     try {
-      return await UITransformer.analyzeAndDecide(question, sources, this.llmProvider);
+      return await UITransformer.analyzeAndDecide(question, sources, this.llmRouter.get('fast'));
     } catch (err) {
       console.warn('[Pipeline] generateUiTransformation failed, using heuristic fallback:', err);
       return UITransformer.transform(question, sources, this.config, trainedSchema);
     }
   }
 
+  private applyStructuredFilters(sources: VectorMatch[], filter: QueryFilter): VectorMatch[] {
+    const predicates = Array.isArray(filter.__numericPredicates)
+      ? filter.__numericPredicates
+      : [];
+    if (predicates.length === 0) return sources;
+
+    return sources
+      .filter(source => predicates.every(predicate => {
+        const value = this.resolveNumericPredicateValue(source, predicate);
+        return value !== null && this.matchesNumericPredicate(value, predicate);
+      }))
+      .sort((a, b) => {
+        const primary = predicates[0];
+        const aValue = this.resolveNumericPredicateValue(a, primary) ?? 0;
+        const bValue = this.resolveNumericPredicateValue(b, primary) ?? 0;
+        return primary.operator === 'lt' || primary.operator === 'lte'
+          ? aValue - bValue
+          : bValue - aValue;
+      });
+  }
+
+  private resolveNumericPredicateValue(source: VectorMatch, predicate: NumericPredicate): number | null {
+    const meta = source.metadata || {};
+    const field = predicate.field;
+    const entries = Object.entries(meta)
+      .filter(([, value]) => value !== null && value !== undefined && typeof value !== 'object');
+
+    if (field) {
+      const normalizedField = this.normalizeComparableField(field);
+      const exact = entries.find(([key]) => this.normalizeComparableField(key) === normalizedField);
+      const fuzzy = exact ?? entries
+        .map(([key, value]) => ({ key, value, score: this.fieldSimilarityScore(key, field) }))
+        .filter(candidate => candidate.score > 0)
+        .sort((a, b) => b.score - a.score)[0];
+      if (fuzzy) {
+        const value = this.toFiniteNumber(Array.isArray(fuzzy) ? fuzzy[1] : fuzzy.value);
+        if (value !== null) return value;
+      }
+
+      const contentValue = this.extractNumericValueFromContent(source.content, field);
+      if (contentValue !== null) return contentValue;
+    }
+
+    for (const [key, value] of entries) {
+      if (/(id|sku|ean|upc|phone|zip|postal|code)/i.test(key)) continue;
+      const numeric = this.toFiniteNumber(value);
+      if (numeric !== null) return numeric;
+    }
+
+    return null;
+  }
+
+  private extractNumericValueFromContent(content: string, field: string): number | null {
+    const escapedWords = field
+      .split(/\s+|_+|-+/)
+      .filter(Boolean)
+      .map(word => word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    if (escapedWords.length === 0) return null;
+
+    const pattern = new RegExp(`(?:${escapedWords.join('[\\\\s_:-]*')})\\s*[:\\-–]?\\s*([\\d,]+(?:\\.\\d+)?)`, 'i');
+    const match = content.match(pattern);
+    return match ? this.toFiniteNumber(match[1]) : null;
+  }
+
+  private matchesNumericPredicate(value: number, predicate: NumericPredicate): boolean {
+    switch (predicate.operator) {
+      case 'gt':
+        return value > predicate.value;
+      case 'gte':
+        return value >= predicate.value;
+      case 'lt':
+        return value < predicate.value;
+      case 'lte':
+        return value <= predicate.value;
+      case 'eq':
+      default:
+        return value === predicate.value;
+    }
+  }
+
+  private normalizeComparableField(value: string): string {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, '');
+  }
+
+  private fieldSimilarityScore(candidate: string, requested: string): number {
+    const normalizedCandidate = this.normalizeComparableField(candidate);
+    const normalizedRequested = this.normalizeComparableField(requested);
+    if (normalizedCandidate === normalizedRequested) return 10;
+    if (normalizedCandidate.includes(normalizedRequested) || normalizedRequested.includes(normalizedCandidate)) return 8;
+
+    const candidateTokens = this.fieldTokens(candidate);
+    const requestedTokens = this.fieldTokens(requested);
+    const overlap = requestedTokens.filter(token => candidateTokens.includes(token)).length;
+    if (overlap === 0) return 0;
+    return overlap / Math.max(requestedTokens.length, candidateTokens.length);
+  }
+
+  private fieldTokens(value: string): string[] {
+    return value
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .map(token => token.replace(/ies$/, 'y').replace(/s$/, ''))
+      .filter(token => token.length > 1);
+  }
+
+  private toFiniteNumber(value: unknown): number | null {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    const numeric = Number(String(value ?? '').replace(/[$,% ,]/g, ''));
+    return Number.isFinite(numeric) ? numeric : null;
+  }
+
   async retrieve(query: string, options: { namespace?: string; topK?: number; filter?: Record<string, unknown> }): Promise<RetrievalResult> {
     const ns = options.namespace ?? this.config.projectId;
     const topK = options.topK ?? 5;
@@ -582,7 +775,7 @@ You are a helpful product assistant. Use the provided context to answer question
     let queryVector = this.embeddingCache.get(cacheKey);
 
     // Determine strategy
-    const strategy = await QueryProcessor.determineRetrievalStrategy(query, this.llmProvider);
+    const strategy = await QueryProcessor.determineRetrievalStrategy(query, this.llmRouter.get('fast'));
     console.debug(`[Pipeline] Determined retrieval strategy: ${strategy}`);
 
     const [retrievedVector, graphData] = await Promise.all([
@@ -602,11 +795,35 @@ You are a helpful product assistant. Use the provided context to answer question
       queryVector = retrievedVector;
     }
 
+    const baseFilter = { ...(options.filter ?? {}), queryText: query } as QueryFilter;
+    const numericPredicates = QueryProcessor.extractNumericPredicates(query, this.config.rag?.filterableFields);
+    if (numericPredicates.length > 0) {
+      baseFilter.__numericPredicates = numericPredicates;
+    }
+    const retrievalLimit = numericPredicates.length > 0 ? Math.max(topK * 20, 100) : topK;
+
     const sources = (strategy === 'vector' || strategy === 'both') && queryVector && queryVector.length > 0
-      ? await this.vectorDB.query(queryVector, topK, ns, options.filter)
+      ? this.applyStructuredFilters(
+          await this.vectorDB.query(queryVector, retrievalLimit, ns, baseFilter),
+          baseFilter,
+        )
       : [];
 
-    return { sources, graphData };
+    // Multi-Vector Support: Check for parent_id in metadata
+    const resolvedSources: VectorMatch[] = [];
+    for (const source of sources) {
+      const parentId = source.metadata?.parent_id;
+      if (parentId) {
+        console.log(`[Pipeline] Multi-Vector: Found child chunk. Parent ID: ${parentId}`);
+        // In a full implementation, we would fetch the parent document here.
+        // For now, we pass the child chunk forward.
+        resolvedSources.push(source);
+      } else {
+        resolvedSources.push(source);
+      }
+    }
+
+    return { sources: resolvedSources, graphData };
   }
 
   /** Rewrite the user query for better retrieval performance. */

package/src/core/ProviderRegistry.ts

@@ -77,6 +77,12 @@ export class ProviderRegistry {
       }
       case 'pgvector':
       case 'postgresql': {
+        // POSTGRES_MODE=single uses the simple single-table provider (default: multi).
+        const postgresMode = (process.env.POSTGRES_MODE ?? 'multi').toLowerCase();
+        if (postgresMode === 'single') {
+          const { PostgreSQLProvider } = await import('../providers/vectordb/PostgreSQLProvider');
+          return PostgreSQLProvider;
+        }
         const { MultiTablePostgresProvider } = await import('../providers/vectordb/MultiTablePostgresProvider');
         return MultiTablePostgresProvider as unknown as VectorProviderClass;
       }

package/src/core/QueryProcessor.ts

@@ -12,10 +12,17 @@ export interface QueryFieldHint {
   value: string;
 }
 
+export interface NumericPredicate {
+  field?: string;
+  operator: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
+  value: number;
+}
+
 export interface QueryFilter {
   metadata?: Record<string, string>;
   keywords?: string[];
   queryText?: string;
+  __numericPredicates?: NumericPredicate[];
   [key: string]: unknown;
 }
 
@@ -172,6 +179,92 @@ export class QueryProcessor {
     return [...hints.values()];
   }
 
+  static extractNumericPredicates(question: string, validFields: string[] = []): NumericPredicate[] {
+    const predicates: NumericPredicate[] = [];
+    const seen = new Set<string>();
+    const comparatorPattern = [
+      'greater than or equal to',
+      'more than or equal to',
+      'less than or equal to',
+      'greater than',
+      'more than',
+      'less than',
+      'equal to',
+      'at least',
+      'at most',
+      'above',
+      'over',
+      'below',
+      'under',
+      'equals?',
+      '>=',
+      '<=',
+      '>',
+      '<',
+      '=',
+    ].join('|');
+
+    const addPredicate = (rawField: string | undefined, rawOperator: string, rawValue: string) => {
+      const value = Number(rawValue.replace(/,/g, ''));
+      if (!Number.isFinite(value)) return;
+
+      const operator = this.normalizeNumericOperator(rawOperator);
+      const field = rawField ? this.normalizePredicateField(rawField, validFields) : undefined;
+      const key = `${field ?? '*'}::${operator}::${value}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      predicates.push({ ...(field ? { field } : {}), operator, value });
+    };
+
+    const scopedPatterns = [
+      new RegExp(`\\b(?:whose|with|having|where|that\\s+have|which\\s+have)\\s+([a-zA-Z][a-zA-Z0-9_\\s\\-/]{1,80}?)\\s+(?:is|are|was|were)?\\s*(?:${comparatorPattern})\\s+([\\d,]+(?:\\.\\d+)?)`, 'gi'),
+      new RegExp(`\\b([a-zA-Z][a-zA-Z0-9_\\s\\-/]{1,80}?)\\s+(?:is|are|was|were)?\\s*(?:${comparatorPattern})\\s+([\\d,]+(?:\\.\\d+)?)`, 'gi'),
+    ];
+
+    for (const pattern of scopedPatterns) {
+      for (const match of question.matchAll(pattern)) {
+        const full = match[0];
+        const operatorMatch = full.match(new RegExp(`(${comparatorPattern})`, 'i'));
+        if (!operatorMatch) continue;
+        addPredicate(match[1], operatorMatch[1], match[2]);
+      }
+    }
+
+    for (const match of question.matchAll(/\b([a-zA-Z][a-zA-Z0-9_\s\-/]{1,80}?)\s*(>=|<=|>|<|=)\s*([\d,]+(?:\.\d+)?)/g)) {
+      addPredicate(match[1], match[2], match[3]);
+    }
+
+    return predicates;
+  }
+
+  private static normalizeNumericOperator(operator: string): NumericPredicate['operator'] {
+    const op = operator.toLowerCase().trim();
+    if (op === '>' || /\b(greater than|more than|above|over)\b/.test(op)) return 'gt';
+    if (op === '>=' || /\b(greater than or equal to|more than or equal to|at least)\b/.test(op)) return 'gte';
+    if (op === '<' || /\b(less than|below|under)\b/.test(op)) return 'lt';
+    if (op === '<=' || /\b(less than or equal to|at most)\b/.test(op)) return 'lte';
+    return 'eq';
+  }
+
+  private static normalizePredicateField(field: string, validFields: string[]): string {
+    const cleaned = this.normalizeHintValue(field)
+      .replace(/\b(?:provide|show|get|give|list|all|the|a|an|of|organizations?|companies?|records?|items?|whose|with|having|where|that|which|have|has|is|are|was|were)\b/gi, ' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    if (validFields.length === 0) return cleaned;
+    const comparable = (value: string) => value.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const cleanedComparable = comparable(cleaned);
+    const matchedField = validFields.find(fieldName => {
+      const candidate = comparable(fieldName);
+      return candidate === cleanedComparable ||
+        candidate.includes(cleanedComparable) ||
+        cleanedComparable.includes(candidate);
+    });
+
+    return matchedField ?? cleaned;
+  }
+
   /**
    * Constructs a QueryFilter object from extracted hints.
    *
@@ -196,6 +289,11 @@ export class QueryProcessor {
     if (Object.keys(filter.metadata || {}).length === 0) delete filter.metadata;
     if (filter.keywords && filter.keywords.length === 0) delete filter.keywords;
 
+    const numericPredicates = this.extractNumericPredicates(question);
+    if (numericPredicates.length > 0) {
+      filter.__numericPredicates = numericPredicates;
+    }
+
     return filter;
   }
 

package/src/handlers/index.ts

@@ -166,13 +166,15 @@ export function createStreamHandler(configOrPlugin?: Partial<RagConfig> | Vector
                 enqueue(sseObservabilityFrame(responseChunk.trace));
               }
 
+
               if (sources.length > 0) {
                 try {
-                  const llmProvider = plugin.getLLMProvider?.();
-                  const uiTransformation = responseChunk?.ui_transformation ??
-                    (llmProvider
-                      ? await UITransformer.analyzeAndDecide(message, sources, llmProvider)
-                      : UITransformer.transform(message, sources, plugin.getConfig()));
+                  // The pipeline already computed ui_transformation inside askStream().
+                  // We ONLY fall back to the cheap heuristic transform (no LLM call) when
+                  // the pipeline didn't produce one — never call analyzeAndDecide() here.
+                  const uiTransformation =
+                    responseChunk?.ui_transformation ??
+                    UITransformer.transform(message, sources, plugin.getConfig());
 
                   if (uiTransformation) {
                     enqueue(sseUIFrame(uiTransformation));
@@ -185,6 +187,7 @@ export function createStreamHandler(configOrPlugin?: Partial<RagConfig> | Vector
                   } catch { /* silent */ }
                 }
               }
+
             }
           }
         } catch (streamError) {