@retrivora-ai/rag-engine 1.9.6 → 1.9.8

package/src/components/MessageBubble.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import React from 'react';
-import { Bot, User, ChevronDown, ChevronRight, Activity, Copy, Check } from 'lucide-react';
+import { Bot, User, ChevronDown, ChevronRight, Activity, Copy, Check, ThumbsUp, ThumbsDown, Clock } from 'lucide-react';
 import ReactMarkdown from 'react-markdown';
 import { MessageBubbleProps, Product, UITransformationResponse } from '../types';
 import { SourceCard } from './SourceCard';
@@ -39,12 +39,111 @@ function normalizePlusSeparatedLists(raw: string): string {
 
 function stripLeakedAnswerWrappers(raw: string): string {
   return raw
-    .replace(/<prose\s+answer(?:\s+in\s+[^>]*)?>\s*([\s\S]*?)\s*<\/prose>/gi, '$1')
+    .replace(/<prose\s+answer(?:\s+in\s+[^>]*)?>[\s\S]*?<\/prose>/gi, '$1')
     .replace(/<\/?prose(?:\s+answer)?[^>]*>/gi, '')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
 }
 
+function formatTime(isoString?: string): string {
+  if (!isoString) return '';
+  try {
+    const d = new Date(isoString);
+    return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  } catch {
+    return '';
+  }
+}
+
+// ─── Feedback Buttons ─────────────────────────────────────────────────────────
+
+interface FeedbackBarProps {
+  messageId: string;
+  onFeedback: (messageId: string, rating: 'thumbs_up' | 'thumbs_down') => void;
+  primaryColor: string;
+}
+
+function FeedbackBar({ messageId, onFeedback, primaryColor }: FeedbackBarProps) {
+  const [rating, setRating] = React.useState<'thumbs_up' | 'thumbs_down' | null>(null);
+  const [submitting, setSubmitting] = React.useState(false);
+
+  const handleRate = async (r: 'thumbs_up' | 'thumbs_down') => {
+    if (rating !== null || submitting) return;
+    setSubmitting(true);
+    setRating(r);
+    try {
+      await onFeedback(messageId, r);
+    } catch {
+      // Rating already set optimistically — keep it
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const isLocked = rating !== null;
+
+  return (
+    <div className="flex items-center gap-1">
+      {/* Divider */}
+      <span className="h-3 w-px bg-slate-200 dark:bg-white/10 mx-1" />
+
+      {/* Thumbs Up */}
+      <button
+        onClick={() => handleRate('thumbs_up')}
+        disabled={isLocked}
+        title={rating === 'thumbs_up' ? 'You liked this' : 'Good response'}
+        className={`group relative flex items-center justify-center w-6 h-6 rounded-lg transition-all duration-200 cursor-pointer border ${
+          rating === 'thumbs_up'
+            ? 'bg-emerald-50 dark:bg-emerald-500/10 border-emerald-200 dark:border-emerald-500/25 text-emerald-600 dark:text-emerald-400 scale-110'
+            : rating === 'thumbs_down'
+            ? 'opacity-30 border-transparent text-slate-300 dark:text-white/20 cursor-not-allowed'
+            : 'border-transparent text-slate-300 dark:text-white/20 hover:text-emerald-500 dark:hover:text-emerald-400 hover:bg-emerald-50 dark:hover:bg-emerald-500/10 hover:border-emerald-200 dark:hover:border-emerald-500/20 hover:scale-110'
+        }`}
+      >
+        <ThumbsUp className="w-3 h-3" />
+        {/* Tooltip */}
+        {!isLocked && (
+          <span className="absolute -top-8 left-1/2 -translate-x-1/2 px-2 py-1 text-[10px] font-medium bg-slate-800 dark:bg-slate-700 text-white rounded-lg opacity-0 group-hover:opacity-100 transition-opacity pointer-events-none whitespace-nowrap shadow-lg z-10">
+            Good response
+          </span>
+        )}
+      </button>
+
+      {/* Thumbs Down */}
+      <button
+        onClick={() => handleRate('thumbs_down')}
+        disabled={isLocked}
+        title={rating === 'thumbs_down' ? 'You disliked this' : 'Bad response'}
+        className={`group relative flex items-center justify-center w-6 h-6 rounded-lg transition-all duration-200 cursor-pointer border ${
+          rating === 'thumbs_down'
+            ? 'bg-rose-50 dark:bg-rose-500/10 border-rose-200 dark:border-rose-500/25 text-rose-600 dark:text-rose-400 scale-110'
+            : rating === 'thumbs_up'
+            ? 'opacity-30 border-transparent text-slate-300 dark:text-white/20 cursor-not-allowed'
+            : 'border-transparent text-slate-300 dark:text-white/20 hover:text-rose-500 dark:hover:text-rose-400 hover:bg-rose-50 dark:hover:bg-rose-500/10 hover:border-rose-200 dark:hover:border-rose-500/20 hover:scale-110'
+        }`}
+      >
+        <ThumbsDown className="w-3 h-3" />
+        {!isLocked && (
+          <span className="absolute -top-8 left-1/2 -translate-x-1/2 px-2 py-1 text-[10px] font-medium bg-slate-800 dark:bg-slate-700 text-white rounded-lg opacity-0 group-hover:opacity-100 transition-opacity pointer-events-none whitespace-nowrap shadow-lg z-10">
+            Bad response
+          </span>
+        )}
+      </button>
+
+      {/* Confirmation pill */}
+      {isLocked && (
+        <span className={`ml-1 text-[10px] font-semibold px-2 py-0.5 rounded-full border transition-all duration-300 ${
+          rating === 'thumbs_up'
+            ? 'text-emerald-600 dark:text-emerald-400 bg-emerald-50 dark:bg-emerald-500/10 border-emerald-200 dark:border-emerald-500/20'
+            : 'text-rose-600 dark:text-rose-400 bg-rose-50 dark:bg-rose-500/10 border-rose-200 dark:border-rose-500/20'
+        }`}>
+          {rating === 'thumbs_up' ? 'Helpful' : 'Not helpful'}
+        </span>
+      )}
+    </div>
+  );
+}
+
 // ─── Main component ───────────────────────────────────────────────────────────
 
 export function MessageBubble({
@@ -55,6 +154,7 @@ export function MessageBubble({
   accentColor = '#8b5cf6',
   onAddToCart,
   viewportSize = 'large',
+  onFeedback,
 }: MessageBubbleProps) {
   const isUser = message.role === 'user';
   const isCompact = viewportSize === 'compact';
@@ -85,7 +185,7 @@ export function MessageBubble({
       if (type && !['text', 'table'].includes(type)) return true;
     }
     if (structuredContent.payload) {
-      return /"?(?:view|type|chartType)"?\s*:\s*"?(?:chart|carousel|pie|bar|line|product_carousel)"?/i.test(structuredContent.payload);
+      return /\"?(?:view|type|chartType)\"?\s*:\s*\"?(?:chart|carousel|pie|bar|line|product_carousel)\"?/i.test(structuredContent.payload);
     }
     return false;
   }, [message.uiTransformation, structuredContent.payload]);
@@ -129,18 +229,10 @@ export function MessageBubble({
   const processedMarkdown = React.useMemo<string>(() => {
     let raw = structuredContent.payload ? structuredContent.text : (cleanContent || message.content);
 
-    // 0. Pre-sanitize: strip $ from non-monetary whole integers.
-    // Real prices always have a decimal (e.g. $257.00). A bare $168 or $9680811891595 is NOT a price.
     raw = raw.replace(/\$\s*(\d+)(?!\.\d)/g, '$1');
     raw = normalizePlusSeparatedLists(raw);
     raw = stripLeakedAnswerWrappers(raw);
-
-    // 0a. Strip bold (**...**) from inline field labels.
-    // The LLM wraps field names like **Stock** — 168 or **EAN** — 9680811891595 in bold.
-    // We want to strip the ** so it renders as plain text, not bold.
     raw = raw.replace(/\*\*([^*\n]+)\*\*(\s*[—\-–:]\s*)/g, '$1$2');
-
-    // 0b. Remove duplicate lines (LLM sometimes repeats fields like Stock, EAN twice)
     raw = raw
       .split('\n')
       .filter((line, idx, arr) => {
@@ -148,13 +240,12 @@ export function MessageBubble({
         return !trimmed || arr.findIndex(l => l.trim() === trimmed) === idx;
       })
       .join('\n');
+
     const hasStructuredUiBlock = Boolean(structuredContent.payload) || /```(?:ui|json|chart)\s*[\s\S]*?"(?:view|chartType|type|data|items|rows|products|results)"\s*:/i.test(raw);
 
-    // 1. Structural fixes
-    raw = raw.replace(/([^\n])\n\|/g, '$1\n\n|') // Ensure blank line before table
-      .replace(/(\|[^\n]*\|)\n\n+(?=\|)/g, '$1\n'); // Remove blank lines between rows
+    raw = raw.replace(/([^\n])\n\|/g, '$1\n\n|')
+      .replace(/(\|[^\n]*\|)\n\n+(?=\|)/g, '$1\n');
 
-    // 2. HEALING: Wrap naked JSON blocks
     if (!isStreaming) {
       raw = raw.replace(/(?:^|\n)\s*\{[\s\S]*\}\s*(?:\n|$)/g, (match) => {
         if (match.includes('```')) return match;
@@ -166,7 +257,6 @@ export function MessageBubble({
       });
     }
 
-    // 2b. Suppress duplicated markdown tables if a UI block is present
     if (hasStructuredUiBlock) {
       raw = stripStructuredUiLabels(stripMarkdownTables(raw))
         .replace(/\n{3,}/g, '\n\n')
@@ -182,18 +272,25 @@ export function MessageBubble({
     [primaryColor, accentColor, isStreaming, onAddToCart, viewportSize],
   );
 
+  const timeLabel = formatTime(message.createdAt);
+  const isCompleted = !isStreaming && message.content;
+
   // ── Render ─────────────────────────────────────────────────────────────────
   return (
     <div className={`flex ${isCompact ? 'gap-2' : 'gap-3'} ${isUser ? 'flex-row-reverse' : 'flex-row'} items-start`}>
       {/* Avatar */}
       <div
-        className={`flex-shrink-0 ${isCompact ? 'w-7 h-7' : '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'
-          }`}
+        className={`flex-shrink-0 ${isCompact ? 'w-7 h-7' : 'w-8 h-8'} rounded-full flex items-center justify-center shadow-md transition-all duration-300 ${
+          isUser
+            ? 'text-white'
+            : 'bg-gradient-to-br from-slate-100 to-slate-200 dark:from-white/10 dark:to-white/5 text-slate-600 dark:text-white/70 ring-1 ring-slate-200/80 dark:ring-white/10'
+        } ${isStreaming && !isUser ? 'ring-2 ring-offset-1 ring-offset-transparent animate-pulse' : ''}`}
         style={isUser ? { background: `linear-gradient(135deg, ${primaryColor}, ${accentColor})` } : {}}
       >
-        {isUser ? <User className={`${isCompact ? 'w-3.5 h-3.5' : 'w-4 h-4'} text-white`} /> : <Bot className={`${isCompact ? 'w-3.5 h-3.5' : 'w-4 h-4'}`} />}
+        {isUser
+          ? <User className={`${isCompact ? 'w-3.5 h-3.5' : 'w-4 h-4'} text-white`} />
+          : <Bot className={`${isCompact ? 'w-3.5 h-3.5' : 'w-4 h-4'}`} />
+        }
       </div>
 
       <div className={`flex flex-col gap-1 min-w-0 ${isCompact ? 'max-w-[94%]' : isMedium ? 'max-w-[92%]' : 'max-w-[90%]'} ${isUser ? 'items-end' : 'items-start'}`}>
@@ -208,28 +305,30 @@ export function MessageBubble({
 
         {/* Bubble */}
         <div
-          className={`relative group ${isCompact ? 'px-3 py-2.5 text-[13px]' : 'px-4 py-3 text-sm'} rounded-2xl 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'
-            }`}
+          className={`relative group ${isCompact ? 'px-3 py-2.5 text-[13px]' : 'px-4 py-3 text-sm'} rounded-2xl leading-relaxed transition-shadow duration-200 ${
+            isUser
+              ? 'text-white rounded-tr-sm shadow-md hover:shadow-lg'
+              : 'bg-white dark:bg-white/5 border border-slate-200/80 dark:border-white/10 text-slate-800 dark:text-white/90 rounded-tl-sm shadow-sm hover:shadow-md hover:border-slate-300/60 dark:hover:border-white/15'
+          }`}
           style={
             isUser ? { background: `linear-gradient(135deg, ${primaryColor}, ${accentColor})` } : {}
           }
         >
           {/* Floating Copy Button for completed assistant messages */}
-          {!isUser && !isStreaming && message.content && (
+          {!isUser && isCompleted && (
             <button
               onClick={handleCopy}
               className={`absolute top-2 right-2 p-1.5 rounded-lg border transition-all duration-200 cursor-pointer ${
                 copied
                   ? 'bg-emerald-500/10 border-emerald-500/20 text-emerald-500 dark:text-emerald-400'
-                  : 'bg-slate-500/5 hover:bg-slate-500/10 border-slate-200 dark:border-white/10 text-slate-400 dark:text-white/30 hover:text-slate-600 dark:hover:text-white/60'
+                  : 'bg-white/60 dark:bg-white/5 hover:bg-white dark:hover:bg-white/10 border-slate-200/60 dark:border-white/10 text-slate-300 dark:text-white/20 hover:text-slate-600 dark:hover:text-white/60 hover:border-slate-300 dark:hover:border-white/20'
               } opacity-0 group-hover:opacity-100 backdrop-blur-sm shadow-sm scale-95 group-hover:scale-100`}
-              title={copied ? "Copied!" : "Copy response"}
+              title={copied ? 'Copied!' : 'Copy response'}
             >
               {copied ? <Check className="w-3.5 h-3.5" /> : <Copy className="w-3.5 h-3.5" />}
             </button>
           )}
+
           {isStreaming && !message.content ? (
             <span className="flex items-center gap-1 py-1">
               <span className="w-1.5 h-1.5 rounded-full bg-slate-400 dark:bg-white/60 animate-bounce [animation-delay:0ms]" />
@@ -255,28 +354,20 @@ export function MessageBubble({
                 </ReactMarkdown>
               )}
 
-              {/* Fix: Always show streaming cursor when isStreaming is true */}
               {isStreaming && (
-                <span className="inline-flex items-center gap-1.5 ml-2 text-emerald-500 animate-pulse align-middle text-xs font-medium">
-                  <HourglassLoader
-                    size={18}
-                    primaryColor={primaryColor}
-                    accentColor={accentColor}
-                    glow={false} />
-                  Thinking...
-                </span>
+                <span 
+                  className="inline-block w-2.5 h-4 ml-1.5 animate-[pulse_1.2s_infinite] align-middle rounded-sm"
+                  style={{ backgroundColor: primaryColor }}
+                />
               )}
             </div>
           )}
         </div>
 
-        {/* Auto-generated visualization — show eagerly during streaming if sources are available */}
+        {/* Auto-generated visualization */}
         {(() => {
           if (isUser || structuredContent.payload) return null;
 
-          // During streaming: if we have sources but no uiTransformation yet,
-          // eagerly render a skeleton carousel for product queries so the user
-          // sees something immediately instead of waiting for the metadata frame.
           if (isStreaming && !message.uiTransformation && sources && sources.length > 0) {
             const hasProductSource = sources.some(s =>
               s.metadata && Object.keys(s.metadata).some(k =>
@@ -301,7 +392,7 @@ export function MessageBubble({
           if (!message.uiTransformation) return null;
           const ui = message.uiTransformation as UITransformationResponse;
           const textContent = (ui.data as { content?: string })?.content ?? '';
-          
+
           const isNegativeOrFallbackText =
             textContent.toLowerCase().includes('cannot answer') ||
             textContent.toLowerCase().includes('no relevant data') ||
@@ -315,7 +406,7 @@ export function MessageBubble({
              !['text', 'table'].includes(ui.type) ||
              (ui.type === 'text' && !hasRichUI && allProducts.length === 0 && textContent &&
               !processedMarkdown.toLowerCase().includes(textContent.trim().toLowerCase())));
-              
+
           if (!shouldShow) return null;
           return (
             <div className="w-full mt-3">
@@ -330,7 +421,6 @@ export function MessageBubble({
           );
         })()}
 
-
         {/* Product Carousel */}
         {!isUser && !hasRichUI && !shouldSuppressProductCarousel && allProducts.length > 0 && (
           <div className="w-full mt-1">
@@ -342,28 +432,50 @@ export function MessageBubble({
           </div>
         )}
 
-        {/* Footer actions: Sources and Trace */}
+        {/* Footer actions: Sources, Trace, Timestamp & Feedback */}
         {!isUser && (
-          <div className="flex items-center gap-4 mt-1 w-full flex-wrap">
+          <div className={`flex items-center gap-3 mt-1.5 w-full flex-wrap ${isCompact ? 'gap-2' : 'gap-3'}`}>
+            {/* Sources toggle */}
             {sources && sources.length > 0 && (
               <button
                 onClick={() => setShowSources(s => !s)}
-                className="text-[11px] text-indigo-400 hover:text-indigo-300 transition-colors flex items-center gap-1"
+                className="text-[11px] text-indigo-400 hover:text-indigo-300 dark:text-indigo-400/70 dark:hover:text-indigo-300 transition-colors flex items-center gap-1 font-medium"
               >
                 {showSources ? <ChevronDown className="w-3 h-3" /> : <ChevronRight className="w-3 h-3" />}
-                {sources.length} source{sources.length !== 1 ? 's' : ''} used
+                {sources.length} source{sources.length !== 1 ? 's' : ''}
               </button>
             )}
 
+            {/* Trace toggle */}
             {message.trace && (
               <button
                 onClick={() => setShowTrace(t => !t)}
-                className="text-[11px] text-emerald-500 hover:text-emerald-400 transition-colors flex items-center gap-1"
+                className="text-[11px] text-emerald-500/70 hover:text-emerald-400 dark:text-emerald-500/50 dark:hover:text-emerald-400 transition-colors flex items-center gap-1 font-medium"
               >
                 <Activity className="w-3 h-3" />
-                {showTrace ? 'Hide Trace' : 'Trace'}
+                {showTrace ? 'Hide trace' : 'Trace'}
               </button>
             )}
+
+            {/* Spacer */}
+            <div className="flex-1" />
+
+            {/* Timestamp */}
+            {timeLabel && isCompleted && (
+              <span className="flex items-center gap-1 text-[10px] text-slate-300 dark:text-white/20 font-medium select-none">
+                <Clock className="w-2.5 h-2.5" />
+                {timeLabel}
+              </span>
+            )}
+
+            {/* Feedback thumbs — only for completed, non-user messages with an ID */}
+            {isCompleted && onFeedback && message.id && (
+              <FeedbackBar
+                messageId={message.id}
+                onFeedback={onFeedback}
+                primaryColor={primaryColor}
+              />
+            )}
           </div>
         )}
 

package/src/components/constants.tsx

@@ -0,0 +1,279 @@
+import React from 'react';
+import {
+  Zap,
+  Database,
+  Layers,
+  Search,
+  Box,
+  Package,
+  Activity,
+  Hexagon,
+  Sparkles,
+  Bot,
+  Brain,
+  Rabbit,
+  Code,
+  Terminal,
+  FileText,
+  Puzzle,
+  MessageSquare,
+  Cpu,
+  Cloud,
+} from 'lucide-react';
+import { ArchitectureCardProps, Snippet, PipelineStep, ProviderPill } from '../types';
+
+export const LANDING_PAGE_CONTENT = {
+  hero: {
+    badge: 'Dynamic & Universal Retrivora AI',
+    title: 'The Universal Bridge for Generative AI',
+    subtitle: 'Retrivora AI is a vendor-agnostic RAG engine that connects any Document to any LLM and Vector Database in minutes.',
+  },
+  lifecycle: {
+    title: 'The RAG Lifecycle',
+  },
+  guide: {
+    title: 'Interactive Guide',
+    subtitle: 'Universal RAG integration for your Next.js applications in minutes.',
+  }
+};
+
+export const VECTOR_DATABASES: ProviderPill[] = [
+  { Icon: Zap, label: 'Pinecone' },
+  { Icon: Database, label: 'PostgreSQL' },
+  { Icon: Layers, label: 'MongoDB' },
+  { Icon: Box, label: 'Qdrant' },
+  { Icon: Search, label: 'Milvus' },
+  { Icon: Package, label: 'ChromaDB' },
+  { Icon: Activity, label: 'Redis' },
+  { Icon: Hexagon, label: 'Weaviate' },
+];
+
+export const AI_MODELS: ProviderPill[] = [
+  { Icon: Rabbit, label: 'Ollama' },
+  { Icon: Sparkles, label: 'OpenAI' },
+  { Icon: Bot, label: 'Anthropic' },
+  { Icon: Brain, label: 'Gemini' },
+  { Icon: Cpu, label: 'Groq' },
+  { Icon: Cloud, label: 'Qwen' },
+  { Icon: Code, label: 'Copilot' },
+  { Icon: Terminal, label: 'LiteLLM' },
+];
+
+export const PIPELINE_STEPS: PipelineStep[] = [
+  {
+    step: '01',
+    Icon: FileText,
+    title: 'Ingest',
+    desc: 'Universal support for PDF, DOCX, CSV, and JSON. Documents are parsed, chunked, and embedded.',
+    colors: { from: '#10b981', to: '#14b8a6' },
+  },
+  {
+    step: '02',
+    Icon: Search,
+    title: 'Retrieve',
+    desc: 'Queries are converted to vectors. Semantic search finds context across any configured Vector DB.',
+    colors: { from: '#14b8a6', to: '#06b6d4' },
+  },
+  {
+    step: '03',
+    Icon: Puzzle,
+    title: 'Augment',
+    desc: 'Retrieved context is injected into the LLM prompt with namespaced project isolation.',
+    colors: { from: '#06b6d4', to: '#3b82f6' },
+  },
+  {
+    step: '04',
+    Icon: MessageSquare,
+    title: 'Generate',
+    desc: 'Providers like OpenAI, Anthropic, or Gemini produce grounded, source-cited responses.',
+    colors: { from: '#3b82f6', to: '#6366f1' },
+  },
+];
+
+export const SNIPPETS: Snippet[] = [
+  {
+    id: 'pipeline',
+    title: 'Retrivora SDK',
+    language: 'typescript',
+    description: 'Create one server-side SDK instance from config; clients never know which providers are used.',
+    code: `import { Retrivora } from '@retrivora-ai/rag-engine/server';
+
+const ai = new Retrivora({
+  projectId: 'support-app',
+  llm: {
+    provider: 'openai',
+    model: 'gpt-5',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+  embedding: {
+    provider: 'openai',
+    model: 'text-embedding-3-small',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+  vectorDatabase: {
+    provider: 'pinecone',
+    indexName: 'support-docs',
+    options: { apiKey: process.env.PINECONE_API_KEY },
+  },
+  retrieval: { strategy: 'hybrid', topK: 5 },
+  workflow: { type: 'agentic-rag' },
+});
+
+await ai.ingest([{
+  docId: 'doc-1',
+  content: 'Retrivora AI simplifies RAG...',
+  metadata: { source: 'docs' }
+}]);
+
+const { reply, sources } = await ai.ask('How does Retrivora work?');`,
+  },
+  {
+    id: 'handlers',
+    title: 'Next.js Routes',
+    language: 'typescript',
+    description: 'Keep secrets and provider code in App Router handlers, then expose simple API endpoints to React.',
+    code: `// app/api/chat/route.ts
+import { Retrivora, createStreamHandler } from '@retrivora-ai/rag-engine/server';
+
+const ai = new Retrivora({
+  projectId: 'support-app',
+  llm: { provider: 'openai', model: 'gpt-5', apiKey: process.env.OPENAI_API_KEY },
+  embedding: { provider: 'openai', model: 'text-embedding-3-small', apiKey: process.env.OPENAI_API_KEY },
+  vectorDatabase: {
+    provider: 'pinecone',
+    indexName: 'support-docs',
+    options: { apiKey: process.env.PINECONE_API_KEY },
+  },
+});
+
+export const POST = createStreamHandler(ai.config);
+
+// app/api/upload/route.ts
+// export const POST = createUploadHandler(ai.config);`,
+  },
+  {
+    id: 'ui',
+    title: 'React Client UI',
+    language: 'typescript',
+    description: 'Import browser-safe components in Client Components; API keys stay on the server.',
+    code: `'use client';
+
+import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
+
+export default function Layout({ children }) {
+  return (
+    <ConfigProvider
+      config={{
+        projectId: 'support-app',
+        ui: {
+          title: 'AI Assistant',
+          showSources: true,
+          allowUpload: true,
+        },
+      }}
+    >
+      {children}
+      <ChatWidget position="bottom-right" />
+    </ConfigProvider>
+  );
+}`,
+  },
+  {
+    id: 'config',
+    title: 'Headless Hook',
+    language: 'typescript',
+    description: 'Build your own chat surface with the same server-backed route.',
+    code: `'use client';
+
+import React from 'react';
+import { useRagChat } from '@retrivora-ai/rag-engine';
+
+export function AskBox() {
+  const [input, setInput] = React.useState('');
+  const { messages, send, isLoading } = useRagChat('support-app', {
+    apiUrl: '/api/chat',
+  });
+
+  return (
+    <form onSubmit={(event) => {
+      event.preventDefault();
+      send(input);
+      setInput('');
+    }}>
+      <input value={input} onChange={(event) => setInput(event.target.value)} />
+      <button disabled={isLoading}>Ask</button>
+
+      {messages.map((message) => (
+        <p key={message.id}>{message.content}</p>
+      ))}
+    </form>
+  );
+}`,
+  },
+  {
+    id: 'env',
+    title: 'Environment',
+    language: 'bash',
+    description: 'The exact environment variable structure required for auto-configuration.',
+    code: `# Project Identity
+RAG_PROJECT_ID=my-project
+
+# Vector DB
+VECTOR_DB_PROVIDER=pinecone
+PINECONE_API_KEY=pcsk_...
+VECTOR_DB_INDEX=products
+
+# AI Services
+LLM_PROVIDER=openai
+LLM_MODEL=gpt-4o
+OPENAI_API_KEY=sk-...`,
+  },
+];
+
+export const ARCHITECTURE_CARDS: ArchitectureCardProps[] = [
+  {
+    icon: <Database className="text-indigo-600" />,
+    title: 'Vector Store',
+    description: 'Universal support for Pinecone, PGVector, MongoDB, Milvus, Qdrant, and more.',
+    badge: 'Vector DB',
+    badgeColor: 'bg-indigo-50 dark:bg-indigo-500/10 text-indigo-600 dark:text-indigo-400 border-indigo-200 dark:border-indigo-500/20',
+  },
+  {
+    icon: <Zap className="text-amber-500" />,
+    title: 'Embeddings',
+    description: 'Seamlessly switch between OpenAI, Ollama, or custom embedding providers.',
+    badge: 'Models',
+    badgeColor: 'bg-amber-50 dark:bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-200 dark:border-amber-500/20',
+  },
+  {
+    icon: <Bot className="text-emerald-500" />,
+    title: 'LLM Orchestration',
+    description: 'Optimized inference across OpenAI, Anthropic, Gemini, and local LLMs.',
+    badge: 'Inference',
+    badgeColor: 'bg-emerald-50 dark:bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border-emerald-200 dark:border-emerald-500/20',
+  },
+];
+
+export const QUICK_START_STEPS = [
+  'Install @retrivora-ai/rag-engine',
+  'Configure your .env.local',
+  'Mount the API handlers',
+  'Drop the ChatWidget'
+];
+
+export const API_ENDPOINTS = ['chat', 'health', 'ingest', 'upload'];
+
+export const CHAT_SUGGESTIONS = [
+  'What can you help me with?',
+  'Summarise the key topics',
+  'Show me an example'
+];
+
+export const BORDER_RADIUS_MAP: Record<string, string> = {
+  none: 'rounded-none',
+  sm: 'rounded-sm',
+  md: 'rounded-md',
+  lg: 'rounded-lg',
+  xl: 'rounded-xl',
+  full: 'rounded-3xl',
+};