LLM Mentions Tracking

1// LLM Mentions Tracking Implementation
2 
3interface LLMMention {
4  platform: 'chatgpt' | 'claude' | 'gemini' | 'perplexity' | 'copilot' | 'other';
5  modelVersion: string;
6  query: string;
7  response: string;
8  mentionDetected: boolean;
9  mentionType: 'direct' | 'indirect' | 'contextual' | 'none';
10  mentionSentiment: 'positive' | 'neutral' | 'negative' | 'mixed';
11  mentionAccuracy: 'accurate' | 'partial' | 'inaccurate' | 'outdated';
12  competitorsMentioned: string[];
13  timestamp: Date;
14  topicCategory: string;
15}
16 
17interface MentionTrackingConfig {
18  brand: string;
19  brandVariations: string[];
20  competitors: string[];
21  platforms: string[];
22  queryLibrary: QueryDefinition[];
23  trackingFrequency: 'daily' | 'weekly' | 'monthly';
24}
25 
26interface QueryDefinition {
27  query: string;
28  category: string;
29  intent: 'informational' | 'commercial' | 'navigational' | 'comparison';
30  expectedMention: boolean;
31  priority: 'high' | 'medium' | 'low';
32}
33 
34// Core mention detection function
35function detectMention(
36  response: string,
37  brand: string,
38  brandVariations: string[]
39): { detected: boolean; type: string; context: string } {
40  const allBrandTerms = [brand, ...brandVariations].map(b => b.toLowerCase());
41  const responseLower = response.toLowerCase();
42  
43  // Direct mention detection
44  for (const term of allBrandTerms) {
45    if (responseLower.includes(term)) {
46      // Extract context around mention
47      const index = responseLower.indexOf(term);
48      const contextStart = Math.max(0, index - 100);
49      const contextEnd = Math.min(response.length, index + term.length + 100);
50      const context = response.substring(contextStart, contextEnd);
51      
52      return {
53        detected: true,
54        type: determineMentionType(context, term),
55        context
56      };
57    }
58  }
59  
60  return { detected: false, type: 'none', context: '' };
61}
62 
63function determineMentionType(context: string, term: string): string {
64  const contextLower = context.toLowerCase();
65  
66  // Check for recommendation context
67  if (contextLower.includes('recommend') || 
68      contextLower.includes('suggest') || 
69      contextLower.includes('best option')) {
70    return 'direct';
71  }
72  
73  // Check for comparison context
74  if (contextLower.includes('compared to') || 
75      contextLower.includes('alternative') ||
76      contextLower.includes('versus')) {
77    return 'contextual';
78  }
79  
80  // Check for list context
81  if (contextLower.includes('include') || 
82      contextLower.includes('such as') ||
83      contextLower.includes('examples')) {
84    return 'indirect';
85  }
86  
87  return 'direct';
88}
89 
90// Sentiment analysis for mentions
91function analyzeMentionSentiment(context: string): string {
92  const positiveIndicators = [
93    'excellent', 'best', 'leading', 'top', 'recommended', 
94    'reliable', 'trusted', 'innovative', 'powerful'
95  ];
96  const negativeIndicators = [
97    'issues', 'problems', 'expensive', 'complex', 'difficult',
98    'outdated', 'limited', 'concerns', 'drawbacks'
99  ];
100  
101  const contextLower = context.toLowerCase();
102  let positiveScore = 0;
103  let negativeScore = 0;
104  
105  positiveIndicators.forEach(indicator => {
106    if (contextLower.includes(indicator)) positiveScore++;
107  });
108  
109  negativeIndicators.forEach(indicator => {
110    if (contextLower.includes(indicator)) negativeScore++;
111  });
112  
113  if (positiveScore > negativeScore + 1) return 'positive';
114  if (negativeScore > positiveScore + 1) return 'negative';
115  if (positiveScore > 0 && negativeScore > 0) return 'mixed';
116  return 'neutral';
117}
118 
119// Cross-platform mention tracking
120async function trackMentionsAcrossPlatforms(
121  config: MentionTrackingConfig,
122  querySubset?: string[]
123): Promise<LLMMention[]> {
124  const queries = querySubset || config.queryLibrary.map(q => q.query);
125  const results: LLMMention[] = [];
126  
127  for (const platform of config.platforms) {
128    for (const queryDef of config.queryLibrary) {
129      if (querySubset && !querySubset.includes(queryDef.query)) continue;
130      
131      const response = await queryPlatform(platform, queryDef.query);
132      const mentionResult = detectMention(
133        response, 
134        config.brand, 
135        config.brandVariations
136      );
137      
138      const competitorsMentioned = config.competitors.filter(
139        competitor => response.toLowerCase().includes(competitor.toLowerCase())
140      );
141      
142      results.push({
143        platform: platform as any,
144        modelVersion: await getModelVersion(platform),
145        query: queryDef.query,
146        response,
147        mentionDetected: mentionResult.detected,
148        mentionType: mentionResult.type as any,
149        mentionSentiment: mentionResult.detected 
150          ? analyzeMentionSentiment(mentionResult.context) as any
151          : 'neutral',
152        mentionAccuracy: mentionResult.detected 
153          ? 'accurate' // Would need fact-checking logic
154          : 'accurate',
155        competitorsMentioned,
156        timestamp: new Date(),
157        topicCategory: queryDef.category
158      });
159    }
160  }
161  
162  return results;
163}
164 
165// Generate mention tracking report
166function generateMentionReport(mentions: LLMMention[]): MentionReport {
167  const totalQueries = mentions.length;
168  const mentionsDetected = mentions.filter(m => m.mentionDetected).length;
169  
170  // Calculate by platform
171  const platforms = [...new Set(mentions.map(m => m.platform))];
172  const byPlatform: Record<string, number> = {};
173  platforms.forEach(platform => {
174    const platformMentions = mentions.filter(m => m.platform === platform);
175    const detected = platformMentions.filter(m => m.mentionDetected).length;
176    byPlatform[platform] = (detected / platformMentions.length) * 100;
177  });
178  
179  // Calculate by topic
180  const topics = [...new Set(mentions.map(m => m.topicCategory))];
181  const byTopic: Record<string, number> = {};
182  topics.forEach(topic => {
183    const topicMentions = mentions.filter(m => m.topicCategory === topic);
184    const detected = topicMentions.filter(m => m.mentionDetected).length;
185    byTopic[topic] = (detected / topicMentions.length) * 100;
186  });
187  
188  // Sentiment distribution
189  const sentimentDist = {
190    positive: mentions.filter(m => m.mentionSentiment === 'positive').length,
191    neutral: mentions.filter(m => m.mentionSentiment === 'neutral').length,
192    negative: mentions.filter(m => m.mentionSentiment === 'negative').length,
193    mixed: mentions.filter(m => m.mentionSentiment === 'mixed').length
194  };
195  
196  return {
197    overallMentionRate: (mentionsDetected / totalQueries) * 100,
198    mentionRateByPlatform: byPlatform,
199    mentionRateByTopic: byTopic,
200    sentimentDistribution: sentimentDist,
201    competitorComparison: calculateCompetitorShares(mentions),
202    gapAnalysis: identifyMentionGaps(mentions)
203  };
204}