@retrivora-ai/rag-engine 2.0.1 → 2.0.3

package/dist/server.js

@@ -2074,6 +2074,8 @@ __export(server_exports, {
   AuthenticationException: () => AuthenticationException,
   BaseVectorProvider: () => BaseVectorProvider,
   BatchProcessor: () => BatchProcessor,
+  CarouselRendererStrategy: () => CarouselRendererStrategy,
+  ChartRendererStrategy: () => ChartRendererStrategy,
   ChromaDBProvider: () => ChromaDBProvider,
   ConfigBuilder: () => ConfigBuilder,
   ConfigResolver: () => ConfigResolver,
@@ -2085,10 +2087,12 @@ __export(server_exports, {
   EmbeddingStrategy: () => EmbeddingStrategy,
   EmbeddingStrategyResolver: () => EmbeddingStrategyResolver,
   GroqProvider: () => GroqProvider,
+  IntentClassifier: () => IntentClassifier,
   LLMFactory: () => LLMFactory,
   LLM_PROFILES: () => LLM_PROFILES,
   LicenseVerifier: () => LicenseVerifier,
   MilvusProvider: () => MilvusProvider,
+  MixedRendererStrategy: () => MixedRendererStrategy,
   MongoDBProvider: () => MongoDBProvider,
   MultiTablePostgresProvider: () => MultiTablePostgresProvider,
   OllamaProvider: () => OllamaProvider,
@@ -2104,13 +2108,25 @@ __export(server_exports, {
   QwenProvider: () => QwenProvider,
   RateLimitException: () => RateLimitException,
   RedisProvider: () => RedisProvider,
+  RendererRegistry: () => RendererRegistry,
   RetrievalException: () => RetrievalException,
   Retrivora: () => Retrivora,
   RetrivoraError: () => RetrivoraError,
+  Rule1SpecificInfoRule: () => Rule1SpecificInfoRule,
+  Rule2ComparisonRule: () => Rule2ComparisonRule,
+  Rule3ProductDiscoveryRule: () => Rule3ProductDiscoveryRule,
+  Rule4AnalyticalRule: () => Rule4AnalyticalRule,
+  Rule5MixedResponseRule: () => Rule5MixedResponseRule,
+  Rule6SmallResultSetRule: () => Rule6SmallResultSetRule,
+  Rule7LargeTableRule: () => Rule7LargeTableRule,
+  RuleEngine: () => RuleEngine,
+  TableRendererStrategy: () => TableRendererStrategy,
+  TextRendererStrategy: () => TextRendererStrategy,
   UniversalLLMAdapter: () => UniversalLLMAdapter,
   UniversalVectorProvider: () => UniversalVectorProvider,
   VECTOR_PROFILES: () => VECTOR_PROFILES,
   VectorPlugin: () => VectorPlugin,
+  VisualizationDecisionEngine: () => VisualizationDecisionEngine,
   WeaviateProvider: () => WeaviateProvider,
   createChatHandler: () => createChatHandler,
   createFeedbackHandler: () => createFeedbackHandler,
@@ -2122,6 +2138,7 @@ __export(server_exports, {
   createSessionsHandler: () => createSessionsHandler,
   createStreamHandler: () => createStreamHandler,
   createUploadHandler: () => createUploadHandler,
+  decideVisualization: () => decideVisualization,
   getRagConfig: () => getRagConfig,
   sseErrorFrame: () => sseErrorFrame,
   sseFrame: () => sseFrame,
@@ -5983,6 +6000,606 @@ var LLMRouter = class {
 
 // src/utils/UITransformer.ts
 init_synonyms();
+
+// src/rendering/IntentClassifier.ts
+var IntentClassifier = class {
+  /**
+   * Fast, zero-latency classifier that maps a user query and optional data context
+   * into a high-level IntentCategory.
+   */
+  static classify(context) {
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const signals = this.extractDataSignals(context);
+    if (this.isInformationLookup(q)) {
+      return { intent: "information_lookup", signals };
+    }
+    if (this.isComparisonQuery(q)) {
+      return { intent: "comparison", signals };
+    }
+    if (this.isProductQuery(q) || signals.isProductLike && this.isRecommendationQuery(q)) {
+      return { intent: "product_search", signals };
+    }
+    if (this.isTrendQuery(q) || signals.hasDateFields && signals.hasNumericFields && /\b(growth|trend|over time|monthly|yearly|weekly)\b/.test(q)) {
+      return { intent: "trend_analysis", signals };
+    }
+    if (this.isRankingQuery(q)) {
+      return { intent: "ranking", signals };
+    }
+    if (this.isAnalyticsQuery(q) || signals.hasNumericFields && signals.hasCategoricalFields && /\b(sales|revenue|performance|count|total|average|breakdown|share|percentage|correlation)\b/.test(q)) {
+      return { intent: "analytics", signals };
+    }
+    if (this.isRecommendationQuery(q)) {
+      return { intent: "recommendation", signals };
+    }
+    return { intent: "information_lookup", signals };
+  }
+  /**
+   * Extract key data structure signals from retrieved documents.
+   */
+  static extractDataSignals(context) {
+    const docs = context.retrievedDocuments || [];
+    const rowCount = docs.length;
+    let hasNumericFields = false;
+    let hasDateFields = false;
+    let hasCategoricalFields = false;
+    let isProductLike = false;
+    let numericFieldCount = 0;
+    let categoricalFieldCount = 0;
+    if (docs.length > 0) {
+      const keys = /* @__PURE__ */ new Set();
+      let numericKeys = /* @__PURE__ */ new Set();
+      let dateKeys = /* @__PURE__ */ new Set();
+      let catKeys = /* @__PURE__ */ new Set();
+      let productKeyMatches = 0;
+      docs.forEach((doc) => {
+        const meta = doc.metadata || {};
+        Object.entries(meta).forEach(([key, val]) => {
+          keys.add(key);
+          const kLower = key.toLowerCase();
+          if (["price", "image", "brand", "in_stock", "rating", "sku", "product"].some((p) => kLower.includes(p))) {
+            productKeyMatches++;
+          }
+          if (typeof val === "number") {
+            numericKeys.add(key);
+          } else if (typeof val === "string") {
+            if (/^\d{4}-\d{2}-\d{2}/.test(val) || !isNaN(Date.parse(val)) && val.length > 5) {
+              dateKeys.add(key);
+            } else if (val.length < 50 && !val.includes("\n")) {
+              catKeys.add(key);
+            }
+          }
+        });
+      });
+      hasNumericFields = numericKeys.size > 0;
+      hasDateFields = dateKeys.size > 0;
+      hasCategoricalFields = catKeys.size > 0;
+      numericFieldCount = numericKeys.size;
+      categoricalFieldCount = catKeys.size;
+      if (productKeyMatches >= 2 || docs.some((d) => d.content.toLowerCase().includes("price") || d.content.toLowerCase().includes("brand"))) {
+        isProductLike = true;
+      }
+    }
+    return {
+      rowCount,
+      hasNumericFields,
+      hasDateFields,
+      hasCategoricalFields,
+      isProductLike,
+      numericFieldCount,
+      categoricalFieldCount
+    };
+  }
+  // ─── Intent Heuristic Checkers ─────────────────────────────────────────────
+  static isInformationLookup(query) {
+    if (/^(what|who|explain|define|where|when|why|how|how does|can|could|does|do|is|are|has|have|will|should|would|meaning of)\s+/i.test(query)) {
+      if (!/\b(compare|versus|vs\.?|trend|monthly|revenue|top selling|best)\b/i.test(query)) {
+        return true;
+      }
+    }
+    if (/^(what is the )?(price|cost|fee|rate) of\b/i.test(query)) {
+      return true;
+    }
+    return false;
+  }
+  static isComparisonQuery(query) {
+    return /\b(compare|comparison|vs\.?|versus|difference between|differ|contrast|against)\b/i.test(query);
+  }
+  static isProductQuery(query) {
+    return /\b(best|recommend|top|buy|shopping|under \$|cheap|shoes|laptops|chairs|headphones|phone|sneakers|apparel|products)\b/i.test(query) && !/\b(compare|chart|sales|revenue|trend)\b/i.test(query);
+  }
+  static isRecommendationQuery(query) {
+    return /\b(recommend|suggest|what should i (buy|get|choose)|best options|top picks)\b/i.test(query);
+  }
+  static isTrendQuery(query) {
+    return /\b(trend|trends|growth|over time|historical|timeline|monthly|yearly|weekly|daily|revenue growth|sales growth)\b/i.test(query);
+  }
+  static isRankingQuery(query) {
+    return /\b(highest|lowest|top\s*\d+|bottom\s*\d+|rank|ranking|top performing|best performing)\b/i.test(query);
+  }
+  static isAnalyticsQuery(query) {
+    return /\b(sales|revenue|analytics|insights|distribution|percentage|share|breakdown|breakup|scatter|correlation|metrics|performance|by region|by category)\b/i.test(query);
+  }
+};
+
+// src/rendering/rules/Rule1SpecificInfoRule.ts
+var Rule1SpecificInfoRule = class {
+  constructor() {
+    this.name = "Rule1SpecificInfo";
+    this.priority = 100;
+  }
+  evaluate(context, intent) {
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const isFactQuery = intent === "information_lookup" || /^(what|who|explain|define|where|when|why|meaning of)\s+/i.test(q) || /^(what is the price of|price of|cost of)\b/i.test(q);
+    const isNonVisual = !/\b(compare|versus|vs\.?|trend|monthly|revenue|best|top 10|chart|table|list|grid)\b/i.test(q);
+    if (isFactQuery && isNonVisual) {
+      return {
+        renderType: "text",
+        confidence: 0.95,
+        reason: "Rule 1: Specific information request (fact, explanation, or definition) requires plain text rendering."
+      };
+    }
+    return null;
+  }
+};
+
+// src/rendering/rules/Rule2ComparisonRule.ts
+var Rule2ComparisonRule = class {
+  constructor() {
+    this.name = "Rule2Comparison";
+    this.priority = 90;
+  }
+  evaluate(context, intent) {
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const isComparison = intent === "comparison" || /\b(compare|comparison|vs\.?|versus|difference between|differ|contrast|against)\b/i.test(q);
+    if (isComparison) {
+      return {
+        renderType: "table",
+        confidence: 0.9,
+        reason: "Rule 2: Comparison query contrasting multiple entities requires structured table rendering."
+      };
+    }
+    return null;
+  }
+};
+
+// src/rendering/rules/Rule3ProductDiscoveryRule.ts
+var Rule3ProductDiscoveryRule = class {
+  constructor() {
+    this.name = "Rule3ProductDiscovery";
+    this.priority = 85;
+  }
+  evaluate(context, intent) {
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const isDiscovery = intent === "product_search" || intent === "recommendation" || /\b(best|recommend|top|buy|shopping|under \$|cheap|shoes|laptops|chairs|headphones|sneakers|apparel|products|show available)\b/i.test(q);
+    const isNotChart = !/\b(chart|sales|revenue|monthly|growth|trend|over time)\b/i.test(q);
+    const isAnalyticalRanking = /\b(top performing|top selling|best performing|performing|sales|revenue|ranking)\b/i.test(q);
+    if (isDiscovery && isNotChart && !isAnalyticalRanking) {
+      return {
+        renderType: "carousel",
+        confidence: 0.9,
+        reason: "Rule 3: Product discovery/recommendation query requires product carousel rendering."
+      };
+    }
+    return null;
+  }
+};
+
+// src/rendering/rules/Rule4AnalyticalRule.ts
+var Rule4AnalyticalRule = class {
+  constructor() {
+    this.name = "Rule4Analytical";
+    this.priority = 80;
+  }
+  evaluate(context, intent) {
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const isAnalytical = intent === "analytics" || intent === "trend_analysis" || intent === "ranking" || /\b(monthly sales|revenue growth|top performing|population trends|sales by|growth|distribution|share|percentage|breakdown|correlation|scatter|trend)\b/i.test(q);
+    if (!isAnalytical) return null;
+    let chartType = "bar";
+    if (intent === "trend_analysis" || /\b(monthly|yearly|weekly|growth|over time|trend|timeline|historical)\b/i.test(q)) {
+      chartType = "line";
+    } else if (/\b(share|percentage|percent|breakup|breakdown|composition|pie|donut|proportion)\b/i.test(q)) {
+      chartType = "pie";
+    } else if (/\b(correlation|scatter|relationship|relation|impact of|depends on)\b/i.test(q)) {
+      chartType = "scatter";
+    } else {
+      chartType = "bar";
+    }
+    return {
+      renderType: "chart",
+      chartType,
+      confidence: 0.85,
+      reason: `Rule 4: Analytical query with numerical insights selects ${chartType} chart.`
+    };
+  }
+};
+
+// src/rendering/rules/Rule5MixedResponseRule.ts
+var Rule5MixedResponseRule = class {
+  constructor() {
+    this.name = "Rule5MixedResponse";
+    this.priority = 95;
+  }
+  evaluate(context, _intent) {
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const isTopSellingThisMonth = /\btop\s*(selling|performing)?\s*products?\s*(this|last)?\s*(month|year|week)\b/i.test(q);
+    const hasMultipleSectionsRequest = /\b(summary|overview)\b/i.test(q) && /\b(carousel|products?|items?)\b/i.test(q) && /\b(chart|sales|trend|revenue)\b/i.test(q);
+    if (isTopSellingThisMonth || hasMultipleSectionsRequest) {
+      return {
+        renderType: "mixed",
+        confidence: 0.95,
+        reason: "Rule 5: Mixed response query requires multi-section composition (text, carousel, chart).",
+        sections: [
+          { type: "text", title: "Summary" },
+          { type: "carousel", title: "Top Products" },
+          { type: "chart", chartType: "bar", title: "Sales Performance" }
+        ]
+      };
+    }
+    return null;
+  }
+};
+
+// src/rendering/rules/Rule6SmallResultSetRule.ts
+var Rule6SmallResultSetRule = class {
+  constructor() {
+    this.name = "Rule6SmallResultSet";
+    this.priority = 110;
+  }
+  evaluate(context, _intent) {
+    const docs = context.retrievedDocuments || [];
+    if (docs.length > 0 && docs.length < 3) {
+      const q = (context.userQuery || "").toLowerCase().trim();
+      const isExplicitComparison = /\b(compare|versus|vs\.?)\b/i.test(q);
+      return {
+        renderType: isExplicitComparison ? "table" : "text",
+        confidence: 0.98,
+        reason: `Rule 6: Small result set (${docs.length} rows < 3). Charts avoided to prevent sparse or uninformative visualizations.`
+      };
+    }
+    return null;
+  }
+};
+
+// src/rendering/rules/Rule7LargeTableRule.ts
+var Rule7LargeTableRule = class {
+  constructor() {
+    this.name = "Rule7LargeTable";
+    this.priority = 75;
+  }
+  evaluate(context, intent) {
+    const docs = context.retrievedDocuments || [];
+    if (docs.length > 5) {
+      const q = (context.userQuery || "").toLowerCase().trim();
+      const hasNumericAgg = intent === "analytics" || intent === "ranking" || /\b(sales|revenue|growth|count|total|average)\b/i.test(q);
+      if (hasNumericAgg) {
+        return {
+          renderType: "mixed",
+          confidence: 0.88,
+          reason: `Rule 7: Large result set (${docs.length} rows > 5) with numeric aggregation rendered as Table + Chart.`,
+          sections: [
+            { type: "table", title: "Detailed Data Table" },
+            { type: "chart", chartType: "bar", title: "Numerical Breakdown" }
+          ]
+        };
+      }
+      return {
+        renderType: "table",
+        confidence: 0.85,
+        reason: `Rule 7: Large result set (${docs.length} rows > 5) rendered as structured table for readability.`
+      };
+    }
+    return null;
+  }
+};
+
+// src/rendering/RuleEngine.ts
+var RuleEngine = class {
+  constructor() {
+    this.rules = [];
+    this.registerDefaultRules();
+  }
+  /**
+   * Register standard rules in priority order.
+   */
+  registerDefaultRules() {
+    this.registerRule(new Rule6SmallResultSetRule());
+    this.registerRule(new Rule1SpecificInfoRule());
+    this.registerRule(new Rule5MixedResponseRule());
+    this.registerRule(new Rule2ComparisonRule());
+    this.registerRule(new Rule3ProductDiscoveryRule());
+    this.registerRule(new Rule4AnalyticalRule());
+    this.registerRule(new Rule7LargeTableRule());
+  }
+  /**
+   * Add or replace a rule in the engine.
+   * Automatically keeps rules sorted by descending priority.
+   */
+  registerRule(rule) {
+    this.rules = this.rules.filter((r) => r.name !== rule.name);
+    this.rules.push(rule);
+    this.rules.sort((a, b) => b.priority - a.priority);
+  }
+  /**
+   * Evaluate context against rules in descending priority order.
+   * Returns the first non-null RenderDecision.
+   */
+  evaluate(context, intent) {
+    for (const rule of this.rules) {
+      const decision = rule.evaluate(context, intent);
+      if (decision) {
+        return decision;
+      }
+    }
+    return {
+      renderType: "text",
+      confidence: 0.7,
+      reason: "Default fallback: No specific visualization rule matched context."
+    };
+  }
+  /**
+   * List all registered rules.
+   */
+  getRegisteredRules() {
+    return this.rules.map((r) => ({ name: r.name, priority: r.priority }));
+  }
+};
+
+// src/rendering/RendererRegistry.ts
+var TextRendererStrategy = class {
+  constructor() {
+    this.type = "text";
+  }
+  render(data, options) {
+    const title = (options == null ? void 0 : options.title) || "Information";
+    if (typeof data === "string") {
+      return { type: "text", title, data: { content: data } };
+    }
+    const docs = Array.isArray(data) ? data : [];
+    const text = docs.map((d) => d.content).join("\n\n");
+    return { type: "text", title, data: { content: text || "No detailed content available." } };
+  }
+};
+var TableRendererStrategy = class {
+  constructor() {
+    this.type = "table";
+  }
+  render(data, options) {
+    const docs = Array.isArray(data) ? data : [];
+    const query = (options == null ? void 0 : options.query) || "";
+    return UITransformer.transform(query, docs, void 0, void 0, {
+      visualizationHint: "table",
+      recommendedChart: "table",
+      filterInStockOnly: false,
+      wantsExplicitTable: true,
+      isTemporal: false,
+      isComparison: true,
+      language: "en"
+    });
+  }
+};
+var CarouselRendererStrategy = class {
+  constructor() {
+    this.type = "carousel";
+  }
+  render(data, options) {
+    const docs = Array.isArray(data) ? data : [];
+    const query = (options == null ? void 0 : options.query) || "";
+    return UITransformer.transform(query, docs, void 0, void 0, {
+      visualizationHint: "product_browse",
+      recommendedChart: "text",
+      filterInStockOnly: false,
+      wantsExplicitTable: false,
+      isTemporal: false,
+      isComparison: false,
+      language: "en"
+    });
+  }
+};
+var ChartRendererStrategy = class {
+  constructor() {
+    this.type = "chart";
+  }
+  render(data, options) {
+    const docs = Array.isArray(data) ? data : [];
+    const query = (options == null ? void 0 : options.query) || "";
+    const chartType = (options == null ? void 0 : options.chartType) || "bar";
+    let hint = "comparison";
+    let rec = "bar_chart";
+    if (chartType === "line") {
+      hint = "trend";
+      rec = "line_chart";
+    } else if (chartType === "pie") {
+      hint = "composition";
+      rec = "pie_chart";
+    } else if (chartType === "scatter") {
+      hint = "correlation";
+      rec = "scatter_plot";
+    }
+    return UITransformer.transform(query, docs, void 0, void 0, {
+      visualizationHint: hint,
+      recommendedChart: rec,
+      filterInStockOnly: false,
+      wantsExplicitTable: false,
+      isTemporal: chartType === "line",
+      isComparison: chartType === "bar",
+      language: "en"
+    });
+  }
+};
+var MixedRendererStrategy = class {
+  constructor() {
+    this.type = "mixed";
+  }
+  render(data, options) {
+    const docs = Array.isArray(data) ? data : [];
+    const sections = (options == null ? void 0 : options.sections) || [];
+    const sectionPayloads = sections.map((s) => {
+      const strategy = RendererRegistry.getStrategy(s.type);
+      return {
+        type: s.type,
+        title: s.title,
+        payload: strategy.render(data, __spreadProps(__spreadValues({}, options), { chartType: s.chartType, title: s.title }))
+      };
+    });
+    return {
+      type: "table",
+      // Fallback container type for compatibility
+      title: (options == null ? void 0 : options.title) || "Composite Response",
+      description: `Mixed payload containing ${sectionPayloads.length} visual sections`,
+      data: { sections: sectionPayloads }
+    };
+  }
+};
+var _RendererRegistry = class _RendererRegistry {
+  /**
+   * Register a new renderer strategy.
+   * Enables seamless addition of custom visualizers (Timeline, Maps, Flow Diagrams, etc.).
+   */
+  static registerStrategy(strategy) {
+    this.strategies.set(String(strategy.type).toLowerCase(), strategy);
+  }
+  /**
+   * Retrieve a registered renderer strategy by type string.
+   */
+  static getStrategy(type) {
+    const key = type.toLowerCase();
+    const strategy = this.strategies.get(key);
+    if (!strategy) {
+      return this.strategies.get("text");
+    }
+    return strategy;
+  }
+  /**
+   * Check if a renderer strategy is registered.
+   */
+  static hasStrategy(type) {
+    return this.strategies.has(type.toLowerCase());
+  }
+  /**
+   * List all registered strategy types.
+   */
+  static getRegisteredTypes() {
+    return Array.from(this.strategies.keys());
+  }
+};
+_RendererRegistry.strategies = /* @__PURE__ */ new Map();
+_RendererRegistry.registerStrategy(new TextRendererStrategy());
+_RendererRegistry.registerStrategy(new TableRendererStrategy());
+_RendererRegistry.registerStrategy(new CarouselRendererStrategy());
+_RendererRegistry.registerStrategy(new ChartRendererStrategy());
+_RendererRegistry.registerStrategy(new MixedRendererStrategy());
+var RendererRegistry = _RendererRegistry;
+
+// src/rendering/VisualizationDecisionEngine.ts
+var LRUDecisionCache = class {
+  constructor(maxSize = 200) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.maxSize = maxSize;
+  }
+  generateKey(context) {
+    var _a2, _b;
+    const q = (context.userQuery || "").toLowerCase().trim();
+    const docCount = (_b = (_a2 = context.retrievedDocuments) == null ? void 0 : _a2.length) != null ? _b : 0;
+    return `${q}::docs:${docCount}`;
+  }
+  get(context) {
+    const key = this.generateKey(context);
+    const item = this.cache.get(key);
+    if (item) {
+      this.cache.delete(key);
+      this.cache.set(key, item);
+      return item.decision;
+    }
+    return void 0;
+  }
+  set(context, decision) {
+    const key = this.generateKey(context);
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== void 0) this.cache.delete(oldest);
+    }
+    this.cache.set(key, { decision, timestamp: Date.now() });
+  }
+  clear() {
+    this.cache.clear();
+  }
+  get size() {
+    return this.cache.size;
+  }
+};
+var VisualizationDecisionEngine = class {
+  /**
+   * Evaluate user query, documents, and context to produce a RenderDecision.
+   * Execution time is < 1ms for cached or rule-matched queries.
+   */
+  static decideVisualization(userQuery, retrievedDocuments, llmResponse, metadata) {
+    const context = {
+      userQuery,
+      retrievedDocuments,
+      llmResponse,
+      metadata
+    };
+    const cached = this.cache.get(context);
+    if (cached) {
+      return cached;
+    }
+    const { intent } = IntentClassifier.classify(context);
+    const decision = this.ruleEngine.evaluate(context, intent);
+    this.cache.set(context, decision);
+    return decision;
+  }
+  /**
+   * Convenience helper to decide AND render the data into a UITransformationResponse.
+   */
+  static render(userQuery, retrievedDocuments, llmResponse, metadata) {
+    const decision = this.decideVisualization(userQuery, retrievedDocuments, llmResponse, metadata);
+    const strategy = RendererRegistry.getStrategy(decision.renderType);
+    return strategy.render(retrievedDocuments || [], __spreadValues({
+      query: userQuery,
+      chartType: decision.chartType,
+      sections: decision.sections
+    }, metadata));
+  }
+  /**
+   * Register a custom rule in the rule engine.
+   */
+  static registerRule(rule) {
+    this.ruleEngine.registerRule(rule);
+    this.cache.clear();
+  }
+  /**
+   * Register a custom renderer strategy.
+   */
+  static registerRendererStrategy(strategy) {
+    RendererRegistry.registerStrategy(strategy);
+  }
+  /**
+   * Clear the decision cache.
+   */
+  static clearCache() {
+    this.cache.clear();
+  }
+  /**
+   * Get size of current decision cache.
+   */
+  static getCacheSize() {
+    return this.cache.size;
+  }
+};
+VisualizationDecisionEngine.ruleEngine = new RuleEngine();
+VisualizationDecisionEngine.cache = new LRUDecisionCache(200);
+function decideVisualization(userQuery, retrievedDocuments, llmResponse, metadata) {
+  return VisualizationDecisionEngine.decideVisualization(
+    userQuery,
+    retrievedDocuments,
+    llmResponse,
+    metadata
+  );
+}
+
+// src/utils/UITransformer.ts
 var UITransformer = class _UITransformer {
   // ─── Public Entry Points ─────────────────────────────────────────────────
   /**
@@ -6029,6 +6646,9 @@ var UITransformer = class _UITransformer {
       return this.hasMultipleFields(filteredData) ? this.transformToTable(filteredData, userQuery) : this.transformToText(filteredData);
     }
     if ((hasProducts || this.isProductQuery(userQuery)) && resolvedIntent.visualizationHint === "product_browse") {
+      if (!this.isProductQuery(userQuery)) {
+        return this.transformToText(filteredData);
+      }
       return this.transformToProductCarousel(filteredData, config, trainedSchema);
     }
     const automatic = this.chooseAutomaticVisualization(filteredData, profile, userQuery);
@@ -6043,6 +6663,11 @@ var UITransformer = class _UITransformer {
    * Step 3 — Fall back to the heuristic `transform()` if either LLM call fails.
    */
   static async analyzeAndDecide(query, sources, llm) {
+    const decision = VisualizationDecisionEngine.decideVisualization(query, sources);
+    if (decision.renderType === "text") {
+      console.debug("[UITransformer] Decision Engine selected plain text rendering \u2014 skipping visual LLM calls.");
+      return this.transformToText(sources);
+    }
     let intent;
     try {
       intent = await this.detectIntent(query, llm, sources);
@@ -6492,7 +7117,7 @@ ${schemaProfileText}` : ""}`;
   }
   static transformToText(data) {
     return this.createTextResponse(
-      "Search Results",
+      "Retrieved Context",
       data.map((item) => item.content).join("\n\n"),
       `Found ${data.length} relevant results`
     );
@@ -6659,16 +7284,13 @@ ${schemaProfileText}` : ""}`;
       "product",
       "price",
       "stock",
-      "item",
       "sku",
       "brand",
-      "model",
       "msrp",
       "inventory",
       "buy",
       "shop",
       "beauty",
-      "care",
       "cosmetic",
       "facial",
       "cream",
@@ -6681,7 +7303,7 @@ ${schemaProfileText}` : ""}`;
     const metadata = item.metadata || {};
     const hasMetadataKey = Object.keys(metadata).some((k) => {
       const val = metadata[k];
-      return ["price", "product", "sku", "brand", "model", "cost", "item"].includes(k.toLowerCase()) && val !== null && val !== void 0 && val !== "";
+      return ["price", "product", "sku", "brand", "cost"].includes(k.toLowerCase()) && val !== null && val !== void 0 && val !== "";
     });
     const hasPricePattern = /\$\s*\d+\.\d{2}/.test(content);
     return hasKeywords || hasMetadataKey || hasPricePattern;
@@ -7370,6 +7992,13 @@ SchemaMapper.TARGET_PROPERTIES = {
 };
 
 // src/core/Pipeline.ts
+function formatNamespace(raw) {
+  if (!raw || !raw.trim()) return "retrivora-default";
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("retrivora-")) return trimmed;
+  const sanitized = trimmed.toLowerCase().replace(/[^a-z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  return `retrivora-${sanitized}`;
+}
 var LRUEmbeddingCache = class {
   constructor(maxSize = 500) {
     this.cache = /* @__PURE__ */ new Map();
@@ -7561,7 +8190,7 @@ ${m.content}`).join("\n\n---\n\n");
    */
   async ingest(documents, namespace) {
     await this.initialize();
-    const ns = namespace != null ? namespace : this.config.projectId;
+    const ns = formatNamespace(namespace != null ? namespace : this.config.projectId);
     const results = [];
     for (const doc of documents) {
       try {
@@ -7780,7 +8409,7 @@ ${m.content}`).join("\n\n---\n\n");
     return __asyncGenerator(this, arguments, function* (question, history = [], namespace) {
       var _a2, _b, _c, _d, _e, _f, _g2, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C;
       yield new __await(this.initialize());
-      const ns = namespace != null ? namespace : this.config.projectId;
+      const ns = formatNamespace(namespace != null ? namespace : this.config.projectId);
       const topK = (_b = (_a2 = this.config.rag) == null ? void 0 : _a2.topK) != null ? _b : 5;
       const scoreThreshold = (_d = (_c = this.config.rag) == null ? void 0 : _c.scoreThreshold) != null ? _d : 0.3;
       const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
@@ -7918,7 +8547,7 @@ ${context}`;
         const isNativeThinking = isClaude37 && (((_p = this.config.llm.options) == null ? void 0 : _p.thinking) === true || ((_q = this.config.llm.options) == null ? void 0 : _q.thinking) === "enabled" || ((_r = this.config.llm.options) == null ? void 0 : _r.thinking) !== false);
         const modelNameLower = this.config.llm.model.toLowerCase();
         const isReasoningModel = modelNameLower.includes("-r1") || modelNameLower.includes("deepseek-r1") || modelNameLower.includes("reasoning") || modelNameLower.includes("thinking");
-        const isSimulatedThinking = !isNativeThinking && (((_s = this.config.llm.options) == null ? void 0 : _s.thinking) === true || ((_t = this.config.llm.options) == null ? void 0 : _t.thinking) === "enabled" || isReasoningModel && ((_u = this.config.llm.options) == null ? void 0 : _u.thinking) !== false);
+        const isSimulatedThinking = !isNativeThinking && (((_s = this.config.llm.options) == null ? void 0 : _s.thinking) === true || ((_t = this.config.llm.options) == null ? void 0 : _t.thinking) === "enabled" || ((_u = this.config.llm.options) == null ? void 0 : _u.thinking) !== false);
         let finalRestrictionSuffix = restrictionSuffix;
         if (isSimulatedThinking) {
           finalRestrictionSuffix += "\n\n(IMPORTANT: You must think step-by-step before answering. Write your thinking process inside a `<think>...</think>` block. Write the `<think>` block first, then follow it with your final response. Keep the thinking process thorough and detailed. Example: `<think>Thinking details here...</think>Final answer text here.`)";
@@ -8244,7 +8873,7 @@ ${context}`;
   }
   async retrieve(query, options) {
     var _a2, _b, _c, _d, _e, _f, _g2;
-    const ns = (_a2 = options.namespace) != null ? _a2 : this.config.projectId;
+    const ns = formatNamespace((_a2 = options.namespace) != null ? _a2 : this.config.projectId);
     const topK = (_b = options.topK) != null ? _b : 5;
     const cacheKey = `${ns}::${query}`;
     let queryVector = this.embeddingCache.get(cacheKey);
@@ -8313,7 +8942,7 @@ Optimized Search Query:`;
   async getSuggestions(query, namespace) {
     if (!query || query.trim().length < 3) return [];
     await this.initialize();
-    const ns = namespace != null ? namespace : this.config.projectId;
+    const ns = formatNamespace(namespace != null ? namespace : this.config.projectId);
     try {
       const { sources } = await this.retrieve(query, { namespace: ns, topK: 5 });
       if (sources.length === 0) return [];
@@ -8883,7 +9512,7 @@ var DocumentParser = class {
    */
   static async parse(file, fileName, mimeType) {
     var _a2;
-    const extension = (_a2 = fileName.split(".").pop()) == null ? void 0 : _a2.toLowerCase();
+    const extension = ((_a2 = fileName.split(".").pop()) == null ? void 0 : _a2.toLowerCase()) || "";
     if (extension === "txt" || extension === "md" || mimeType === "text/plain" || mimeType === "text/markdown") {
       return this.readAsText(file);
     }
@@ -8899,6 +9528,29 @@ var DocumentParser = class {
     if (extension === "csv" || mimeType === "text/csv") {
       return this.readAsText(file);
     }
+    if (extension === "xlsx" || extension === "xls" || mimeType.includes("spreadsheet") || mimeType.includes("excel")) {
+      try {
+        const xlsx = await import("xlsx");
+        const buffer = Buffer.isBuffer(file) ? file : Buffer.from(await file.arrayBuffer());
+        const workbook = xlsx.read(buffer, { type: "buffer" });
+        const sheetsText = [];
+        for (const sheetName of workbook.SheetNames) {
+          const sheet = workbook.Sheets[sheetName];
+          const csv = xlsx.utils.sheet_to_csv(sheet);
+          if (csv && csv.trim()) {
+            sheetsText.push(`--- Sheet: ${sheetName} ---
+${csv.trim()}`);
+          }
+        }
+        return sheetsText.join("\n\n") || `[Empty Excel Workbook: ${fileName}]`;
+      } catch (e) {
+        try {
+          return await this.readAsText(file);
+        } catch (e2) {
+          return `[Excel File Content: ${fileName}]`;
+        }
+      }
+    }
     if (extension === "pdf" || mimeType === "application/pdf") {
       try {
         const pdf = await import("pdf-parse");
@@ -8910,15 +9562,15 @@ var DocumentParser = class {
         return `[PDF Parsing Error for ${fileName}]`;
       }
     }
-    if (extension === "docx" || mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") {
+    if (extension === "docx" || extension === "doc" || mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document" || mimeType === "application/msword") {
       try {
         const mammoth = await import("mammoth");
         const buffer = Buffer.isBuffer(file) ? file : Buffer.from(await file.arrayBuffer());
         const result = await mammoth.extractRawText({ buffer });
         return result.value;
       } catch (err) {
-        console.warn('[DocumentParser] DOCX parsing failed. Make sure "mammoth" is installed.', err);
-        return `[DOCX Parsing Error for ${fileName}]`;
+        console.warn('[DocumentParser] Word parsing failed. Make sure "mammoth" is installed.', err);
+        return `[Word Parsing Error for ${fileName}]`;
       }
     }
     try {
@@ -9758,6 +10410,7 @@ function createUploadHandler(configOrPlugin, options) {
       }
       const documents = [];
       for (const file of files) {
+        const isExcel = file.name.toLowerCase().endsWith(".xlsx") || file.name.toLowerCase().endsWith(".xls") || file.type.includes("spreadsheet") || file.type.includes("excel");
         if (file.name.toLowerCase().endsWith(".csv") || file.type === "text/csv") {
           const text = await file.text();
           const Papa = await import("papaparse");
@@ -9790,7 +10443,7 @@ function createUploadHandler(configOrPlugin, options) {
                 metadata: __spreadValues(__spreadProps(__spreadValues({
                   fileName: file.name,
                   fileSize: file.size,
-                  fileType: file.type,
+                  fileType: file.type || "text/csv",
                   uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
                 }, dimension ? { dimension } : {}), {
                   csvHeaders: csvCols
@@ -9798,6 +10451,42 @@ function createUploadHandler(configOrPlugin, options) {
               });
             }
           }
+        } else if (isExcel) {
+          const xlsx = await import("xlsx");
+          const buffer = Buffer.isBuffer(file) ? file : Buffer.from(await file.arrayBuffer());
+          const workbook = xlsx.read(buffer, { type: "buffer" });
+          for (const sheetName of workbook.SheetNames) {
+            const sheet = workbook.Sheets[sheetName];
+            const jsonRows = xlsx.utils.sheet_to_json(sheet, { defval: "" });
+            if (jsonRows && jsonRows.length > 0) {
+              let i = 0;
+              const headers = Object.keys(jsonRows[0] || {});
+              for (const rowData of jsonRows) {
+                i++;
+                const contentParts = [];
+                for (const [key, val] of Object.entries(rowData)) {
+                  if (key && val !== void 0 && val !== null && String(val).trim()) {
+                    contentParts.push(`${key}: ${val}`);
+                  }
+                }
+                if (contentParts.length > 0) {
+                  documents.push({
+                    docId: `${file.name}-${sheetName}-row-${i}`,
+                    content: contentParts.join(", "),
+                    metadata: __spreadValues(__spreadProps(__spreadValues({
+                      fileName: file.name,
+                      sheetName,
+                      fileSize: file.size,
+                      fileType: file.type || "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                      uploadedAt: (/* @__PURE__ */ new Date()).toISOString()
+                    }, dimension ? { dimension } : {}), {
+                      headers
+                    }), rowData)
+                  });
+                }
+              }
+            }
+          }
         } else {
           const content = await DocumentParser.parse(file, file.name, file.type);
           documents.push({
@@ -10025,6 +10714,8 @@ function createRagHandler(configOrPlugin, options) {
   AuthenticationException,
   BaseVectorProvider,
   BatchProcessor,
+  CarouselRendererStrategy,
+  ChartRendererStrategy,
   ChromaDBProvider,
   ConfigBuilder,
   ConfigResolver,
@@ -10036,10 +10727,12 @@ function createRagHandler(configOrPlugin, options) {
   EmbeddingStrategy,
   EmbeddingStrategyResolver,
   GroqProvider,
+  IntentClassifier,
   LLMFactory,
   LLM_PROFILES,
   LicenseVerifier,
   MilvusProvider,
+  MixedRendererStrategy,
   MongoDBProvider,
   MultiTablePostgresProvider,
   OllamaProvider,
@@ -10055,13 +10748,25 @@ function createRagHandler(configOrPlugin, options) {
   QwenProvider,
   RateLimitException,
   RedisProvider,
+  RendererRegistry,
   RetrievalException,
   Retrivora,
   RetrivoraError,
+  Rule1SpecificInfoRule,
+  Rule2ComparisonRule,
+  Rule3ProductDiscoveryRule,
+  Rule4AnalyticalRule,
+  Rule5MixedResponseRule,
+  Rule6SmallResultSetRule,
+  Rule7LargeTableRule,
+  RuleEngine,
+  TableRendererStrategy,
+  TextRendererStrategy,
   UniversalLLMAdapter,
   UniversalVectorProvider,
   VECTOR_PROFILES,
   VectorPlugin,
+  VisualizationDecisionEngine,
   WeaviateProvider,
   createChatHandler,
   createFeedbackHandler,
@@ -10073,6 +10778,7 @@ function createRagHandler(configOrPlugin, options) {
   createSessionsHandler,
   createStreamHandler,
   createUploadHandler,
+  decideVisualization,
   getRagConfig,
   sseErrorFrame,
   sseFrame,