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
fix(onboarding): retry LLM suggestion calls and fall back to manual entry (#443)
Gökhan Geyik48e9f067acd9
diff --git a/server/src/lib/audit/audit.test.js b/server/src/lib/audit/audit.test.jsindex b5b0e46e3..030abe994 100644--- a/server/src/lib/audit/audit.test.js+++ b/server/src/lib/audit/audit.test.js@@ -5,7 +5,7 @@ import { fleschReadingEase, classifyLinks, jsonLd, countPhrases } from './signalimport { jsonLdPresence, h1Quality } from './signals/structure.js';import { https, metaDescription } from './signals/trust.js';import { length } from './signals/content.js';-import { withRetry } from './retry.js';+import { withRetry } from '../retry.js';/** Build a minimal audit context from an HTML string (no network). */function ctxFromHtml(html, extra = {}) {diff --git a/server/src/lib/audit/llm-signals.js b/server/src/lib/audit/llm-signals.jsindex 3531d21c9..51d5127b7 100644--- a/server/src/lib/audit/llm-signals.js+++ b/server/src/lib/audit/llm-signals.js@@ -14,7 +14,7 @@ import { generateObject } from 'ai';import { z } from 'zod';import { resolveModel } from '../ai-provider.js';import { signalsByKey } from './rubric.js';-import { withRetry } from './retry.js';+import { withRetry } from '../retry.js';import { logger } from '../logger.js';const DEFAULT_MODEL = 'google/gemini-3-flash-preview';diff --git a/server/src/lib/audit/recommendations.js b/server/src/lib/audit/recommendations.jsindex 1c7ad2054..5059fe11b 100644--- a/server/src/lib/audit/recommendations.js+++ b/server/src/lib/audit/recommendations.js@@ -14,7 +14,7 @@ import { generateObject } from 'ai';import { z } from 'zod';import { resolveModel } from '../ai-provider.js';import { signalsByKey } from './rubric.js';-import { withRetry } from './retry.js';+import { withRetry } from '../retry.js';import { logger } from '../logger.js';const DEFAULT_MODEL = 'google/gemini-3-flash-preview';diff --git a/server/src/lib/audit/retry.js b/server/src/lib/retry.jssimilarity index 56%rename from server/src/lib/audit/retry.jsrename to server/src/lib/retry.jsindex 007a9973d..3ee9ba8e1 100644--- a/server/src/lib/audit/retry.js+++ b/server/src/lib/retry.js@@ -1,8 +1,10 @@/**- * Retry wrapper for the audit's LLM calls. Provider blips (rate limits,- * transient 5xx, the occasional malformed structured-output response) should- * not silently drop a whole audit's LLM verdicts or recommendations — one bad- * round-trip is usually fixed by trying again a moment later.+ * Shared retry wrapper for LLM calls (promoted from lib/audit for #379).+ * Provider blips (rate limits, transient 5xx, the occasional malformed+ * structured-output response) should not drop a whole operation — one bad+ * round-trip is usually fixed by trying again a moment later. Callers wrap+ * the FULL operation (research + structuring for two-phase flows) so a+ * schema miss in phase 2 re-runs everything, not just the last call.*//**@@ -11,7 +13,7 @@* @param {{ attempts?: number, baseDelayMs?: number, label?: string }} [opts]* @returns {Promise<T>}*/-import { logger } from '../logger.js';+import { logger } from './logger.js';export async function withRetry(fn, { attempts = 3, baseDelayMs = 500, label = 'llm' } = {}) {let lastErr;@@ -24,7 +26,7 @@ export async function withRetry(fn, { attempts = 3, baseDelayMs = 500, label = 'const delay = baseDelayMs * 2 ** i;logger.warn({ label, attempt: i + 1, attempts, delayMs: delay, err: err.message },- `[audit] ${label} attempt ${i + 1}/${attempts} failed; retrying`,+ `[retry] ${label} attempt ${i + 1}/${attempts} failed; retrying`,);await new Promise((resolve) => setTimeout(resolve, delay));}diff --git a/server/src/routes/competitors.js b/server/src/routes/competitors.jsindex 83168818d..251cf2c86 100644--- a/server/src/routes/competitors.js+++ b/server/src/routes/competitors.js@@ -3,6 +3,7 @@ import { generateText, generateObject } from 'ai';import { z } from 'zod';import { resolveModel } from '../lib/ai-provider.js';import { getLanguageName } from '../lib/languages.js';+import { withRetry } from '../lib/retry.js';const router = Router();@@ -45,18 +46,26 @@ Description: ${description || 'Not specified'}Find REAL companies that compete directly with "${brandName}" — selling similar products/services to similar audiences, especially in the ${langName}-speaking market. For each competitor, provide the company name and their actual website domain.`;- const { text: research } = await generateText({- model: resolveModel(competitorModel, { useSearchGrounding: true }),- prompt: researchPrompt,- });+ // #379 — retry the WHOLE two-phase flow: the schema's .min(3) means a+ // Phase-2 under-count throws NoObjectGeneratedError, and re-running the+ // research gives the structuring phase fresh material to work with.+ const { object } = await withRetry(+ async () => {+ const { text: research } = await generateText({+ model: resolveModel(competitorModel, { useSearchGrounding: true }),+ prompt: researchPrompt,+ });- // Phase 2: structure the research into the schema- const { object } = await generateObject({- model: resolveModel(competitorModel),- schema: competitorSchema,- system: `Extract competitor information from the research below. Only include companies with REAL, verified domains. Return the root domain (e.g. "monday.com"), not full URLs. Do NOT include "${brandName}" itself.`,- prompt: research,- });+ // Phase 2: structure the research into the schema+ return generateObject({+ model: resolveModel(competitorModel),+ schema: competitorSchema,+ system: `Extract competitor information from the research below. Only include companies with REAL, verified domains. Return the root domain (e.g. "monday.com"), not full URLs. Do NOT include "${brandName}" itself.`,+ prompt: research,+ });+ },+ { attempts: 3, baseDelayMs: 500, label: 'competitor-suggest' },+ );return res.json({ competitors: object.competitors });} catch (error) {diff --git a/server/src/routes/prompts.js b/server/src/routes/prompts.jsindex 497ecffeb..a5c4c0eb1 100644--- a/server/src/routes/prompts.js+++ b/server/src/routes/prompts.js@@ -6,6 +6,7 @@ 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';+import { withRetry } from '../lib/retry.js';const router = Router();@@ -442,12 +443,18 @@ Based on this brand's industry and context, generate 10 short, generic search prconst promptModel = process.env.PROMPT_SUGGESTION_MODEL || 'google/gemini-3-flash-preview';const aiModel = resolveModel(model || promptModel);- const { object } = await generateObject({- model: aiModel,- schema: promptSuggestionSchema,- system: getSystemPrompt(langName),- prompt: userPrompt,- });+ // #379 — bounded retry so one transient failure or schema miss doesn't+ // drop the whole suggestion step.+ const { object } = await withRetry(+ () =>+ generateObject({+ model: aiModel,+ schema: promptSuggestionSchema,+ system: getSystemPrompt(langName),+ prompt: userPrompt,+ }),+ { attempts: 3, baseDelayMs: 500, label: 'prompt-suggest' },+ );return res.json({ prompts: object.prompts });} catch (error) {@@ -487,10 +494,14 @@ router.post('/from-topics', async (req, res) => {const topicList = topics.map((t, i) => `${i + 1}. ${t}`).join('\n');- const { object } = await generateObject({- model: aiModel,- schema: topicPromptSchema,- system: `You are an AEO (Answer Engine Optimization) expert. Generate exactly 5 search prompts per topic that real users would type into AI search engines. Current year: ${new Date().getFullYear()}.+ // #379 — this is the onboarding prompts step's generator; a single+ // transient failure here used to strand the user with an empty step.+ const { object } = await withRetry(+ () =>+ generateObject({+ model: aiModel,+ schema: topicPromptSchema,+ system: `You are an AEO (Answer Engine Optimization) expert. Generate exactly 5 search prompts per topic that real users would type into AI search engines. Current year: ${new Date().getFullYear()}.RULES:- Keep prompts SHORT and concise — between 30 and 100 characters. Aim for 40-80 characters.@@ -500,7 +511,7 @@ RULES:- Focus on queries where the brand could organically appear in AI-generated answers.- Make prompts diverse: include comparisons, how-tos, best-of lists, recommendations, alternatives.IMPORTANT: All prompts MUST be written in ${langName}.`,- prompt: `Brand: ${brandName}+ prompt: `Brand: ${brandName}Industry: ${industry || 'Not specified'}Description: ${description || 'Not specified'}Language: ${langName} — write ALL prompts in this language.@@ -509,7 +520,9 @@ Generate 5 search prompts for each of these topics:${topicList}Return the exact topic names as provided above.`,- });+ }),+ { attempts: 3, baseDelayMs: 500, label: 'prompts-from-topics' },+ );return res.json({ topicPrompts: object.topicPrompts });} catch (error) {diff --git a/server/src/routes/topics.js b/server/src/routes/topics.jsindex 5a786db0e..7910b0b64 100644--- a/server/src/routes/topics.js+++ b/server/src/routes/topics.js@@ -2,6 +2,7 @@ import { Router } from 'express';import { generateText, generateObject } from 'ai';import { z } from 'zod';import { resolveModel } from '../lib/ai-provider.js';+import { withRetry } from '../lib/retry.js';import { getLanguageName } from '../lib/languages.js';const router = Router();@@ -56,17 +57,24 @@ Topics should be diverse: include competitive comparisons, product features, indIMPORTANT: Generate all topic names in ${langName}.`;- const { text: research } = await generateText({- model: resolveModel(topicModel, { useSearchGrounding: true }),- prompt: researchPrompt,- });-- const { object } = await generateObject({- model: resolveModel(topicModel),- schema: topicSchema,- system: `Extract AEO tracking topics from the research below. Each topic should be concise (3-8 words) and represent an area where AI assistants might mention or discuss "${brandName}". Do NOT include the brand name "${brandName}" in any topic — keep them generic. Include a mix of: competitive comparisons, product/service features, industry trends, use cases, and problem-solving topics. Each topic MUST focus on a single concept — never combine two ideas with "and" or "&". IMPORTANT: All topic names MUST be written in ${langName}.`,- prompt: research,- });+ // #379 — retry the WHOLE two-phase flow: a schema miss in the structuring+ // phase re-runs the research too, not just the last call.+ const { object } = await withRetry(+ async () => {+ const { text: research } = await generateText({+ model: resolveModel(topicModel, { useSearchGrounding: true }),+ prompt: researchPrompt,+ });++ return generateObject({+ model: resolveModel(topicModel),+ schema: topicSchema,+ system: `Extract AEO tracking topics from the research below. Each topic should be concise (3-8 words) and represent an area where AI assistants might mention or discuss "${brandName}". Do NOT include the brand name "${brandName}" in any topic — keep them generic. Include a mix of: competitive comparisons, product/service features, industry trends, use cases, and problem-solving topics. Each topic MUST focus on a single concept — never combine two ideas with "and" or "&". IMPORTANT: All topic names MUST be written in ${langName}.`,+ prompt: research,+ });+ },+ { attempts: 3, baseDelayMs: 500, label: 'topic-suggest' },+ );return res.json({ topics: object.topics });} catch (error) {diff --git a/web/src/app/[locale]/(onboarding)/dashboard/onboarding/page.tsx b/web/src/app/[locale]/(onboarding)/dashboard/onboarding/page.tsxindex 3caff34ec..0c6ccf6fa 100644--- a/web/src/app/[locale]/(onboarding)/dashboard/onboarding/page.tsx+++ b/web/src/app/[locale]/(onboarding)/dashboard/onboarding/page.tsx@@ -247,6 +247,9 @@ export default function OnboardingPage() {const [selectedTopics, setSelectedTopics] = useState<Set<string>>(new Set());const [customTopic, setCustomTopic] = useState('');const [loadingTopics, setLoadingTopics] = useState(false);+ // #379 — suggestions can fail even after the server's retries; each step+ // then shows an inline "add your own" fallback instead of a bare toast.+ const [topicSuggestError, setTopicSuggestError] = useState(false);const [topicLoadingMsg, setTopicLoadingMsg] = useState('');const topicMsgIdx = useRef(0);@@ -269,6 +272,7 @@ export default function OnboardingPage() {// Step 4const [topicPrompts, setTopicPrompts] = useState<TopicPromptsData[]>([]);const [loadingPrompts, setLoadingPrompts] = useState(false);+ const [promptGenError, setPromptGenError] = useState(false);// Step 5interface CompetitorItem {@@ -278,6 +282,7 @@ export default function OnboardingPage() {}const [suggestedCompetitors, setSuggestedCompetitors] = useState<CompetitorItem[]>([]);const [loadingCompetitors, setLoadingCompetitors] = useState(false);+ const [competitorSuggestError, setCompetitorSuggestError] = useState(false);const [competitorName, setCompetitorName] = useState('');const [competitorDomain, setCompetitorDomain] = useState('');const [savingCompetitors, setSavingCompetitors] = useState(false);@@ -570,6 +575,7 @@ export default function OnboardingPage() {const fetchTopicSuggestions = async () => {setLoadingTopics(true);+ setTopicSuggestError(false);try {const supabase = createClient();const {@@ -599,7 +605,7 @@ export default function OnboardingPage() {setSelectedTopics(new Set(names.slice(0, 7)));} catch (err) {console.error('Topic suggestion error:', err);- toast.error('Failed to generate topic suggestions');+ setTopicSuggestError(true);} finally {setLoadingTopics(false);}@@ -638,9 +644,10 @@ export default function OnboardingPage() {const handleGeneratePrompts = async () => {if (!createdBrand) return;setLoadingPrompts(true);+ setPromptGenError(false);+ const topicNames = Array.from(selectedTopics);try {// Save topics to DB- const topicNames = Array.from(selectedTopics);await createTopics(createdBrand.id, topicNames);const supabase = createClient();@@ -680,7 +687,13 @@ export default function OnboardingPage() {setStep(4);} catch (err) {console.error('Prompt generation error:', err);- toast.error('Failed to generate prompts from topics');+ // #379 — don't strand the user on the topics step behind a bare toast:+ // advance with empty per-topic groups so the manual add inputs are+ // usable, and explain inline. Continue stays disabled until they add+ // at least one prompt.+ setPromptGenError(true);+ setTopicPrompts(topicNames.map((topic) => ({ topic, prompts: [] })));+ setStep(4);} finally {setLoadingPrompts(false);}@@ -734,6 +747,7 @@ export default function OnboardingPage() {const fetchCompetitorSuggestions = async () => {setLoadingCompetitors(true);+ setCompetitorSuggestError(false);try {const supabase = createClient();const {@@ -766,7 +780,7 @@ export default function OnboardingPage() {);} catch (err) {console.error('Competitor suggestion error:', err);- toast.error('Failed to generate competitor suggestions');+ setCompetitorSuggestError(true);} finally {setLoadingCompetitors(false);}@@ -1130,6 +1144,16 @@ export default function OnboardingPage() {</div>) : (<div className="space-y-2">+ {topicSuggestError && (+ <div className="flex items-center justify-between gap-3 rounded-lg border border-amber-500/40 bg-amber-500/10 px-4 py-3 text-sm">+ <span>+ Couldn't fetch topic suggestions right now — add your own below.+ </span>+ <Button variant="outline" size="sm" onClick={fetchTopicSuggestions}>+ Try again+ </Button>+ </div>+ )}{suggestedTopics.map((topic) => {const isSelected = selectedTopics.has(topic);return (@@ -1280,6 +1304,13 @@ export default function OnboardingPage() {</Button></div>+ {promptGenError && (+ <div className="mb-4 rounded-lg border border-amber-500/40 bg-amber-500/10 px-4 py-3 text-sm">+ Couldn't generate prompt suggestions right now — add your own to each topic below+ to continue.+ </div>+ )}+<div className="mb-4"><p className="text-sm font-medium">Your Prompt List</p><p className="text-xs text-muted-foreground">{totalPrompts} prompts total</p>@@ -1349,6 +1380,16 @@ export default function OnboardingPage() {</div>) : (<div className="space-y-4">+ {competitorSuggestError && (+ <div className="flex items-center justify-between gap-3 rounded-lg border border-amber-500/40 bg-amber-500/10 px-4 py-3 text-sm">+ <span>+ Couldn't fetch competitor suggestions right now — add your own below.+ </span>+ <Button variant="outline" size="sm" onClick={fetchCompetitorSuggestions}>+ Try again+ </Button>+ </div>+ )}{suggestedCompetitors.length > 0 && (<div className="space-y-2"><p className="text-xs font-medium text-muted-foreground uppercase tracking-wider">