@retrivora-ai/rag-engine 0.1.0

package/src/components/ChatWindow.tsx

@@ -0,0 +1,248 @@
+'use client';
+
+import React, { useState, useRef, useEffect, useCallback } from 'react';
+import {
+  Bot,
+  Trash2,
+  X,
+  Sparkles,
+  ArrowUp,
+  TriangleAlert,
+} from 'lucide-react';
+import { MessageBubble } from './MessageBubble';
+import { useConfig } from './ConfigProvider';
+import { useRagChat } from '@/hooks/useRagChat';
+
+interface ChatWindowProps {
+  /** Additional className for the wrapper div */
+  className?: string;
+  /** Inline styles for the wrapper div */
+  style?: React.CSSProperties;
+  /** Called when the close button is clicked (for widget mode) */
+  onClose?: () => void;
+  /** Whether to show a close (X) button in the header */
+  showClose?: boolean;
+}
+
+export function ChatWindow({ className = '', style, onClose, showClose = false }: ChatWindowProps) {
+  const { ui, projectId } = useConfig();
+  const [input, setInput] = useState('');
+  const [mounted, setMounted] = useState(false);
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const { messages, send, clear, isLoading, error } = useRagChat(projectId, {
+    namespace: projectId,
+  });
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setMounted(true);
+  }, []);
+
+  // Scroll to bottom on new message (but not on initial mount with empty messages)
+  useEffect(() => {
+    if (messages.length > 0 || isLoading) {
+      bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
+    }
+  }, [messages, isLoading]);
+
+  const sendMessage = useCallback(async () => {
+    const text = input.trim();
+    if (!text || isLoading) return;
+    setInput('');
+    await send(text);
+    window.setTimeout(() => inputRef.current?.focus(), 50);
+  }, [input, isLoading, send]);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      sendMessage();
+    }
+  };
+
+  const clearHistory = () => {
+    clear();
+  };
+
+  const isEmpty = messages.length === 0;
+
+  const borderRadiusMap = {
+    none: 'rounded-none',
+    sm: 'rounded-sm',
+    md: 'rounded-md',
+    lg: 'rounded-lg',
+    xl: 'rounded-xl',
+    full: 'rounded-3xl',
+  };
+
+  const currentRadius = borderRadiusMap[ui.borderRadius || 'xl'];
+  const isGlass = ui.visualStyle !== 'solid';
+
+  return (
+    <div
+      className={`flex flex-col border border-slate-200 dark:border-white/10 shadow-2xl transition-all duration-300 ${currentRadius} ${
+        isGlass 
+          ? 'bg-white/90 dark:bg-[#0f0f1a]/90 backdrop-blur-xl' 
+          : 'bg-white dark:bg-[#0f0f1a]'
+      } ${className}`}
+      style={{ '--primary': ui.primaryColor, '--accent': ui.accentColor, ...style } as React.CSSProperties}
+    >
+      {/* ── Header ── */}
+      <div
+        className="flex items-center justify-between px-5 py-4 border-b border-slate-200 dark:border-white/10"
+        style={{ background: `linear-gradient(135deg, ${ui.primaryColor}15, ${ui.accentColor}10)` }}
+      >
+        <div className="flex items-center gap-3">
+          {ui.logoUrl ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img src={ui.logoUrl} alt="logo" className="w-8 h-8 rounded-lg object-cover" />
+          ) : (
+            <div
+              className={`w-9 h-9 flex items-center justify-center shadow-md ${ui.borderRadius === 'full' ? 'rounded-full' : 'rounded-xl'}`}
+              style={{ background: `linear-gradient(135deg, ${ui.primaryColor}, ${ui.accentColor})` }}
+            >
+              <Bot className="w-5 h-5 text-white" />
+            </div>
+          )}
+          <div>
+            <h2 className="text-slate-900 dark:text-white font-semibold text-sm leading-tight">{ui.title}</h2>
+            {ui.poweredBy && (
+              <p className="text-slate-500 dark:text-white/40 text-[11px] leading-tight">{`Powered by ${ui.poweredBy}`}</p>
+            )}
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2">
+          {/* Online indicator */}
+          <span className="flex items-center gap-1 text-[10px] text-emerald-500 dark:text-emerald-400">
+            <span className="w-1.5 h-1.5 rounded-full bg-emerald-500 dark:bg-emerald-400 animate-pulse" />
+            Online
+          </span>
+
+          {mounted && messages.length > 0 && (
+            <button
+              onClick={clearHistory}
+              title="Clear conversation"
+              className="w-7 h-7 rounded-lg flex items-center justify-center text-slate-400 hover:text-slate-600 dark:text-white/40 dark:hover:text-white/70 hover:bg-slate-100 dark:hover:bg-white/10 transition-all cursor-pointer"
+            >
+              <Trash2 className="w-3.5 h-3.5" />
+            </button>
+          )}
+
+          {showClose && onClose && (
+            <button
+              onClick={onClose}
+              title="Close chat"
+              className="w-7 h-7 rounded-lg flex items-center justify-center text-slate-400 hover:text-slate-600 dark:text-white/40 dark:hover:text-white/70 hover:bg-slate-100 dark:hover:bg-white/10 transition-all cursor-pointer"
+            >
+              <X className="w-4 h-4" />
+            </button>
+          )}
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto px-4 py-4 space-y-5 scrollbar-thin scrollbar-thumb-slate-200 dark:scrollbar-thumb-white/10 scrollbar-track-transparent min-h-0 bg-slate-50 dark:bg-transparent">
+        {!mounted || isEmpty ? (
+          /* Welcome state */
+          <div className="h-full flex flex-col items-center justify-center text-center gap-4 px-6 py-12">
+            <div
+              className={`w-16 h-16 flex items-center justify-center shadow-lg ${ui.borderRadius === 'full' ? 'rounded-full' : 'rounded-2xl'}`}
+              style={{ background: `linear-gradient(135deg, ${ui.primaryColor}, ${ui.accentColor})` }}
+            >
+              <Sparkles className="w-8 h-8 text-white" />
+            </div>
+            <div>
+              <p className="text-slate-800 dark:text-white/80 font-medium leading-relaxed">{ui.welcomeMessage}</p>
+              <p className="text-slate-500 dark:text-white/30 text-sm mt-2">
+                Ask a question to get started
+              </p>
+            </div>
+
+            {/* Suggested prompts */}
+            <div className="flex flex-wrap gap-2 justify-center mt-2">
+              {['What can you help me with?', 'Summarise the key topics', 'Show me an example'].map(
+                (suggestion) => (
+                  <button
+                    key={suggestion}
+                    onClick={() => {
+                      setInput(suggestion);
+                      inputRef.current?.focus();
+                    }}
+                    className="px-3 py-1.5 rounded-full text-xs border border-slate-200 dark:border-white/10 text-slate-600 dark:text-white/50 hover:text-slate-900 dark:hover:text-white/80 hover:border-slate-300 dark:hover:border-white/20 hover:bg-slate-100 dark:hover:bg-white/5 transition-all"
+                  >
+                    {suggestion}
+                  </button>
+                )
+              )}
+            </div>
+          </div>
+        ) : (
+          messages.map((msg) => (
+            <MessageBubble
+              key={msg.id}
+              message={msg}
+              sources={msg.sources}
+              primaryColor={ui.primaryColor}
+              accentColor={ui.accentColor}
+            />
+          ))
+        )}
+
+        {/* Typing indicator */}
+        {isLoading && (
+          <MessageBubble
+            message={{ role: 'assistant', content: '' }}
+            isStreaming
+            primaryColor={ui.primaryColor}
+            accentColor={ui.accentColor}
+          />
+        )}
+
+        {/* Error */}
+        {error && (
+          <div className="flex items-center gap-2 text-rose-500 dark:text-rose-400 text-sm bg-rose-50 dark:bg-rose-400/10 border border-rose-200 dark:border-rose-400/20 rounded-xl px-4 py-3">
+            <TriangleAlert className="w-4 h-4 flex-shrink-0" />
+            <span>{error}</span>
+          </div>
+        )}
+
+        <div ref={bottomRef} />
+      </div>
+
+      {/* ── Input ── */}
+      <div className={`px-4 pb-4 pt-2 border-t border-slate-200 dark:border-white/10 ${isGlass ? 'bg-transparent' : 'bg-white dark:bg-[#0f0f1a]'}`}>
+        <div className={`flex items-end gap-2 bg-slate-50 dark:bg-white/5 border border-slate-200 dark:border-white/10 p-2 focus-within:border-slate-300 dark:focus-within:border-white/20 transition-all ${ui.borderRadius === 'full' ? 'rounded-3xl' : 'rounded-2xl'}`}>
+          <textarea
+            ref={inputRef}
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder={ui.placeholder}
+            rows={1}
+            disabled={isLoading}
+            className="flex-1 bg-transparent text-slate-900 dark:text-white/90 placeholder-slate-400 dark:placeholder-white/30 text-sm resize-none outline-none py-1.5 px-2 max-h-32 leading-relaxed disabled:opacity-50"
+            style={{ scrollbarWidth: 'none' }}
+          />
+
+          <button
+            onClick={sendMessage}
+            disabled={!input.trim() || isLoading}
+            className="flex-shrink-0 w-9 h-9 rounded-xl flex items-center justify-center transition-all disabled:opacity-30 disabled:cursor-not-allowed hover:scale-105 active:scale-95 shadow-md"
+            style={{
+              background:
+                input.trim() && !isLoading
+                  ? `linear-gradient(135deg, ${ui.primaryColor}, ${ui.accentColor})`
+                  : 'rgba(148, 163, 184, 0.2)', // slate-400/20 for light mode disabled
+            }}
+          >
+            <ArrowUp className="w-4 h-4 text-white" />
+          </button>
+        </div>
+        <p className="text-center text-[10px] text-slate-400 dark:text-white/20 mt-2">
+          Press Enter to send · Shift+Enter for new line
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/components/ConfigProvider.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+/**
+ * ConfigProvider — React Context that makes RagConfig (UI subset) available
+ * to all child components without prop drilling.
+ *
+ * Only the UI-safe portions of RagConfig are exposed to the client.
+ */
+
+import React, { createContext, useContext, ReactNode } from 'react';
+import { UIConfig } from '@/config/RagConfig';
+import { mergeDefined } from '@/utils/templateUtils';
+
+export interface ClientConfig {
+  projectId: string;
+  ui: Required<UIConfig>;
+}
+
+const defaultConfig: ClientConfig = {
+  projectId: 'default',
+  ui: {
+    title: 'AI Assistant',
+    subtitle: 'Powered by RAG',
+    primaryColor: '#6366f1',
+    accentColor: '#8b5cf6',
+    logoUrl: '',
+    placeholder: 'Ask me anything…',
+    showSources: true,
+    welcomeMessage: "Hello! I'm your AI assistant. Ask me anything about your documents.",
+    showWidget: true,
+    poweredBy: 'RAG',
+    visualStyle: 'glass',
+    borderRadius: 'xl',
+  },
+};
+
+const ConfigContext = createContext<ClientConfig>(defaultConfig);
+
+export function ConfigProvider({
+  config,
+  children,
+}: {
+  config?: { projectId?: string; ui?: Partial<UIConfig> };
+  children: ReactNode;
+}) {
+  const merged: ClientConfig = {
+    projectId: config?.projectId || defaultConfig.projectId,
+    ui: mergeDefined(defaultConfig.ui, config?.ui) as Required<UIConfig>,
+  };
+
+  return <ConfigContext.Provider value={merged}>{children}</ConfigContext.Provider>;
+}
+
+export function useConfig(): ClientConfig {
+  return useContext(ConfigContext);
+}

package/src/components/MessageBubble.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import React from 'react';
+import { Bot, User, ChevronDown, ChevronRight } from 'lucide-react';
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { ChatMessage } from '@/llm/ILLMProvider';
+import { VectorMatch } from '@/vectordb/IVectorDB';
+import { SourceCard } from './SourceCard';
+
+interface MessageBubbleProps {
+  message: ChatMessage;
+  sources?: VectorMatch[];
+  isStreaming?: boolean;
+  primaryColor?: string;
+  accentColor?: string;
+}
+
+export function MessageBubble({
+  message,
+  sources,
+  isStreaming = false,
+  primaryColor = '#6366f1',
+  accentColor = '#8b5cf6',
+}: MessageBubbleProps) {
+  const isUser = message.role === 'user';
+  const [showSources, setShowSources] = React.useState(false);
+
+  return (
+    <div className={`flex gap-3 ${isUser ? 'flex-row-reverse' : 'flex-row'} items-start`}>
+      {/* Avatar */}
+      <div
+        className={`flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center shadow-lg ${
+          isUser ? 'text-white' : 'bg-slate-100 dark:bg-white/10 text-slate-700 dark:text-white/80'
+        }`}
+        style={isUser ? { background: `linear-gradient(135deg, ${primaryColor}, ${accentColor})` } : {}}
+      >
+        {isUser
+          ? <User className="w-4 h-4 text-white" />
+          : <Bot className="w-4 h-4" />
+        }
+      </div>
+
+      <div className={`flex flex-col gap-1 max-w-[75%] ${isUser ? 'items-end' : 'items-start'}`}>
+        {/* Bubble */}
+        <div
+          className={`relative px-4 py-3 rounded-2xl text-sm leading-relaxed shadow-sm dark:shadow-lg ${
+            isUser
+              ? 'text-white rounded-tr-sm'
+              : 'bg-white dark:bg-white/5 border border-slate-200 dark:border-white/10 text-slate-800 dark:text-white/90 rounded-tl-sm'
+          }`}
+          style={
+            isUser
+              ? { background: `linear-gradient(135deg, ${primaryColor}, ${accentColor})` }
+              : {}
+          }
+        >
+          {isStreaming ? (
+            <span className="flex items-center gap-1">
+              <span className="w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:0ms]" />
+              <span className="w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:150ms]" />
+              <span className="w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:300ms]" />
+            </span>
+          ) : (
+            <div className={`prose prose-sm max-w-none ${isUser ? 'prose-invert' : 'dark:prose-invert'}`}>
+              <ReactMarkdown remarkPlugins={[remarkGfm]}>
+                {message.content}
+              </ReactMarkdown>
+            </div>
+          )}
+        </div>
+
+        {/* Sources toggle */}
+        {!isUser && sources && sources.length > 0 && (
+          <div className="w-full">
+            <button
+              onClick={() => setShowSources((s) => !s)}
+              className="text-[11px] text-indigo-400 hover:text-indigo-300 transition-colors flex items-center gap-1 mt-1"
+            >
+              {showSources
+                ? <ChevronDown className="w-3 h-3" />
+                : <ChevronRight className="w-3 h-3" />
+              }
+              {sources.length} source{sources.length !== 1 ? 's' : ''} used
+            </button>
+
+            {showSources && (
+              <div className="mt-2 flex flex-col gap-2">
+                {sources.map((src, i) => (
+                  <SourceCard key={src.id} source={src} index={i} />
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/SourceCard.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import React from 'react';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import { VectorMatch } from '@/vectordb/IVectorDB';
+
+interface SourceCardProps {
+  source: VectorMatch;
+  index: number;
+}
+
+export function SourceCard({ source, index }: SourceCardProps) {
+  const [expanded, setExpanded] = React.useState(false);
+  const scorePercent = Math.round(source.score * 100);
+
+  const scoreColor =
+    source.score >= 0.8
+      ? 'text-emerald-400'
+      : source.score >= 0.6
+      ? 'text-amber-400'
+      : 'text-rose-400';
+
+  const scoreBg =
+    source.score >= 0.8
+      ? 'bg-emerald-50 border-emerald-100 dark:bg-emerald-400/10 dark:border-emerald-400/20'
+      : source.score >= 0.6
+      ? 'bg-amber-50 border-amber-100 dark:bg-amber-400/10 dark:border-amber-400/20'
+      : 'bg-rose-50 border-rose-100 dark:bg-rose-400/10 dark:border-rose-400/20';
+
+  const preview = source.content.slice(0, 120);
+  const hasMore = source.content.length > 120;
+
+  return (
+    <div
+      className={`rounded-xl border backdrop-blur-sm p-3 transition-all duration-200 hover:scale-[1.01] cursor-pointer ${scoreBg}`}
+      onClick={() => setExpanded((e) => !e)}
+    >
+      <div className="flex items-start justify-between gap-2">
+        <div className="flex items-center gap-2 min-w-0">
+          <span className="flex-shrink-0 w-5 h-5 rounded-full bg-slate-200 dark:bg-white/10 flex items-center justify-center text-[10px] font-bold text-slate-500 dark:text-white/60">
+            {index + 1}
+          </span>
+          <span className="text-xs text-slate-500 dark:text-white/50 truncate font-mono">
+            {(source.metadata?.docId as string) ?? source.id}
+          </span>
+        </div>
+        <span className={`flex-shrink-0 text-xs font-semibold ${scoreColor} tabular-nums`}>
+          {scorePercent}%
+        </span>
+      </div>
+
+      <p className="mt-2 text-xs text-slate-600 dark:text-white/70 leading-relaxed">
+        {expanded ? source.content : `${preview}${hasMore && !expanded ? '…' : ''}`}
+      </p>
+
+      {hasMore && (
+        <button className="mt-1 text-[10px] text-indigo-400 hover:text-indigo-300 transition-colors flex items-center gap-0.5">
+          {expanded
+            ? <><ChevronUp className="w-3 h-3" /> Show less</>
+            : <><ChevronDown className="w-3 h-3" /> Show more</>
+          }
+        </button>
+      )}
+    </div>
+  );
+}

package/src/components/ThemeProvider.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+import * as React from 'react';
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+
+export function ThemeProvider({ children, ...props }: React.ComponentProps<typeof NextThemesProvider>) {
+  return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
+}

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import * as React from 'react';
+import { Moon, Sun } from 'lucide-react';
+import { useTheme } from 'next-themes';
+import { useHydrated } from '@/hooks/useHydrated';
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  const mounted = useHydrated();
+
+  if (!mounted) {
+    return <div className="w-8 h-8 rounded-lg" />; // Placeholder to avoid layout shift
+  }
+
+  return (
+    <button
+      onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
+      className="w-8 h-8 rounded-lg flex items-center justify-center text-slate-500 hover:text-slate-900 dark:text-white/40 dark:hover:text-white/70 hover:bg-slate-100 dark:hover:bg-white/10 transition-all"
+      aria-label="Toggle theme"
+    >
+      {theme === 'dark' ? (
+        <Sun className="w-4 h-4" />
+      ) : (
+        <Moon className="w-4 h-4" />
+      )}
+    </button>
+  );
+}

package/src/config/RagConfig.ts

@@ -0,0 +1,159 @@
+/**
+ * Master configuration interface for Retrivora AI.
+ * Each consuming project provides one RagConfig object to drive
+ * vector DB selection, LLM selection, embedding, and UI branding.
+ */
+
+// ---------------------------------------------------------------------------
+// Vector DB
+// ---------------------------------------------------------------------------
+
+export type VectorDBProvider = 'pinecone' | 'pgvector' | 'mongodb' | 'rest' | 'universal_rest' | 'custom';
+
+export interface VectorDBConfig {
+  /** Which vector database to use */
+  provider: VectorDBProvider;
+  /** The index / table name to query */
+  indexName: string;
+  /** Provider-specific options (API keys, connection strings, etc.)
+   *
+   * For 'universal_rest', the following options are supported:
+   * - baseUrl: string
+   * - headers?: Record<string, string>
+   * - queryPath?: string
+   * - upsertPath?: string
+   * - queryPayloadTemplate?: string (e.g. '{"vector": {{vector}}, "limit": {{topK}}}')
+   * - upsertPayloadTemplate?: string (e.g. '{"id": "{{id}}", "vector": {{vector}}}')
+   * - responseExtractPath?: string (e.g. 'data.results')
+   * - idPath?: string (e.g. '_id')
+   * - scorePath?: string (e.g. 'similarity')
+   * - contentPath?: string (e.g. 'text')
+   */
+  options: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// LLM Provider
+// ---------------------------------------------------------------------------
+
+export type LLMProvider = 'openai' | 'anthropic' | 'ollama' | 'rest' | 'universal_rest' | 'custom';
+
+export interface LLMConfig {
+  /** Which LLM provider to use */
+  provider: LLMProvider;
+  /** Model name, e.g. "gpt-4o", "claude-3-opus-20240229", "llama3" */
+  model: string;
+  /** API key for cloud providers */
+  apiKey?: string;
+  /** Base URL — required for Ollama or self-hosted endpoints */
+  baseUrl?: string;
+  /** Custom system prompt injected before every chat */
+  systemPrompt?: string;
+  /** Max tokens in the LLM response */
+  maxTokens?: number;
+  /** Sampling temperature (0–1) */
+  temperature?: number;
+  /** Provider-specific options
+   * 
+   * For 'universal_rest', the following options are supported:
+   * - headers?: Record<string, string>
+   * - chatPath?: string
+   * - chatPayloadTemplate?: string (e.g. '{"prompt": "{{prompt}}", "max_tokens": {{maxTokens}}}')
+   * - responseExtractPath?: string (e.g. 'choices[0].text' or 'response')
+   */
+  options?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Embedding
+// ---------------------------------------------------------------------------
+
+export type EmbeddingProvider = 'openai' | 'ollama' | 'rest' | 'universal_rest' | 'custom';
+
+export interface EmbeddingConfig {
+  /** Which embedding provider to use */
+  provider: EmbeddingProvider;
+  /** Model name, e.g. "text-embedding-ada-002", "nomic-embed-text" */
+  model: string;
+  /** API key (if needed) */
+  apiKey?: string;
+  /** Base URL for custom / Ollama embedding endpoints */
+  baseUrl?: string;
+  /** Output vector dimension — must match the index dimension */
+  dimensions?: number;
+  /** Provider-specific options for custom adapters */
+  options?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// UI Branding
+// ---------------------------------------------------------------------------
+
+export interface UIConfig {
+  /** Title shown in the chat header */
+  title?: string;
+  /** Subtitle / description below the title */
+  subtitle?: string;
+  /** Primary brand colour (CSS colour string) */
+  primaryColor?: string;
+  /** Accent colour for user message bubbles */
+  accentColor?: string;
+  /** URL to a logo image */
+  logoUrl?: string;
+  /** Input placeholder text */
+  placeholder?: string;
+  /** Show source cards after each answer */
+  showSources?: boolean;
+  /** Welcome message shown on first load */
+  welcomeMessage?: string;
+  /** Whether to show the floating chat widget. Defaults to true. */
+  showWidget?: boolean;
+  /** Custom 'Powered by' text shown in the header */
+  poweredBy?: string;
+  /** Visual style: 'glass' (default) or 'solid' */
+  visualStyle?: 'glass' | 'solid';
+  /** Border radius: 'none', 'sm', 'md', 'lg', 'xl', 'full' */
+  borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+}
+
+// ---------------------------------------------------------------------------
+// RAG Pipeline Tuning
+// ---------------------------------------------------------------------------
+
+export interface RAGConfig {
+  /** Number of top-K chunks retrieved per query */
+  topK?: number;
+  /** Minimum similarity score to include a chunk (0–1) */
+  scoreThreshold?: number;
+  /** Target chunk size in tokens */
+  chunkSize?: number;
+  /** Overlap between adjacent chunks in tokens */
+  chunkOverlap?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Root Config
+// ---------------------------------------------------------------------------
+
+export interface RagConfig {
+  /**
+   * Unique identifier for the consuming project.
+   * Used as the vector DB namespace to achieve multi-tenancy.
+   */
+  projectId: string;
+
+  /** Vector database configuration */
+  vectorDb: VectorDBConfig;
+
+  /** LLM configuration */
+  llm: LLMConfig;
+
+  /** Embedding configuration */
+  embedding: EmbeddingConfig;
+
+  /** Optional UI branding overrides */
+  ui?: UIConfig;
+
+  /** Optional RAG pipeline tuning knobs */
+  rag?: RAGConfig;
+}