@retrivora-ai/rag-engine 1.9.2 → 1.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retrivora-ai/rag-engine",
-  "version": "1.9.2",
+  "version": "1.9.6",
   "description": "Retrivora AI is a plug-and-play AI engine for RAG chat experiences — generic vector DB + LLM provider, embeddable or standalone.",
   "author": "Abhinav Alkuchi",
   "license": "MIT",

package/src/app/api/chat/route.ts

@@ -1,4 +1,4 @@
 import { createStreamHandler } from '@/handlers';
-import { getRagConfig } from '@/config/serverConfig';
+import { plugin } from '@/lib/plugin';
 
-export const POST = createStreamHandler(getRagConfig());
+export const POST = createStreamHandler(plugin);

package/src/app/api/health/route.ts

@@ -1,4 +1,5 @@
 import { createHealthHandler } from '@/handlers';
-import { getRagConfig } from '@/config/serverConfig';
+import { plugin } from '@/lib/plugin';
+
+export const GET = createHealthHandler(plugin);
 
-export const GET = createHealthHandler(getRagConfig());

package/src/app/api/ingest/route.ts

@@ -21,6 +21,7 @@
  */
 
 import { createIngestHandler } from '@/handlers';
-import { getRagConfig } from '@/config/serverConfig';
+import { plugin } from '@/lib/plugin';
+
+export const POST = createIngestHandler(plugin);
 
-export const POST = createIngestHandler(getRagConfig());

package/src/app/api/suggestions/route.ts

@@ -1,4 +1,5 @@
 import { createSuggestionsHandler } from '@/handlers';
-import { getRagConfig } from '@/config/serverConfig';
+import { plugin } from '@/lib/plugin';
+
+export const POST = createSuggestionsHandler(plugin);
 
-export const POST = createSuggestionsHandler(getRagConfig());

package/src/app/api/upload/route.ts

@@ -1,4 +1,5 @@
 import { createUploadHandler } from '@/handlers';
-import { getRagConfig } from '@/config/serverConfig';
+import { plugin } from '@/lib/plugin';
+
+export const POST = createUploadHandler(plugin);
 
-export const POST = createUploadHandler(getRagConfig());

package/src/app/constants.tsx

@@ -89,49 +89,85 @@ export const PIPELINE_STEPS: PipelineStep[] = [
 export const SNIPPETS: Snippet[] = [
   {
     id: 'pipeline',
-    title: 'Pipeline API',
+    title: 'Retrivora SDK',
     language: 'typescript',
-    description: 'Orchestrate the full RAG flow programmatically with the Pipeline class.',
-    code: `import { Pipeline, getRagConfig } from '@retrivora-ai/rag-engine/server';
+    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 config = getRagConfig();
-const pipeline = new Pipeline(config);
+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' },
+});
 
-// Ingest documents
-await pipeline.ingest([{
+await ai.ingest([{
   docId: 'doc-1',
   content: 'Retrivora AI simplifies RAG...',
   metadata: { source: 'docs' }
 }]);
 
-// Ask a question
-const { reply, sources } = await pipeline.ask('How does Retrivora work?');`,
+const { reply, sources } = await ai.ask('How does Retrivora work?');`,
   },
   {
     id: 'handlers',
-    title: 'Route Handlers',
+    title: 'Next.js Routes',
     language: 'typescript',
-    description: 'Deploy production-ready API endpoints in seconds using pre-built factories.',
-    code: `import { createChatStreamHandler, createUploadHandler, getRagConfig } from '@retrivora-ai/rag-engine/server';
+    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 config = getRagConfig();
+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 },
+  },
+});
 
-// src/app/api/chat/route.ts
-export const POST = createChatStreamHandler(config);
+export const POST = createStreamHandler(ai.config);
 
-// src/app/api/upload/route.ts
-export const POST = createUploadHandler(config);`,
+// app/api/upload/route.ts
+// export const POST = createUploadHandler(ai.config);`,
   },
   {
     id: 'ui',
-    title: 'React Components',
+    title: 'React Client UI',
     language: 'typescript',
-    description: 'Embed beautiful, themeable AI interfaces with headless logic or pre-built widgets.',
-    code: `import { ConfigProvider, ChatWidget } from '@retrivora-ai/rag-engine';
+    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: 'demo' }}>
+    <ConfigProvider
+      config={{
+        projectId: 'support-app',
+        ui: {
+          title: 'AI Assistant',
+          showSources: true,
+          allowUpload: true,
+        },
+      }}
+    >
       {children}
       <ChatWidget position="bottom-right" />
     </ConfigProvider>
@@ -140,16 +176,35 @@ export default function Layout({ children }) {
   },
   {
     id: 'config',
-    title: 'Config Builder',
+    title: 'Headless Hook',
     language: 'typescript',
-    description: 'Fluent, type-safe configuration builder for granular control over providers.',
-    code: `import { ConfigBuilder } from '@retrivora-ai/rag-engine/server';
-
-const config = new ConfigBuilder()
-  .vectorDb('pinecone', { apiKey: '...', indexName: 'docs' })
-  .llm('ollama', 'llama3.2')
-  .embedding('ollama', 'nomic-embed-text')
-  .build();`,
+    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',

package/src/app/layout.tsx

@@ -7,23 +7,33 @@ import { getRagConfig } from '@/config/serverConfig';
 
 const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
 
+// Build server-side config once — same singleton source as route handlers.
+const ragConfig = getRagConfig();
+
 export const metadata: Metadata = {
-  title: 'Retrivora AI',
+  title: ragConfig.ui?.title ?? 'Retrivora AI',
   description:
+    ragConfig.ui?.subtitle ??
     'A configurable Retrieval-Augmented Generation chatbot — generic across any vector database and LLM provider.',
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
-  const clientConfig = getRagConfig();
-
   return (
     <html lang="en" className={inter.variable} suppressHydrationWarning>
-      <body className="bg-slate-50 dark:bg-[#080811] text-slate-900 dark:text-white antialiased transition-colors duration-300" suppressHydrationWarning>
-        <ThemeProvider attribute="class" defaultTheme="dark" enableSystem disableTransitionOnChange>
+      <body className="bg-slate-50 text-slate-900 antialiased transition-colors duration-300" suppressHydrationWarning>
+        <ThemeProvider attribute="class" defaultTheme="light" disableTransitionOnChange>
           <ConfigProvider
             config={{
-              projectId: clientConfig.projectId,
-              ui: clientConfig.ui,
+              projectId: ragConfig.projectId,
+              ui: ragConfig.ui,
+              // Pass embedding model/dimensions so client-side components
+              // (e.g. DocumentUpload) know the vector dimensions in use.
+              embedding: ragConfig.embedding
+                ? {
+                    model: ragConfig.embedding.model,
+                    dimensions: ragConfig.embedding.dimensions,
+                  }
+                : undefined,
             }}
           >
             {children}
@@ -33,3 +43,4 @@ export default function RootLayout({ children }: { children: React.ReactNode })
     </html>
   );
 }
+

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/config/RagConfig.ts

@@ -199,6 +199,36 @@ export interface RAGConfig {
   vectorKeywords?: string[];
 }
 
+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';
+  /** Number of documents/chunks retrieved per query. */
+  topK?: number;
+  /** Minimum similarity score to include a retrieved chunk. */
+  scoreThreshold?: number;
+  /** Whether to rerank retrieved chunks before generation. */
+  useReranking?: boolean;
+  /** Provider-specific retrieval options for future strategies. */
+  options?: Record<string, unknown>;
+}
+
+export interface WorkflowConfig {
+  /** High-level workflow selector from the SDK prompt. */
+  type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic';
+  /** Future workflow/provider-specific options. */
+  options?: Record<string, unknown>;
+}
+
 // ---------------------------------------------------------------------------
 // Root Config
 // ---------------------------------------------------------------------------
@@ -228,3 +258,20 @@ export interface RagConfig {
   /** Optional Graph database configuration */
   graphDb?: GraphDBConfig;
 }
+
+/**
+ * Friendly SDK configuration accepted by the top-level Retrivora facade.
+ * It supports the prompt's `vectorDatabase`, `retrieval`, and `workflow`
+ * naming while normalizing to the internal RagConfig shape.
+ */
+export type UniversalRagConfig =
+  Partial<Omit<RagConfig, 'vectorDb' | 'rag' | 'llm' | 'embedding' | 'graphDb'>> & {
+    vectorDb?: Partial<VectorDBConfig>;
+    vectorDatabase?: Partial<VectorDBConfig>;
+    llm?: Partial<LLMConfig>;
+    embedding?: Partial<EmbeddingConfig>;
+    graphDb?: Partial<GraphDBConfig>;
+    retrieval?: RetrievalConfig;
+    rag?: RAGConfig;
+    workflow?: WorkflowConfig;
+  };

package/src/config/serverConfig.ts

@@ -167,6 +167,8 @@ export function getEnvConfig(env: Record<string, string | undefined> = process.e
       temperature: readNumber(env, 'LLM_TEMPERATURE', 0.7),
       options: {
         profile: readString(env, 'LLM_UNIVERSAL_PROFILE'),
+        thinking: readString(env, 'LLM_THINKING') === 'true' || readString(env, 'LLM_THINKING') === 'enabled' ? true : (readString(env, 'LLM_THINKING') === 'false' ? false : undefined),
+        thinkingBudget: env.LLM_THINKING_BUDGET ? parseInt(env.LLM_THINKING_BUDGET, 10) : undefined,
       },
     },
     embedding: {
@@ -202,6 +204,29 @@ export function getEnvConfig(env: Record<string, string | undefined> = process.e
       scoreThreshold: readNumber(env, 'RAG_SCORE_THRESHOLD', 0),
       chunkSize: readNumber(env, 'RAG_CHUNK_SIZE', 1000),
       chunkOverlap: readNumber(env, 'RAG_CHUNK_OVERLAP', 200),
+      filterableFields: readString(env, 'RAG_FILTERABLE_FIELDS')?.split(',').map(f => f.trim()),
+      // Query pipeline toggles — read from .env.local
+      useQueryTransformation: readString(env, 'RAG_USE_QUERY_TRANSFORMATION') === 'true',
+      useReranking: readString(env, 'RAG_USE_RERANKING') === 'true',
+      useGraphRetrieval: readString(env, 'RAG_USE_GRAPH_RETRIEVAL') === 'true',
+      architecture: (readString(env, 'RAG_ARCHITECTURE') ?? 'simple') as 'simple' | 'graph' | 'hybrid' | 'agentic',
+      chunkingStrategy: (readString(env, 'RAG_CHUNKING_STRATEGY') ?? 'recursive') as 'recursive' | 'markdown' | 'semantic' | 'llamaindex',
+      uiMapping: (() => {
+        const raw = readString(env, 'RAG_UI_MAPPING');
+        if (!raw) return undefined;
+        try { return JSON.parse(raw) as Record<string, string>; } catch { return undefined; }
+      })(),
     },
+    // Optional graph DB — driven by GRAPH_DB_PROVIDER env var
+    ...(readString(env, 'GRAPH_DB_PROVIDER') ? {
+      graphDb: {
+        provider: readString(env, 'GRAPH_DB_PROVIDER')! as 'neo4j' | 'memgraph' | 'simple' | 'custom',
+        options: {
+          uri: readString(env, 'GRAPH_DB_URI'),
+          username: readString(env, 'GRAPH_DB_USERNAME'),
+          password: readString(env, 'GRAPH_DB_PASSWORD'),
+        },
+      },
+    } : {}),
   };
 }

package/src/core/ConfigResolver.ts

@@ -6,9 +6,10 @@
  * environment variables are only parsed once per process, avoiding
  * repeated work in serverless cold starts and per-request handler calls.
  */
-import { RagConfig } from '../config/RagConfig';
+import { RagConfig, UniversalRagConfig, RAGConfig, RetrievalConfig, WorkflowConfig } from '../config/RagConfig';
 import { mergeDefined } from '../utils/templateUtils';
 import { getEnvConfig } from '../config/serverConfig';
+import { ConfigurationException } from '../exceptions';
 
 
 
@@ -64,18 +65,69 @@ export class ConfigResolver {
     };
   }
 
+  /**
+   * Resolves the public SDK config shape used by `new Retrivora({...})`.
+   * Supports aliases from the product prompt while preserving existing env
+   * fallback behavior.
+   */
+  static resolveUniversal(hostConfig?: UniversalRagConfig, env: Record<string, string | undefined> = process.env): RagConfig {
+    if (!hostConfig) return this.resolve(undefined, env);
+
+    const normalized: Partial<RagConfig> = {
+      ...hostConfig,
+      vectorDb: hostConfig.vectorDb ?? hostConfig.vectorDatabase,
+      rag: this.mergeRetrievalWorkflow(hostConfig.rag, hostConfig.retrieval, hostConfig.workflow),
+    } as Partial<RagConfig>;
+
+    return this.resolve(normalized, env);
+  }
+
   /**
    * Validates the configuration for required fields.
    */
   static validate(config: RagConfig): void {
     if (!config.projectId) {
-      throw new Error('[ConfigResolver] projectId is required');
+      throw new ConfigurationException('[ConfigResolver] projectId is required');
     }
     if (!config.vectorDb.provider) {
-      throw new Error('[ConfigResolver] vectorDb.provider is required');
+      throw new ConfigurationException('[ConfigResolver] vectorDb.provider is required');
     }
     if (!config.llm.provider) {
-      throw new Error('[ConfigResolver] llm.provider is required');
+      throw new ConfigurationException('[ConfigResolver] llm.provider is required');
+    }
+  }
+
+  private static mergeRetrievalWorkflow(
+    rag?: RAGConfig,
+    retrieval?: RetrievalConfig,
+    workflow?: WorkflowConfig,
+  ): RAGConfig | undefined {
+    if (!rag && !retrieval && !workflow) return undefined;
+
+    const normalized: RAGConfig = { ...(rag ?? {}) };
+
+    if (retrieval) {
+      normalized.topK = retrieval.topK ?? normalized.topK;
+      normalized.scoreThreshold = retrieval.scoreThreshold ?? normalized.scoreThreshold;
+      normalized.useReranking = retrieval.useReranking ?? normalized.useReranking;
+
+      if (retrieval.strategy === 'hybrid') normalized.architecture = normalized.architecture ?? 'hybrid';
+      if (retrieval.strategy === 'agentic') normalized.architecture = 'agentic';
+      if (retrieval.strategy === 'contextual-compression') normalized.useReranking = true;
+    }
+
+    if (workflow?.type) {
+      const type = workflow.type;
+      if (type === 'agentic' || type === 'agentic-rag') normalized.architecture = 'agentic';
+      else if (type === 'hybrid-rag') normalized.architecture = 'hybrid';
+      else if (type === 'graph-rag') {
+        normalized.architecture = 'graph';
+        normalized.useGraphRetrieval = true;
+      } else if (type === 'simple-rag' || type === 'rag') {
+        normalized.architecture = normalized.architecture ?? 'simple';
+      }
     }
+
+    return normalized;
   }
 }

package/src/core/ConfigValidator.ts

@@ -4,6 +4,7 @@ import {
 } from '../config/constants';
 import { ProviderRegistry } from './ProviderRegistry';
 import { LLMFactory } from '../llm/LLMFactory';
+import { ConfigurationException } from '../exceptions';
 
 export interface ValidationError {
   field: string;
@@ -190,7 +191,7 @@ export class ConfigValidator {
       const message = errorItems
         .map((e) => `${e.field}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`)
         .join('\n  ');
-      throw new Error(`[ConfigValidator] Configuration validation failed:\n  ${message}`);
+      throw new ConfigurationException(`[ConfigValidator] Configuration validation failed:\n  ${message}`, errorItems);
     }
   }
 }