@retrivora-ai/rag-engine 1.8.9 → 1.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retrivora-ai/rag-engine",
-  "version": "1.8.9",
+  "version": "1.9.1",
   "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/components/MarkdownComponents.tsx

@@ -20,9 +20,9 @@ export function createMarkdownComponents({
   viewportSize,
 }: MarkdownComponentsProps): Components {
   return {
-    p: ({ ...props }: React.HTMLAttributes<HTMLParagraphElement>) => (
-      <p className="whitespace-pre-line" {...props} />
-    ),
+    // p: ({ ...props }: React.HTMLAttributes<HTMLParagraphElement>) => (
+    //   <p className="whitespace-pre-line" {...props} />
+    // ),
     table: ({ ...props }: React.HTMLAttributes<HTMLTableElement>) => {
       // Fix: intercept table rendering during streaming instead of using sentinel
       if (isStreaming) {

package/src/components/MessageBubble.tsx

@@ -22,6 +22,28 @@ import {
 import { createMarkdownComponents } from './MarkdownComponents';
 import { UIDispatcher } from './UIDispatcher';
 
+function normalizePlusSeparatedLists(raw: string): string {
+  return raw
+    .split('\n')
+    .map((line) => {
+      const productListLine =
+        /[—:]\s*\d+\s+\+\s+[A-Za-z]/.test(line) ||
+        /\b(products?|categories?|in stock|out of stock)\b/i.test(line);
+      if (!productListLine) return line;
+
+      return line.replace(/\s+\+\s+(?=[A-Za-z0-9])/g, ', ');
+    })
+    .join('\n');
+}
+
+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)?[^>]*>/gi, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
 // ─── Main component ───────────────────────────────────────────────────────────
 
 export function MessageBubble({
@@ -56,6 +78,11 @@ export function MessageBubble({
     return false;
   }, [message.uiTransformation, structuredContent.payload]);
 
+  const uiTransformationType = (message.uiTransformation as UITransformationResponse | undefined)?.type;
+  const shouldSuppressProductCarousel = Boolean(
+    uiTransformationType && !['text', 'product_carousel', 'carousel'].includes(uiTransformationType),
+  );
+
   const shouldRenderStructuredOnly = !isUser && hasRichUI && isLikelyUiOnlyMessage(structuredContent.text);
 
   // ── Extraction ─────────────────────────────────────────────────────────────
@@ -89,6 +116,26 @@ 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) => {
+        const trimmed = line.trim();
+        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
@@ -194,7 +241,7 @@ export function MessageBubble({
           const ui = message.uiTransformation as UITransformationResponse;
           const textContent = (ui.data as { content?: string })?.content ?? '';
           const shouldShow =
-            (ui.type === 'table' && allProducts.length === 0) ||
+            ui.type === 'table' ||
             !['text', 'table'].includes(ui.type) ||
             (ui.type === 'text' && !hasRichUI && allProducts.length === 0 && textContent &&
               !processedMarkdown.toLowerCase().includes(textContent.trim().toLowerCase()));
@@ -213,7 +260,7 @@ export function MessageBubble({
         })()}
 
         {/* Product Carousel */}
-        {!isUser && !hasRichUI && allProducts.length > 0 && (
+        {!isUser && !hasRichUI && !shouldSuppressProductCarousel && allProducts.length > 0 && (
           <div className="w-full mt-1">
             <ProductCarousel
               products={allProducts}

package/src/components/ProductCard.tsx

@@ -6,7 +6,34 @@ import { ShoppingCart, ExternalLink } from 'lucide-react';
 
 import { ProductCardProps } from '../types';
 
+function cleanProductDescription(raw: unknown): string {
+  if (raw === null || raw === undefined) return '';
+
+  const source = String(raw);
+  const bodyMatch = source.match(
+    /\bBody\s*\(HTML\)\s*:\s*([\s\S]*?)(?=\s*[,.]?\s+\b(?:Handle|Title|Vendor|Type|Tags|Published|Option\d*\s+Name|Option\d*\s+Value|Option|Variant|Image|SKU|Price|Status|Category)\b\s*:|$)/i,
+  );
+  const descriptionMatch = bodyMatch ?? source.match(
+    /\b(?:Description|Summary|Details|Body)\s*:\s*([\s\S]*?)(?=\s*[,.]?\s+\b(?:Handle|Title|Vendor|Type|Tags|Published|Option\d*\s+Name|Option\d*\s+Value|Option|Variant|Image|SKU|Price|Status|Category)\b\s*:|$)/i,
+  );
+
+  return (descriptionMatch?.[1] ?? source)
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\[[^\]]*TYPE[^\]]*\]/gi, ' ')
+    .replace(/\b(?:Handle|Title|Vendor|Type|Tags|Published|Option\d*\s+Name|Option\d*\s+Value|Option|Variant|Image|SKU|Price|Status|Category)\s*:\s*[^,.\n:]+[,.]?/gi, ' ')
+    .replace(/\bBody\s*\(HTML\)\s*:\s*/gi, ' ')
+    .replace(/\b(?:Description|Summary|Details|Body|Content)\s*:\s*/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
 export function ProductCard({ product, primaryColor = '#6366f1', onAddToCart }: ProductCardProps) {
+  const description = cleanProductDescription(product.description);
+
   return (
     <div className="flex-shrink-0 w-full bg-white dark:bg-white/5 border border-slate-200 dark:border-white/10 rounded-xl overflow-hidden shadow-sm hover:shadow-md transition-all duration-300 group">
       {/* Product Image */}
@@ -20,7 +47,7 @@ export function ProductCard({ product, primaryColor = '#6366f1', onAddToCart }:
             className="object-cover group-hover:scale-105 transition-transform duration-500"
           />
         ) : (
-          <div className="text-slate-400 dark:text-white/20">
+          <div className="text-slate-400 dark:text-white/20 cursor-pointer" onClick={() => onAddToCart?.(product)}>
             <ShoppingCart className="w-12 h-12" />
           </div>
         )}
@@ -41,23 +68,23 @@ export function ProductCard({ product, primaryColor = '#6366f1', onAddToCart }:
           </h3>
           {product.price && (
             <span className="text-sm font-bold" style={{ color: primaryColor }}>
-              {typeof product.price === 'number' 
-                ? `$${product.price}` 
+              {typeof product.price === 'number'
+                ? `$${product.price}`
                 : (String(product.price).match(/^[\d.]/) ? `$${product.price}` : product.price)}
             </span>
           )}
         </div>
 
-        {product.description && (
+        {description && (
           <p className="text-[11px] text-slate-500 dark:text-white/50 line-clamp-2 leading-relaxed">
-            {product.description}
+            {description}
           </p>
         )}
 
         <div className="mt-2 flex gap-2">
           <button
             onClick={() => onAddToCart?.(product)}
-            className="flex-1 py-2 px-3 rounded-lg text-[11px] font-medium text-white shadow-sm hover:opacity-90 transition-opacity flex items-center justify-center gap-1.5"
+            className="flex-1 py-2 px-3 rounded-lg text-[11px] font-medium text-white shadow-sm hover:opacity-90 transition-opacity flex items-center justify-center gap-1.5 cursor-pointer"
             style={{ background: primaryColor }}
           >
             <ShoppingCart className="w-3 h-3" />

package/src/components/UIDispatcher.tsx

@@ -166,6 +166,7 @@ export function UIDispatcher({ rawContent, primaryColor, accentColor, isStreamin
   onAddToCart?: (product: Product) => void;
   viewportSize?: ChatViewportSize;
 }) {
+  console.log('rawContent', rawContent);
   const result = React.useMemo<{ config: UIConfig } | { error: string } | { loading: true }>(() => {
     try {
       const clean = rawContent

package/src/components/VisualizationRenderer.tsx

@@ -9,6 +9,8 @@ import {
   Bar,
   LineChart,
   Line,
+  ScatterChart,
+  Scatter,
   XAxis,
   YAxis,
   CartesianGrid,
@@ -22,7 +24,18 @@ import {
   PolarRadiusAxis,
 } from 'recharts';
 import { ProductCarousel } from './ProductCarousel';
-import { Product, UITransformationResponse, VisualizationType, PieChartData, BarChartData, LineChartDataPoint, TableData, CarouselProduct } from '../types';
+import {
+  Product,
+  UITransformationResponse,
+  VisualizationType,
+  PieChartData,
+  BarChartData,
+  LineChartDataPoint,
+  ScatterPlotDataPoint,
+  MetricCardData,
+  TableData,
+  CarouselProduct,
+} from '../types';
 
 import { CHART_COLORS } from './DynamicChart';
 
@@ -30,6 +43,13 @@ function getColor(index: number): string {
   return CHART_COLORS[index % CHART_COLORS.length];
 }
 
+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)?[^>]*>/gi, '')
+    .trim();
+}
+
 // ─── Custom Tooltip ───────────────────────────────────────────────────────────
 
 interface TooltipPayloadItem {
@@ -145,10 +165,20 @@ function renderVisualization(
         return <PieChartView data={data as PieChartData[]} isStreaming={isStreaming} />;
       case 'bar_chart':
         return <BarChartView data={data as BarChartData[]} primaryColor={primaryColor} isStreaming={isStreaming} />;
+      case 'histogram':
+        return <BarChartView data={data as BarChartData[]} primaryColor={primaryColor} isStreaming={isStreaming} />;
+      case 'horizontal_bar':
+        return <BarChartView data={data as BarChartData[]} primaryColor={primaryColor} isStreaming={isStreaming} layout="vertical" />;
       case 'line_chart':
         return <LineChartView data={data as LineChartDataPoint[]} primaryColor={primaryColor} isStreaming={isStreaming} />;
+      case 'scatter_plot':
+        return <ScatterPlotView data={data as ScatterPlotDataPoint[]} primaryColor={primaryColor} isStreaming={isStreaming} />;
       case 'radar_chart':
         return <RadarChartView data={data as Record<string, unknown>[]} isStreaming={isStreaming} />;
+      case 'metric_card':
+        return <MetricCardView data={data as MetricCardData} isStreaming={isStreaming} />;
+      case 'geo_map':
+        return <BarChartView data={data as BarChartData[]} primaryColor={primaryColor} isStreaming={isStreaming} />;
       case 'table':
         return <TableView data={data as TableData} isStreaming={isStreaming} />;
       case 'product_carousel':
@@ -204,7 +234,12 @@ function PieChartView({ data, isStreaming }: { data: PieChartData[]; isStreaming
   const chartData = data.map((item) => ({
     name: item.label,
     value: item.value,
+    inStockCount: item.inStockCount,
+    outOfStockCount: item.outOfStockCount,
   }));
+  const hasStockBreakdown = chartData.some(
+    (item) => item.inStockCount !== undefined || item.outOfStockCount !== undefined,
+  );
 
   return (
     <div className="bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 p-4 shadow-sm">
@@ -228,13 +263,52 @@ function PieChartView({ data, isStreaming }: { data: PieChartData[]; isStreaming
           <Legend wrapperStyle={{ fontSize: 12 }} verticalAlign="bottom" />
         </PieChart>
       </ResponsiveContainer>
+      {hasStockBreakdown && (
+        <div className="mt-3 grid gap-2 sm:grid-cols-2">
+          {chartData.map((item, index) => {
+            const inStock = Number(item.inStockCount ?? 0);
+            const outOfStock = Number(item.outOfStockCount ?? 0);
+            const status = inStock > 0 ? `${inStock} in stock` : 'Out of stock';
+            const mutedStatus = outOfStock > 0 ? `${outOfStock} out` : null;
+
+            return (
+              <div
+                key={item.name}
+                className="flex min-w-0 items-center justify-between gap-3 rounded-md border border-slate-100 px-2.5 py-2 text-xs dark:border-white/10"
+              >
+                <span className="flex min-w-0 items-center gap-2 text-slate-700 dark:text-white/75">
+                  <span
+                    className="h-2.5 w-2.5 flex-shrink-0 rounded-full"
+                    style={{ background: getColor(index) }}
+                  />
+                  <span className="truncate">{item.name}</span>
+                </span>
+                <span className={inStock > 0 ? 'whitespace-nowrap font-medium text-emerald-600' : 'whitespace-nowrap font-medium text-rose-600'}>
+                  {status}
+                  {mutedStatus && <span className="ml-1 text-slate-400">({mutedStatus})</span>}
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      )}
     </div>
   );
 }
 
 // ─── Bar Chart ────────────────────────────────────────────────────────────────
 
-function BarChartView({ data, primaryColor, isStreaming }: { data: BarChartData[]; primaryColor?: string; isStreaming?: boolean }) {
+function BarChartView({
+  data,
+  primaryColor,
+  isStreaming,
+  layout = 'horizontal',
+}: {
+  data: BarChartData[];
+  primaryColor?: string;
+  isStreaming?: boolean;
+  layout?: 'horizontal' | 'vertical';
+}) {
   if (isStreaming) return <ChartSkeleton type="bar" />;
   if (!Array.isArray(data) || data.length === 0) {
     return <div className="text-xs text-red-500">Invalid bar chart data</div>;
@@ -253,15 +327,28 @@ function BarChartView({ data, primaryColor, isStreaming }: { data: BarChartData[
   return (
     <div className="bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 p-4 shadow-sm overflow-x-auto">
       <ResponsiveContainer width="100%" height={260}>
-        <BarChart data={chartData} margin={{ top: 10, right: 10, left: -20, bottom: 0 }}>
+        <BarChart
+          data={chartData}
+          layout={layout}
+          margin={{ top: 10, right: 10, left: layout === 'vertical' ? 20 : -20, bottom: 0 }}
+        >
           <CartesianGrid strokeDasharray="3 3" vertical={false} stroke="#e2e8f0" />
-          <XAxis
-            dataKey="category"
-            tick={{ fontSize: 11, fill: '#64748b' }}
-            tickLine={false}
-            axisLine={{ stroke: '#cbd5e1' }}
-          />
-          <YAxis tick={{ fontSize: 11, fill: '#64748b' }} tickLine={false} axisLine={false} />
+          {layout === 'vertical' ? (
+            <>
+              <XAxis type="number" tick={{ fontSize: 11, fill: '#64748b' }} tickLine={false} axisLine={{ stroke: '#cbd5e1' }} />
+              <YAxis type="category" dataKey="category" width={110} tick={{ fontSize: 11, fill: '#64748b' }} tickLine={false} axisLine={false} />
+            </>
+          ) : (
+            <>
+              <XAxis
+                dataKey="category"
+                tick={{ fontSize: 11, fill: '#64748b' }}
+                tickLine={false}
+                axisLine={{ stroke: '#cbd5e1' }}
+              />
+              <YAxis tick={{ fontSize: 11, fill: '#64748b' }} tickLine={false} axisLine={false} />
+            </>
+          )}
           <Tooltip content={<CustomTooltip />} cursor={{ fill: '#f1f5f9' }} />
           <Legend wrapperStyle={{ fontSize: 12 }} />
           {hasStock ? (
@@ -278,6 +365,51 @@ function BarChartView({ data, primaryColor, isStreaming }: { data: BarChartData[
   );
 }
 
+// ─── Scatter Plot ─────────────────────────────────────────────────────────────
+
+function ScatterPlotView({ data, primaryColor, isStreaming }: { data: ScatterPlotDataPoint[]; primaryColor?: string; isStreaming?: boolean }) {
+  if (isStreaming) return <ChartSkeleton type="bar" />;
+  if (!Array.isArray(data) || data.length === 0) {
+    return <div className="text-xs text-red-500">Invalid scatter plot data</div>;
+  }
+
+  return (
+    <div className="bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 p-4 shadow-sm overflow-x-auto">
+      <ResponsiveContainer width="100%" height={260}>
+        <ScatterChart margin={{ top: 10, right: 10, left: -20, bottom: 0 }}>
+          <CartesianGrid strokeDasharray="3 3" stroke="#e2e8f0" />
+          <XAxis type="number" dataKey="x" tick={{ fontSize: 11, fill: '#64748b' }} tickLine={false} axisLine={{ stroke: '#cbd5e1' }} />
+          <YAxis type="number" dataKey="y" tick={{ fontSize: 11, fill: '#64748b' }} tickLine={false} axisLine={false} />
+          <Tooltip content={<CustomTooltip />} cursor={{ strokeDasharray: '3 3' }} />
+          <Scatter name="Value" data={data} fill={primaryColor ?? getColor(0)} />
+        </ScatterChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
+
+// ─── Metric Card ──────────────────────────────────────────────────────────────
+
+function MetricCardView({ data, isStreaming }: { data: MetricCardData; isStreaming?: boolean }) {
+  if (isStreaming) return <ChartSkeleton type="bar" />;
+  if (!data || typeof data.value !== 'number') {
+    return <div className="text-xs text-red-500">Invalid metric data</div>;
+  }
+
+  return (
+    <div className="rounded-xl border border-slate-200 bg-white p-4 shadow-sm dark:border-white/10 dark:bg-slate-900">
+      <div className="text-xs font-medium uppercase text-slate-500 dark:text-slate-400">{data.label}</div>
+      <div className="mt-2 text-3xl font-semibold text-slate-900 dark:text-white">
+        {data.value.toLocaleString()}
+        {data.unit && <span className="ml-1 text-base text-slate-500">{data.unit}</span>}
+      </div>
+      {data.operation && (
+        <div className="mt-1 text-xs text-slate-500 dark:text-slate-400">{data.operation}</div>
+      )}
+    </div>
+  );
+}
+
 // ─── Line Chart ───────────────────────────────────────────────────────────────
 
 function LineChartView({ data, primaryColor, isStreaming }: { data: LineChartDataPoint[]; primaryColor?: string; isStreaming?: boolean }) {
@@ -451,7 +583,7 @@ function CarouselView({
 // ─── Text / Prose ─────────────────────────────────────────────────────────────
 
 function TextView({ data }: { data: unknown }) {
-  const content = (data as { content?: string })?.content || String(data ?? '');
+  const content = stripLeakedAnswerWrappers((data as { content?: string })?.content || String(data ?? ''));
 
   return (
     <div className="bg-white dark:bg-slate-900 rounded-xl border border-slate-200 dark:border-white/10 p-4 shadow-sm">

package/src/config/EmbeddingStrategy.ts

@@ -51,24 +51,25 @@ export class EmbeddingStrategyResolver {
     llmConfig: LLMConfig,
     embeddingConfig?: EmbeddingConfig
   ): EmbeddingStrategy {
-    // If embedding config not provided, use integrated strategy
+    // No explicit embedding config — LLM provider must handle embeddings itself.
     if (!embeddingConfig) {
       return this.supportsEmbedding(llmConfig.provider)
         ? EmbeddingStrategy.INTEGRATED
         : EmbeddingStrategy.SEPARATE;
     }
 
-    // If embedding config differs from LLM provider, use separate
+    // Different provider for embeddings (e.g. Anthropic LLM + OpenAI embeddings).
     if (embeddingConfig.provider !== (llmConfig.provider as EmbeddingProvider)) {
       return EmbeddingStrategy.SEPARATE;
     }
 
-    // If same provider but different models/configs, use external
+    // Same provider, different model (e.g. OpenAI gpt-4o + text-embedding-3-small).
+    // Use EXTERNAL so the factory creates a dedicated embedding-model client.
     if (embeddingConfig.model !== llmConfig.model) {
       return EmbeddingStrategy.EXTERNAL;
     }
 
-    // Default to integrated
+    // Same provider, same model — fully integrated.
     return EmbeddingStrategy.INTEGRATED;
   }
 

package/src/config/RagConfig.ts

@@ -44,8 +44,6 @@ export interface VectorDBConfig {
    * - searchFields?: string[] | string // optional override for which columns receive exact-match boosts
    */
   options: Record<string, unknown>;
-  /** Optional distance metric (defaults to cosine if not specified and supported by provider) */
-  distanceMetric?: 'cosine' | 'euclidean' | 'dotproduct';
 }
 
 // ---------------------------------------------------------------------------
@@ -189,6 +187,16 @@ export interface RAGConfig {
    * e.g., { "name": "ProductName", "price": "SalesPrice", "image": "ThumbnailUrl" }
    */
   uiMapping?: Record<string, string>;
+  /**
+   * Custom keywords that signal graph-based retrieval should be used.
+   * Defaults to built-in list (relationship, connect, hierarchy, etc.).
+   */
+  graphKeywords?: string[];
+  /**
+   * Custom keywords that signal vector-based retrieval should be used.
+   * Defaults to built-in list (find, search, tell me about, etc.).
+   */
+  vectorKeywords?: string[];
 }
 
 // ---------------------------------------------------------------------------

package/src/config/serverConfig.ts

@@ -126,12 +126,27 @@ export function getEnvConfig(env: Record<string, string | undefined> = process.e
 
   const embeddingApiKeyByProvider: Record<string, string | undefined> = {
     openai: readString(env, 'OPENAI_API_KEY'),
+    anthropic: readString(env, 'ANTHROPIC_API_KEY'), // Anthropic needs a separate embedding provider; key kept for completeness
     gemini: readString(env, 'GEMINI_API_KEY'),
     ollama: undefined,
     universal_rest: readString(env, 'EMBEDDING_API_KEY') ?? readString(env, 'OPENAI_API_KEY'),
     custom: readString(env, 'EMBEDDING_API_KEY') ?? readString(env, 'OPENAI_API_KEY'),
   };
 
+  /**
+   * Provider-aware default models.
+   * Applied when LLM_MODEL env var is not explicitly set.
+   */
+  const DEFAULT_MODEL_BY_PROVIDER: Record<string, string> = {
+    openai: 'gpt-4o',
+    anthropic: 'claude-3-5-sonnet-20241022',
+    gemini: 'gemini-2.0-flash',
+    ollama: 'llama3',
+    universal_rest: 'default',
+    rest: 'default',
+    custom: 'default',
+  };
+
   return {
     projectId,
     vectorDb: {
@@ -144,7 +159,7 @@ export function getEnvConfig(env: Record<string, string | undefined> = process.e
     },
     llm: {
       provider: llmProvider,
-      model: readString(env, 'LLM_MODEL') ?? 'gpt-4o',
+      model: readString(env, 'LLM_MODEL') ?? DEFAULT_MODEL_BY_PROVIDER[llmProvider] ?? 'gpt-4o',
       apiKey: llmApiKeyByProvider[llmProvider] ?? '',
       baseUrl: readString(env, 'LLM_BASE_URL'),
       systemPrompt: readString(env, 'LLM_SYSTEM_PROMPT'),

package/src/core/LLMRouter.ts

@@ -0,0 +1,79 @@
+import { ILLMProvider } from '../llm/ILLMProvider';
+import { LLMFactory } from '../llm/LLMFactory';
+import { RagConfig, LLMConfig } from '../config/RagConfig';
+
+/**
+ * Provider-aware fast model defaults.
+ * Maps an LLM provider name to a sensible lightweight model for routing tasks.
+ */
+const FAST_MODEL_DEFAULTS: Record<string, string> = {
+  openai: 'gpt-4o-mini',
+  gemini: 'gemini-2.0-flash',
+  anthropic: 'claude-3-haiku-20240307',
+  ollama: '', // Ollama has no universal lightweight default — reuse main model
+  rest: '',
+  universal_rest: '',
+  custom: '',
+};
+
+/**
+ * LLMRouter — manages multiple LLM instances for different task roles.
+ *
+ * Roles:
+ *  - 'default' : the main configured LLM (used for chat generation)
+ *  - 'fast'    : a lightweight model for classification/routing tasks (UI decisions, strategy)
+ *  - 'powerful': reserved for future use (defaults to main model)
+ *
+ * Provider-agnostic: will never mix provider SDKs (e.g., won't set a Gemini model name on an
+ * OpenAI client). If FAST_LLM_MODEL is set in the environment it is applied to the *same* provider.
+ */
+export class LLMRouter {
+  private models = new Map<string, ILLMProvider>();
+
+  constructor(private config: RagConfig) {}
+
+  /**
+   * Initialize all LLM roles.
+   *
+   * @param prebuiltDefault - optional pre-built provider (from EmbeddingStrategyResolver).
+   *   When provided it is used directly as the 'default' role without re-constructing.
+   */
+  async initialize(prebuiltDefault?: ILLMProvider): Promise<void> {
+    // 1. Seed 'default' — prefer the pre-built provider so we don't double-construct it.
+    const defaultModel = prebuiltDefault ?? LLMFactory.create(this.config.llm, this.config.embedding);
+    this.models.set('default', defaultModel);
+
+    // 2. Resolve 'fast' model — always stays on the SAME provider to avoid SDK mismatches.
+    const envFastModel = process.env.FAST_LLM_MODEL;
+    const providerFastDefault = FAST_MODEL_DEFAULTS[this.config.llm.provider] ?? '';
+
+    const fastModelName = envFastModel || providerFastDefault;
+
+    if (fastModelName && fastModelName !== this.config.llm.model) {
+      console.log(`[LLMRouter] Fast role → provider="${this.config.llm.provider}" model="${fastModelName}"`);
+      const fastConfig: LLMConfig = {
+        ...this.config.llm,
+        model: fastModelName,
+      };
+      this.models.set('fast', LLMFactory.create(fastConfig, this.config.embedding));
+    } else {
+      console.log(`[LLMRouter] Fast role → reusing default model (no lightweight alternative configured).`);
+      this.models.set('fast', defaultModel);
+    }
+
+    // 3. 'powerful' defaults to main model (reserved for future use)
+    this.models.set('powerful', defaultModel);
+  }
+
+  /**
+   * Retrieve a model provider by its task role.
+   * Falls back to 'default' if the requested role is not registered.
+   */
+  get(role: 'fast' | 'powerful' | 'default'): ILLMProvider {
+    const provider = this.models.get(role) ?? this.models.get('default');
+    if (!provider) {
+      throw new Error(`[LLMRouter] No provider registered for role: "${role}". Did you call initialize()?`);
+    }
+    return provider;
+  }
+}