@retrivora-ai/rag-engine 1.9.6 → 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/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',
+};

package/src/config/RagConfig.ts

@@ -202,16 +202,16 @@ export interface RAGConfig {
 export interface RetrievalConfig {
   /** Retrieval strategy selected by the host app. */
   strategy?:
-    | 'vector'
-    | 'keyword'
-    | 'hybrid'
-    | 'multi-query'
-    | 'self-query'
-    | 'parent-document'
-    | 'contextual-compression'
-    | 'ensemble'
-    | 'recursive'
-    | 'agentic';
+  | 'vector'
+  | 'keyword'
+  | 'hybrid'
+  | 'multi-query'
+  | 'self-query'
+  | 'parent-document'
+  | 'contextual-compression'
+  | 'ensemble'
+  | 'recursive'
+  | 'agentic';
   /** Number of documents/chunks retrieved per query. */
   topK?: number;
   /** Minimum similarity score to include a retrieved chunk. */

package/src/config/constants.ts

@@ -4,6 +4,7 @@
  * This file serves as the single source of truth for all statically supported
  * providers and stylistic options in the Retrivora AI RAG Engine.
  */
+export const VERSION = '1.9.6';
 
 export const VECTOR_DB_PROVIDERS = [
   'pinecone',

package/src/core/ConfigResolver.ts

@@ -9,7 +9,6 @@
 import { RagConfig, UniversalRagConfig, RAGConfig, RetrievalConfig, WorkflowConfig } from '../config/RagConfig';
 import { mergeDefined } from '../utils/templateUtils';
 import { getEnvConfig } from '../config/serverConfig';
-import { ConfigurationException } from '../exceptions';
 
 
 
@@ -32,33 +31,33 @@ export class ConfigResolver {
       projectId: hostConfig.projectId || envConfig.projectId,
       vectorDb: hostConfig.vectorDb
         ? {
-            ...envConfig.vectorDb,
-            ...hostConfig.vectorDb,
-            options: {
-              ...envConfig.vectorDb.options,
-              ...(hostConfig.vectorDb.options || {}),
-            },
-          }
+          ...envConfig.vectorDb,
+          ...hostConfig.vectorDb,
+          options: {
+            ...envConfig.vectorDb.options,
+            ...(hostConfig.vectorDb.options || {}),
+          },
+        }
         : envConfig.vectorDb,
       llm: hostConfig.llm
         ? {
-            ...envConfig.llm,
-            ...hostConfig.llm,
-            options: {
-              ...(envConfig.llm.options || {}),
-              ...(hostConfig.llm.options || {}),
-            },
-          }
+          ...envConfig.llm,
+          ...hostConfig.llm,
+          options: {
+            ...(envConfig.llm.options || {}),
+            ...(hostConfig.llm.options || {}),
+          },
+        }
         : envConfig.llm,
       embedding: hostConfig.embedding
         ? {
-            ...envConfig.embedding,
-            ...hostConfig.embedding,
-            options: {
-              ...(envConfig.embedding.options || {}),
-              ...(hostConfig.embedding.options || {}),
-            },
-          }
+          ...envConfig.embedding,
+          ...hostConfig.embedding,
+          options: {
+            ...(envConfig.embedding.options || {}),
+            ...(hostConfig.embedding.options || {}),
+          },
+        }
         : envConfig.embedding,
       ui: hostConfig.ui ? mergeDefined(envConfig.ui, hostConfig.ui) : envConfig.ui,
       rag: hostConfig.rag ? { ...envConfig.rag, ...hostConfig.rag } : envConfig.rag,
@@ -87,13 +86,13 @@ export class ConfigResolver {
    */
   static validate(config: RagConfig): void {
     if (!config.projectId) {
-      throw new ConfigurationException('[ConfigResolver] projectId is required');
+      throw new Error('[ConfigResolver] projectId is required');
     }
     if (!config.vectorDb.provider) {
-      throw new ConfigurationException('[ConfigResolver] vectorDb.provider is required');
+      throw new Error('[ConfigResolver] vectorDb.provider is required');
     }
     if (!config.llm.provider) {
-      throw new ConfigurationException('[ConfigResolver] llm.provider is required');
+      throw new Error('[ConfigResolver] llm.provider is required');
     }
   }
 

package/src/core/Pipeline.ts

@@ -2,6 +2,7 @@ import { BaseVectorProvider } from '../providers/vectordb/BaseVectorProvider';
 import { BaseGraphProvider } from '../providers/graphdb/BaseGraphProvider';
 import { ILLMProvider } from '../llm/ILLMProvider';
 import { ChatMessage } from '../types';
+import { EmbeddingFailedException } from '../exceptions';
 import { DocumentChunker, Chunk } from '../rag/DocumentChunker';
 import { EntityExtractor } from '../rag/EntityExtractor';
 import { Reranker } from '../rag/Reranker';
@@ -327,7 +328,7 @@ You are a helpful assistant. Use the provided context to answer questions accura
     );
 
     if (vectors.length !== chunks.length) {
-      throw new Error(
+      throw new EmbeddingFailedException(
         `[Pipeline] Embedding mismatch: got ${vectors.length} vectors for ${chunks.length} chunks. ` +
         `Check embedding provider logs for individual chunk failures.`
       );

package/src/core/ProviderRegistry.ts

@@ -10,7 +10,7 @@ import { ProviderNotFoundException } from '../exceptions';
  * ProviderRegistry — dynamic provider loader for Vector DBs and LLMs.
  */
 type VectorProviderClass = {
-  new (config: VectorDBConfig): BaseVectorProvider;
+  new(config: VectorDBConfig): BaseVectorProvider;
   getValidator?: () => IProviderValidator;
   getHealthChecker?: () => IProviderHealthChecker;
 };
@@ -20,10 +20,10 @@ type GraphProviderClass = new (config: GraphDBConfig) => BaseGraphProvider;
 export class ProviderRegistry {
   private static vectorProviders: Record<string, VectorProviderClass> = {};
   private static graphProviders: Record<string, GraphProviderClass> = {};
-  
+
   private static vectorValidators: Record<string, IProviderValidator> = {};
   private static vectorHealthCheckers: Record<string, IProviderHealthChecker> = {};
-  
+
   private static llmValidators: Record<string, IProviderValidator> = {};
   private static llmHealthCheckers: Record<string, IProviderHealthChecker> = {};
 
@@ -39,7 +39,7 @@ export class ProviderRegistry {
 
   static async getVectorValidator(provider: string): Promise<IProviderValidator | null> {
     if (this.vectorValidators[provider]) return this.vectorValidators[provider];
-    
+
     // Try to load built-in validator
     try {
       const providerClass = await this.loadVectorProviderClass(provider);
@@ -55,7 +55,7 @@ export class ProviderRegistry {
 
   static async getVectorHealthChecker(provider: string): Promise<IProviderHealthChecker | null> {
     if (this.vectorHealthCheckers[provider]) return this.vectorHealthCheckers[provider];
-    
+
     try {
       const providerClass = await this.loadVectorProviderClass(provider);
       if (providerClass.getHealthChecker) {