@retrivora-ai/rag-engine 2.0.1 → 2.0.3

package/src/rendering/RendererRegistry.ts

@@ -0,0 +1,164 @@
+import { IRendererStrategy, RenderType } from './types';
+import { UITransformationResponse, VectorMatch } from '../types';
+import { UITransformer } from '../utils/UITransformer';
+
+// ── Default Strategy Implementations ───────────────────────────────────────────
+
+export class TextRendererStrategy implements IRendererStrategy {
+  readonly type = 'text';
+
+  render(data: unknown, options?: Record<string, unknown>): UITransformationResponse {
+    const title = (options?.title as string) || 'Information';
+    if (typeof data === 'string') {
+      return { type: 'text', title, data: { content: data } };
+    }
+    const docs = Array.isArray(data) ? (data as VectorMatch[]) : [];
+    const text = docs.map(d => d.content).join('\n\n');
+    return { type: 'text', title, data: { content: text || 'No detailed content available.' } };
+  }
+}
+
+export class TableRendererStrategy implements IRendererStrategy {
+  readonly type = 'table';
+
+  render(data: unknown, options?: Record<string, unknown>): UITransformationResponse {
+    const docs = Array.isArray(data) ? (data as VectorMatch[]) : [];
+    const query = (options?.query as string) || '';
+    return UITransformer.transform(query, docs, undefined, undefined, {
+      visualizationHint: 'table',
+      recommendedChart: 'table',
+      filterInStockOnly: false,
+      wantsExplicitTable: true,
+      isTemporal: false,
+      isComparison: true,
+      language: 'en',
+    });
+  }
+}
+
+export class CarouselRendererStrategy implements IRendererStrategy {
+  readonly type = 'carousel';
+
+  render(data: unknown, options?: Record<string, unknown>): UITransformationResponse {
+    const docs = Array.isArray(data) ? (data as VectorMatch[]) : [];
+    const query = (options?.query as string) || '';
+    return UITransformer.transform(query, docs, undefined, undefined, {
+      visualizationHint: 'product_browse',
+      recommendedChart: 'text',
+      filterInStockOnly: false,
+      wantsExplicitTable: false,
+      isTemporal: false,
+      isComparison: false,
+      language: 'en',
+    });
+  }
+}
+
+export class ChartRendererStrategy implements IRendererStrategy {
+  readonly type = 'chart';
+
+  render(data: unknown, options?: Record<string, unknown>): UITransformationResponse {
+    const docs = Array.isArray(data) ? (data as VectorMatch[]) : [];
+    const query = (options?.query as string) || '';
+    const chartType = (options?.chartType as string) || 'bar';
+
+    let hint: any = 'comparison';
+    let rec: any = '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, undefined, undefined, {
+      visualizationHint: hint,
+      recommendedChart: rec,
+      filterInStockOnly: false,
+      wantsExplicitTable: false,
+      isTemporal: chartType === 'line',
+      isComparison: chartType === 'bar',
+      language: 'en',
+    });
+  }
+}
+
+export class MixedRendererStrategy implements IRendererStrategy {
+  readonly type = 'mixed';
+
+  render(data: unknown, options?: Record<string, unknown>): UITransformationResponse {
+    const docs = Array.isArray(data) ? (data as VectorMatch[]) : [];
+    const sections = (options?.sections as Array<{ type: RenderType; chartType?: string; title?: string }>) || [];
+
+    const sectionPayloads = sections.map(s => {
+      const strategy = RendererRegistry.getStrategy(s.type);
+      return {
+        type: s.type,
+        title: s.title,
+        payload: strategy.render(data, { ...options, chartType: s.chartType, title: s.title }),
+      };
+    });
+
+    return {
+      type: 'table', // Fallback container type for compatibility
+      title: (options?.title as string) || 'Composite Response',
+      description: `Mixed payload containing ${sectionPayloads.length} visual sections`,
+      data: { sections: sectionPayloads },
+    };
+  }
+}
+
+// ── Renderer Registry Class ───────────────────────────────────────────────────
+
+export class RendererRegistry {
+  private static strategies = new Map<string, IRendererStrategy>();
+
+  static {
+    // Register default strategies
+    this.registerStrategy(new TextRendererStrategy());
+    this.registerStrategy(new TableRendererStrategy());
+    this.registerStrategy(new CarouselRendererStrategy());
+    this.registerStrategy(new ChartRendererStrategy());
+    this.registerStrategy(new MixedRendererStrategy());
+  }
+
+  /**
+   * Register a new renderer strategy.
+   * Enables seamless addition of custom visualizers (Timeline, Maps, Flow Diagrams, etc.).
+   */
+  static registerStrategy(strategy: IRendererStrategy): void {
+    this.strategies.set(String(strategy.type).toLowerCase(), strategy);
+  }
+
+  /**
+   * Retrieve a registered renderer strategy by type string.
+   */
+  static getStrategy(type: string): IRendererStrategy {
+    const key = type.toLowerCase();
+    const strategy = this.strategies.get(key);
+    if (!strategy) {
+      // Fallback to text strategy if unknown type requested
+      return this.strategies.get('text')!;
+    }
+    return strategy;
+  }
+
+  /**
+   * Check if a renderer strategy is registered.
+   */
+  static hasStrategy(type: string): boolean {
+    return this.strategies.has(type.toLowerCase());
+  }
+
+  /**
+   * List all registered strategy types.
+   */
+  static getRegisteredTypes(): string[] {
+    return Array.from(this.strategies.keys());
+  }
+}

package/src/rendering/RuleEngine.ts

@@ -0,0 +1,67 @@
+import { DecisionContext, IntentCategory, IRenderRule, RenderDecision } from './types';
+import { Rule1SpecificInfoRule } from './rules/Rule1SpecificInfoRule';
+import { Rule2ComparisonRule } from './rules/Rule2ComparisonRule';
+import { Rule3ProductDiscoveryRule } from './rules/Rule3ProductDiscoveryRule';
+import { Rule4AnalyticalRule } from './rules/Rule4AnalyticalRule';
+import { Rule5MixedResponseRule } from './rules/Rule5MixedResponseRule';
+import { Rule6SmallResultSetRule } from './rules/Rule6SmallResultSetRule';
+import { Rule7LargeTableRule } from './rules/Rule7LargeTableRule';
+
+export class RuleEngine {
+  private rules: IRenderRule[] = [];
+
+  constructor() {
+    this.registerDefaultRules();
+  }
+
+  /**
+   * Register standard rules in priority order.
+   */
+  private registerDefaultRules() {
+    this.registerRule(new Rule6SmallResultSetRule());   // Priority 110 (Small data guardrail)
+    this.registerRule(new Rule1SpecificInfoRule());    // Priority 100 (Fact/definition)
+    this.registerRule(new Rule5MixedResponseRule());    // Priority 95  (Multi-section)
+    this.registerRule(new Rule2ComparisonRule());       // Priority 90  (Comparison)
+    this.registerRule(new Rule3ProductDiscoveryRule()); // Priority 85  (Product/carousel)
+    this.registerRule(new Rule4AnalyticalRule());       // Priority 80  (Charts)
+    this.registerRule(new Rule7LargeTableRule());       // Priority 75  (Large datasets > 5)
+  }
+
+  /**
+   * Add or replace a rule in the engine.
+   * Automatically keeps rules sorted by descending priority.
+   */
+  registerRule(rule: IRenderRule): void {
+    // Remove existing rule with same name if present
+    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: DecisionContext, intent: IntentCategory): RenderDecision {
+    for (const rule of this.rules) {
+      const decision = rule.evaluate(context, intent);
+      if (decision) {
+        return decision;
+      }
+    }
+
+    // Default fallback
+    return {
+      renderType: 'text',
+      confidence: 0.70,
+      reason: 'Default fallback: No specific visualization rule matched context.',
+    };
+  }
+
+  /**
+   * List all registered rules.
+   */
+  getRegisteredRules(): Array<{ name: string; priority: number }> {
+    return this.rules.map(r => ({ name: r.name, priority: r.priority }));
+  }
+}

package/src/rendering/VisualizationDecisionEngine.ts

@@ -0,0 +1,164 @@
+import { DecisionContext, RenderDecision } from './types';
+import { IntentClassifier } from './IntentClassifier';
+import { RuleEngine } from './RuleEngine';
+import { RendererRegistry } from './RendererRegistry';
+import { UITransformationResponse, VectorMatch } from '../types';
+
+/**
+ * LRU Cache for visualization decisions to achieve sub-millisecond repeated execution.
+ */
+class LRUDecisionCache {
+  private cache = new Map<string, { decision: RenderDecision; timestamp: number }>();
+  private maxSize: number;
+
+  constructor(maxSize = 200) {
+    this.maxSize = maxSize;
+  }
+
+  private generateKey(context: DecisionContext): string {
+    const q = (context.userQuery || '').toLowerCase().trim();
+    const docCount = context.retrievedDocuments?.length ?? 0;
+    return `${q}::docs:${docCount}`;
+  }
+
+  get(context: DecisionContext): RenderDecision | undefined {
+    const key = this.generateKey(context);
+    const item = this.cache.get(key);
+    if (item) {
+      // Refresh LRU position
+      this.cache.delete(key);
+      this.cache.set(key, item);
+      return item.decision;
+    }
+    return undefined;
+  }
+
+  set(context: DecisionContext, decision: RenderDecision): void {
+    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 !== undefined) this.cache.delete(oldest);
+    }
+    this.cache.set(key, { decision, timestamp: Date.now() });
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * High-Performance Visualization Decision Engine.
+ * Intelligently determines whether to render text, table, carousel, chart, or mixed sections
+ * BEFORE expensive visual generation or LLM visual calls execute.
+ */
+export class VisualizationDecisionEngine {
+  private static ruleEngine = new RuleEngine();
+  private static cache = new LRUDecisionCache(200);
+
+  /**
+   * Evaluate user query, documents, and context to produce a RenderDecision.
+   * Execution time is < 1ms for cached or rule-matched queries.
+   */
+  static decideVisualization(
+    userQuery: string,
+    retrievedDocuments?: VectorMatch[],
+    llmResponse?: string,
+    metadata?: Record<string, unknown>
+  ): RenderDecision {
+    const context: DecisionContext = {
+      userQuery,
+      retrievedDocuments,
+      llmResponse,
+      metadata,
+    };
+
+    // Check LRU cache first
+    const cached = this.cache.get(context);
+    if (cached) {
+      return cached;
+    }
+
+    // Step 1: Zero-latency Intent Classification
+    const { intent } = IntentClassifier.classify(context);
+
+    // Step 2: Evaluate priority rules
+    const decision = this.ruleEngine.evaluate(context, intent);
+
+    // Cache result
+    this.cache.set(context, decision);
+
+    return decision;
+  }
+
+  /**
+   * Convenience helper to decide AND render the data into a UITransformationResponse.
+   */
+  static render(
+    userQuery: string,
+    retrievedDocuments?: VectorMatch[],
+    llmResponse?: string,
+    metadata?: Record<string, unknown>
+  ): UITransformationResponse {
+    const decision = this.decideVisualization(userQuery, retrievedDocuments, llmResponse, metadata);
+    const strategy = RendererRegistry.getStrategy(decision.renderType);
+    return strategy.render(retrievedDocuments || [], {
+      query: userQuery,
+      chartType: decision.chartType,
+      sections: decision.sections,
+      ...metadata,
+    });
+  }
+
+  /**
+   * Register a custom rule in the rule engine.
+   */
+  static registerRule(rule: import('./types').IRenderRule): void {
+    this.ruleEngine.registerRule(rule);
+    this.cache.clear(); // Clear cache when rules change
+  }
+
+  /**
+   * Register a custom renderer strategy.
+   */
+  static registerRendererStrategy(strategy: import('./types').IRendererStrategy): void {
+    RendererRegistry.registerStrategy(strategy);
+  }
+
+  /**
+   * Clear the decision cache.
+   */
+  static clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get size of current decision cache.
+   */
+  static getCacheSize(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Top-level function export matching prompt specification.
+ */
+export function decideVisualization(
+  userQuery: string,
+  retrievedDocuments?: VectorMatch[],
+  llmResponse?: string,
+  metadata?: Record<string, unknown>
+): RenderDecision {
+  return VisualizationDecisionEngine.decideVisualization(
+    userQuery,
+    retrievedDocuments,
+    llmResponse,
+    metadata
+  );
+}

package/src/rendering/__tests__/VisualizationDecisionEngine.test.ts

@@ -0,0 +1,237 @@
+import { VisualizationDecisionEngine, decideVisualization } from '../VisualizationDecisionEngine';
+import { RendererRegistry } from '../RendererRegistry';
+import { IRendererStrategy, RenderDecision } from '../types';
+import { VectorMatch, UITransformationResponse } from '../../types';
+
+describe('VisualizationDecisionEngine Specification Tests', () => {
+  beforeEach(() => {
+    VisualizationDecisionEngine.clearCache();
+  });
+
+  // Mock retrieved documents helper
+  const createMockDocs = (count: number, withNumeric = false): VectorMatch[] => {
+    return Array.from({ length: count }, (_, i) => ({
+      id: `doc-${i + 1}`,
+      score: 0.95 - i * 0.05,
+      content: `Item ${i + 1} content details`,
+      metadata: {
+        title: `Product ${i + 1}`,
+        price: withNumeric ? 100 + i * 50 : undefined,
+        sales: withNumeric ? 500 - i * 30 : undefined,
+        category: `Category ${ (i % 3) + 1 }`,
+        date: `2026-0${ (i % 9) + 1 }-01`,
+      },
+    }));
+  };
+
+  // ── Rule 1: Specific Information Requests ──────────────────────────────────
+  describe('Rule 1: Specific Information Requests', () => {
+
+    test('should render text for "What is Pinecone?"', () => {
+      const decision = decideVisualization('What is Pinecone?', createMockDocs(4));
+      expect(decision.renderType).toBe('text');
+      expect(decision.confidence).toBeGreaterThanOrEqual(0.9);
+    });
+
+    test('should render text for "What is the price of iPhone 16?"', () => {
+      const decision = decideVisualization('What is the price of iPhone 16?', createMockDocs(4, true));
+      expect(decision.renderType).toBe('text');
+    });
+
+    test('should render text for "Explain RAG."', () => {
+      const decision = decideVisualization('Explain RAG.', createMockDocs(3));
+      expect(decision.renderType).toBe('text');
+    });
+
+    test('should render text for "Who is the CEO of OpenAI?"', () => {
+      const decision = decideVisualization('Who is the CEO of OpenAI?', createMockDocs(4));
+      expect(decision.renderType).toBe('text');
+    });
+
+    test('should render text for "What is namespace in Pinecone?"', () => {
+      const decision = decideVisualization('What is namespace in Pinecone?', createMockDocs(5));
+      expect(decision.renderType).toBe('text');
+    });
+  });
+
+  // ── Rule 2: Comparison Queries ─────────────────────────────────────────────
+  describe('Rule 2: Comparison Queries', () => {
+
+    test('should render table for "Compare GPT-4 vs Claude"', () => {
+      const decision = decideVisualization('Compare GPT-4 vs Claude', createMockDocs(4));
+      expect(decision.renderType).toBe('table');
+      expect(decision.confidence).toBeGreaterThanOrEqual(0.85);
+    });
+
+    test('should render table for "Compare iPhone vs Pixel"', () => {
+      const decision = decideVisualization('Compare iPhone vs Pixel', createMockDocs(4));
+      expect(decision.renderType).toBe('table');
+    });
+
+    test('should render table for "Difference between React and Vue"', () => {
+      const decision = decideVisualization('Difference between React and Vue', createMockDocs(4));
+      expect(decision.renderType).toBe('table');
+    });
+  });
+
+  // ── Rule 3: Product Discovery ──────────────────────────────────────────────
+  describe('Rule 3: Product Discovery', () => {
+
+    test('should render carousel for "Best gaming laptops"', () => {
+      const decision = decideVisualization('Best gaming laptops', createMockDocs(4, true));
+      expect(decision.renderType).toBe('carousel');
+    });
+
+    test('should render carousel for "Recommend office chairs"', () => {
+      const decision = decideVisualization('Recommend office chairs', createMockDocs(5, true));
+      expect(decision.renderType).toBe('carousel');
+    });
+
+    test('should render carousel for "Best headphones under $200"', () => {
+      const decision = decideVisualization('Best headphones under $200', createMockDocs(4, true));
+      expect(decision.renderType).toBe('carousel');
+    });
+
+    test('should render carousel for "Show available Nike shoes"', () => {
+      const decision = decideVisualization('Show available Nike shoes', createMockDocs(5, true));
+      expect(decision.renderType).toBe('carousel');
+    });
+  });
+
+  // ── Rule 4: Analytical Queries & Chart Types ───────────────────────────────
+  describe('Rule 4: Analytical Queries', () => {
+
+    test('should render line chart for "Monthly sales"', () => {
+      const decision = decideVisualization('Monthly sales', createMockDocs(5, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('line');
+    });
+
+    test('should render line chart for "Revenue growth"', () => {
+      const decision = decideVisualization('Revenue growth', createMockDocs(5, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('line');
+    });
+
+    test('should render bar chart for "Top performing products"', () => {
+      const decision = decideVisualization('Top performing products', createMockDocs(4, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('bar');
+    });
+
+    test('should render line chart for "Population trends"', () => {
+      const decision = decideVisualization('Population trends', createMockDocs(5, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('line');
+    });
+
+    test('should render bar chart for "Sales by region"', () => {
+      const decision = decideVisualization('Sales by region', createMockDocs(4, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('bar');
+    });
+
+    test('should render pie chart for "Percentage breakdown of categories"', () => {
+      const decision = decideVisualization('Percentage breakdown of categories', createMockDocs(4, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('pie');
+    });
+
+    test('should render scatter chart for "Correlation between price and rating"', () => {
+      const decision = decideVisualization('Correlation between price and rating', createMockDocs(4, true));
+      expect(decision.renderType).toBe('chart');
+      expect(decision.chartType).toBe('scatter');
+    });
+  });
+
+  // ── Rule 5: Mixed Responses ────────────────────────────────────────────────
+  describe('Rule 5: Mixed Responses', () => {
+
+    test('should render mixed sections for "Show top selling products this month"', () => {
+      const decision = decideVisualization('Show top selling products this month.', createMockDocs(5, true));
+      expect(decision.renderType).toBe('mixed');
+      expect(decision.sections).toBeDefined();
+      expect(decision.sections?.length).toBe(3);
+
+      const sectionTypes = decision.sections?.map(s => s.type);
+      expect(sectionTypes).toEqual(['text', 'carousel', 'chart']);
+    });
+  });
+
+  // ── Rule 6: Small Result Sets (< 3 rows) ───────────────────────────────────
+  describe('Rule 6: Small Result Sets', () => {
+
+    test('should demote chart to text when result count is 2 (< 3 rows)', () => {
+      const decision = decideVisualization('Monthly sales', createMockDocs(2, true));
+      expect(decision.renderType).toBe('text'); // Demoted from chart to text
+      expect(decision.reason).toContain('Rule 6');
+    });
+
+    test('should allow table for explicit comparison even with 2 rows', () => {
+      const decision = decideVisualization('Compare GPT-4 vs Claude', createMockDocs(2));
+      expect(decision.renderType).toBe('table');
+    });
+  });
+
+  // ── Rule 7: Large Tables (> 5 rows) ────────────────────────────────────────
+  describe('Rule 7: Large Tables', () => {
+
+    test('should render table for generic non-analytical large dataset (> 5 rows)', () => {
+      const decision = decideVisualization('List overall documents in system', createMockDocs(8));
+      expect(decision.renderType).toBe('table');
+      expect(decision.reason).toContain('Rule 7');
+    });
+
+    test('should render mixed table+chart for large analytical dataset (> 5 rows)', () => {
+      const decision = decideVisualization('Regional sales statistics', createMockDocs(8, true));
+      expect(decision.renderType).toBe('mixed');
+      expect(decision.sections?.some(s => s.type === 'table')).toBe(true);
+      expect(decision.sections?.some(s => s.type === 'chart')).toBe(true);
+    });
+  });
+
+  // ── Strategy Registry & Extensibility ──────────────────────────────────────
+  describe('Extensibility & Strategy Registry', () => {
+
+    test('should support registering custom timeline renderer strategy', () => {
+      class TimelineRendererStrategy implements IRendererStrategy {
+        readonly type = 'timeline';
+        render(data: unknown): UITransformationResponse {
+          return {
+            type: 'text',
+            title: 'Timeline Events',
+            data: { content: 'Rendered timeline' },
+          };
+        }
+      }
+
+      RendererRegistry.registerStrategy(new TimelineRendererStrategy());
+      expect(RendererRegistry.hasStrategy('timeline')).toBe(true);
+
+      const strategy = RendererRegistry.getStrategy('timeline');
+      const res = strategy.render(createMockDocs(3));
+      expect(res.title).toBe('Timeline Events');
+    });
+  });
+
+  // ── Performance & LRU Decision Cache ──────────────────────────────────────
+  describe('Performance & Caching', () => {
+
+    test('should return cached decisions on repeated queries in < 1ms', () => {
+      const query = 'What is namespace in Pinecone?';
+      const docs = createMockDocs(4);
+
+      const t0 = performance.now();
+      const firstDecision = decideVisualization(query, docs);
+      const t1 = performance.now();
+
+      const t2 = performance.now();
+      const secondDecision = decideVisualization(query, docs);
+      const t3 = performance.now();
+
+      expect(firstDecision.renderType).toBe(secondDecision.renderType);
+      expect(t3 - t2).toBeLessThan(1.0); // Sub-millisecond execution
+      expect(VisualizationDecisionEngine.getCacheSize()).toBeGreaterThan(0);
+    });
+  });
+});

package/src/rendering/index.ts

@@ -0,0 +1,12 @@
+export * from './types';
+export { IntentClassifier } from './IntentClassifier';
+export { RuleEngine } from './RuleEngine';
+export { RendererRegistry, TextRendererStrategy, TableRendererStrategy, CarouselRendererStrategy, ChartRendererStrategy, MixedRendererStrategy } from './RendererRegistry';
+export { VisualizationDecisionEngine, decideVisualization } from './VisualizationDecisionEngine';
+export { Rule1SpecificInfoRule } from './rules/Rule1SpecificInfoRule';
+export { Rule2ComparisonRule } from './rules/Rule2ComparisonRule';
+export { Rule3ProductDiscoveryRule } from './rules/Rule3ProductDiscoveryRule';
+export { Rule4AnalyticalRule } from './rules/Rule4AnalyticalRule';
+export { Rule5MixedResponseRule } from './rules/Rule5MixedResponseRule';
+export { Rule6SmallResultSetRule } from './rules/Rule6SmallResultSetRule';
+export { Rule7LargeTableRule } from './rules/Rule7LargeTableRule';

package/src/rendering/rules/Rule1SpecificInfoRule.ts

@@ -0,0 +1,28 @@
+import { DecisionContext, IntentCategory, IRenderRule, RenderDecision } from '../types';
+
+export class Rule1SpecificInfoRule implements IRenderRule {
+  readonly name = 'Rule1SpecificInfo';
+  readonly priority = 100;
+
+  evaluate(context: DecisionContext, intent: IntentCategory): RenderDecision | null {
+    const q = (context.userQuery || '').toLowerCase().trim();
+
+    // Check specific fact/definition/explanation indicators
+    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;
+  }
+}