@retrivora-ai/rag-engine 1.9.3 → 1.9.7

package/src/components/DocViewer.tsx

@@ -4,8 +4,28 @@ import React from 'react';
 import { Snippet } from '@/app/types';
 import { SNIPPETS } from '@/app/constants';
 import { CodeViewer } from './CodeViewer';
+import { ArrowLeft, ArrowRight } from 'lucide-react';
 
 export function DocViewer({ activeSnippet, setActiveSnippet }: { activeSnippet: Snippet, setActiveSnippet: (s: Snippet) => void }) {
+  const currentIndex = SNIPPETS.findIndex((s) => s.id === activeSnippet.id);
+  const totalSteps = SNIPPETS.length;
+  const isFirst = currentIndex === 0;
+  const isLast = currentIndex === totalSteps - 1;
+
+  const handlePrev = () => {
+    if (!isFirst) {
+      setActiveSnippet(SNIPPETS[currentIndex - 1]);
+    }
+  };
+
+  const handleNext = () => {
+    if (!isLast) {
+      setActiveSnippet(SNIPPETS[currentIndex + 1]);
+    }
+  };
+
+  const progressPercent = Math.round(((currentIndex + 1) / totalSteps) * 100);
+
   return (
     <>
       <div className="mb-6 flex flex-wrap gap-2 border-b border-slate-100 dark:border-white/5 pb-6">
@@ -23,14 +43,60 @@ export function DocViewer({ activeSnippet, setActiveSnippet }: { activeSnippet:
         ))}
       </div>
 
+      {/* Visual Progress Bar */}
+      <div className="mb-6 bg-slate-100 dark:bg-white/5 rounded-full h-2.5 overflow-hidden border border-slate-200/50 dark:border-white/5 relative">
+        <div 
+          className="h-full bg-gradient-to-r from-indigo-500 via-indigo-600 to-violet-600 transition-all duration-500 rounded-full shadow-[0_0_8px_rgba(99,102,241,0.5)]"
+          style={{ width: `${progressPercent}%` }}
+        />
+      </div>
+
       <div className="flex-grow flex flex-col gap-6 animate-in fade-in slide-in-from-bottom-2 duration-500">
-        <div className="max-w-2xl">
-          <h3 className="text-xl font-bold text-slate-900 dark:text-white mb-2">{activeSnippet.title}</h3>
-          <p className="text-sm text-slate-500 dark:text-white/40 leading-relaxed font-medium italic">
-            {activeSnippet.description}
-          </p>
+        <div className="max-w-2xl flex items-start justify-between gap-4 flex-wrap sm:flex-nowrap">
+          <div>
+            <h3 className="text-xl font-bold text-slate-900 dark:text-white mb-2 flex items-center gap-3">
+              {activeSnippet.title}
+              <span className="text-[10px] font-extrabold uppercase px-2 py-0.5 rounded bg-indigo-50 dark:bg-indigo-500/10 border border-indigo-100 dark:border-indigo-500/20 text-indigo-600 dark:text-indigo-400">
+                Step {currentIndex + 1} of {totalSteps}
+              </span>
+            </h3>
+            <p className="text-sm text-slate-500 dark:text-white/40 leading-relaxed font-medium italic">
+              {activeSnippet.description}
+            </p>
+          </div>
+          <span className="text-xs font-mono font-bold text-indigo-600 dark:text-indigo-400 self-center shrink-0">
+            {progressPercent}% Complete
+          </span>
         </div>
+        
         <CodeViewer snippet={activeSnippet} />
+
+        {/* Next/Prev Navigation */}
+        <div className="flex items-center justify-between border-t border-slate-200 dark:border-white/10 pt-6 mt-4">
+          <button
+            onClick={handlePrev}
+            disabled={isFirst}
+            className={`flex items-center gap-2 px-5 py-2.5 rounded-xl text-xs font-bold transition-all border ${
+              isFirst
+                ? 'opacity-40 cursor-not-allowed border-slate-200 dark:border-white/5 text-slate-400 dark:text-white/20 bg-slate-50 dark:bg-transparent'
+                : 'bg-white dark:bg-white/5 border-slate-200 dark:border-white/10 text-slate-700 dark:text-white/70 hover:border-slate-300 dark:hover:border-white/20 active:scale-95'
+            }`}
+          >
+            <ArrowLeft size={14} /> Previous Step
+          </button>
+          
+          <button
+            onClick={handleNext}
+            disabled={isLast}
+            className={`flex items-center gap-2 px-6 py-2.5 rounded-xl text-xs font-bold transition-all border ${
+              isLast
+                ? 'opacity-40 cursor-not-allowed border-slate-200 dark:border-white/5 text-slate-400 dark:text-white/20 bg-slate-50 dark:bg-transparent'
+                : 'bg-indigo-600 text-white border-indigo-600 hover:bg-indigo-700 hover:border-indigo-700 active:scale-95 shadow-md shadow-indigo-500/10'
+            }`}
+          >
+            {isLast ? 'Complete!' : 'Next Step'} <ArrowRight size={14} />
+          </button>
+        </div>
       </div>
     </>
   );

package/src/components/Documentation.tsx

@@ -1,9 +1,9 @@
 'use client';
 
 import React from 'react';
-import { FileText, Zap, Package, ExternalLink } from 'lucide-react';
+import { FileText, Zap, Package, ExternalLink, Code } from 'lucide-react';
 import { DocViewer } from '@/components/DocViewer';
-import { LANDING_PAGE_CONTENT, QUICK_START_STEPS, API_ENDPOINTS, SNIPPETS } from '@/app/constants';
+import { LANDING_PAGE_CONTENT, QUICK_START_STEPS, ADVANCED_STEPS, API_ENDPOINTS, SNIPPETS } from '@/app/constants';
 import { Snippet } from '@/app/types';
 
 export function Documentation() {
@@ -16,20 +16,83 @@ export function Documentation() {
         <p className="text-slate-600 dark:text-white/40 max-w-2xl mx-auto">{LANDING_PAGE_CONTENT.guide.subtitle}</p>
       </div>
       <div className="relative z-10 w-full grid gap-16 lg:grid-cols-[280px_1fr] items-start">
-        <aside className="flex flex-col gap-10">
+        <aside className="flex flex-col gap-8">
           <section>
-            <h2 className="mb-6 text-[10px] font-black text-slate-400 dark:text-white/30 uppercase tracking-[0.3em] flex items-center gap-3">
+            <h2 className="mb-4 text-[10px] font-black text-slate-400 dark:text-white/30 uppercase tracking-[0.3em] flex items-center gap-3">
               <FileText size={14} className="text-indigo-500" /> Quick Start
             </h2>
-            <ol className="space-y-6">
-              {QUICK_START_STEPS.map((step, i) => (
-                <li key={i} className="group flex items-start gap-4">
-                  <span className="flex h-6 w-6 shrink-0 items-center justify-center rounded-lg bg-white dark:bg-white/5 text-slate-600 dark:text-white/40 font-mono text-[10px] border border-slate-200 dark:border-white/10 shadow-sm">{i + 1}</span>
-                  <span className="text-xs text-slate-500 dark:text-white/50 font-medium leading-relaxed pt-1">{step}</span>
-                </li>
-              ))}
+            <ol className="space-y-2.5">
+              {QUICK_START_STEPS.map((step, i) => {
+                const isActive = activeSnippet.id === step.id;
+                return (
+                  <li key={step.id}>
+                    <button
+                      onClick={() => {
+                        const snip = SNIPPETS.find((s) => s.id === step.id);
+                        if (snip) setActiveSnippet(snip);
+                      }}
+                      className={`w-full flex items-start gap-4 p-3 rounded-xl border text-left transition-all active:scale-[0.98] ${
+                        isActive
+                          ? 'bg-indigo-500/10 dark:bg-indigo-500/10 border-indigo-200 dark:border-indigo-500/30'
+                          : 'bg-white dark:bg-white/3 border-slate-200 dark:border-white/5 hover:border-slate-300 dark:hover:border-white/10 hover:bg-slate-50 dark:hover:bg-white/5 shadow-sm'
+                      }`}
+                    >
+                      <span className={`flex h-6 w-6 shrink-0 items-center justify-center rounded-lg font-mono text-[10px] font-bold border transition-all ${
+                        isActive
+                          ? 'bg-indigo-600 text-white border-indigo-600 shadow-md shadow-indigo-500/20'
+                          : 'bg-slate-100 dark:bg-white/5 text-slate-600 dark:text-white/40 border-slate-200 dark:border-white/10'
+                      }`}>{i + 1}</span>
+                      <div className="pt-0.5">
+                        <span className={`text-xs font-semibold block transition-colors ${
+                          isActive ? 'text-indigo-600 dark:text-indigo-400 font-bold' : 'text-slate-700 dark:text-white/70 font-medium'
+                        }`}>{step.text}</span>
+                        <span className="text-[9px] text-slate-400 dark:text-white/30 block mt-0.5">Step {i + 1}</span>
+                      </div>
+                    </button>
+                  </li>
+                );
+              })}
+            </ol>
+          </section>
+
+          <section>
+            <h2 className="mb-4 text-[10px] font-black text-slate-400 dark:text-white/30 uppercase tracking-[0.3em] flex items-center gap-3">
+              <Code size={14} className="text-violet-500" /> Advanced Options
+            </h2>
+            <ol className="space-y-2.5">
+              {ADVANCED_STEPS.map((step, i) => {
+                const isActive = activeSnippet.id === step.id;
+                return (
+                  <li key={step.id}>
+                    <button
+                      onClick={() => {
+                        const snip = SNIPPETS.find((s) => s.id === step.id);
+                        if (snip) setActiveSnippet(snip);
+                      }}
+                      className={`w-full flex items-start gap-4 p-3 rounded-xl border text-left transition-all active:scale-[0.98] ${
+                        isActive
+                          ? 'bg-violet-500/10 dark:bg-violet-500/10 border-violet-200 dark:border-violet-500/30'
+                          : 'bg-white dark:bg-white/3 border-slate-200 dark:border-white/5 hover:border-slate-300 dark:hover:border-white/10 hover:bg-slate-50 dark:hover:bg-white/5 shadow-sm'
+                      }`}
+                    >
+                      <span className={`flex h-6 w-6 shrink-0 items-center justify-center rounded-lg font-mono text-[10px] font-bold border transition-all ${
+                        isActive
+                          ? 'bg-violet-600 text-white border-violet-600 shadow-md shadow-violet-500/20'
+                          : 'bg-slate-100 dark:bg-white/5 text-slate-600 dark:text-white/40 border-slate-200 dark:border-white/10'
+                      }`}>{i + 5}</span>
+                      <div className="pt-0.5">
+                        <span className={`text-xs font-semibold block transition-colors ${
+                          isActive ? 'text-violet-600 dark:text-violet-400 font-bold' : 'text-slate-700 dark:text-white/70 font-medium'
+                        }`}>{step.text}</span>
+                        <span className="text-[9px] text-slate-400 dark:text-white/30 block mt-0.5">Extension</span>
+                      </div>
+                    </button>
+                  </li>
+                );
+              })}
             </ol>
           </section>
+
           <section className="rounded-2xl border border-slate-200 dark:border-white/10 bg-white dark:bg-white/3 p-6 shadow-sm">
             <h2 className="mb-6 text-[10px] font-black text-slate-400 dark:text-white/30 uppercase tracking-[0.3em] flex items-center gap-3">
               <Zap size={14} className="text-indigo-500" /> API Endpoints

package/src/components/MessageBubble.tsx

@@ -21,6 +21,7 @@ import {
 } from '../utils/ProductExtractor';
 import { createMarkdownComponents } from './MarkdownComponents';
 import { UIDispatcher } from './UIDispatcher';
+import { ThinkingBlock } from './ThinkingBlock';
 
 function normalizePlusSeparatedLists(raw: string): string {
   return raw
@@ -196,6 +197,15 @@ export function MessageBubble({
       </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'}`}>
+        {/* Thinking Steps */}
+        {!isUser && message.thinking && (
+          <ThinkingBlock
+            thinking={message.thinking}
+            thinkingMs={message.thinkingMs}
+            isStreaming={isStreaming && !message.content}
+          />
+        )}
+
         {/* 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
@@ -260,9 +270,35 @@ export function MessageBubble({
           )}
         </div>
 
-        {/* Auto-generated visualization fallback */}
+        {/* Auto-generated visualization — show eagerly during streaming if sources are available */}
         {(() => {
-          if (isUser || structuredContent.payload || !message.uiTransformation) return null;
+          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 =>
+                ['name','title','price','brand','image','product','sku','category'].includes(k.toLowerCase())
+              )
+            );
+            if (hasProductSource) {
+              return (
+                <div className="w-full mt-3">
+                  <VisualizationRenderer
+                    data={{ type: 'product_carousel', title: 'Recommended Products', description: 'Loading...', data: [] }}
+                    primaryColor={primaryColor}
+                    onAddToCart={onAddToCart}
+                    className="rounded-3xl border border-slate-200/60 dark:border-white/10 bg-white/90 dark:bg-slate-900/80 p-4"
+                    isStreaming={true}
+                  />
+                </div>
+              );
+            }
+          }
+
+          if (!message.uiTransformation) return null;
           const ui = message.uiTransformation as UITransformationResponse;
           const textContent = (ui.data as { content?: string })?.content ?? '';
           
@@ -294,6 +330,7 @@ export function MessageBubble({
           );
         })()}
 
+
         {/* Product Carousel */}
         {!isUser && !hasRichUI && !shouldSuppressProductCarousel && allProducts.length > 0 && (
           <div className="w-full mt-1">

package/src/components/ThinkingBlock.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import React, { useState, useEffect, useRef } from 'react';
+import { Brain, ChevronDown, ChevronRight, Loader2 } from 'lucide-react';
+
+interface ThinkingBlockProps {
+  thinking: string;
+  thinkingMs?: number;
+  isStreaming?: boolean;
+}
+
+export function ThinkingBlock({ thinking, thinkingMs, isStreaming = false }: ThinkingBlockProps) {
+  const [isExpanded, setIsExpanded] = useState(true);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Collapse by default when streaming finishes
+  useEffect(() => {
+    if (!isStreaming) {
+      setIsExpanded(false);
+    } else {
+      setIsExpanded(true);
+    }
+  }, [isStreaming]);
+
+  // Auto-scroll thinking container while streaming
+  useEffect(() => {
+    if (isStreaming && isExpanded && containerRef.current) {
+      containerRef.current.scrollTop = containerRef.current.scrollHeight;
+    }
+  }, [thinking, isStreaming, isExpanded]);
+
+  const durationSec = thinkingMs ? (thinkingMs / 1000).toFixed(1) : null;
+
+  return (
+    <div className="w-full max-w-2xl my-1.5 border border-slate-200 dark:border-white/10 rounded-xl bg-slate-50/50 dark:bg-white/5 overflow-hidden transition-all duration-200">
+      {/* Header */}
+      <button
+        onClick={() => setIsExpanded(!isExpanded)}
+        className="w-full px-4 py-2.5 flex items-center justify-between text-xs font-medium text-slate-500 dark:text-white/40 hover:bg-slate-100 dark:hover:bg-white/10 transition-colors cursor-pointer select-none"
+      >
+        <div className="flex items-center gap-2">
+          {isStreaming ? (
+            <Loader2 className="w-3.5 h-3.5 animate-spin text-slate-400 dark:text-white/30" />
+          ) : (
+            <Brain className="w-3.5 h-3.5 text-slate-400 dark:text-white/40" />
+          )}
+          <span>
+            {isStreaming 
+              ? 'Thinking...' 
+              : durationSec 
+                ? `Thought for ${durationSec}s` 
+                : 'Thinking process'}
+          </span>
+        </div>
+        <div>
+          {isExpanded ? (
+            <ChevronDown className="w-3.5 h-3.5 text-slate-400 dark:text-white/30" />
+          ) : (
+            <ChevronRight className="w-3.5 h-3.5 text-slate-400 dark:text-white/30" />
+          )}
+        </div>
+      </button>
+
+      {/* Body */}
+      {isExpanded && (
+        <div 
+          ref={containerRef}
+          className="px-4 pb-3 pt-1 border-t border-slate-200 dark:border-white/10 text-xs font-mono leading-relaxed text-slate-600 dark:text-white/60 bg-slate-50/20 dark:bg-transparent max-h-60 overflow-y-auto whitespace-pre-wrap select-text break-words"
+        >
+          {thinking}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/VisualizationRenderer.tsx

@@ -183,7 +183,10 @@ function renderVisualization(
         return <TableView data={data as TableData} isStreaming={isStreaming} />;
       case 'product_carousel':
       case 'carousel':
+        // Show skeleton while streaming so the user sees an indicator immediately
+        if (isStreaming) return <CarouselSkeleton />;
         return <CarouselView data={data as CarouselProduct[]} onAddToCart={onAddToCart} primaryColor={primaryColor} />;
+
       case 'text':
       default:
         return <TextView data={data} />;
@@ -194,7 +197,30 @@ function renderVisualization(
   }
 }
 
-// ─── Chart Skeleton ────────────────────────────────────────────────────────────
+// ─── Carousel Skeleton ───────────────────────────────────────────────────────
+
+function CarouselSkeleton() {
+  return (
+    <div className="w-full py-2">
+      <div className="mb-3 h-4 w-36 rounded-full bg-slate-200 animate-pulse" />
+      <div className="flex gap-3 overflow-hidden">
+        {Array.from({ length: 4 }).map((_, i) => (
+          <div
+            key={i}
+            className="flex-shrink-0 w-44 rounded-2xl border border-slate-200 bg-white shadow-sm overflow-hidden animate-pulse"
+          >
+            <div className="h-28 bg-slate-100" />
+            <div className="p-3 space-y-2">
+              <div className="h-3 w-28 rounded-full bg-slate-200" />
+              <div className="h-3 w-16 rounded-full bg-slate-100" />
+              <div className="h-3 w-20 rounded-full bg-emerald-100" />
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
 
 function ChartSkeleton({ type }: { type: 'pie' | 'bar' | 'table' }) {
   if (type === 'pie') {

package/src/components/constants.tsx

@@ -0,0 +1,275 @@
+import React from 'react';
+import {
+  Zap,
+  Database,
+  Layers,
+  Search,
+  Box,
+  Package,
+  Activity,
+  Hexagon,
+  Sparkles,
+  Bot,
+  Brain,
+  Rabbit,
+  Code,
+  Terminal,
+  FileText,
+  Puzzle,
+  MessageSquare,
+} 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: 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',
+};