Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(server): record brand mention position on tracking results (#569)
Gökhan Geyik22c8cd30774c
diff --git a/server/src/lib/cloro-result-handler.js b/server/src/lib/cloro-result-handler.jsindex 36bfceff0..d6e891a70 100644--- a/server/src/lib/cloro-result-handler.js+++ b/server/src/lib/cloro-result-handler.js@@ -64,6 +64,8 @@ export async function handleScraperResult({model_used: aiResponse.model,region: region ?? null,competitor_mentions: metrics.competitorMentions,+ mention_position: metrics.mentionPosition,+ mentioned_entity_count: metrics.mentionedEntityCount,shopping_cards: aiResponse.shopping_cards ?? [],inline_products: aiResponse.inline_products ?? [],search_queries: Array.isArray(aiResponse.search_queries) ? aiResponse.search_queries : [],diff --git a/server/src/lib/response-parser.js b/server/src/lib/response-parser.jsindex 0f08b1afa..5631a5e6e 100644--- a/server/src/lib/response-parser.js+++ b/server/src/lib/response-parser.js@@ -86,6 +86,52 @@ export function countBrandMentions(text, brand) {return count;}+/**+ * First word-boundary occurrence index of a term (case-insensitive), or -1.+ */+function firstOccurrenceIndex(text, term) {+ if (!term) return -1;+ const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+ const match = new RegExp(`\\b${escaped}\\b`, 'i').exec(text);+ return match ? match.index : -1;+}++/**+ * Where the brand lands in the answer's mention order, among the brand and+ * its tracked competitors. Deterministic: earliest word-boundary occurrence+ * of each entity's name/domain in the URL-stripped answer text.+ *+ * @returns {{ mentionPosition: number | null, mentionedEntityCount: number }}+ * mentionPosition — 1-based rank of the brand's first mention (1 = named+ * first), null when the brand isn't mentioned at all.+ * mentionedEntityCount — how many of the tracked entities (brand ++ * competitors) the answer mentions; 0 marks "computed, nothing found",+ * while NULL in the database means "not computed yet" (backfill marker).+ */+export function computeMentionPosition(text, brand, competitors = []) {+ const cleanText = stripUrls(text);++ const entityFirstIndex = (names) => {+ let best = -1;+ for (const name of names) {+ const idx = firstOccurrenceIndex(cleanText, name);+ if (idx >= 0 && (best === -1 || idx < best)) best = idx;+ }+ return best;+ };++ const brandIndex = entityFirstIndex([brand.brandName, ...(brand.domains || [])]);+ const competitorIndexes = (competitors || [])+ .map((comp) => entityFirstIndex([comp.name, ...(comp.domain ? [comp.domain] : [])]))+ .filter((idx) => idx >= 0);++ const mentionedEntityCount = competitorIndexes.length + (brandIndex >= 0 ? 1 : 0);+ if (brandIndex < 0) return { mentionPosition: null, mentionedEntityCount };++ const namedBefore = competitorIndexes.filter((idx) => idx < brandIndex).length;+ return { mentionPosition: namedBefore + 1, mentionedEntityCount };+}+/*** Parse the AI response and compute visibility metrics for a brand.* Sentiment must be provided externally (from AI analysis).@@ -93,7 +139,7 @@ export function countBrandMentions(text, brand) {* @param {{ brandName: string, domains: string[] }} brand* @param {'positive'|'neutral'|'negative'} sentiment - AI-analyzed sentiment* @param {Array<{ id: string, name: string, domain: string }>} [competitors] - Optional competitor list- * @returns {{ mentionCount: number, citationCount: number, sentiment: string, visibilityScore: number, competitorMentions: Array }}+ * @returns {{ mentionCount: number, citationCount: number, sentiment: string, visibilityScore: number, competitorMentions: Array, mentionPosition: number | null, mentionedEntityCount: number }}*/export function parseResponse(response, brand, sentiment = 'neutral', competitors = []) {const { text, citations } = response;@@ -150,7 +196,22 @@ export function parseResponse(response, brand, sentiment = 'neutral', competitor};});- return { mentionCount, citationCount, sentiment, visibilityScore, competitorMentions };+ // --- Mention order among brand + competitors (position signal) ---+ const { mentionPosition, mentionedEntityCount } = computeMentionPosition(+ text,+ brand,+ competitors,+ );++ return {+ mentionCount,+ citationCount,+ sentiment,+ visibilityScore,+ competitorMentions,+ mentionPosition,+ mentionedEntityCount,+ };}/**diff --git a/server/src/lib/response-parser.test.js b/server/src/lib/response-parser.test.jsindex 832d87b6f..995a3f932 100644--- a/server/src/lib/response-parser.test.js+++ b/server/src/lib/response-parser.test.js@@ -1,5 +1,5 @@import { describe, it, expect } from 'vitest';-import { countBrandMentions, parseResponse } from './response-parser.js';+import { computeMentionPosition, countBrandMentions, parseResponse } from './response-parser.js';describe('response-parser', () => {describe('countBrandMentions', () => {@@ -262,4 +262,68 @@ describe('response-parser', () => {});});});++ describe('computeMentionPosition', () => {+ const brand = { brandName: 'Acme', domains: ['acme.com'] };+ const competitors = [+ { id: 'c1', name: 'Globex', domain: 'globex.com' },+ { id: 'c2', name: 'Initech', domain: 'initech.com' },+ { id: 'c3', name: 'Umbrella', domain: 'umbrella.com' },+ ];++ it('ranks the brand first when it is named before every competitor', () => {+ const text = 'Acme leads the market, ahead of Globex and Initech.';+ expect(computeMentionPosition(text, brand, competitors)).toEqual({+ mentionPosition: 1,+ mentionedEntityCount: 3,+ });+ });++ it('ranks the brand by how many competitors are named before it', () => {+ const text = 'Top picks: Globex, Initech, and also Acme as a budget option.';+ expect(computeMentionPosition(text, brand, competitors)).toEqual({+ mentionPosition: 3,+ mentionedEntityCount: 3,+ });+ });++ it('returns a null position when the brand is not mentioned', () => {+ const text = 'Globex and Umbrella dominate this space.';+ expect(computeMentionPosition(text, brand, competitors)).toEqual({+ mentionPosition: null,+ mentionedEntityCount: 2,+ });+ });++ it('counts a domain occurrence as a brand mention for positioning', () => {+ const text = 'Globex is popular, but acme.com has the best docs.';+ expect(computeMentionPosition(text, brand, competitors)).toEqual({+ mentionPosition: 2,+ mentionedEntityCount: 2,+ });+ });++ it('ignores names that only appear inside URLs', () => {+ const text = 'Initech is the leader. See [comparison](https://acme.com/vs) for details.';+ expect(computeMentionPosition(text, brand, competitors)).toEqual({+ mentionPosition: null,+ mentionedEntityCount: 1,+ });+ });++ it('reports zero entities for an answer that names nobody', () => {+ expect(computeMentionPosition('Nothing relevant here.', brand, competitors)).toEqual({+ mentionPosition: null,+ mentionedEntityCount: 0,+ });+ });++ it("uses each entity's earliest occurrence, not its last", () => {+ const text = 'Globex... later Acme appears. Globex again at the end.';+ expect(computeMentionPosition(text, brand, competitors)).toEqual({+ mentionPosition: 2,+ mentionedEntityCount: 2,+ });+ });+ });});diff --git a/server/src/scripts/backfill-mention-position.js b/server/src/scripts/backfill-mention-position.jsnew file mode 100644index 000000000..3d7dc80c2--- /dev/null+++ b/server/src/scripts/backfill-mention-position.js@@ -0,0 +1,135 @@+/**+ * Backfill mention_position / mentioned_entity_count on historical+ * prompt_results from the stored answer text (00038).+ *+ * Run: `node src/scripts/backfill-mention-position.js [--days N] [--brand <id>] [--dry-run]`+ *+ * Scope: brands of organizations whose subscription is active or trialing+ * (churned orgs' data never surfaces in any dashboard, so recomputing it is+ * wasted work). Narrow further with --brand, or --days to limit history.+ *+ * Idempotent: only rows with `mentioned_entity_count IS NULL` are touched —+ * that column is the "computed" marker (0 = computed, nothing found), so+ * re-running skips everything already processed. Batches are small and+ * paced so the shared database stays responsive.+ *+ * Positions are computed against the brand's CURRENT competitor roster —+ * competitors added or removed since a result was scraped shift historical+ * positions accordingly, same as every other read-time aggregation here.+ */+import 'dotenv/config';+import supabaseAdmin from '../config/supabase.js';+import { computeMentionPosition } from '../lib/response-parser.js';++const BATCH_SIZE = 500;+const BATCH_PAUSE_MS = 250;++const args = process.argv.slice(2);+const dryRun = args.includes('--dry-run');+const daysArg = args.includes('--days') ? Number(args[args.indexOf('--days') + 1]) : null;+const brandArg = args.includes('--brand') ? args[args.indexOf('--brand') + 1] : null;++const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));++async function eligibleBrands() {+ const { data: orgs, error: orgErr } = await supabaseAdmin+ .from('organizations')+ .select('id')+ .in('subscription_status', ['active', 'trialing']);+ if (orgErr) throw new Error(orgErr.message);++ let query = supabaseAdmin+ .from('brands')+ .select('id, name, organization_id')+ .in(+ 'organization_id',+ (orgs ?? []).map((o) => o.id),+ );+ if (brandArg) query = query.eq('id', brandArg);++ const { data: brands, error } = await query;+ if (error) throw new Error(error.message);+ return brands ?? [];+}++async function brandContext(brand) {+ const [{ data: domains }, { data: competitors }] = await Promise.all([+ supabaseAdmin.from('brand_domains').select('domain').eq('brand_id', brand.id),+ supabaseAdmin.from('competitors').select('id, name, domain').eq('brand_id', brand.id),+ ]);+ return {+ brandInfo: { brandName: brand.name, domains: (domains ?? []).map((d) => d.domain) },+ competitors: competitors ?? [],+ };+}++async function backfillBrand(brand) {+ const { brandInfo, competitors } = await brandContext(brand);+ let updated = 0;++ for (;;) {+ let query = supabaseAdmin+ .from('prompt_results')+ .select('id, response')+ .eq('brand_id', brand.id)+ .is('mentioned_entity_count', null)+ .not('response', 'is', null)+ .order('created_at', { ascending: false })+ .limit(BATCH_SIZE);+ if (daysArg) {+ query = query.gte('created_at', new Date(Date.now() - daysArg * 86_400_000).toISOString());+ }++ const { data: rows, error } = await query;+ if (error) throw new Error(error.message);+ if (!rows?.length) break;++ // Update in small concurrent chunks: one-by-one round-trips would take+ // hours over the full history, while unbounded concurrency would hammer+ // the shared database.+ const CONCURRENCY = 20;+ for (let i = 0; i < rows.length; i += CONCURRENCY) {+ const chunk = rows.slice(i, i + CONCURRENCY);+ await Promise.all(+ chunk.map(async (row) => {+ const { mentionPosition, mentionedEntityCount } = computeMentionPosition(+ row.response ?? '',+ brandInfo,+ competitors,+ );+ if (!dryRun) {+ const { error: updateErr } = await supabaseAdmin+ .from('prompt_results')+ .update({+ mention_position: mentionPosition,+ mentioned_entity_count: mentionedEntityCount,+ })+ .eq('id', row.id);+ if (updateErr) throw new Error(updateErr.message);+ }+ updated++;+ }),+ );+ }++ console.log(` ${brand.name}: ${updated} rows${dryRun ? ' (dry run)' : ''}`);+ if (dryRun) break; // dry run would loop forever — nothing gets marked+ if (rows.length < BATCH_SIZE) break;+ await sleep(BATCH_PAUSE_MS);+ }++ return updated;+}++const brands = await eligibleBrands();+console.log(+ `Backfilling mention positions for ${brands.length} brand(s)` ++ `${daysArg ? `, last ${daysArg} day(s)` : ', full history'}${dryRun ? ' — DRY RUN' : ''}`,+);++let total = 0;+for (const brand of brands) {+ total += await backfillBrand(brand);+}+console.log(`Done. ${total} row(s) ${dryRun ? 'would be' : ''} updated.`);+process.exit(0);diff --git a/server/src/workers/tracking-worker.js b/server/src/workers/tracking-worker.jsindex 9066d362a..8ed2dd2a4 100644--- a/server/src/workers/tracking-worker.js+++ b/server/src/workers/tracking-worker.js@@ -348,6 +348,8 @@ export async function processTrackingJob({ brandId, promptId, promptIds, job })model_used: aiResponse.model,region: meta.region,competitor_mentions: metrics.competitorMentions,+ mention_position: metrics.mentionPosition,+ mentioned_entity_count: metrics.mentionedEntityCount,search_queries: Array.isArray(aiResponse.search_queries)? aiResponse.search_queries: [],@@ -430,6 +432,8 @@ export async function processTrackingJob({ brandId, promptId, promptIds, job })model_used: aiResponse.model,region,competitor_mentions: metrics.competitorMentions,+ mention_position: metrics.mentionPosition,+ mentioned_entity_count: metrics.mentionedEntityCount,});} catch (err) {logger.error({ err, model: modelName, region }, 'ai model task failed');diff --git a/supabase/migrations/00038_mention_position.sql b/supabase/migrations/00038_mention_position.sqlnew file mode 100644index 000000000..88a6be12e--- /dev/null+++ b/supabase/migrations/00038_mention_position.sql@@ -0,0 +1,18 @@+-- Track where the brand lands in each answer's mention order.+--+-- mention_position 1-based rank of the brand's first mention among+-- the brand + tracked competitors named in the+-- answer (1 = named first); NULL when the brand+-- isn't mentioned in the answer.+-- mentioned_entity_count how many tracked entities the answer names.+-- 0 = computed, nothing found; NULL = not+-- computed yet (rows from before this migration —+-- the backfill script keys off this).+--+-- Computed deterministically at parse time (response-parser.js) — no LLM.+-- Not surfaced anywhere yet: the signal accumulates first so any future+-- position-aware scoring can be calibrated against real distributions.++ALTER TABLE "public"."prompt_results"+ ADD COLUMN IF NOT EXISTS "mention_position" integer,+ ADD COLUMN IF NOT EXISTS "mentioned_entity_count" integer;diff --git a/supabase/schema.sql b/supabase/schema.sqlindex ea518de7d..bf54e5ac9 100644--- a/supabase/schema.sql+++ b/supabase/schema.sql@@ -4252,3 +4252,25 @@ $$;GRANT EXECUTE ON FUNCTION public.prompt_visibility_summaries(uuid, timestamptz)TO authenticated;+-- ─────────────────────────────────────────────────────────────────────────+-- migrations/00038_mention_position.sql+-- ─────────────────────────────────────────────────────────────────────────+-- Track where the brand lands in each answer's mention order.+--+-- mention_position 1-based rank of the brand's first mention among+-- the brand + tracked competitors named in the+-- answer (1 = named first); NULL when the brand+-- isn't mentioned in the answer.+-- mentioned_entity_count how many tracked entities the answer names.+-- 0 = computed, nothing found; NULL = not+-- computed yet (rows from before this migration —+-- the backfill script keys off this).+--+-- Computed deterministically at parse time (response-parser.js) — no LLM.+-- Not surfaced anywhere yet: the signal accumulates first so any future+-- position-aware scoring can be calibrated against real distributions.++ALTER TABLE "public"."prompt_results"+ ADD COLUMN IF NOT EXISTS "mention_position" integer,+ ADD COLUMN IF NOT EXISTS "mentioned_entity_count" integer;+diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.tsindex aaf6075b1..b528a18d3 100644--- a/web/src/types/supabase.ts+++ b/web/src/types/supabase.ts@@ -698,6 +698,8 @@ export type Database = {id: string;inline_products: Json;mention_count: number;+ mention_position: number | null;+ mentioned_entity_count: number | null;model_used: string | null;platform: string;prompt_id: string;@@ -717,6 +719,8 @@ export type Database = {id?: string;inline_products?: Json;mention_count?: number;+ mention_position?: number | null;+ mentioned_entity_count?: number | null;model_used?: string | null;platform: string;prompt_id: string;@@ -736,6 +740,8 @@ export type Database = {id?: string;inline_products?: Json;mention_count?: number;+ mention_position?: number | null;+ mentioned_entity_count?: number | null;model_used?: string | null;platform?: string;prompt_id?: string;