@finos/legend-lego 2.0.195 → 2.0.196

package/lib/legend-ai/stores/LegendAIChatState.js

@@ -15,12 +15,30 @@
  */
 import { useState, useRef, useCallback, useEffect } from 'react';
 import { assertErrorThrown, noop, uuid } from '@finos/legend-shared';
-import { LegendAIQuestionIntent, LegendAIThinkingStepStatus, LegendAIMessageRole, TDSServiceSourceType, buildColumnDefsFromNames, } from '../LegendAITypes.js';
+import { LegendAIQuestionIntent, LegendAIThinkingStepStatus, LegendAIMessageRole, LegendAIErrorType, LegendAIServiceError, TDSServiceSourceType, buildColumnDefsFromNames, LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID, } from '../LegendAITypes.js';
 import { LegendAIJudgeVerdict, } from '../LegendAI_LegendApplicationPlugin_Extension.js';
 const MAX_ERROR_MESSAGE_LENGTH = 500;
 const MAX_THINKING_ERROR_PREVIEW_LENGTH = 200;
 const DEFAULT_MAX_JUDGE_ATTEMPTS = 5;
+const DEFAULT_MAX_EXECUTION_RETRIES = 3;
+const ANALYSIS_TIMEOUT_MS = 15_000;
 const SUGGESTED_QUERIES_DELIMITER = '---SUGGESTED_QUERIES---';
+export function elapsedSeconds(startTime, decimals = 1) {
+    return ((Date.now() - startTime) / 1000).toFixed(decimals);
+}
+function withTimeout(promise, ms) {
+    let timer;
+    return Promise.race([
+        promise.finally(() => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(undefined), ms);
+        }),
+    ]);
+}
 function deduplicateColumns(columns) {
     const seen = new Map();
     return columns.map((col) => {
@@ -29,7 +47,7 @@ function deduplicateColumns(columns) {
         return count === 0 ? col : `${col}_${count + 1}`;
     });
 }
-function createMessagePair(text) {
+export function createMessagePair(text) {
     return [
         { id: uuid(), role: LegendAIMessageRole.USER, text },
         {
@@ -38,14 +56,17 @@ function createMessagePair(text) {
             thinkingSteps: [],
             sql: null,
             textAnswer: null,
+            dataContext: null,
             gridData: null,
             error: null,
+            errorType: null,
             sqlGenTime: null,
             execTime: null,
             thinkingDuration: null,
             isProcessing: true,
             isExecuting: false,
             suggestedQueries: [],
+            fallbackAction: null,
         },
     ];
 }
@@ -66,7 +87,7 @@ export function addThinkingStep(setMessages, label) {
             ...msg.thinkingSteps.map((s) => s.status === LegendAIThinkingStepStatus.ACTIVE
                 ? { ...s, status: LegendAIThinkingStepStatus.DONE }
                 : s),
-            { label, status: LegendAIThinkingStepStatus.ACTIVE },
+            { id: uuid(), label, status: LegendAIThinkingStepStatus.ACTIVE },
         ],
     }));
 }
@@ -77,14 +98,21 @@ export function completeThinkingSteps(setMessages) {
             : s),
     }));
 }
-export function finishWithThinkingError(setMessages, errorMsg, startTime) {
+export function classifyError(error) {
+    if (error instanceof LegendAIServiceError) {
+        return error.errorType;
+    }
+    return LegendAIErrorType.GENERAL;
+}
+export function finishWithThinkingError(setMessages, errorMsg, startTime, errorType) {
     updateLastAssistant(setMessages, (msg) => ({
         thinkingSteps: msg.thinkingSteps.map((s) => s.status === LegendAIThinkingStepStatus.ACTIVE
             ? { ...s, status: LegendAIThinkingStepStatus.ERROR }
             : s),
         error: errorMsg.slice(0, MAX_ERROR_MESSAGE_LENGTH),
+        errorType: errorType ?? null,
         isProcessing: false,
-        thinkingDuration: ((Date.now() - startTime) / 1000).toFixed(1),
+        thinkingDuration: elapsedSeconds(startTime),
     }));
 }
 export function buildConversationHistory(messages) {
@@ -196,7 +224,7 @@ export async function handleMetadataQuestion(question, metadata, context, startT
         textAnswer: answer,
         suggestedQueries,
         isProcessing: false,
-        thinkingDuration: ((Date.now() - startTime) / 1000).toFixed(1),
+        thinkingDuration: elapsedSeconds(startTime),
     }));
 }
 export async function generateAndJudgeSql(question, services, coordinates, context, startTime) {
@@ -208,12 +236,12 @@ export async function generateAndJudgeSql(question, services, coordinates, conte
     const { sql: generatedSql, failure, suggestion, } = plugin.extractSqlFromResponse(answerText);
     if (failure) {
         addThinkingStep(setMessages, `Generation failed: ${failure}`);
-        finishWithThinkingError(setMessages, buildGenerationFailureMessage(failure, suggestion, services), startTime);
+        finishWithThinkingError(setMessages, buildGenerationFailureMessage(failure, suggestion, services), startTime, LegendAIErrorType.GENERATION);
         return null;
     }
     if (!generatedSql) {
         addThinkingStep(setMessages, 'Could not extract SQL from response');
-        finishWithThinkingError(setMessages, 'Could not extract SQL from LLM response.\nTry rephrasing your question or ask about a specific service.', startTime);
+        finishWithThinkingError(setMessages, 'Could not extract SQL from LLM response.\nTry rephrasing your question or ask about a specific service.', startTime, LegendAIErrorType.GENERATION);
         return null;
     }
     const maxAttempts = config.maxJudgeAttempts ?? DEFAULT_MAX_JUDGE_ATTEMPTS;
@@ -251,10 +279,10 @@ function reportExecutionResult(rawResult, setMessages, execStartTime, startTime)
     completeThinkingSteps(setMessages);
     updateLastAssistant(setMessages, () => ({
         gridData: { columnDefs: buildColumnDefsFromNames(columns), rowData: rows },
-        execTime: ((Date.now() - execStartTime) / 1000).toFixed(2),
+        execTime: elapsedSeconds(execStartTime, 2),
         isProcessing: false,
         isExecuting: false,
-        thinkingDuration: ((Date.now() - startTime) / 1000).toFixed(1),
+        thinkingDuration: elapsedSeconds(startTime),
     }));
     return { columns, rows };
 }
@@ -269,10 +297,13 @@ export async function executeSqlAndReport(sql, services, config, plugin, setMess
     }
     catch (executeError) {
         assertErrorThrown(executeError);
+        const execErrorType = classifyError(executeError);
         addThinkingStep(setMessages, `Execution failed: ${executeError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
-        finishWithThinkingError(setMessages, buildExecutionErrorMessage(executeError.message, services), startTime);
+        finishWithThinkingError(setMessages, buildExecutionErrorMessage(executeError.message, services), startTime, execErrorType === LegendAIErrorType.GENERAL
+            ? LegendAIErrorType.EXECUTION
+            : execErrorType);
         updateLastAssistant(setMessages, () => ({
-            execTime: ((Date.now() - execStartTime) / 1000).toFixed(2),
+            execTime: elapsedSeconds(execStartTime, 2),
             isExecuting: false,
         }));
         return undefined;
@@ -287,25 +318,100 @@ export async function executePureQueryAndReport(pureQuery, pureExecutionContext,
     }
     catch (executeError) {
         assertErrorThrown(executeError);
+        const execErrorType = classifyError(executeError);
         addThinkingStep(setMessages, `Execution failed: ${executeError.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
         completeThinkingSteps(setMessages);
         updateLastAssistant(setMessages, () => ({
-            execTime: ((Date.now() - execStartTime) / 1000).toFixed(2),
+            execTime: elapsedSeconds(execStartTime, 2),
             isExecuting: false,
             isProcessing: false,
             error: `Execution failed: ${executeError.message.slice(0, MAX_ERROR_MESSAGE_LENGTH)}`,
-            thinkingDuration: ((Date.now() - startTime) / 1000).toFixed(1),
+            errorType: execErrorType === LegendAIErrorType.GENERAL
+                ? LegendAIErrorType.EXECUTION
+                : execErrorType,
+            thinkingDuration: elapsedSeconds(startTime),
         }));
         return { columns: [], rows: [] };
     }
 }
-export async function processQuestionViaOrchestrator(question, dataProductCoordinates, _metadata, context, pureExecutionContext) {
+export async function analyzeOrchestratorResults(question, query, execResult, metadata, context, startTime) {
+    const { config, plugin, setMessages } = context;
+    addThinkingStep(setMessages, 'Analyzing results...');
+    updateLastAssistant(setMessages, () => ({
+        isProcessing: true,
+    }));
+    const analysis = await withTimeout(plugin.analyzeQueryResults(question, query, execResult.columns, execResult.rows, metadata, config), ANALYSIS_TIMEOUT_MS);
+    if (analysis) {
+        completeThinkingSteps(setMessages);
+        updateLastAssistant(setMessages, () => ({
+            textAnswer: analysis.summary,
+            suggestedQueries: analysis.suggestedQueries,
+            isProcessing: false,
+            thinkingDuration: elapsedSeconds(startTime),
+        }));
+    }
+}
+async function handleEmptyOrchestratorResults(question, legendQuery, orchestratorOptions, metadata, resolvedEntities, context, startTime) {
+    const { dataProductCoordinates, pureExecutionContext } = orchestratorOptions;
+    const { config, plugin, setMessages } = context;
+    if (resolvedEntities.relatedEntities.length > 0) {
+        const alternateRoot = resolvedEntities.relatedEntities[0];
+        if (alternateRoot) {
+            addThinkingStep(setMessages, `No results with ${resolvedEntities.rootEntity.split('::').pop() ?? resolvedEntities.rootEntity}, retrying with ${alternateRoot.split('::').pop() ?? alternateRoot}...`);
+            try {
+                const retryResponse = await plugin.generateQueryViaOrchestrator({
+                    user_question: question,
+                    semantic_search_resolution_details: {
+                        data_product_coordinates: dataProductCoordinates,
+                        root_entity: alternateRoot,
+                        related_entities: resolvedEntities.relatedEntities.slice(1),
+                    },
+                }, config);
+                updateLastAssistant(setMessages, () => ({
+                    sql: retryResponse.legend_query,
+                    sqlGenTime: elapsedSeconds(startTime, 2),
+                    isExecuting: true,
+                }));
+                const retryResult = await executePureQueryAndReport(retryResponse.legend_query, pureExecutionContext, dataProductCoordinates, config, plugin, setMessages, startTime);
+                if (retryResult.rows.length > 0) {
+                    await analyzeOrchestratorResults(question, retryResponse.legend_query, retryResult, metadata, context, startTime);
+                    return;
+                }
+            }
+            catch {
+                /* empty */
+            }
+        }
+    }
+    addThinkingStep(setMessages, 'No results returned \u2014 building contextual guidance...');
+    updateLastAssistant(setMessages, () => ({
+        isProcessing: true,
+    }));
+    const fallback = await withTimeout(plugin.buildNoResultsFallback(question, legendQuery, metadata, config), ANALYSIS_TIMEOUT_MS);
+    if (fallback) {
+        completeThinkingSteps(setMessages);
+        updateLastAssistant(setMessages, () => ({
+            textAnswer: fallback.summary,
+            suggestedQueries: fallback.suggestedQueries,
+            isProcessing: false,
+            thinkingDuration: elapsedSeconds(startTime),
+        }));
+    }
+}
+export async function processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext, preResolvedEntities) {
     const { config, plugin, setMessages } = context;
     const startTime = Date.now();
     try {
-        addThinkingStep(setMessages, 'Resolving entities for your query...');
-        const resolvedEntities = await plugin.resolveEntitiesForQuery(question, dataProductCoordinates, config);
-        addThinkingStep(setMessages, `Found root entity: ${resolvedEntities.rootEntity.split('::').pop() ?? resolvedEntities.rootEntity}`);
+        let resolvedEntities;
+        if (preResolvedEntities) {
+            resolvedEntities = preResolvedEntities;
+            addThinkingStep(setMessages, `Using pre-resolved root entity: ${resolvedEntities.rootEntity.split('::').pop() ?? resolvedEntities.rootEntity}`);
+        }
+        else {
+            addThinkingStep(setMessages, 'Resolving entities for your query...');
+            resolvedEntities = await plugin.resolveEntitiesForQuery(question, dataProductCoordinates, config, pureExecutionContext);
+            addThinkingStep(setMessages, `Found root entity: ${resolvedEntities.rootEntity.split('::').pop() ?? resolvedEntities.rootEntity}`);
+        }
         if (resolvedEntities.relatedEntities.length > 0) {
             addThinkingStep(setMessages, `Found ${resolvedEntities.relatedEntities.length} related entities`);
         }
@@ -318,7 +424,7 @@ export async function processQuestionViaOrchestrator(question, dataProductCoordi
                 related_entities: resolvedEntities.relatedEntities,
             },
         }, config);
-        const queryGenTime = ((Date.now() - startTime) / 1000).toFixed(2);
+        const queryGenTime = elapsedSeconds(startTime, 2);
         completeThinkingSteps(setMessages);
         updateLastAssistant(setMessages, () => ({
             sql: orchestratorResponse.legend_query,
@@ -331,98 +437,465 @@ export async function processQuestionViaOrchestrator(question, dataProductCoordi
                 isProcessing: false,
                 isExecuting: false,
                 error: 'No execution context available — cannot execute query via engine.',
-                thinkingDuration: ((Date.now() - startTime) / 1000).toFixed(1),
+                errorType: LegendAIErrorType.EXECUTION,
+                thinkingDuration: elapsedSeconds(startTime),
             }));
             return;
         }
-        await executePureQueryAndReport(orchestratorResponse.legend_query, pureExecutionContext, dataProductCoordinates, config, plugin, setMessages, startTime);
+        const execResult = await executePureQueryAndReport(orchestratorResponse.legend_query, pureExecutionContext, dataProductCoordinates, config, plugin, setMessages, startTime);
+        try {
+            if (execResult.rows.length > 0) {
+                await analyzeOrchestratorResults(question, orchestratorResponse.legend_query, execResult, metadata, context, startTime);
+            }
+            else {
+                await handleEmptyOrchestratorResults(question, orchestratorResponse.legend_query, { dataProductCoordinates, pureExecutionContext }, metadata, resolvedEntities, context, startTime);
+            }
+        }
+        catch {
+            /* empty */
+        }
+        finally {
+            completeThinkingSteps(setMessages);
+            updateLastAssistant(setMessages, () => ({
+                isProcessing: false,
+                thinkingDuration: elapsedSeconds(startTime),
+            }));
+        }
     }
     catch (error) {
         assertErrorThrown(error);
+        const orchErrorType = classifyError(error);
         addThinkingStep(setMessages, `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
-        finishWithThinkingError(setMessages, error.message, startTime);
+        try {
+            addThinkingStep(setMessages, 'Building guidance from available metadata...');
+            const fallbackText = await withTimeout(plugin.buildFailureFallback(question, error.message, metadata, config), ANALYSIS_TIMEOUT_MS);
+            if (fallbackText) {
+                completeThinkingSteps(setMessages);
+                updateLastAssistant(setMessages, () => ({
+                    dataContext: fallbackText,
+                    isProcessing: false,
+                    thinkingDuration: elapsedSeconds(startTime),
+                }));
+                return;
+            }
+        }
+        catch {
+            /* empty */
+        }
+        finishWithThinkingError(setMessages, error.message, startTime, orchErrorType);
     }
 }
+function cleanLlmSqlResponse(raw) {
+    return raw
+        .trim()
+        .replace(/^```\w*\n?/, '')
+        .replace(/\n?```$/, '')
+        .replace(/;\s*$/, '')
+        .trim();
+}
+function isValidSqlCorrection(trimmed, currentSql) {
+    return (trimmed.length > 0 &&
+        trimmed.toLowerCase().startsWith('select') &&
+        trimmed !== currentSql);
+}
+const ALIAS_DOT_COL_PATTERN = /\b(?<tbl>[a-z]\w*)\s*\.\s*"(?<col>[^"]+)"/gi;
+const JOIN_PATTERN = /\bJOIN\b/i;
+const ORDER_BY_SPLIT = /\bORDER\s+BY\b/i;
+export function sanitizeJoinOrderBy(sql) {
+    if (!JOIN_PATTERN.test(sql)) {
+        return sql;
+    }
+    const parts = sql.split(ORDER_BY_SPLIT);
+    if (parts.length < 2) {
+        return sql;
+    }
+    const beforeOrderBy = parts[0] ?? '';
+    const afterOrderBy = parts.slice(1).join('ORDER BY').replace(/^\s+/, '');
+    const selectAliases = new Map();
+    const aliasRegex = /\b(?<tbl>[a-z]\w*)\s*\.\s*"(?<col>[^"]+)"\s+AS\s+(?:"(?<qAlias>[^"]+)"|(?<uAlias>\w+))/gi;
+    let m;
+    while ((m = aliasRegex.exec(beforeOrderBy)) !== null) {
+        const tableAlias = (m.groups?.tbl ?? '').toLowerCase();
+        const colName = (m.groups?.col ?? '').toLowerCase();
+        const asAlias = m.groups?.qAlias ?? m.groups?.uAlias ?? '';
+        selectAliases.set(`${tableAlias}.${colName}`, asAlias);
+    }
+    if (selectAliases.size === 0) {
+        return sql;
+    }
+    const rewritten = afterOrderBy.replaceAll(ALIAS_DOT_COL_PATTERN, (...args) => {
+        const groups = args[args.length - 1];
+        const key = `${groups.tbl.toLowerCase()}.${groups.col.toLowerCase()}`;
+        const alias = selectAliases.get(key);
+        return alias ? `"${alias}"` : String(args[0]);
+    });
+    if (rewritten === afterOrderBy) {
+        return sql;
+    }
+    return `${beforeOrderBy}ORDER BY ${rewritten}`;
+}
+const UNION_ALL_PATTERN = /\bUNION\s+ALL\b/i;
+const LITERAL_COL_PATTERN = /,\s*'[^']*'\s+AS\s+(?:"[^"]+"|[a-z]\w*)/gi;
+export function sanitizeLiteralColumns(sql) {
+    if (!UNION_ALL_PATTERN.test(sql)) {
+        return sql;
+    }
+    LITERAL_COL_PATTERN.lastIndex = 0;
+    if (!LITERAL_COL_PATTERN.test(sql)) {
+        return sql;
+    }
+    LITERAL_COL_PATTERN.lastIndex = 0;
+    return sql.replace(LITERAL_COL_PATTERN, '');
+}
+const SERVICE_PARAM_DATE_LIKE = /date|time|day|month|year|period|asOf|businessDate|processingDate|snapshot/i;
+function hasUnresolvableParams(service) {
+    return service.parameters.some((p) => !SERVICE_PARAM_DATE_LIKE.test(p));
+}
+function getNonDateParamNames(service) {
+    return service.parameters.filter((p) => !SERVICE_PARAM_DATE_LIKE.test(p));
+}
+export function stripNonDateServiceParams(sql) {
+    return sql.replaceAll(/,\s*\w+\s*=>\s*'[^']*'/g, (match) => {
+        const paramName = /,\s*(?<param>\w+)\s*=>/.exec(match)?.groups?.param;
+        if (!paramName) {
+            return match;
+        }
+        if (paramName === 'coordinates' ||
+            SERVICE_PARAM_DATE_LIKE.test(paramName)) {
+            return match;
+        }
+        return '';
+    });
+}
+async function executeSqlForServices(sql, services, dataProductCoordinates, plugin, config) {
+    const safeSql = sanitizeLiteralColumns(sanitizeJoinOrderBy(sql));
+    const isAccessPoint = services.some((s) => s.sourceType === TDSServiceSourceType.ACCESS_POINT);
+    if (isAccessPoint && dataProductCoordinates) {
+        return plugin.executeLakehouseSql(safeSql, dataProductCoordinates, config);
+    }
+    return plugin.executeSql(safeSql, config);
+}
+async function executeSqlWithRetries(initialSql, question, services, coordinates, dataProductCoordinates, context) {
+    const { plugin, config, setMessages } = context;
+    let currentSql = initialSql;
+    for (let attempt = 0; attempt <= DEFAULT_MAX_EXECUTION_RETRIES; attempt++) {
+        try {
+            const result = await executeSqlForServices(currentSql, services, dataProductCoordinates, plugin, config);
+            return { sql: currentSql, result };
+        }
+        catch (executeError) {
+            assertErrorThrown(executeError);
+            if (attempt >= DEFAULT_MAX_EXECUTION_RETRIES) {
+                return { sql: currentSql, error: executeError.message };
+            }
+            addThinkingStep(setMessages, `Execution failed (attempt ${attempt + 1}/${DEFAULT_MAX_EXECUTION_RETRIES + 1}), correcting query...`);
+            const corrected = await attemptErrorCorrection(currentSql, executeError.message, question, services, coordinates, plugin, config);
+            if (corrected) {
+                currentSql = corrected;
+                updateLastAssistant(setMessages, () => ({ sql: currentSql }));
+                continue;
+            }
+            return { sql: currentSql, error: executeError.message };
+        }
+    }
+    return { sql: currentSql };
+}
+async function attemptErrorCorrection(currentSql, errorMessage, question, services, coordinates, plugin, config) {
+    const prompt = plugin.buildErrorCorrectionPrompt(currentSql, errorMessage, question, services, coordinates);
+    if (!prompt) {
+        return undefined;
+    }
+    try {
+        const correctedSql = await plugin.callLLM(prompt, config);
+        const trimmed = cleanLlmSqlResponse(correctedSql);
+        if (isValidSqlCorrection(trimmed, currentSql)) {
+            return trimmed;
+        }
+    }
+    catch {
+        /* empty */
+    }
+    return undefined;
+}
+async function attemptZeroRowCorrection(currentSql, question, services, coordinates, dataProductCoordinates, context) {
+    const { plugin, config, setMessages } = context;
+    addThinkingStep(setMessages, 'Query returned 0 rows, attempting filter correction...');
+    const prompt = plugin.buildZeroRowCorrectionPrompt(currentSql, question, services, coordinates);
+    if (!prompt) {
+        return undefined;
+    }
+    try {
+        const correctedSql = await plugin.callLLM(prompt, config);
+        const trimmed = cleanLlmSqlResponse(correctedSql);
+        if (!isValidSqlCorrection(trimmed, currentSql)) {
+            return undefined;
+        }
+        addThinkingStep(setMessages, 'Retrying with corrected filters...');
+        updateLastAssistant(setMessages, () => ({ sql: trimmed }));
+        try {
+            const retryResult = await executeSqlForServices(trimmed, services, dataProductCoordinates, plugin, config);
+            if (retryResult.rows.length > 0) {
+                return { sql: trimmed, result: retryResult };
+            }
+        }
+        catch {
+            /* empty */
+        }
+    }
+    catch {
+        /* empty */
+    }
+    return undefined;
+}
+function buildZeroRowMessage(services) {
+    const withUnresolvable = services.filter((s) => hasUnresolvableParams(s));
+    if (withUnresolvable.length > 0) {
+        const parts = [];
+        for (const svc of withUnresolvable) {
+            for (const paramName of getNonDateParamNames(svc)) {
+                const matchingCol = svc.columns.find((c) => c.name === paramName);
+                const docHint = matchingCol?.documentation ?? matchingCol?.sampleValues;
+                if (docHint) {
+                    parts.push(`**${paramName}** (${docHint})`);
+                }
+                else {
+                    parts.push(`**${paramName}**`);
+                }
+            }
+        }
+        const uniqueParts = [...new Set(parts)];
+        const firstSvc = withUnresolvable[0];
+        const firstParam = firstSvc
+            ? (getNonDateParamNames(firstSvc)[0] ?? 'parameter')
+            : 'parameter';
+        return `The SQL query executed successfully but returned **0 rows**. This service requires specific values for ${uniqueParts.join(', ')} to return data. Please include ${uniqueParts.length === 1 ? 'a value' : 'values'} in your question, e.g., "show data where ${firstParam} is [your value]".`;
+    }
+    return 'The SQL query executed successfully but returned **0 rows**. The applied filters may not match any records, or the specific values may not exist in the queried datasets.';
+}
+function offerOrchestratorFallbackMessage(setMessages, startTime, fallbackMessage) {
+    updateLastAssistant(setMessages, () => ({
+        textAnswer: fallbackMessage,
+        fallbackAction: {
+            label: 'Try Legend AI Orchestrator',
+            actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
+        },
+        isProcessing: false,
+        thinkingDuration: elapsedSeconds(startTime),
+    }));
+}
+function reportFatalQueryError(setMessages, startTime, errorMessage, errorType) {
+    finishWithThinkingError(setMessages, errorMessage, startTime, errorType);
+}
+function handleSqlGenerationFailure(setMessages, startTime, hasOrchestratorFallback, orchestratorMessage, errorMessage, errorType) {
+    completeThinkingSteps(setMessages);
+    if (hasOrchestratorFallback) {
+        offerOrchestratorFallbackMessage(setMessages, startTime, orchestratorMessage);
+    }
+    else {
+        reportFatalQueryError(setMessages, startTime, errorMessage, errorType);
+    }
+}
+async function reportQueryResults(report, metadata, context, startTime, hasOrchestratorFallback) {
+    const { currentSql, sqlResult, question, services } = report;
+    const { setMessages } = context;
+    if (sqlResult.rows.length > 0) {
+        const columns = deduplicateColumns(sqlResult.columns);
+        const rows = sqlResult.rows;
+        completeThinkingSteps(setMessages);
+        addThinkingStep(setMessages, `Retrieved ${rows.length} row${rows.length === 1 ? '' : 's'}`);
+        completeThinkingSteps(setMessages);
+        updateLastAssistant(setMessages, () => ({
+            sql: currentSql,
+            gridData: {
+                columnDefs: buildColumnDefsFromNames(columns),
+                rowData: rows,
+            },
+            execTime: elapsedSeconds(startTime, 2),
+            isProcessing: true,
+            isExecuting: false,
+            thinkingDuration: elapsedSeconds(startTime),
+        }));
+        try {
+            await analyzeOrchestratorResults(question, currentSql, sqlResult, metadata, context, startTime);
+        }
+        catch {
+            /* empty */
+        }
+        finally {
+            completeThinkingSteps(setMessages);
+            updateLastAssistant(setMessages, () => ({
+                isProcessing: false,
+                thinkingDuration: elapsedSeconds(startTime),
+            }));
+        }
+    }
+    else {
+        addThinkingStep(setMessages, 'Query returned 0 rows after correction attempts.');
+        completeThinkingSteps(setMessages);
+        const fallback = hasOrchestratorFallback
+            ? {
+                fallbackAction: {
+                    label: 'Try Legend AI Orchestrator',
+                    actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
+                },
+            }
+            : {};
+        updateLastAssistant(setMessages, () => ({
+            textAnswer: buildZeroRowMessage(services),
+            ...fallback,
+            isProcessing: false,
+            isExecuting: false,
+            thinkingDuration: elapsedSeconds(startTime),
+        }));
+    }
+}
+async function selectBestServices(question, services, context) {
+    const { plugin, config, setMessages } = context;
+    if (services.length <= 1) {
+        return services;
+    }
+    try {
+        addThinkingStep(setMessages, 'Selecting best service for your query...');
+        return await plugin.selectRelevantServices(question, services, config);
+    }
+    catch {
+        return services;
+    }
+}
+async function tryRecoverZeroRows(currentSql, sqlResult, question, selectedServices, coordinates, dataProductCoordinates, context) {
+    const { plugin, config, setMessages } = context;
+    let recoveredSql = currentSql;
+    let recoveredResult = sqlResult;
+    const strippedSql = stripNonDateServiceParams(recoveredSql);
+    if (strippedSql !== recoveredSql) {
+        addThinkingStep(setMessages, 'Trying query without guessed parameter values...');
+        try {
+            const strippedResult = await executeSqlForServices(strippedSql, selectedServices, dataProductCoordinates, plugin, config);
+            if (strippedResult.rows.length > 0) {
+                recoveredSql = strippedSql;
+                recoveredResult = strippedResult;
+                updateLastAssistant(setMessages, () => ({ sql: strippedSql }));
+            }
+        }
+        catch {
+            /* empty */
+        }
+    }
+    if (recoveredResult.rows.length === 0) {
+        const correction = await attemptZeroRowCorrection(recoveredSql, question, selectedServices, coordinates, dataProductCoordinates, context);
+        if (correction) {
+            recoveredSql = correction.sql;
+            recoveredResult = correction.result;
+        }
+    }
+    return { sql: recoveredSql, result: recoveredResult };
+}
 async function processDataQuery(question, services, coordinates, metadata, context, startTime, orchestratorOptions) {
-    const { config, plugin, setMessages } = context;
+    const { config, setMessages } = context;
     const dataProductCoordinates = orchestratorOptions?.dataProductCoordinates;
-    const pureExecutionContext = orchestratorOptions?.pureExecutionContext;
+    const hasOrchestratorFallback = Boolean(config.orchestratorUrl && dataProductCoordinates);
     if (services.length === 0) {
-        if (config.orchestratorUrl && dataProductCoordinates) {
-            completeThinkingSteps(setMessages);
-            await processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext);
-            return;
-        }
-        finishWithThinkingError(setMessages, 'No TDS services available for querying', startTime);
+        handleSqlGenerationFailure(setMessages, startTime, hasOrchestratorFallback, 'No TDS services available for SQL querying. You can try the Legend AI Orchestrator to generate a Pure query instead.', 'No TDS services available for querying', LegendAIErrorType.GENERAL);
         return;
     }
     addThinkingStep(setMessages, 'Found relevant services to query');
-    const judgedSql = await generateAndJudgeSql(question, services, coordinates, context, startTime);
+    const selectedServices = await selectBestServices(question, services, context);
+    const judgedSql = await generateAndJudgeSql(question, selectedServices, coordinates, context, startTime);
     if (!judgedSql) {
-        if (config.orchestratorUrl && dataProductCoordinates) {
-            addThinkingStep(setMessages, 'SQL generation could not handle this query, trying Legend AI orchestrator...');
-            updateLastAssistant(setMessages, () => ({
-                error: null,
-                isProcessing: true,
-            }));
-            await processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext);
-            return;
-        }
+        addThinkingStep(setMessages, 'SQL generation could not produce a valid query.');
+        handleSqlGenerationFailure(setMessages, startTime, hasOrchestratorFallback, 'SQL generation could not handle this query. You can try the Legend AI Orchestrator to generate a Pure query instead.', 'SQL generation could not handle this query. Try rephrasing your question.', LegendAIErrorType.GENERATION);
         return;
     }
-    const sqlGenTimeValue = ((Date.now() - startTime) / 1000).toFixed(2);
+    const sqlGenTimeValue = elapsedSeconds(startTime, 2);
     completeThinkingSteps(setMessages);
     updateLastAssistant(setMessages, () => ({
         sql: judgedSql,
         sqlGenTime: sqlGenTimeValue,
         isExecuting: true,
     }));
-    const sqlResult = await executeSqlAndReport(judgedSql, services, config, plugin, setMessages, startTime, dataProductCoordinates);
-    if (sqlResult?.rows.length === 0 &&
-        config.orchestratorUrl &&
-        dataProductCoordinates) {
-        addThinkingStep(setMessages, 'SQL query returned no results, trying Legend AI orchestrator...');
+    const execOutcome = await executeSqlWithRetries(judgedSql, question, selectedServices, coordinates, dataProductCoordinates, context);
+    if (execOutcome.error) {
+        const execErrorType = classifyError(new Error(execOutcome.error));
+        addThinkingStep(setMessages, `Execution failed: ${execOutcome.error.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
+        finishWithThinkingError(setMessages, buildExecutionErrorMessage(execOutcome.error, selectedServices), startTime, execErrorType === LegendAIErrorType.GENERAL
+            ? LegendAIErrorType.EXECUTION
+            : execErrorType);
         updateLastAssistant(setMessages, () => ({
-            gridData: null,
-            error: null,
-            isProcessing: true,
             isExecuting: false,
+            ...(hasOrchestratorFallback
+                ? {
+                    fallbackAction: {
+                        label: 'Try Legend AI Orchestrator',
+                        actionId: LEGEND_AI_ORCHESTRATOR_FALLBACK_ACTION_ID,
+                    },
+                }
+                : {}),
         }));
-        await processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext);
+        return;
     }
+    if (!execOutcome.result) {
+        return;
+    }
+    let currentSql = execOutcome.sql;
+    let sqlResult = execOutcome.result;
+    if (sqlResult.rows.length === 0) {
+        const recovered = await tryRecoverZeroRows(currentSql, sqlResult, question, selectedServices, coordinates, dataProductCoordinates, context);
+        currentSql = recovered.sql;
+        sqlResult = recovered.result;
+    }
+    await reportQueryResults({
+        currentSql,
+        sqlResult,
+        question,
+        services: selectedServices,
+    }, metadata, context, startTime, hasOrchestratorFallback);
 }
 export async function processQuestion(question, services, coordinates, metadata, context, dataProductCoordinates, pureExecutionContext) {
     const { config, plugin, setMessages } = context;
     const startTime = Date.now();
     try {
         addThinkingStep(setMessages, 'Analyzing your question...');
-        const serviceNames = services.map((s) => s.title);
-        const intent = await plugin.classifyQuestionIntent(question, services.length > 0, config, serviceNames);
-        if (intent === LegendAIQuestionIntent.METADATA) {
-            await handleMetadataQuestion(question, metadata, context, startTime, services.length > 0);
-            return;
-        }
-        if (intent === LegendAIQuestionIntent.ORCHESTRATOR) {
-            if (config.orchestratorUrl && dataProductCoordinates) {
-                completeThinkingSteps(setMessages);
-                await processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext);
-                return;
-            }
-            addThinkingStep(setMessages, 'Orchestrator not available, trying SQL generation...');
-        }
-        await processDataQuery(question, services, coordinates, metadata, context, startTime, dataProductCoordinates
+        const orchestratorOpts = dataProductCoordinates
             ? {
                 dataProductCoordinates,
                 ...(pureExecutionContext === undefined
                     ? {}
                     : { pureExecutionContext }),
             }
-            : undefined);
+            : undefined;
+        if (services.length > 0) {
+            const serviceNames = services.map((s) => s.title);
+            const intent = await plugin.classifyQuestionIntent(question, true, config, serviceNames);
+            if (intent === LegendAIQuestionIntent.METADATA) {
+                await handleMetadataQuestion(question, metadata, context, startTime, true);
+                return;
+            }
+            // DATA_QUERY or ORCHESTRATOR — try SQL generation.
+            // If SQL throws, fall back to metadata as a safety net
+            // (e.g. misclassified metadata question).
+            try {
+                await processDataQuery(question, services, coordinates, metadata, context, startTime, orchestratorOpts);
+            }
+            catch (sqlError) {
+                assertErrorThrown(sqlError);
+                addThinkingStep(setMessages, 'SQL generation failed, answering from product metadata...');
+                await handleMetadataQuestion(question, metadata, context, startTime, true);
+            }
+            return;
+        }
+        // No services available — use orchestrator if configured, else metadata only.
+        if (config.orchestratorUrl && dataProductCoordinates) {
+            completeThinkingSteps(setMessages);
+            await processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext);
+        }
+        else {
+            await handleMetadataQuestion(question, metadata, context, startTime, false);
+        }
     }
     catch (error) {
         assertErrorThrown(error);
         addThinkingStep(setMessages, `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
-        finishWithThinkingError(setMessages, error.message, startTime);
+        finishWithThinkingError(setMessages, error.message, startTime, classifyError(error));
     }
 }
 export async function processQuestionWithIntent(question, intent, services, coordinates, metadata, context, orchestratorOptions) {
@@ -431,11 +904,32 @@ export async function processQuestionWithIntent(question, intent, services, coor
     const pureExecutionContext = orchestratorOptions?.pureExecutionContext;
     if (intent === LegendAIQuestionIntent.METADATA) {
         const startTime = Date.now();
-        await handleMetadataQuestion(question, metadata, context, startTime, services.length > 0);
+        try {
+            await handleMetadataQuestion(question, metadata, context, startTime, services.length > 0);
+        }
+        catch (error) {
+            assertErrorThrown(error);
+            addThinkingStep(setMessages, `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
+            finishWithThinkingError(setMessages, error.message, startTime, classifyError(error));
+        }
         return;
     }
     if (intent === LegendAIQuestionIntent.ORCHESTRATOR) {
         if (config.orchestratorUrl && dataProductCoordinates) {
+            // When services are available, try SQL first even for ORCHESTRATOR intent
+            if (services.length > 0) {
+                const startTime = Date.now();
+                try {
+                    addThinkingStep(setMessages, 'Preparing data query...');
+                    await processDataQuery(question, services, coordinates, metadata, context, startTime, orchestratorOptions);
+                }
+                catch (error) {
+                    assertErrorThrown(error);
+                    addThinkingStep(setMessages, `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
+                    finishWithThinkingError(setMessages, error.message, startTime, classifyError(error));
+                }
+                return;
+            }
             await processQuestionViaOrchestrator(question, dataProductCoordinates, metadata, context, pureExecutionContext);
             return;
         }
@@ -448,7 +942,7 @@ export async function processQuestionWithIntent(question, intent, services, coor
     catch (error) {
         assertErrorThrown(error);
         addThinkingStep(setMessages, `Error: ${error.message.slice(0, MAX_THINKING_ERROR_PREVIEW_LENGTH)}`);
-        finishWithThinkingError(setMessages, error.message, startTime);
+        finishWithThinkingError(setMessages, error.message, startTime, classifyError(error));
     }
 }
 export const useLegendAIChatState = (services, coordinates, config, metadata, plugin, dataProductCoordinates, pureExecutionContext) => {
@@ -543,6 +1037,46 @@ export const useLegendAIChatState = (services, coordinates, config, metadata, pl
         dataProductCoordinates,
         pureExecutionContext,
     ]);
+    const runFallbackAction = useCallback((messageId) => {
+        if (isSending || !config.orchestratorUrl || !dataProductCoordinates) {
+            return;
+        }
+        // Find the user question associated with this assistant message
+        let question;
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg?.role === LegendAIMessageRole.ASSISTANT &&
+                msg.id === messageId &&
+                i > 0) {
+                const userMsg = messages[i - 1];
+                if (userMsg?.role === LegendAIMessageRole.USER) {
+                    question = userMsg.text;
+                }
+            }
+        }
+        if (!question) {
+            return;
+        }
+        setIsSending(true);
+        setMessages((prev) => prev.map((m) => m.id === messageId && m.role === LegendAIMessageRole.ASSISTANT
+            ? { ...m, fallbackAction: null, error: null, isProcessing: true }
+            : m));
+        const history = buildConversationHistory(messages);
+        const q = question;
+        processQuestionViaOrchestrator(q, dataProductCoordinates, metadata, { config, plugin, history, setMessages }, pureExecutionContext)
+            .catch(noop())
+            .finally(() => {
+            setIsSending(false);
+        });
+    }, [
+        isSending,
+        messages,
+        config,
+        metadata,
+        plugin,
+        dataProductCoordinates,
+        pureExecutionContext,
+    ]);
     return {
         questionText,
         setQuestionText,
@@ -550,6 +1084,7 @@ export const useLegendAIChatState = (services, coordinates, config, metadata, pl
         messages,
         askQuestion,
         askQuestionWithIntent,
+        runFallbackAction,
         clearChat,
         expandedThinking,
         toggleThinking,