@retrivora-ai/rag-engine 1.9.3 → 1.9.7

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;
+        }
       }
     }
 
@@ -192,9 +196,10 @@ 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) => {
-      // Normalize MongoDB's vectorSearchScore (which is shifted to [0, 1] e.g. (1+cos)/2)
-      // back to the standard [-1, 1] cosine space. This ensures the global relevance 
-      // threshold (e.g. 0.4) properly filters out random orthogonal matches.
+      // 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 {

package/src/providers/vectordb/MultiTablePostgresProvider.ts

@@ -72,6 +72,11 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
         ON ${this.uploadTable}
         USING hnsw (embedding vector_cosine_ops)
       `);
+      await client.query(`
+        CREATE INDEX IF NOT EXISTS "${this.uploadTable}_fts_idx"
+        ON "${this.uploadTable}"
+        USING gin (to_tsvector('english', content))
+      `);
 
       const res = await client.query(`
         SELECT table_name 
@@ -158,6 +163,11 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
           ON "${tableName}"
           USING hnsw (embedding vector_cosine_ops)
         `);
+        await client.query(`
+          CREATE INDEX IF NOT EXISTS "${tableName}_fts_idx"
+          ON "${tableName}"
+          USING gin (to_tsvector('english', content))
+        `);
         
         // Ensure this new table is added to our search scope
         if (!this.tables.includes(tableName)) {
@@ -297,9 +307,12 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
               const synonyms = FIELD_SYNONYMS[key] ?? [];
               const keysToCheck = [key, ...synonyms];
 
-              // Map each candidate key to LOWER(metadata->>'candidate')
-              const coalesceExprs = keysToCheck.map(k => `LOWER(metadata->>'${k}')`);
-              return `COALESCE(${coalesceExprs.join(', ')}) = LOWER($${paramIdx})`;
+              // Map each candidate key to LOWER(coalesce(metadata->>'key', to_jsonb(t)->>'key'))
+              const coalesceExprs = keysToCheck.flatMap(k => [
+                `metadata->>'${k}'`,
+                `to_jsonb(t)->>'${k}'`
+              ]);
+              return `COALESCE(${coalesceExprs.map(expr => `LOWER(${expr})`).join(', ')}) = LOWER($${paramIdx})`;
             });
           whereClause = `WHERE ${conditions.join(' AND ')}`;
         }
@@ -312,31 +325,50 @@ export class MultiTablePostgresProvider extends BaseVectorProvider {
                    CASE WHEN LOWER(val) IN (${entityHints.map((h) => `'${h.replace(/'/g, "''")}'`).join(', ')})
                    THEN 1.0 ELSE 0.0 END
                  ), 0)
-                 FROM jsonb_each_text(to_jsonb(t)) AS kv(key, val)
+                 FROM jsonb_each_text(COALESCE(v.metadata, k.metadata)) AS kv(key, val)
                  WHERE key IN (${this.searchFields.map(f => `'${f}'`).join(', ')})
                ) * 3.0`
             : '';
 
-          // Actual Hybrid Search: Semantic Vector Score + Full-Text Keyword Rank
+          // Optimized Subquery CTE Hybrid Search (Uses HNSW vector index & GIN fulltext index)
           sqlQuery = `
-            SELECT *, 
-             (1 - (embedding <=> $1::vector)) AS vector_score,
-             COALESCE(ts_rank(to_tsvector('english', (to_jsonb(t) - 'embedding')::text), to_tsquery('english', $2)), 0) AS keyword_score,
-             ((1 - (embedding <=> $1::vector)) + (COALESCE(ts_rank(to_tsvector('english', (to_jsonb(t) - 'embedding')::text), to_tsquery('english', $2)), 0) * 2.0) ${exactNameScoreExpr}) AS hybrid_score
-            FROM "${table}" t
-            ${whereClause}
+            WITH vector_search AS (
+              SELECT *, (1 - (embedding <=> $1::vector)) AS vector_score
+              FROM "${table}" t
+              ${whereClause}
+              ORDER BY embedding <=> $1::vector ASC
+              LIMIT ${tableLimit}
+            ),
+            keyword_search AS (
+              SELECT *, COALESCE(ts_rank(to_tsvector('english', content), to_tsquery('english', $2)), 0) AS keyword_score
+              FROM "${table}" t
+              WHERE ${whereClause ? whereClause.replace('WHERE', '') : 'TRUE'}
+                AND to_tsvector('english', content) @@ to_tsquery('english', $2)
+              ORDER BY keyword_score DESC
+              LIMIT ${tableLimit}
+            )
+            SELECT 
+              COALESCE(v.id, k.id) AS id,
+              COALESCE(v.namespace, k.namespace) AS namespace,
+              COALESCE(v.content, k.content) AS content,
+              COALESCE(v.metadata, k.metadata) AS metadata,
+              COALESCE(v.vector_score, 0) AS vector_score,
+              COALESCE(k.keyword_score, 0) AS keyword_score,
+              (COALESCE(v.vector_score, 0) + COALESCE(k.keyword_score, 0) * 2.0 ${exactNameScoreExpr}) AS hybrid_score
+            FROM vector_search v
+            FULL OUTER JOIN keyword_search k ON v.id = k.id
             ORDER BY hybrid_score DESC
             LIMIT ${tableLimit}
           `;
           params = [vectorLiteral, dynamicKeywordQuery, ...filterParams];
         } else {
-          // Fallback to Vector-only Search
+          // Fallback to Vector-only Search (ordered ASC to use HNSW index)
           sqlQuery = `
             SELECT *, 
             (1 - (embedding <=> $1::vector)) AS hybrid_score
             FROM "${table}" t
             ${whereClause}
-            ORDER BY hybrid_score DESC
+            ORDER BY embedding <=> $1::vector ASC
             LIMIT ${tableLimit}
           `;
           params = [vectorLiteral, ...filterParams];

package/src/rag/EntityExtractor.ts

@@ -41,7 +41,7 @@ Text to extract from:
       // 1. Try to find the JSON block using a regex
       const jsonMatch = response.match(/\{[\s\S]*\}/);
       const cleanJson = jsonMatch ? jsonMatch[0] : response.trim();
-      
+
       return JSON.parse(cleanJson);
     } catch {
       // 2. If parsing fails, try to repair truncated JSON
@@ -62,7 +62,7 @@ Text to extract from:
    */
   private repairTruncatedJson(json: string): string | null {
     let text = json.trim();
-    
+
     // Find the first { and work from there
     const startIdx = text.indexOf('{');
     if (startIdx === -1) return null;

package/src/rag/Reranker.ts

@@ -6,8 +6,8 @@ export class Reranker {
    * Re-ranks matches based on a secondary relevance score using an LLM.
    */
   async rerank(
-    matches: VectorMatch[], 
-    query: string, 
+    matches: VectorMatch[],
+    query: string,
     limit: number = 5,
     llm?: ILLMProvider
   ): Promise<VectorMatch[]> {
@@ -27,7 +27,7 @@ export class Reranker {
       const scoredMatches = matches.map(match => {
         const contentLower = match.content.toLowerCase();
         let keywordScore = 0;
-        
+
         keywords.forEach(keyword => {
           if (contentLower.includes(keyword)) {
             keywordScore += 1;
@@ -55,22 +55,15 @@ export class Reranker {
     try {
       // Take top 10 matches to avoid large context and high latency
       const topN = matches.slice(0, 10);
-      
-      const prompt = `You are a relevance ranking expert.
-Given the following user query and a list of retrieved document chunks, rank the chunks by relevance to the query.
-Return the result as a comma-separated list of document indices in order of relevance, from most relevant to least relevant.
-Use the indices provided in brackets like [0], [1], etc.
-Only return the indices (e.g., "2,0,1"), nothing else. Do not include brackets in the output.
-
-Query: "${query}"
-
-Documents:
-${topN.map((m, i) => `[${i}] ${m.content.replace(/\n/g, ' ')}`).join('\n')}`;
 
       const response = await llm.chat(
-        [{ role: 'user', content: prompt }],
+        [{ role: 'user', content: `Query: "${query}"\n\nDocuments:\n${topN.map((m, i) => `[${i}] ${m.content.replace(/\n/g, ' ')}`).join('\n')}` }],
         '',
-        { temperature: 0, maxTokens: 50 }
+        {
+          systemPrompt: 'You are a relevance ranking expert. Given the user query and a list of retrieved document chunks, rank the chunks by relevance to the query. Return the result as a comma-separated list of document indices in order of relevance, from most relevant to least relevant. Use the indices provided in brackets like [0], [1], etc. Only return the indices (e.g., "2,0,1"), nothing else. Do not include brackets in the output.',
+          temperature: 0,
+          maxTokens: 50
+        }
       );
 
       const cleanedResponse = response.trim().replace(/[\[\]\s]/g, '');

package/src/server.ts

@@ -6,7 +6,20 @@
  */
 
 // ── Shared Types ──────────────────────────────────────────────
-export type { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig, UIConfig, RAGConfig, VectorDBProvider, LLMProvider, EmbeddingProvider } from './config/RagConfig';
+export type {
+  RagConfig,
+  UniversalRagConfig,
+  RetrievalConfig,
+  WorkflowConfig,
+  VectorDBConfig,
+  LLMConfig,
+  EmbeddingConfig,
+  UIConfig,
+  RAGConfig,
+  VectorDBProvider,
+  LLMProvider,
+  EmbeddingProvider,
+} from './config/RagConfig';
 export type { VectorMatch, UpsertDocument, IngestDocument, ChatResponse, ChatMessage, ChatOptions } from './types';
 export type { ILLMProvider, EmbedOptions } from './llm/ILLMProvider';
 export type { Chunk, ChunkOptions } from './rag/DocumentChunker';
@@ -15,6 +28,7 @@ export type { ValidationError } from './core/ConfigValidator';
 export type { BatchOptions, BatchResult } from './core/BatchProcessor';
 
 // ── Core Orchestration ─────────────────────────────────────────
+export { Retrivora } from './core/Retrivora';
 export { VectorPlugin } from './core/VectorPlugin';
 export { Pipeline } from './core/Pipeline';
 export { ConfigResolver } from './core/ConfigResolver';
@@ -60,8 +74,23 @@ export {
   createIngestHandler,
   createHealthHandler,
   createUploadHandler,
+  createRagHandler,
   sseFrame,
   sseTextFrame,
   sseMetaFrame,
   sseErrorFrame,
 } from './handlers';
+
+// ── Exceptions ────────────────────────────────────────────────
+export type { RetrivoraErrorCode } from './exceptions';
+export {
+  RetrivoraError,
+  ProviderNotFoundException,
+  EmbeddingFailedException,
+  RetrievalException,
+  RateLimitException,
+  ConfigurationException,
+  AuthenticationException,
+  wrapError,
+} from './exceptions';
+

package/src/types/chat.ts

@@ -14,6 +14,13 @@ export interface RagMessage extends ChatMessage {
   /** Full observability trace emitted by the backend. Only present on assistant messages. */
   trace?: import('./index').ObservabilityTrace;
   createdAt: string;
+  /**
+   * Chain-of-thought reasoning from the LLM.
+   * Populated by native Anthropic extended thinking or simulated <think> tag stripping.
+   */
+  thinking?: string;
+  /** Wall-clock ms the model spent in the thinking phase. */
+  thinkingMs?: number;
 }
 
 export interface ChatOptions {
@@ -42,6 +49,8 @@ export interface UseRagChatOptions {
   onReply?: (message: RagMessage) => void;
   /** Called on error */
   onError?: (error: string) => void;
+  /** Optional custom headers to send with the chat request */
+  headers?: Record<string, string>;
 }
 
 export interface UseRagChatReturn {

package/src/types/props.ts

@@ -1,8 +1,37 @@
-import { ReactNode, CSSProperties, MouseEvent } from 'react';
+import { ReactNode, CSSProperties, MouseEvent, ElementType } from 'react';
 import { Product, VectorMatch } from './index';
 import { RagMessage } from './chat';
 import { UIConfig } from '../config/RagConfig';
 
+export interface ArchitectureCardProps {
+  icon: ReactNode;
+  title: string;
+  description: string;
+  badge: string;
+  badgeColor: string;
+}
+
+export interface Snippet {
+  id: string;
+  title: string;
+  description: string;
+  code: string;
+  language: string;
+}
+
+export interface PipelineStep {
+  step: string;
+  Icon: ElementType;
+  title: string;
+  desc: string;
+  colors: { from: string; to: string };
+}
+
+export interface ProviderPill {
+  Icon: ElementType;
+  label: string;
+}
+
 export type ChatViewportSize = 'compact' | 'medium' | 'large';
 
 export interface ChatWindowProps {
@@ -26,6 +55,10 @@ export interface ChatWindowProps {
   isMaximized?: boolean;
   /** Called when the user clicks 'Add to Cart' on a product */
   onAddToCart?: (product: Product) => void;
+  /** Optional custom API URL to send chat messages to */
+  apiUrl?: string;
+  /** Optional custom headers to send with the chat request */
+  headers?: Record<string, string>;
 }
 
 export interface ChatWidgetProps {
@@ -33,6 +66,10 @@ export interface ChatWidgetProps {
   position?: 'bottom-right' | 'bottom-left';
   /** Called when the user clicks 'Add to Cart' on a product */
   onAddToCart?: (product: Product) => void;
+  /** Optional custom API URL to send chat messages to */
+  apiUrl?: string;
+  /** Optional custom headers to send with the chat request */
+  headers?: Record<string, string>;
 }
 
 export interface MessageBubbleProps {