@retrivora-ai/rag-engine 1.9.2 → 1.9.6

package/src/hooks/useRagChat.ts

@@ -25,11 +25,12 @@ import { useStoredMessages } from './useStoredMessages';
 // ─── SSE Frame Parser ──────────────────────────────────────────────────────────
 
 interface SseTextFrame         { type: 'text';             text: string }
-interface SseMetaFrame         { type: 'metadata';         sources?: VectorMatch[] }
+interface SseThinkingFrame     { type: 'thinking';         text: string }
+interface SseMetaFrame         { type: 'metadata';         sources?: VectorMatch[]; thinkingMs?: number }
 interface SseErrorFrame        { type: 'error';            error: string }
 interface SseUiFrame           { type: 'ui_transformation'; data: unknown }
 interface SseObservabilityFrame { type: 'observability';   data: ObservabilityTrace }
-type SseFrame = SseTextFrame | SseMetaFrame | SseErrorFrame | SseUiFrame | SseObservabilityFrame;
+type SseFrame = SseTextFrame | SseThinkingFrame | SseMetaFrame | SseErrorFrame | SseUiFrame | SseObservabilityFrame;
 
 /**
  * Parse all complete SSE frames from a raw chunk string.
@@ -135,6 +136,8 @@ export function useRagChat(
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
         let assistantContent = '';
+        let thinkingContent = '';
+        let thinkingMs: number | undefined;
         let sources: VectorMatch[] = [];
         let uiTransformation: unknown = null;
         let trace: ObservabilityTrace | undefined;
@@ -146,14 +149,20 @@ export function useRagChat(
         // O(N) ReactMarkdown re-parses where N = number of token chunks.
         let pendingFlush = false;
         const pendingContentRef = { current: '' };
+        const pendingThinkingRef = { current: '' };
 
         const flushTextUpdate = (msgId: string) => {
           pendingFlush = false;
           const snapshot = pendingContentRef.current;
+          const thinkingSnapshot = pendingThinkingRef.current;
           setMessages((prev) =>
             prev.map((msg) =>
               msg.id === msgId
-                ? { ...msg, content: snapshot }
+                ? { 
+                    ...msg, 
+                    content: snapshot,
+                    thinking: thinkingSnapshot || undefined,
+                  }
                 : msg
             )
           );
@@ -199,8 +208,13 @@ export function useRagChat(
               pendingContentRef.current = assistantContent;
               // Schedule a batched RAF flush instead of immediate setMessages
               scheduleFlush(assistantMessageId);
+            } else if (frame.type === 'thinking' && frame.text) {
+              thinkingContent += frame.text;
+              pendingThinkingRef.current = thinkingContent;
+              scheduleFlush(assistantMessageId);
             } else if (frame.type === 'metadata') {
               sources = frame.sources ?? [];
+              thinkingMs = (frame as any).thinkingMs;
               hasNonTextFrame = true;
             } else if (frame.type === 'ui_transformation') {
               uiTransformation = frame.data;
@@ -222,6 +236,8 @@ export function useRagChat(
                   ? {
                       ...msg,
                       content: assistantContent,
+                      thinking: thinkingContent || undefined,
+                      thinkingMs: thinkingMs,
                       sources: sources.length > 0 ? sources : msg.sources,
                       uiTransformation: uiTransformation || (msg as RagMessage).uiTransformation,
                     }
@@ -235,7 +251,11 @@ export function useRagChat(
         if (buffer.trim()) {
           for (const frame of parseSseChunk(buffer)) {
             if (frame.type === 'text' && frame.text) assistantContent += frame.text;
-            else if (frame.type === 'metadata') sources = frame.sources ?? [];
+            else if (frame.type === 'thinking' && frame.text) thinkingContent += frame.text;
+            else if (frame.type === 'metadata') {
+              sources = frame.sources ?? [];
+              thinkingMs = (frame as any).thinkingMs;
+            }
             else if (frame.type === 'observability') trace = (frame as SseObservabilityFrame).data;
           }
         }
@@ -248,6 +268,8 @@ export function useRagChat(
           sources: sources.length > 0 ? sources : undefined,
           uiTransformation: uiTransformation ?? undefined,
           trace,
+          thinking: thinkingContent || undefined,
+          thinkingMs: thinkingMs,
           createdAt: new Date().toISOString(),
         };
         setMessages((prev) =>

package/src/index.ts

@@ -21,9 +21,33 @@ export { useRagChat } from './hooks/useRagChat';
 export { addSynonyms } from './utils/synonyms';
 
 // ── Types (Interfaces/Types only, no Node.js deps) ─────────────
-export type { RagConfig, VectorDBConfig, VectorDBProvider, LLMConfig, LLMProvider, EmbeddingConfig, EmbeddingProvider, UIConfig, RAGConfig } from './config/RagConfig';
+export type {
+  RagConfig,
+  UniversalRagConfig,
+  RetrievalConfig,
+  WorkflowConfig,
+  VectorDBConfig,
+  VectorDBProvider,
+  LLMConfig,
+  LLMProvider,
+  EmbeddingConfig,
+  EmbeddingProvider,
+  UIConfig,
+  RAGConfig,
+} from './config/RagConfig';
 export type { ILLMProvider, EmbedOptions } from './llm/ILLMProvider';
 export type { Chunk, ChunkOptions } from './rag/DocumentChunker';
+export type { Retrivora } from './core/Retrivora';
+export type { RetrivoraErrorCode } from './exceptions';
+export {
+  RetrivoraError,
+  ProviderNotFoundException,
+  EmbeddingFailedException,
+  RetrievalException,
+  RateLimitException,
+  ConfigurationException,
+  AuthenticationException,
+} from './exceptions';
 export type { 
   VectorMatch, 
   UpsertDocument, 

package/src/lib/plugin.ts

@@ -0,0 +1,24 @@
+/**
+ * lib/plugin.ts — Singleton VectorPlugin for this Next.js application.
+ *
+ * All API route handlers import this module to share ONE plugin instance
+ * (and therefore one pipeline + one DB connection pool) across the process.
+ *
+ * Why a singleton?
+ * - Prevents a new MongoDB/Postgres connection being opened on every request.
+ * - Ensures the LRU embedding cache is shared across all chat requests.
+ * - In serverless environments (Vercel) the module is cached per function
+ *   instance, so cold-starts initialize once and stay warm.
+ *
+ * To swap provider at runtime, change .env.local and restart the dev server.
+ */
+
+import { VectorPlugin } from '@/core/VectorPlugin';
+import { getRagConfig } from '@/config/serverConfig';
+
+// Build config once from environment variables at module load time.
+const ragConfig = getRagConfig();
+
+// Create and export the singleton.
+// VectorPlugin is lazy — it doesn't open connections until the first request.
+export const plugin = new VectorPlugin(ragConfig);

package/src/llm/LLMFactory.ts

@@ -6,6 +6,7 @@ import { OllamaProvider } from './providers/OllamaProvider';
 import { GeminiProvider } from './providers/GeminiProvider';
 import { UniversalLLMAdapter } from './providers/UniversalLLMAdapter';
 import { IProviderValidator, IProviderHealthChecker } from '../core/ProviderInterfaces';
+import { ProviderNotFoundException } from '../exceptions';
 
 interface LLMProviderStatic {
   getValidator?: () => IProviderValidator;
@@ -81,7 +82,9 @@ export class LLMFactory {
         if (llmConfig.baseUrl || (llmConfig.options as Record<string, unknown>)?.baseUrl) {
           return new UniversalLLMAdapter(llmConfig);
         }
-        throw new Error(
+        throw new ProviderNotFoundException(
+          'LLM',
+          String(llmConfig.provider),
           `[LLMFactory] Unknown provider "${llmConfig.provider}". ` +
           `Built-in providers: ${LLMFactory.listProviders().join(', ')}. ` +
           `Register a custom provider with LLMFactory.register().`

package/src/llm/providers/AnthropicProvider.ts

@@ -8,6 +8,7 @@ import { ChatMessage, ChatOptions } from '../../types';
 import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
 import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
 import { ValidationError } from '../../core/ConfigValidator';
+import { buildSystemContent } from '../utils';
 
 export class AnthropicProvider implements ILLMProvider {
   private readonly client: Anthropic;
@@ -75,63 +76,112 @@ export class AnthropicProvider implements ILLMProvider {
   }
 
   async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
-    const resolvedPrompt = options?.systemPrompt ??
+    const basePrompt =
+      options?.systemPrompt ??
       this.llmConfig.systemPrompt ??
-      `You are a helpful assistant. Use the context below to answer the user's question accurately.\n\nContext:\n${context}`;
+      'You are a helpful assistant. Use the context below to answer the user\'s question accurately.';
 
-    const system = resolvedPrompt.includes('{{context}}')
-      ? resolvedPrompt.replace('{{context}}', context)
-      : options?.systemPrompt
-        ? resolvedPrompt // per-call: context is already in the user message
-        : `${resolvedPrompt}\n\nContext:\n${context}`;
+    const system = buildSystemContent(basePrompt, context);
 
     const anthropicMessages: Anthropic.MessageParam[] = messages.map((m) => ({
       role: m.role === 'assistant' ? 'assistant' : 'user',
       content: m.content,
     }));
 
+    const isClaude37 = this.llmConfig.model.includes('claude-3-7-sonnet');
+    const isThinkingEnabled = this.llmConfig.options?.thinking === true || 
+                              this.llmConfig.options?.thinking === 'enabled' ||
+                              (isClaude37 && this.llmConfig.options?.thinking !== false);
+
+    const extraParams: any = {};
+    if (isThinkingEnabled && isClaude37) {
+      extraParams.betas = ['interleaved-thinking-2025-05-14'];
+      const maxTokens = options?.maxTokens ?? this.llmConfig.maxTokens ?? 4096;
+      const budget = Math.min(
+        typeof this.llmConfig.options?.thinkingBudget === 'number'
+          ? this.llmConfig.options?.thinkingBudget
+          : 2048,
+        maxTokens - 1
+      );
+      extraParams.thinking = {
+        type: 'enabled',
+        budget_tokens: budget,
+      };
+      extraParams.max_tokens = Math.max(maxTokens, budget + 1024);
+    }
+
     const response = await this.client.messages.create({
       model: this.llmConfig.model,
       max_tokens: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
       system,
       messages: anthropicMessages,
-    });
+      ...extraParams,
+    } as any);
 
-    const block = response.content[0];
-    return block.type === 'text' ? block.text : '';
+    let reply = '';
+    for (const block of response.content) {
+      if (block.type === 'text') {
+        reply += block.text;
+      }
+    }
+    return reply;
   }
 
   async *chatStream(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string> {
-    const resolvedPrompt = options?.systemPrompt ??
+    const basePrompt =
+      options?.systemPrompt ??
       this.llmConfig.systemPrompt ??
-      `You are a helpful assistant. Use the context below to answer the user's question accurately.\n\nContext:\n${context}`;
+      'You are a helpful assistant. Use the context below to answer the user\'s question accurately.';
 
-    const system = resolvedPrompt.includes('{{context}}')
-      ? resolvedPrompt.replace('{{context}}', context)
-      : options?.systemPrompt
-        ? resolvedPrompt
-        : `${resolvedPrompt}\n\nContext:\n${context}`;
+    const system = buildSystemContent(basePrompt, context);
 
     const anthropicMessages: Anthropic.MessageParam[] = messages.map((m) => ({
       role: m.role === 'assistant' ? 'assistant' : 'user',
       content: m.content,
     }));
 
+    const isClaude37 = this.llmConfig.model.includes('claude-3-7-sonnet');
+    const isThinkingEnabled = this.llmConfig.options?.thinking === true || 
+                              this.llmConfig.options?.thinking === 'enabled' ||
+                              (isClaude37 && this.llmConfig.options?.thinking !== false);
+
+    const extraParams: any = {};
+    if (isThinkingEnabled && isClaude37) {
+      extraParams.betas = ['interleaved-thinking-2025-05-14'];
+      const maxTokens = options?.maxTokens ?? this.llmConfig.maxTokens ?? 4096;
+      const budget = Math.min(
+        typeof this.llmConfig.options?.thinkingBudget === 'number'
+          ? this.llmConfig.options?.thinkingBudget
+          : 2048,
+        maxTokens - 1
+      );
+      extraParams.thinking = {
+        type: 'enabled',
+        budget_tokens: budget,
+      };
+      extraParams.max_tokens = Math.max(maxTokens, budget + 1024);
+    }
+
     const stream = await this.client.messages.create({
       model: this.llmConfig.model,
       max_tokens: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
       system,
       messages: anthropicMessages,
       stream: true,
-    });
+      ...extraParams,
+    } as any) as any;
 
     if (!stream) {
       throw new Error('[AnthropicProvider] messages.create stream is undefined');
     }
 
     for await (const chunk of stream) {
-      if (chunk.type === 'content_block_delta' && chunk.delta.type === 'text_delta') {
-        yield chunk.delta.text;
+      if (chunk.type === 'content_block_delta') {
+        if (chunk.delta.type === 'text_delta') {
+          yield chunk.delta.text;
+        } else if ((chunk.delta as any).type === 'thinking_delta') {
+          yield `\x00THINKING\x00${(chunk.delta as any).thinking}`;
+        }
       }
     }
   }

package/src/llm/providers/GeminiProvider.ts

@@ -20,6 +20,7 @@ import { ChatMessage, ChatOptions } from '../../types';
 import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
 import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
 import { ValidationError } from '../../core/ConfigValidator';
+import { buildSystemContent } from '../utils';
 
 const DEFAULT_EMBEDDING_MODEL = 'text-embedding-004';
 const DEFAULT_TEMPERATURE = 0.7;
@@ -165,18 +166,6 @@ export class GeminiProvider implements ILLMProvider {
     return sanitizeModel(optionsModel ?? this.embeddingConfig?.model ?? DEFAULT_EMBEDDING_MODEL);
   }
 
-  /**
-   * Build the system instruction string, inserting the RAG context either via
-   * the `{{context}}` placeholder or by appending it.
-   */
-  private buildSystemInstruction(context: string): string {
-    const base =
-      this.llmConfig.systemPrompt ??
-      `You are a helpful assistant. Answer questions based on the provided context.\n\nContext:\n${context}`;
-
-    return base.includes('{{context}}') ? base.replace('{{context}}', context) : `${base}\n\nContext:\n${context}`;
-  }
-
   /**
    * Convert ChatMessage[] to the Gemini contents format.
    *
@@ -199,9 +188,14 @@ export class GeminiProvider implements ILLMProvider {
   // -------------------------------------------------------------------------
 
   async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
+    const basePrompt =
+      options?.systemPrompt ??
+      this.llmConfig.systemPrompt ??
+      'You are a helpful assistant. Answer questions based on the provided context.';
+
     const model = this.client.getGenerativeModel({
       model: this.llmConfig.model,
-      systemInstruction: this.buildSystemInstruction(context),
+      systemInstruction: buildSystemContent(basePrompt, context),
     });
 
     const result = await model.generateContent({
@@ -217,9 +211,14 @@ export class GeminiProvider implements ILLMProvider {
   }
 
   async *chatStream(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string> {
+    const basePrompt =
+      options?.systemPrompt ??
+      this.llmConfig.systemPrompt ??
+      'You are a helpful assistant. Answer questions based on the provided context.';
+
     const model = this.client.getGenerativeModel({
       model: this.llmConfig.model,
-      systemInstruction: this.buildSystemInstruction(context),
+      systemInstruction: buildSystemContent(basePrompt, context),
     });
 
     const result = await model.generateContentStream({
@@ -309,4 +308,4 @@ export class GeminiProvider implements ILLMProvider {
       return false;
     }
   }
-  }
+}

package/src/llm/providers/OllamaProvider.ts

@@ -8,6 +8,7 @@ import { ChatMessage, ChatOptions } from '../../types';
 import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
 import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
 import { ValidationError } from '../../core/ConfigValidator';
+import { buildSystemContent } from '../utils';
 
 interface OllamaChatResponse {
   message: { content: string };
@@ -24,7 +25,8 @@ export class OllamaProvider implements ILLMProvider {
 
   constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig) {
     const baseURL = llmConfig.baseUrl ?? 'http://localhost:11434';
-    this.http = axios.create({ baseURL, timeout: 120_000 });
+    const timeout = Number(llmConfig.options?.timeout) || 300_000;
+    this.http = axios.create({ baseURL, timeout });
     this.llmConfig = llmConfig;
     this.embeddingConfig = embeddingConfig;
   }
@@ -85,7 +87,11 @@ export class OllamaProvider implements ILLMProvider {
   }
 
   async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
-    const system = this.buildSystemPrompt(context, options?.systemPrompt);
+    const basePrompt =
+      options?.systemPrompt ??
+      this.llmConfig.systemPrompt ??
+      'You are a helpful assistant. Use the provided context to answer the user\'s question.';
+    const system = buildSystemContent(basePrompt, context);
 
     const { data } = await this.http.post<OllamaChatResponse>('/api/chat', {
       model: this.llmConfig.model,
@@ -104,7 +110,11 @@ export class OllamaProvider implements ILLMProvider {
   }
 
   async *chatStream(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string> {
-    const system = this.buildSystemPrompt(context, options?.systemPrompt);
+    const basePrompt =
+      options?.systemPrompt ??
+      this.llmConfig.systemPrompt ??
+      'You are a helpful assistant. Use the provided context to answer the user\'s question.';
+    const system = buildSystemContent(basePrompt, context);
 
     const response = await this.http.post('/api/chat', {
       model: this.llmConfig.model,
@@ -159,19 +169,6 @@ export class OllamaProvider implements ILLMProvider {
     }
   }
 
-  private buildSystemPrompt(context: string, overridePrompt?: string): string {
-    if (overridePrompt) {
-      // Per-call override: use as-is (context is already embedded in user message)
-      return overridePrompt;
-    }
-    const systemPrompt =
-      this.llmConfig.systemPrompt ??
-      `You are a helpful assistant. Use the provided context to answer the user's question.\n\nContext:\n${context}`;
-
-    return systemPrompt.includes('{{context}}')
-      ? systemPrompt.replace('{{context}}', context)
-      : `${systemPrompt}\n\nContext:\n${context}`;
-  }
 
   async embed(text: string, options?: EmbedOptions): Promise<number[]> {
     const model =

package/src/llm/providers/OpenAIProvider.ts

@@ -8,6 +8,7 @@ import { ChatMessage, ChatOptions } from '../../types';
 import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
 import { IProviderValidator, IProviderHealthChecker, HealthCheckResult } from '../../core/ProviderInterfaces';
 import { ValidationError } from '../../core/ConfigValidator';
+import { buildSystemContent } from '../utils';
 
 export class OpenAIProvider implements ILLMProvider {
   private readonly client: OpenAI;
@@ -80,17 +81,14 @@ export class OpenAIProvider implements ILLMProvider {
   }
 
   async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
-    const resolvedSystemPrompt = options?.systemPrompt ??
+    const basePrompt =
+      options?.systemPrompt ??
       this.llmConfig.systemPrompt ??
-      `You are a helpful assistant. Answer questions based on the provided context.\n\nContext:\n${context}`;
+      'You are a helpful assistant. Answer questions based on the provided context.';
 
     const systemMessage: OpenAI.Chat.ChatCompletionSystemMessageParam = {
       role: 'system',
-      content: resolvedSystemPrompt.includes('{{context}}')
-        ? resolvedSystemPrompt.replace('{{context}}', context)
-        : options?.systemPrompt
-          ? resolvedSystemPrompt // per-call override: use as-is, context already in user message
-          : `${resolvedSystemPrompt}\n\nContext:\n${context}`,
+      content: buildSystemContent(basePrompt, context),
     };
 
     const formattedMessages: OpenAI.Chat.ChatCompletionMessageParam[] = [
@@ -113,17 +111,14 @@ export class OpenAIProvider implements ILLMProvider {
   }
   
   async *chatStream(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string> {
-    const resolvedSystemPrompt = options?.systemPrompt ??
+    const basePrompt =
+      options?.systemPrompt ??
       this.llmConfig.systemPrompt ??
-      `You are a helpful assistant. Answer questions based on the provided context.\n\nContext:\n${context}`;
+      'You are a helpful assistant. Answer questions based on the provided context.';
 
     const systemMessage: OpenAI.Chat.ChatCompletionSystemMessageParam = {
       role: 'system',
-      content: resolvedSystemPrompt.includes('{{context}}')
-        ? resolvedSystemPrompt.replace('{{context}}', context)
-        : options?.systemPrompt
-          ? resolvedSystemPrompt
-          : `${resolvedSystemPrompt}\n\nContext:\n${context}`,
+      content: buildSystemContent(basePrompt, context),
     };
 
     const formattedMessages: OpenAI.Chat.ChatCompletionMessageParam[] = [

package/src/llm/providers/UniversalLLMAdapter.ts

@@ -31,20 +31,20 @@ export class UniversalLLMAdapter implements ILLMProvider {
 
   constructor(config: LLMConfig | EmbeddingConfig) {
     this.model = config.model;
-    
+
     // Type narrow to extract LLM-specific fields safely
     const llmConfig = config as LLMConfig;
-    
+
     // Merge profile defaults if specified in options
     const options = (llmConfig.options as Record<string, unknown>) ?? {};
     let profile: Record<string, unknown> = {};
-    
+
     if (typeof options.profile === 'string') {
       profile = (LLM_PROFILES as Record<string, Record<string, unknown>>)[options.profile] || {};
     } else if (typeof options.profile === 'object' && options.profile !== null) {
       profile = options.profile as Record<string, unknown>;
     }
-    
+
     this.opts = { ...profile, ...(llmConfig.options ?? {}) } as UniversalLLMOptions;
     this.systemPrompt = llmConfig.systemPrompt ?? 'You are a helpful AI assistant. Use the provided context to answer the user.';
     this.maxTokens = llmConfig.maxTokens ?? 1024;
@@ -71,7 +71,7 @@ export class UniversalLLMAdapter implements ILLMProvider {
 
   async chat(messages: ChatMessage[], context?: string): Promise<string> {
     const path = this.opts.chatPath ?? '/chat/completions';
-    
+
     const formattedMessages = [
       { role: 'system', content: `${this.systemPrompt}\n\nContext:\n${context ?? 'None'}` },
       ...messages,

package/src/llm/utils.ts

@@ -0,0 +1,46 @@
+/**
+ * LLM utility helpers shared across all provider implementations.
+ *
+ * These are pure functions with no external dependencies so they can
+ * be imported by any provider without creating circular references.
+ */
+
+/**
+ * Builds the final system message content by injecting the RAG context
+ * into a system prompt using one of two strategies:
+ *
+ *  1. **Placeholder substitution** — if the prompt contains `{{context}}`,
+ *     that token is replaced with the retrieved context string.
+ *
+ *  2. **Appendage** — if there is no placeholder, the context is appended
+ *     after a separator so the LLM always receives the retrieved evidence,
+ *     regardless of whether the caller supplied a per-call `systemPrompt`
+ *     override.
+ *
+ * This function is intentionally strict: it never silently drops context.
+ * If `context` is empty or the sentinel "No relevant context found." the
+ * prompt is returned as-is so the LLM is not polluted with an empty block.
+ *
+ * @param systemPrompt - The base system prompt (from config or per-call override).
+ * @param context      - The retrieved RAG context string.
+ * @returns            - The resolved system message content ready to send.
+ */
+export function buildSystemContent(systemPrompt: string, context: string): string {
+  const noContext =
+    !context ||
+    context.trim() === '' ||
+    context.trim() === 'No relevant context found.';
+
+  // Replace {{context}} placeholder regardless of whether context is empty
+  // so the prompt is never sent with a raw placeholder token.
+  if (systemPrompt.includes('{{context}}')) {
+    return systemPrompt.replace('{{context}}', noContext ? '' : context);
+  }
+
+  // Without a placeholder: only append context when there is actual content.
+  if (noContext) {
+    return systemPrompt;
+  }
+
+  return `${systemPrompt}\n\n---\nContext:\n${context}`;
+}

package/src/providers/vectordb/MongoDBProvider.ts

@@ -153,7 +153,11 @@ export class MongoDBProvider extends BaseVectorProvider {
       if (key === 'namespace') {
         vectorSearchFilter.namespace = value;
       } else {
-        matchFilter[key] = value;
+        if (typeof value === 'string') {
+          matchFilter[key] = { $regex: new RegExp(`^${value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'i') };
+        } else {
+          matchFilter[key] = value;
+        }
       }
     }
 
@@ -191,12 +195,20 @@ export class MongoDBProvider extends BaseVectorProvider {
 
     const results = await this.collection!.aggregate(pipeline).toArray();
 
-    return (results as unknown as Array<{ _id: string; score: number; [key: string]: unknown }>).map((res) => ({
-      id: res._id,
-      content: res[this.contentKey] as string,
-      metadata: (res[this.metadataKey] as Record<string, unknown>) || {},
-      score: res.score,
-    }));
+    return (results as unknown as Array<{ _id: string; score: number; [key: string]: unknown }>).map((res) => {
+      // Atlas Vector Search returns cosine similarity mapped to [0, 1] via (1 + cos_sim) / 2.
+      // We reverse this mapping with (score * 2) - 1 to restore the standard cosine range
+      // of [-1, 1], so downstream scoreThreshold comparisons work consistently across
+      // all vector DB providers (which natively return values in [-1, 1]).
+      const normalizedScore = (res.score * 2) - 1;
+
+      return {
+        id: res._id,
+        content: res[this.contentKey] as string,
+        metadata: (res[this.metadataKey] as Record<string, unknown>) || {},
+        score: normalizedScore,
+      };
+    });
   }
 
   async delete(id: string | number, namespace?: string): Promise<void> {