@retrivora-ai/rag-engine 1.9.0 → 1.9.2

package/src/core/LLMRouter.ts

@@ -0,0 +1,79 @@
+import { ILLMProvider } from '../llm/ILLMProvider';
+import { LLMFactory } from '../llm/LLMFactory';
+import { RagConfig, LLMConfig } from '../config/RagConfig';
+
+/**
+ * Provider-aware fast model defaults.
+ * Maps an LLM provider name to a sensible lightweight model for routing tasks.
+ */
+const FAST_MODEL_DEFAULTS: Record<string, string> = {
+  openai: 'gpt-4o-mini',
+  gemini: 'gemini-2.0-flash',
+  anthropic: 'claude-3-haiku-20240307',
+  ollama: '', // Ollama has no universal lightweight default — reuse main model
+  rest: '',
+  universal_rest: '',
+  custom: '',
+};
+
+/**
+ * LLMRouter — manages multiple LLM instances for different task roles.
+ *
+ * Roles:
+ *  - 'default' : the main configured LLM (used for chat generation)
+ *  - 'fast'    : a lightweight model for classification/routing tasks (UI decisions, strategy)
+ *  - 'powerful': reserved for future use (defaults to main model)
+ *
+ * Provider-agnostic: will never mix provider SDKs (e.g., won't set a Gemini model name on an
+ * OpenAI client). If FAST_LLM_MODEL is set in the environment it is applied to the *same* provider.
+ */
+export class LLMRouter {
+  private models = new Map<string, ILLMProvider>();
+
+  constructor(private config: RagConfig) {}
+
+  /**
+   * Initialize all LLM roles.
+   *
+   * @param prebuiltDefault - optional pre-built provider (from EmbeddingStrategyResolver).
+   *   When provided it is used directly as the 'default' role without re-constructing.
+   */
+  async initialize(prebuiltDefault?: ILLMProvider): Promise<void> {
+    // 1. Seed 'default' — prefer the pre-built provider so we don't double-construct it.
+    const defaultModel = prebuiltDefault ?? LLMFactory.create(this.config.llm, this.config.embedding);
+    this.models.set('default', defaultModel);
+
+    // 2. Resolve 'fast' model — always stays on the SAME provider to avoid SDK mismatches.
+    const envFastModel = process.env.FAST_LLM_MODEL;
+    const providerFastDefault = FAST_MODEL_DEFAULTS[this.config.llm.provider] ?? '';
+
+    const fastModelName = envFastModel || providerFastDefault;
+
+    if (fastModelName && fastModelName !== this.config.llm.model) {
+      console.log(`[LLMRouter] Fast role → provider="${this.config.llm.provider}" model="${fastModelName}"`);
+      const fastConfig: LLMConfig = {
+        ...this.config.llm,
+        model: fastModelName,
+      };
+      this.models.set('fast', LLMFactory.create(fastConfig, this.config.embedding));
+    } else {
+      console.log(`[LLMRouter] Fast role → reusing default model (no lightweight alternative configured).`);
+      this.models.set('fast', defaultModel);
+    }
+
+    // 3. 'powerful' defaults to main model (reserved for future use)
+    this.models.set('powerful', defaultModel);
+  }
+
+  /**
+   * Retrieve a model provider by its task role.
+   * Falls back to 'default' if the requested role is not registered.
+   */
+  get(role: 'fast' | 'powerful' | 'default'): ILLMProvider {
+    const provider = this.models.get(role) ?? this.models.get('default');
+    if (!provider) {
+      throw new Error(`[LLMRouter] No provider registered for role: "${role}". Did you call initialize()?`);
+    }
+    return provider;
+  }
+}

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();
@@ -334,7 +354,10 @@ You are a helpful product assistant. Use the provided context to answer question
     );
 
     if (upsertResult.errors.length > 0) {
-      console.warn(`[Pipeline] Ingestion: ${upsertResult.errors.length} batches failed`);
+      console.warn(`[Pipeline] Ingestion: ${upsertResult.errors.length} batches failed. Error details:`);
+      upsertResult.errors.forEach((err, idx) => {
+        console.warn(`  Batch ${idx + 1} Error: ${err.error.message || String(err.error)}`);
+      });
     }
 
     return upsertResult.totalProcessed;
@@ -397,6 +420,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,58 +445,131 @@ 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 hasMetadataFilter = filter.metadata && Object.keys(filter.metadata).length > 0;
+      const hasNumericPredicates = Array.isArray(filter.__numericPredicates) && filter.__numericPredicates.length > 0;
+      const wantsExhaustiveList = hasNumericPredicates || hasMetadataFilter || /\b(list|all|show|provide|give|get|browse|find|search|display)\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.
-        sources = await this.reranker.rerank(sources, question, topK);
-      } else {
-        sources = sources.slice(0, topK);
+      const structuredSources = this.applyStructuredFilters(rawSources, filter);
+      let fullSources = hasNumericPredicates
+        ? structuredSources
+        : structuredSources.filter((m) => m.score >= scoreThreshold);
+      const rerankLimit = wantsExhaustiveList ? retrievalLimit : topK;
+      if (!hasNumericPredicates && this.config.rag?.useReranking) {
+        fullSources = await this.reranker.rerank(fullSources, question, rerankLimit);
+      } else if (!wantsExhaustiveList) {
+        fullSources = fullSources.slice(0, topK);
       }
       const rerankMs = performance.now() - rerankStart;
 
-      // 4. Context Augmentation
-      let context = sources.length
-        ? sources.map((m, i) => `[Source ${i + 1}]\n${m.content}`).join('\n\n---\n\n')
+      // 4. Context Augmentation - Review all retrieved/reranked sources for full comprehension
+      let context = fullSources.length
+        ? fullSources.map((m, i) => `[Source ${i + 1}]\n${m.content}`).join('\n\n---\n\n')
         : 'No relevant context found.';
 
+      // Count the records of relevant sources to pass into the slice dynamically
+      let displayCount = 15; // default fallback
+
+      if (hasMetadataFilter) {
+        // If a metadata filter matches (e.g. brand, category), all of those matches are highly relevant
+        displayCount = fullSources.length;
+      } else {
+        // For general semantic queries, count the number of matches meeting high relevance threshold
+        const highlyRelevant = fullSources.filter(m => m.score >= 0.4);
+        displayCount = Math.max(highlyRelevant.length, topK);
+        // Cap non-metadata semantic searches to a maximum of 15 to keep the UI clean
+        if (displayCount > 15) {
+          displayCount = 15;
+        }
+      }
+
+      // Ensure they are sorted from highest to lowest score, then slice using our dynamic count
+      const sources = [...fullSources]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, displayCount);
+
       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.)';
+      // 4.6 Start UI Transformation concurrently with generation to drastically reduce latency
+      const uiTransformationPromise = trainedSchemaPromise.then(trainedSchema =>
+        this.generateUiTransformation(
+          question,
+          sources,
+          trainedSchema,
+          hasNumericPredicates,
+        )
+      ).catch(uiError => {
+        console.warn('[Pipeline] UI transformation failed concurrently:', uiError);
+        return UITransformer.transform(question, sources, this.config);
+      });
+
+      // 5. Generation (Streaming)
+      const restrictionSuffix = '\n\n(IMPORTANT: Format your response beautifully using rich Markdown! Use bolding for emphasis, headings (##) for structure, bullet points for lists, and proper line breaks between paragraphs to make it highly readable. However, NEVER generate Markdown 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 markdown 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 +578,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 +611,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 +628,11 @@ 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
+      const uiTransformation = await uiTransformationPromise;
+
       yield {
         reply: '',
         sources,
@@ -548,6 +641,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 +664,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 +802,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 +822,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;
       }