feat: add insights recommender engine for template/variant suggestions

src/lib/insights/recommender.test.ts

@@ -0,0 +1,113 @@
+import { scoreRecommendation, recommendTemplateVariant } from './recommender';
+import type { GeneratedInsight } from '@/lib/analytics/insights';
+
+describe('Recommender Engine', () => {
+  describe('scoreRecommendation', () => {
+    it('should give high score to high-confidence template insights', () => {
+      const insight: GeneratedInsight = {
+        id: 'template-2026-04-07',
+        observation: '"bold-statement" template performed best',
+        confidence_level: 'high',
+        applies_to: 'template',
+        recommendation: 'Use bold-statement',
+        created_at: new Date().toISOString(),
+      };
+      const score = scoreRecommendation(insight);
+      expect(score).toBeGreaterThan(0.8);
+    });
+
+    it('should weight recent insights higher than old ones', () => {
+      const recentInsight: GeneratedInsight = {
+        id: 'template-2026-04-14',
+        observation: '"split-screen" template worked well',
+        confidence_level: 'high',
+        applies_to: 'template',
+        recommendation: 'Use split-screen',
+        created_at: new Date().toISOString(),
+      };
+
+      const oldInsight: GeneratedInsight = {
+        id: 'template-2026-03-14',
+        observation: '"numbered-steps" template worked well',
+        confidence_level: 'high',
+        applies_to: 'template',
+        recommendation: 'Use numbered-steps',
+        created_at: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
+      };
+
+      const recentScore = scoreRecommendation(recentInsight);
+      const oldScore = scoreRecommendation(oldInsight);
+      expect(recentScore).toBeGreaterThan(oldScore);
+    });
+
+    it('should give lower score to low-confidence insights', () => {
+      const lowConfInsight: GeneratedInsight = {
+        id: 'template-2026-04-14',
+        observation: 'Some template might work',
+        confidence_level: 'low',
+        applies_to: 'template',
+        recommendation: 'Maybe try this',
+        created_at: new Date().toISOString(),
+      };
+      const score = scoreRecommendation(lowConfInsight);
+      expect(score).toBeLessThan(0.5);
+    });
+  });
+
+  describe('recommendTemplateVariant', () => {
+    it('should return null when no insights provided', () => {
+      const rec = recommendTemplateVariant([]);
+      expect(rec).toBeNull();
+    });
+
+    it('should recommend template based on highest-scored insight', () => {
+      const insights: GeneratedInsight[] = [
+        {
+          id: 'template-1',
+          observation: '"bold-statement" performed best',
+          confidence_level: 'high',
+          applies_to: 'template',
+          recommendation: 'Use bold-statement',
+          created_at: new Date().toISOString(),
+        },
+        {
+          id: 'variant-1',
+          observation: '"alternate" variant got more engagement',
+          confidence_level: 'high',
+          applies_to: 'template',
+          recommendation: 'Try alternate variant',
+          created_at: new Date().toISOString(),
+        },
+      ];
+
+      const rec = recommendTemplateVariant(insights);
+      expect(rec).not.toBeNull();
+      expect(rec?.template).toBe('bold-statement');
+      expect(rec?.confidence).toBe('high');
+    });
+
+    it('should filter out non-template insights', () => {
+      const insights: GeneratedInsight[] = [
+        {
+          id: 'palette-1',
+          observation: 'Blue palette got engagement',
+          confidence_level: 'high',
+          applies_to: 'palette',
+          recommendation: 'Use blue',
+          created_at: new Date().toISOString(),
+        },
+        {
+          id: 'template-1',
+          observation: '"quote-card" template worked',
+          confidence_level: 'medium',
+          applies_to: 'template',
+          recommendation: 'Use quote-card',
+          created_at: new Date().toISOString(),
+        },
+      ];
+
+      const rec = recommendTemplateVariant(insights);
+      expect(rec?.template).toBe('quote-card');
+    });
+  });
+});

src/lib/insights/recommender.ts

@@ -0,0 +1,98 @@
+import type { GeneratedInsight } from '@/lib/analytics/insights';
+import type { Template } from '@/types/carousel';
+
+export interface TemplateRecommendation {
+  template: Template;
+  confidence: 'high' | 'medium' | 'low';
+  reason: string;
+  score: number;
+}
+
+/**
+ * Score an insight based on confidence level, recency, and relevance.
+ * Returns 0-1 score where 1 is highest recommendation.
+ */
+export function scoreRecommendation(insight: GeneratedInsight): number {
+  // Base score from confidence level
+  const confidenceScores: Record<string, number> = {
+    high: 1.0,
+    medium: 0.6,
+    low: 0.3,
+  };
+  let score = confidenceScores[insight.confidence_level] || 0.3;
+
+  // Adjust for recency (insights older than 2 weeks get lower score)
+  const createdDate = new Date(insight.created_at).getTime();
+  const now = Date.now();
+  const ageInDays = (now - createdDate) / (1000 * 60 * 60 * 24);
+
+  if (ageInDays > 14) {
+    score *= Math.max(0.5, 1 - ageInDays / 60); // Decay over 60 days
+  }
+
+  return Math.min(1, Math.max(0, score));
+}
+
+/**
+ * Extract template name from insight observation string.
+ * Looks for template names in quotes within observation.
+ */
+function extractTemplateFromObservation(observation: string): Template | null {
+  const templates: Template[] = ['bold-statement', 'split-screen', 'numbered-steps', 'quote-card', 'data-point'];
+
+  for (const template of templates) {
+    // Look for template name in quotes or as part of sentence
+    const regex = new RegExp(`["']?${template}["']?`, 'i');
+    if (regex.test(observation)) {
+      return template;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Recommend a template/variant based on highest-scored insights.
+ * Returns null if no valid recommendations found.
+ */
+export function recommendTemplateVariant(
+  insights: GeneratedInsight[]
+): TemplateRecommendation | null {
+  // Filter to template-related insights only
+  const templateInsights = insights.filter(
+    (i) => i.applies_to === 'template'
+  );
+
+  if (templateInsights.length === 0) {
+    return null;
+  }
+
+  // Score and sort
+  const scored = templateInsights
+    .map((insight) => ({
+      insight,
+      score: scoreRecommendation(insight),
+      template: extractTemplateFromObservation(insight.observation),
+    }))
+    .filter((item) => item.template !== null)
+    .sort((a, b) => b.score - a.score);
+
+  if (scored.length === 0) {
+    return null;
+  }
+
+  const best = scored[0];
+  return {
+    template: best.template!,
+    confidence: best.insight.confidence_level,
+    reason: best.insight.recommendation,
+    score: best.score,
+  };
+}
+
+/**
+ * Filter insights to only high/medium confidence ones suitable for display.
+ */
+export function filterHighConfidenceInsights(insights: GeneratedInsight[]): GeneratedInsight[] {
+  return insights.filter((i) => i.confidence_level === 'high' || i.confidence_level === 'medium');
+}