@retrivora-ai/rag-engine 1.9.3 → 1.9.7

package/src/core/Pipeline.ts

@@ -2,6 +2,7 @@ import { BaseVectorProvider } from '../providers/vectordb/BaseVectorProvider';
 import { BaseGraphProvider } from '../providers/graphdb/BaseGraphProvider';
 import { ILLMProvider } from '../llm/ILLMProvider';
 import { ChatMessage } from '../types';
+import { EmbeddingFailedException } from '../exceptions';
 import { DocumentChunker, Chunk } from '../rag/DocumentChunker';
 import { EntityExtractor } from '../rag/EntityExtractor';
 import { Reranker } from '../rag/Reranker';
@@ -115,24 +116,15 @@ async function scoreHallucination(
     ? context.slice(0, maxContextChars) + '\n...[truncated]'
     : context;
 
-  const prompt = `You are an AI quality checker. Given the CONTEXT retrieved from a knowledge base and the ANSWER generated from it, rate how well-grounded the answer is.
-
-CONTEXT:
-${truncatedContext}
-
-ANSWER:
-${answer}
-
-Return ONLY a valid JSON object with no markdown fences:
-{"score": <float 0-1>, "reason": "<one sentence>"}
-
-Where score 0 = fully grounded in context, score 1 = likely hallucinated or unsupported.`;
-
   try {
     const raw = await llm.chat(
-      [{ role: 'user', content: prompt }],
+      [{ role: 'user', content: `CONTEXT:\n${truncatedContext}\n\nANSWER:\n${answer}` }],
       '',
-      { temperature: 0, maxTokens: 120 },
+      {
+        systemPrompt: 'You are an AI quality checker. Given the CONTEXT retrieved from a knowledge base and the ANSWER generated from it, rate how well-grounded the answer is. Return ONLY a valid JSON object with no markdown fences: {"score": <float 0-1>, "reason": "<one sentence>"} where score 0 = fully grounded in context, score 1 = likely hallucinated or unsupported.',
+        temperature: 0,
+        maxTokens: 120
+      },
     );
 
     const jsonMatch = raw.match(/\{[\s\S]*\}/);
@@ -223,7 +215,13 @@ You are a helpful assistant. Use the provided context to answer questions accura
 - Do NOT try to format product lists as tables.
 `;
 
-    this.config.llm.systemPrompt = chartInstruction;
+    // Merge chartInstruction with any user-supplied systemPrompt.
+    // We append rather than overwrite so plugin consumers who pass a custom
+    // systemPrompt do not have it silently replaced.
+    const userPromptPrefix = this.config.llm.systemPrompt
+      ? `${this.config.llm.systemPrompt}\n\n`
+      : '';
+    this.config.llm.systemPrompt = `${userPromptPrefix}${chartInstruction}`;
 
     this.vectorDB = await ProviderRegistry.createVectorProvider(this.config.vectorDb);
 
@@ -330,7 +328,7 @@ You are a helpful assistant. Use the provided context to answer questions accura
     );
 
     if (vectors.length !== chunks.length) {
-      throw new Error(
+      throw new EmbeddingFailedException(
         `[Pipeline] Embedding mismatch: got ${vectors.length} vectors for ${chunks.length} chunks. ` +
         `Check embedding provider logs for individual chunk failures.`
       );
@@ -431,7 +429,9 @@ You are a helpful assistant. Use the provided context to answer questions accura
     await this.initialize();
     const ns = namespace ?? this.config.projectId;
     const topK = this.config.rag?.topK ?? 5;
-    const scoreThreshold = this.config.rag?.scoreThreshold ?? 0.0;
+    // Default score threshold of 0.3 filters random matches while keeping
+    // genuinely relevant chunks. Users can override via rag.scoreThreshold.
+    const scoreThreshold = this.config.rag?.scoreThreshold ?? 0.3;
     const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     const requestStart = performance.now();
 
@@ -462,10 +462,11 @@ You are a helpful assistant. Use the provided context to answer questions accura
       const cacheKey = `${ns}::${searchQuery}`;
       const cachedVector = this.embeddingCache.get(cacheKey);
 
+      const useGraph = this.graphDB && this.config.rag?.useGraphRetrieval;
       const [strategyResult, embeddedVector] = await Promise.all([
         QueryProcessor.determineRetrievalStrategy(
           searchQuery,
-          this.llmRouter.get('fast'),
+          useGraph ? this.llmRouter.get('fast') : undefined,
           this.config.rag?.graphKeywords,
           this.config.rag?.vectorKeywords
         ),
@@ -546,48 +547,186 @@ You are a helpful assistant. Use the provided context to answer questions accura
         context = `GRAPH KNOWLEDGE:\n${graphContext}\n\nVECTOR CONTEXT:\n${context}`;
       }
 
-      // 4.5 Schema Training — fire-and-forget, never blocks the stream.
+      // 4.5 Schema Training — true fire-and-forget, never gates anything.
       const allMetadataKeys = Array.from(new Set(sources.flatMap(s => Object.keys(s.metadata || {}))));
-      const trainedSchemaPromise = allMetadataKeys.length > 0
-        ? SchemaMapper.train(this.llmProvider, ns, allMetadataKeys).catch(() => undefined)
-        : Promise.resolve(undefined);
-
-      // 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);
-      });
+      const cachedSchema = allMetadataKeys.length > 0
+        ? SchemaMapper.getCached(ns, allMetadataKeys)
+        : undefined;
+
+      // Kick off schema training in the background — don't await it before starting UI transform.
+      // The next request will benefit from the trained schema via the cache.
+      if (allMetadataKeys.length > 0 && !cachedSchema) {
+        SchemaMapper.train(this.llmProvider, ns, allMetadataKeys).catch(() => { /* non-critical */ });
+      }
+
+      // 4.6 Start UI Transformation concurrently with generation.
+      // For product queries: use the fast heuristic immediately — no LLM call needed.
+      // For analytics queries: fire analyzeAndDecide() in parallel with text streaming.
+      const isProductQ = UITransformer.isProductQueryPublic(question);
+      const uiTransformationPromise = isProductQ
+        // Product carousel: pure heuristic, zero LLM latency
+        ? Promise.resolve(
+            UITransformer.transform(question, sources, this.config, cachedSchema,
+              { visualizationHint: 'product_browse', recommendedChart: 'text', filterInStockOnly: false, wantsExplicitTable: false, isTemporal: false, isComparison: false, language: 'en' }
+            )
+          )
+        : this.generateUiTransformation(
+            question,
+            sources,
+            cachedSchema,
+            hasNumericPredicates,
+          ).catch(uiError => {
+            console.warn('[Pipeline] UI transformation failed concurrently:', uiError);
+            return UITransformer.transform(question, sources, this.config, cachedSchema);
+          });
 
       // 5. Generation (Streaming)
+      // Start hallucination scoring as a background promise BEFORE streaming
+      // so that the score runs concurrently with text delivery to the client.
+      // We await it together with uiTransformationPromise (see step 7) so the
+      // metadata frame is never yielded until the score is resolved — no
+      // post-yield mutation required.
+      let hallucinationScoringPromise: Promise<{ score: number; reason: string } | undefined> =
+        Promise.resolve(undefined);
+
       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 isClaude37 = this.config.llm.model.includes('claude-3-7-sonnet');
+      const isNativeThinking = isClaude37 && (this.config.llm.options?.thinking === true || this.config.llm.options?.thinking === 'enabled' || this.config.llm.options?.thinking !== false);
+      
+      const modelNameLower = this.config.llm.model.toLowerCase();
+      const isReasoningModel = modelNameLower.includes('-r1') || modelNameLower.includes('deepseek-r1') || modelNameLower.includes('reasoning') || modelNameLower.includes('thinking');
+      const isSimulatedThinking = !isNativeThinking && (
+        this.config.llm.options?.thinking === true || 
+        this.config.llm.options?.thinking === 'enabled' ||
+        (isReasoningModel && this.config.llm.options?.thinking !== false)
+      );
+
+      let finalRestrictionSuffix = restrictionSuffix;
+      if (isSimulatedThinking) {
+        finalRestrictionSuffix += '\n\n(IMPORTANT: You must think step-by-step before answering. Write your thinking process inside a `<think>...</think>` block. Write the `<think>` block first, then follow it with your final response. Keep the thinking process thorough and detailed. Example: `<think>Thinking details here...</think>Final answer text here.`)';
+      }
+
       const hardenedHistory = [...history];
-      const userQuestion = { role: 'user', content: question + restrictionSuffix } as ChatMessage;
+      const userQuestion = { role: 'user', content: question + finalRestrictionSuffix } as ChatMessage;
       const messages: ChatMessage[] = [...hardenedHistory, userQuestion];
 
       const systemPrompt = this.config.llm.systemPrompt ?? '';
       const userPrompt = messages.map(m => `${m.role}: ${m.content}`).join('\n');
 
       let fullReply = '';
+      let thinkingText = '';
+      let thinkingStartMs = performance.now();
+      let thinkingDurationMs = 0;
       const generateStart = performance.now();
 
       if (this.llmProvider.chatStream) {
         const stream = this.llmProvider.chatStream(messages, context);
         if (!stream) throw new Error(`[Pipeline] ${this.config.llm.provider} chatStream returned undefined`);
+        
+        let inThinking = false;
+        let textBuffer = '';
+
         for await (const chunk of stream) {
-          fullReply += chunk;
-          yield chunk;
+          // 1. Native Anthropic thinking
+          if (chunk.startsWith('\x00THINKING\x00')) {
+            const thinkingDelta = chunk.slice('\x00THINKING\x00'.length);
+            thinkingText += thinkingDelta;
+            thinkingDurationMs = performance.now() - thinkingStartMs;
+            yield { type: 'thinking', text: thinkingDelta } as any;
+            continue;
+          }
+
+          // 2. Simulated thinking tag parsing
+          if (isSimulatedThinking) {
+            textBuffer += chunk;
+            while (textBuffer.length > 0) {
+              if (!inThinking) {
+                const thinkIndex = textBuffer.indexOf('<think>');
+                if (thinkIndex !== -1) {
+                  const before = textBuffer.slice(0, thinkIndex);
+                  if (before) {
+                    fullReply += before;
+                    yield before;
+                  }
+                  inThinking = true;
+                  thinkingStartMs = performance.now();
+                  textBuffer = textBuffer.slice(thinkIndex + '<think>'.length);
+                } else {
+                  const maxSafeLength = textBuffer.length - '<think>'.length;
+                  if (maxSafeLength > 0) {
+                    const safeText = textBuffer.slice(0, maxSafeLength);
+                    fullReply += safeText;
+                    yield safeText;
+                    textBuffer = textBuffer.slice(maxSafeLength);
+                  }
+                  break;
+                }
+              } else {
+                const endThinkIndex = textBuffer.indexOf('</think>');
+                if (endThinkIndex !== -1) {
+                  const thinkingDelta = textBuffer.slice(0, endThinkIndex);
+                  if (thinkingDelta) {
+                    thinkingText += thinkingDelta;
+                    thinkingDurationMs = performance.now() - thinkingStartMs;
+                    yield { type: 'thinking', text: thinkingDelta } as any;
+                  }
+                  inThinking = false;
+                  textBuffer = textBuffer.slice(endThinkIndex + '</think>'.length);
+                } else {
+                  const maxSafeLength = textBuffer.length - '</think>'.length;
+                  if (maxSafeLength > 0) {
+                    const thinkingDelta = textBuffer.slice(0, maxSafeLength);
+                    thinkingText += thinkingDelta;
+                    thinkingDurationMs = performance.now() - thinkingStartMs;
+                    yield { type: 'thinking', text: thinkingDelta } as any;
+                    textBuffer = textBuffer.slice(maxSafeLength);
+                  }
+                  break;
+                }
+              }
+            }
+          } else {
+            fullReply += chunk;
+            yield chunk;
+          }
+        }
+
+        // Flush any remaining buffer
+        if (isSimulatedThinking && textBuffer.length > 0) {
+          if (inThinking) {
+            thinkingText += textBuffer;
+            yield { type: 'thinking', text: textBuffer } as any;
+          } else {
+            fullReply += textBuffer;
+            yield textBuffer;
+          }
         }
       } else {
         const reply = await this.llmProvider.chat(messages, context);
-        fullReply = reply;
-        yield reply;
+        if (isSimulatedThinking) {
+          const thinkStart = reply.indexOf('<think>');
+          const thinkEnd = reply.indexOf('</think>');
+          if (thinkStart !== -1 && thinkEnd !== -1 && thinkEnd > thinkStart) {
+            thinkingText = reply.slice(thinkStart + '<think>'.length, thinkEnd);
+            fullReply = reply.slice(0, thinkStart) + reply.slice(thinkEnd + '</think>'.length);
+            thinkingDurationMs = 100;
+          } else {
+            fullReply = reply;
+          }
+        } else {
+          fullReply = reply;
+        }
+        yield fullReply;
+      }
+
+      // Kick off hallucination scoring now that we have the full reply.
+      // It runs in parallel with the remaining post-processing below.
+      const runHallucination = this.config.llm.options?.hallucinationScoring === true ||
+                              (this.config.llm.provider !== 'ollama' && this.config.llm.options?.hallucinationScoring !== false);
+      if (runHallucination) {
+        hallucinationScoringPromise = scoreHallucination(this.llmProvider, fullReply, context)
+          .catch(() => undefined);
       }
 
       const generateMs = performance.now() - generateStart;
@@ -612,14 +751,20 @@ You are a helpful assistant. Use the provided context to answer questions accura
         estimatedCostUsd: estimateCostUsd(promptTokens, completionTokens, this.config.llm.model),
       };
 
-      // 7. Yield metadata frame IMMEDIATELY after generation — don't wait for scoring/UI.
-      // Hallucination scoring and UI transformation are kicked off as background tasks.
+      // 7. Await both UI transformation and hallucination score concurrently
+      // before yielding the metadata frame. This guarantees the trace is always
+      // complete when the consumer receives it — no post-yield mutation needed.
+      const [uiTransformation, hallucinationResult] = await Promise.all([
+        uiTransformationPromise,
+        hallucinationScoringPromise,
+      ]);
+
       const trace: ObservabilityTrace = {
         requestId,
         query: question,
         rewrittenQuery,
         systemPrompt,
-        userPrompt: question + restrictionSuffix,
+        userPrompt: question + finalRestrictionSuffix,
         chunks: sources.map((s) => ({
           id: s.id,
           score: s.score,
@@ -630,28 +775,22 @@ You are a helpful assistant. Use the provided context to answer questions accura
         latency,
         tokens,
         timestamp: new Date().toISOString(),
+        // Hallucination score is now always present when available
+        ...(hallucinationResult ? {
+          hallucinationScore: hallucinationResult.score,
+          hallucinationReason: hallucinationResult.reason,
+        } : {}),
       };
 
-      const uiTransformation = await uiTransformationPromise;
-
       yield {
         reply: '',
         sources,
         graphData,
         ui_transformation: uiTransformation,
         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 */ });
+        thinking: thinkingText || undefined,
+        thinkingMs: thinkingDurationMs > 0 ? Math.round(thinkingDurationMs) : undefined,
+      } as ChatResponse & { trace: ObservabilityTrace; thinking?: string; thinkingMs?: number };
 
     } catch (error) {
       throw new Error(`[Pipeline] Stream failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -665,22 +804,31 @@ You are a helpful assistant. Use the provided context to answer questions accura
   private async generateUiTransformation(
     question: string,
     sources: VectorMatch[],
-    trainedSchema?: SchemaMap,
+    cachedSchema?: SchemaMap,
     forceDeterministic: boolean = false,
   ): Promise<unknown> {
     if (!sources || sources.length === 0) {
-      return UITransformer.transform(question, sources, this.config, trainedSchema);
+      return UITransformer.transform(question, sources, this.config, cachedSchema);
+    }
+
+    // Fast heuristic for product queries — skip both LLM calls entirely.
+    if (UITransformer.isProductQueryPublic(question)) {
+      return UITransformer.transform(question, sources, this.config, cachedSchema,
+        { visualizationHint: 'product_browse', recommendedChart: 'text', filterInStockOnly: false, wantsExplicitTable: false, isTemporal: false, isComparison: false, language: 'en' }
+      );
     }
 
-    if (forceDeterministic) {
-      return UITransformer.transform(question, sources, this.config, trainedSchema);
+    const isLocalProvider = this.config.llm.provider === 'ollama';
+    const disableLlmUiTransform = this.config.llm.options?.disableLlmUiTransform === true;
+    if (forceDeterministic || isLocalProvider || disableLlmUiTransform) {
+      return UITransformer.transform(question, sources, this.config, cachedSchema);
     }
 
     try {
       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);
+      return UITransformer.transform(question, sources, this.config, cachedSchema);
     }
   }
 
@@ -803,7 +951,11 @@ You are a helpful assistant. Use the provided context to answer questions accura
     let queryVector = this.embeddingCache.get(cacheKey);
 
     // Determine strategy
-    const strategy = await QueryProcessor.determineRetrievalStrategy(query, this.llmRouter.get('fast'));
+    const useGraph = this.graphDB && this.config.rag?.useGraphRetrieval;
+    const strategy = await QueryProcessor.determineRetrievalStrategy(
+      query,
+      useGraph ? this.llmRouter.get('fast') : undefined
+    );
     console.debug(`[Pipeline] Determined retrieval strategy: ${strategy}`);
 
     const [retrievedVector, graphData] = await Promise.all([
@@ -868,10 +1020,13 @@ Optimized Search Query:`;
 
     const rewrite = await this.llmProvider.chat(
       [
-        { role: 'system', content: 'You are an assistant that optimizes search queries for RAG systems.' },
         { role: 'user', content: prompt }
       ],
-      ''
+      '',
+      {
+        systemPrompt: 'You are an assistant that optimizes search queries for RAG systems. Focus on extracting the core intent and entities. Do not answer the question, just rewrite it.',
+        temperature: 0
+      }
     );
 
     return rewrite.trim() || question;
@@ -901,10 +1056,13 @@ Suggestions:`;
 
       const response = await this.llmProvider.chat(
         [
-          { role: 'system', content: 'You are a helpful assistant that generates search suggestions.' },
           { role: 'user', content: prompt }
         ],
-        ''
+        '',
+        {
+          systemPrompt: 'You are a helpful assistant that generates search suggestions based on the provided snippets. Focus on questions that can be answered by the context, keep each under 10 words, and return ONLY a JSON array of strings.',
+          temperature: 0
+        }
       );
 
       const match = response.match(/\[[\s\S]*\]/);

package/src/core/ProviderRegistry.ts

@@ -4,12 +4,13 @@ import { VectorDBConfig, GraphDBConfig, LLMConfig, EmbeddingConfig } from '../co
 import { LLMFactory } from '../llm/LLMFactory';
 import { ILLMProvider } from '../llm/ILLMProvider';
 import { IProviderValidator, IProviderHealthChecker } from './ProviderInterfaces';
+import { ProviderNotFoundException } from '../exceptions';
 
 /**
  * ProviderRegistry — dynamic provider loader for Vector DBs and LLMs.
  */
 type VectorProviderClass = {
-  new (config: VectorDBConfig): BaseVectorProvider;
+  new(config: VectorDBConfig): BaseVectorProvider;
   getValidator?: () => IProviderValidator;
   getHealthChecker?: () => IProviderHealthChecker;
 };
@@ -19,10 +20,10 @@ type GraphProviderClass = new (config: GraphDBConfig) => BaseGraphProvider;
 export class ProviderRegistry {
   private static vectorProviders: Record<string, VectorProviderClass> = {};
   private static graphProviders: Record<string, GraphProviderClass> = {};
-  
+
   private static vectorValidators: Record<string, IProviderValidator> = {};
   private static vectorHealthCheckers: Record<string, IProviderHealthChecker> = {};
-  
+
   private static llmValidators: Record<string, IProviderValidator> = {};
   private static llmHealthCheckers: Record<string, IProviderHealthChecker> = {};
 
@@ -38,7 +39,7 @@ export class ProviderRegistry {
 
   static async getVectorValidator(provider: string): Promise<IProviderValidator | null> {
     if (this.vectorValidators[provider]) return this.vectorValidators[provider];
-    
+
     // Try to load built-in validator
     try {
       const providerClass = await this.loadVectorProviderClass(provider);
@@ -54,7 +55,7 @@ export class ProviderRegistry {
 
   static async getVectorHealthChecker(provider: string): Promise<IProviderHealthChecker | null> {
     if (this.vectorHealthCheckers[provider]) return this.vectorHealthCheckers[provider];
-    
+
     try {
       const providerClass = await this.loadVectorProviderClass(provider);
       if (providerClass.getHealthChecker) {
@@ -116,7 +117,7 @@ export class ProviderRegistry {
         return UniversalVectorProvider;
       }
       default:
-        throw new Error(`Unsupported vector provider: ${provider}`);
+        throw new ProviderNotFoundException('vector', provider);
     }
   }
 
@@ -137,11 +138,19 @@ export class ProviderRegistry {
         return new SimpleGraphProvider(config);
       }
       default:
-        throw new Error(`Unsupported graph provider: ${provider}`);
+        throw new ProviderNotFoundException('graph', provider);
     }
   }
 
   static createLLMProvider(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider {
     return LLMFactory.create(llmConfig, embeddingConfig);
   }
+
+  static registerLLMProvider(name: string, factory: (config: LLMConfig) => ILLMProvider): void {
+    LLMFactory.register(name, factory);
+  }
+
+  static createEmbeddingProvider(embeddingConfig: EmbeddingConfig): ILLMProvider {
+    return LLMFactory.createEmbeddingProvider(embeddingConfig);
+  }
 }

package/src/core/QueryProcessor.ts

@@ -72,6 +72,30 @@ export class QueryProcessor {
       }
     };
 
+    const activeValidFields = validFields.length > 0
+      ? validFields
+      : ['brand', 'category', 'price', 'rating', 'stock', 'stock_quantity', 'status', 'name', 'title'];
+
+    const resolveValidField = (fieldStr: string): string | null => {
+      const cleaned = this.normalizeHintValue(fieldStr)
+        .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();
+      
+      const comparable = (v: string) => v.toLowerCase().replace(/[^a-z0-9]/g, '');
+      const cleanedComparable = comparable(cleaned);
+      if (!cleanedComparable) return null;
+
+      const matchedField = activeValidFields.find(fieldName => {
+        const candidate = comparable(fieldName);
+        return candidate === cleanedComparable ||
+          candidate.includes(cleanedComparable) ||
+          cleanedComparable.includes(candidate);
+      });
+
+      return matchedField ?? null;
+    };
+
     // 1. Quoted phrases
     for (const match of question.matchAll(/["']([^"']{2,100})["']/g)) {
       addHint(match[1]);
@@ -105,7 +129,13 @@ export class QueryProcessor {
       const field = match[1];
       const value = match[2];
       if (field && !this.isLikelyPromptPhrase(field)) {
-        addHint(value, field);
+        const resolvedField = resolveValidField(field);
+        if (resolvedField) {
+          addHint(value, resolvedField);
+        } else {
+          addHint(value);
+          addHint(field);
+        }
       }
     }
 
@@ -161,13 +191,17 @@ export class QueryProcessor {
 
     for (const pattern of fieldValuePatterns) {
       for (const match of question.matchAll(pattern)) {
-        const field = this.normalizeHintValue(match[1] ?? '');
+        const field = match[1] ?? '';
         const value = match[2] ?? '';
 
-        if (field && !this.isLikelyPromptPhrase(field)) {
-          addHint(value, field);
+        const resolvedField = resolveValidField(field);
+        if (resolvedField) {
+          addHint(value, resolvedField);
         } else {
           addHint(value);
+          if (field && !this.isLikelyPromptPhrase(field)) {
+            addHint(field);
+          }
         }
       }
     }

package/src/core/Retrivora.ts

@@ -0,0 +1,91 @@
+import { RagConfig, RetrievalConfig, UniversalRagConfig } from '../config/RagConfig';
+import { ChatMessage, ChatResponse, IngestDocument } from '../types';
+import { ConfigResolver } from './ConfigResolver';
+import { ConfigValidator } from './ConfigValidator';
+import { Pipeline } from './Pipeline';
+import { wrapError, RetrivoraErrorCode } from '../exceptions';
+
+/**
+ * Public SDK facade matching the prompt-level Retrivora API.
+ *
+ * It keeps provider details behind configuration and delegates execution to the
+ * existing Pipeline implementation.
+ */
+export class Retrivora {
+  private readonly pipeline: Pipeline;
+  readonly config: RagConfig;
+
+  constructor(config?: UniversalRagConfig) {
+    this.config = ConfigResolver.resolveUniversal(config);
+    this.pipeline = new Pipeline(this.config);
+  }
+
+  async initialize(): Promise<void> {
+    try {
+      await ConfigValidator.validateAndThrow(this.config);
+    } catch (err) {
+      throw wrapError(err, 'CONFIGURATION_ERROR');
+    }
+    try {
+      await this.pipeline.initialize();
+    } catch (err) {
+      throw wrapError(err, 'AUTHENTICATION_ERROR');
+    }
+  }
+
+  async ingest(
+    documents: IngestDocument[],
+    namespace?: string,
+  ): Promise<Array<{ docId: string | number; chunksIngested: number }>> {
+    try {
+      return await this.pipeline.ingest(documents, namespace);
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
+  }
+
+  async ask(question: string, history: ChatMessage[] = [], namespace?: string): Promise<ChatResponse> {
+    try {
+      return await this.pipeline.ask(question, history, namespace);
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
+  }
+
+  async *askStream(
+    question: string,
+    history: ChatMessage[] = [],
+    namespace?: string,
+  ): AsyncIterable<string | ChatResponse> {
+    try {
+      const stream = this.pipeline.askStream(question, history, namespace);
+      for await (const chunk of stream) {
+        yield chunk;
+      }
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
+  }
+
+  getPipeline(): Pipeline {
+    return this.pipeline;
+  }
+}
+
+export type { RetrievalConfig, UniversalRagConfig };
+