Skip to content

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.

feat(prompts): Query Fan-out intent column — classifyPromptIntent + on-demand cache (closes #333) (#353)

Gökhan Geyike01990dcdf2c
diff --git a/server/src/lib/intent-extraction.js b/server/src/lib/intent-extraction.js
index 00cce2df9..6b120aaf9 100644
--- a/server/src/lib/intent-extraction.js
+++ b/server/src/lib/intent-extraction.js
@@ -73,3 +73,41 @@ export async function extractIntentKeywords(promptText, aiModel) {
});
return { intent: object.intent, keywords: object.keywords };
}
+
+// Intent-only schema — reuses the EXACT enum from intentKeywordSchema so the
+// Query Fan-out "intent" column can never drift from the Insights one.
+export const intentOnlySchema = z.object({
+ intent: intentKeywordSchema.shape.intent,
+});
+
+export const INTENT_ONLY_SYSTEM_PROMPT = `You classify the primary search intent behind a short query into exactly one of these labels:
+
+- comparison: weighing multiple options against each other
+- how-to: accomplishing a task or process
+- what-is: a definition or understanding a concept
+- best-top: finding the best / top options in a category
+- vs-review: a head-to-head or a review of a specific thing
+- recommendation: asking for a suggestion or what to pick
+- problem-solving: fixing an issue or troubleshooting
+- other: none of the above fits
+
+Return only the single best-fitting label.`;
+
+/**
+ * Classify the primary search intent of a query — intent only, no keyword
+ * extraction and no volume work, so it's a cheaper call than
+ * extractIntentKeywords. Shares the same intent enum (#333).
+ *
+ * @param {string} text - The sub-query / prompt to classify.
+ * @param {import('ai').LanguageModel} aiModel - A resolved AI SDK model (from `resolveModel`).
+ * @returns {Promise<string>} one of the intent enum values
+ */
+export async function classifyPromptIntent(text, aiModel) {
+ const { object } = await generateObject({
+ model: aiModel,
+ schema: intentOnlySchema,
+ system: INTENT_ONLY_SYSTEM_PROMPT,
+ prompt: `Classify the search intent of this query:\n\n"${text}"`,
+ });
+ return object.intent;
+}
diff --git a/server/src/routes/prompts.js b/server/src/routes/prompts.js
index cc1f95ad0..497ecffeb 100644
--- a/server/src/routes/prompts.js
+++ b/server/src/routes/prompts.js
@@ -3,6 +3,7 @@ import { generateObject } from 'ai';
import { z } from 'zod';
import supabaseAdmin from '../config/supabase.js';
import { resolveModel } from '../lib/ai-provider.js';
+import { classifyPromptIntent } from '../lib/intent-extraction.js';
import { getLanguageName } from '../lib/languages.js';
import { requireFeature } from '../lib/plan-guard.js';
@@ -520,4 +521,75 @@ Return the exact topic names as provided above.`,
}
});
+// POST /api/prompts/fanout-intents — classify the search intent of observed
+// query fan-out sub-queries (#333). Intent is brand-independent, so it's cached
+// globally per normalized query string in `fanout_query_intents`; only
+// cache-misses hit the LLM. Body: { queries: string[] }.
+const FANOUT_INTENT_MAX_QUERIES = 200;
+const FANOUT_INTENT_CONCURRENCY = 6;
+// Cache-lookup batch size — keeps each `.in('query', ...)` URL well under
+// PostgREST / proxy length limits even with long sub-queries.
+const FANOUT_INTENT_LOOKUP_CHUNK = 40;
+
+function normalizeIntentQuery(raw) {
+ return typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim().toLowerCase().slice(0, 512) : '';
+}
+
+router.post('/fanout-intents', async (req, res) => {
+ try {
+ const raw = Array.isArray(req.body?.queries) ? req.body.queries : [];
+ // Normalize + dedup; cap the batch so a crafted call can't fan out into
+ // hundreds of LLM calls.
+ const queries = [...new Set(raw.map(normalizeIntentQuery).filter(Boolean))].slice(
+ 0,
+ FANOUT_INTENT_MAX_QUERIES,
+ );
+ if (queries.length === 0) return res.json({ intents: {} });
+
+ // 1. Read the cache in bounded chunks — a single `.in('query', ...)` over
+ // up to 200 text values can blow past PostgREST's URL length limit. A read
+ // error must surface (500), not silently fall through to classifying every
+ // query via the LLM.
+ const intents = {};
+ for (let i = 0; i < queries.length; i += FANOUT_INTENT_LOOKUP_CHUNK) {
+ const chunk = queries.slice(i, i + FANOUT_INTENT_LOOKUP_CHUNK);
+ const { data: cached, error: cacheErr } = await supabaseAdmin
+ .from('fanout_query_intents')
+ .select('query, intent')
+ .in('query', chunk);
+ if (cacheErr) throw cacheErr;
+ for (const row of cached ?? []) intents[row.query] = row.intent;
+ }
+
+ // 2. Classify the misses (bounded concurrency), then persist them.
+ const misses = queries.filter((q) => !(q in intents));
+ if (misses.length > 0) {
+ const aiModel = resolveModel();
+ const fresh = [];
+ for (let i = 0; i < misses.length; i += FANOUT_INTENT_CONCURRENCY) {
+ const chunk = misses.slice(i, i + FANOUT_INTENT_CONCURRENCY);
+ const settled = await Promise.allSettled(
+ chunk.map((q) => classifyPromptIntent(q, aiModel).then((intent) => ({ q, intent }))),
+ );
+ for (const s of settled) {
+ if (s.status === 'fulfilled') {
+ intents[s.value.q] = s.value.intent;
+ fresh.push({ query: s.value.q, intent: s.value.intent });
+ }
+ }
+ }
+ if (fresh.length > 0) {
+ await supabaseAdmin
+ .from('fanout_query_intents')
+ .upsert(fresh, { onConflict: 'query', ignoreDuplicates: true });
+ }
+ }
+
+ return res.json({ intents });
+ } catch (error) {
+ req.log.error({ err: error }, 'fanout intents classification error');
+ return res.status(500).json({ error: error.message });
+ }
+});
+
export default router;
diff --git a/supabase/migrations/00022_fanout_query_intents.sql b/supabase/migrations/00022_fanout_query_intents.sql
new file mode 100644
index 000000000..e5ff5bbdf
--- /dev/null
+++ b/supabase/migrations/00022_fanout_query_intents.sql
@@ -0,0 +1,24 @@
+-- 00022_fanout_query_intents.sql
+-- On-demand, brand-independent cache of the search intent of a fan-out sub-query.
+--
+-- The Query Fan-out tab (#333) labels each observed sub-query with the same
+-- 7-value intent taxonomy the Insights "intent" column uses. Intent is derived
+-- from an LLM call, so we cache it per distinct (normalized, lower-cased) query
+-- string — the intent of "best running shoes 2026" is the same for every brand,
+-- so one classification is reused everywhere. Populated on-demand at read time,
+-- never during tracking ingest.
+--
+-- Written only by the server (service role) via /api/prompts/fanout-intents;
+-- RLS is enabled with no policies so it isn't readable/writable by anon or
+-- authenticated clients directly.
+
+CREATE TABLE IF NOT EXISTS fanout_query_intents (
+ query text PRIMARY KEY,
+ intent text NOT NULL,
+ created_at timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE fanout_query_intents IS
+ 'Cache of a fan-out sub-query''s search intent (#333). Key is the normalized (trimmed, whitespace-collapsed, lower-cased) query; intent is one of comparison/how-to/what-is/best-top/vs-review/recommendation/problem-solving/other. Brand-independent, populated on-demand.';
+
+ALTER TABLE fanout_query_intents ENABLE ROW LEVEL SECURITY;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 89588bfdd..a36e88cde 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -2957,3 +2957,31 @@ ALTER TABLE prompt_results
COMMENT ON COLUMN prompt_results.search_queries IS
'Observed query fan-out from the answer engine: [{ query, engine?, source_platform }]. Copilot is the primary source; Perplexity secondary (web queries, carries engine); ChatGPT usually empty. Defaults to [].';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00022_fanout_query_intents.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- 00022_fanout_query_intents.sql
+-- On-demand, brand-independent cache of the search intent of a fan-out sub-query.
+--
+-- The Query Fan-out tab (#333) labels each observed sub-query with the same
+-- 7-value intent taxonomy the Insights "intent" column uses. Intent is derived
+-- from an LLM call, so we cache it per distinct (normalized, lower-cased) query
+-- string — the intent of "best running shoes 2026" is the same for every brand,
+-- so one classification is reused everywhere. Populated on-demand at read time,
+-- never during tracking ingest.
+--
+-- Written only by the server (service role) via /api/prompts/fanout-intents;
+-- RLS is enabled with no policies so it isn't readable/writable by anon or
+-- authenticated clients directly.
+
+CREATE TABLE IF NOT EXISTS fanout_query_intents (
+ query text PRIMARY KEY,
+ intent text NOT NULL,
+ created_at timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE fanout_query_intents IS
+ 'Cache of a fan-out sub-query''s search intent (#333). Key is the normalized (trimmed, whitespace-collapsed, lower-cased) query; intent is one of comparison/how-to/what-is/best-top/vs-review/recommendation/problem-solving/other. Brand-independent, populated on-demand.';
+
+ALTER TABLE fanout_query_intents ENABLE ROW LEVEL SECURITY;
+
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx
index 60092fd90..a5a967745 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx
@@ -3,8 +3,15 @@
import { useCallback, useEffect, useState } from 'react';
import { toast } from 'sonner';
import { Link } from '@/i18n/navigation';
-import { getQueryFanout, trackFanoutQuery, type QueryFanoutData } from '@/lib/actions/fanout';
+import {
+ getQueryFanout,
+ trackFanoutQuery,
+ classifyFanoutIntents,
+ type QueryFanoutData,
+} from '@/lib/actions/fanout';
import { PLATFORM_LABELS } from '@/config/platform-labels';
+import { INTENT_LABELS, INTENT_COLORS } from '@/config/intent-labels';
+import { cn } from '@/lib/utils';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
@@ -27,12 +34,22 @@ export function QueryFanoutTab({ brandId }: { brandId: string }) {
const [data, setData] = useState<QueryFanoutData | null>(null);
const [loading, setLoading] = useState(true);
const [addingKey, setAddingKey] = useState<string | null>(null);
+ // Intent is keyed by the lower-cased sub-query (matches the server cache key).
+ const [intents, setIntents] = useState<Record<string, string>>({});
const load = useCallback(async () => {
setLoading(true);
try {
const result = await getQueryFanout(brandId, { days: 30 });
setData(result);
+ // Fill in intents on-demand (cached server-side) — non-blocking, so the
+ // table paints immediately and the intent badges appear as they resolve.
+ const queries = result.subQueries.map((s) => s.query);
+ if (queries.length > 0) {
+ classifyFanoutIntents(queries)
+ .then((map) => setIntents((prev) => ({ ...prev, ...map })))
+ .catch(() => {});
+ }
} catch (err) {
toast.error(err instanceof Error ? err.message : 'Failed to load query fan-out');
setData({ subQueries: [], totalObserved: 0 });
@@ -92,7 +109,8 @@ export function QueryFanoutTab({ brandId }: { brandId: string }) {
<TableHead>Sub-query</TableHead>
<TableHead className="w-[160px]">Engine</TableHead>
<TableHead className="w-[120px] text-right">Times searched</TableHead>
- <TableHead className="w-[240px]">Sourced prompts</TableHead>
+ <TableHead className="w-[220px]">Sourced prompts</TableHead>
+ <TableHead className="w-[130px]">Intent</TableHead>
<TableHead className="w-[64px] text-right">Track</TableHead>
</TableRow>
</TableHeader>
@@ -116,6 +134,9 @@ export function QueryFanoutTab({ brandId }: { brandId: string }) {
<TableCell>
<SourcedPrompts prompts={sq.sourcedPrompts} />
</TableCell>
+ <TableCell>
+ <IntentBadge intent={intents[key]} />
+ </TableCell>
<TableCell className="text-right">
{sq.tracked ? (
<Badge
@@ -187,3 +208,17 @@ function SourcedPrompts({ prompts }: { prompts: { id: string; text: string }[] }
</div>
);
}
+
+function IntentBadge({ intent }: { intent?: string }) {
+ // Intents load on-demand (async, cached server-side); show a placeholder
+ // until this row's classification resolves.
+ if (!intent) return <span className="text-xs text-muted-foreground">—</span>;
+ return (
+ <Badge
+ variant="outline"
+ className={cn('text-[10px] whitespace-nowrap', INTENT_COLORS[intent] ?? '')}
+ >
+ {INTENT_LABELS[intent] ?? intent}
+ </Badge>
+ );
+}
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx
index 09e4befeb..3a5a502c3 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/page.tsx
@@ -13,6 +13,7 @@ const PlatformVolumeChart = dynamic(() => import('./_charts').then((m) => m.Plat
});
import { SuggestionsCard } from './_suggestions-card';
import { QueryFanoutTab } from './_fanout-tab';
+import { INTENT_LABELS, INTENT_COLORS } from '@/config/intent-labels';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Badge } from '@/components/ui/badge';
import { Button, buttonVariants } from '@/components/ui/button';
@@ -175,28 +176,6 @@ function SortableHead({
);
}
-// ─── Intent labels ───────────────────────────────────────────────────────────
-
-const INTENT_LABELS: Record<string, string> = {
- comparison: 'Comparison',
- 'how-to': 'How-to',
- 'what-is': 'What is',
- 'best-top': 'Best / Top',
- 'vs-review': 'vs. / Review',
- recommendation: 'Recommendation',
- 'problem-solving': 'Problem Solving',
-};
-
-const INTENT_COLORS: Record<string, string> = {
- comparison: 'border-indigo-500/30 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
- 'how-to': 'border-violet-500/30 bg-violet-500/10 text-violet-600 dark:text-violet-400',
- 'what-is': 'border-purple-400/30 bg-purple-400/10 text-purple-600 dark:text-purple-400',
- 'best-top': 'border-blue-400/30 bg-blue-400/10 text-blue-600 dark:text-blue-400',
- 'vs-review': 'border-cyan-500/30 bg-cyan-500/10 text-cyan-600 dark:text-cyan-400',
- recommendation: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
- 'problem-solving': 'border-amber-500/30 bg-amber-500/10 text-amber-600 dark:text-amber-400',
-};
-
const PROMPT_EXPORT_HEADERS = [
'text',
'topic_id',
diff --git a/web/src/config/intent-labels.ts b/web/src/config/intent-labels.ts
new file mode 100644
index 000000000..7ebdb4bf3
--- /dev/null
+++ b/web/src/config/intent-labels.ts
@@ -0,0 +1,29 @@
+/**
+ * Shared 7-value search-intent taxonomy — display labels + badge colors.
+ *
+ * Used by the Insights "intent" column (Prompt Volumes) and the Query Fan-out
+ * intent column so the two never drift. The values mirror the full enum in
+ * `server/src/lib/intent-extraction.js` (`intentKeywordSchema.intent`),
+ * including `'other'`, so a classified intent always renders a styled label.
+ */
+export const INTENT_LABELS: Record<string, string> = {
+ comparison: 'Comparison',
+ 'how-to': 'How-to',
+ 'what-is': 'What is',
+ 'best-top': 'Best / Top',
+ 'vs-review': 'vs. / Review',
+ recommendation: 'Recommendation',
+ 'problem-solving': 'Problem Solving',
+ other: 'Other',
+};
+
+export const INTENT_COLORS: Record<string, string> = {
+ comparison: 'border-indigo-500/30 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
+ 'how-to': 'border-violet-500/30 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+ 'what-is': 'border-purple-400/30 bg-purple-400/10 text-purple-600 dark:text-purple-400',
+ 'best-top': 'border-blue-400/30 bg-blue-400/10 text-blue-600 dark:text-blue-400',
+ 'vs-review': 'border-cyan-500/30 bg-cyan-500/10 text-cyan-600 dark:text-cyan-400',
+ recommendation: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+ 'problem-solving': 'border-amber-500/30 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+ other: 'border-slate-400/30 bg-slate-400/10 text-slate-600 dark:text-slate-400',
+};
diff --git a/web/src/lib/actions/fanout.ts b/web/src/lib/actions/fanout.ts
index 2dbafc224..510f005da 100644
--- a/web/src/lib/actions/fanout.ts
+++ b/web/src/lib/actions/fanout.ts
@@ -3,6 +3,7 @@
import { revalidatePath } from 'next/cache';
import { createClient } from '@/lib/supabase/server';
import { addPromptToSet } from '@/lib/actions/prompt';
+import { API_BASE_URL } from '@/config/api';
/**
* Query Fan-out (#333) — read + promote actions over the OBSERVED sub-queries
@@ -226,3 +227,34 @@ export async function trackFanoutQuery(
revalidatePath('/dashboard/prompts');
return { promptId: created.id };
}
+
+/**
+ * Classify the search intent of fan-out sub-queries via the server (#333).
+ * Intent is brand-independent and cached server-side, so this is a cheap
+ * on-demand lookup — a sub-query is classified by the LLM once and reused
+ * everywhere after. Returns a map of normalized (lower-cased) query → intent.
+ */
+export async function classifyFanoutIntents(queries: string[]): Promise<Record<string, string>> {
+ if (queries.length === 0) return {};
+
+ const supabase = await createClient();
+ const {
+ data: { session },
+ } = await supabase.auth.getSession();
+ if (!session) throw new Error('Not authenticated');
+
+ const res = await fetch(`${API_BASE_URL}/api/prompts/fanout-intents`, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: `Bearer ${session.access_token}`,
+ },
+ body: JSON.stringify({ queries }),
+ });
+ if (!res.ok) {
+ const body = await res.json().catch(() => ({}));
+ throw new Error(body.error || `Server error: ${res.status}`);
+ }
+ const data = await res.json();
+ return (data.intents ?? {}) as Record<string, string>;
+}