@duckcodeailabs/dql-agent 1.6.7 → 1.6.9

package/dist/metadata/analysis-planner.js

@@ -0,0 +1,632 @@
+const STOP_WORDS = new Set([
+    'about', 'after', 'again', 'against', 'all', 'also', 'and', 'answer', 'any', 'are', 'around',
+    'based', 'before', 'between', 'build', 'can', 'complete', 'could', 'data', 'dataset', 'datasets',
+    'deep', 'detail', 'detailed', 'does', 'for', 'from', 'give', 'have', 'help', 'into', 'latest',
+    'more', 'need', 'needs', 'over', 'please', 'provide', 'question', 'research', 'reserach', 'show',
+    'that', 'the', 'their', 'them', 'this', 'through', 'use', 'using', 'what', 'when', 'where',
+    'which', 'with', 'would', 'you',
+]);
+const METRIC_WORDS = [
+    'amount', 'arr', 'average', 'avg', 'balance', 'bookings', 'churn', 'conversion', 'cost',
+    'count', 'duration', 'expense', 'growth', 'kpi', 'margin', 'metric', 'mrr', 'orders',
+    'points', 'profit', 'quantity', 'rate', 'revenue', 'sales', 'score', 'scorer', 'scoring', 'spend', 'stats',
+    'statistics', 'total', 'usage', 'value', 'volume',
+];
+const DIMENSION_WORDS = [
+    'account', 'category', 'channel', 'cohort', 'customer', 'department', 'entity', 'geo',
+    'location', 'market', 'merchant', 'month', 'person', 'player', 'product', 'profile',
+    'region', 'segment', 'sku', 'team', 'type', 'user', 'vendor', 'week', 'year',
+];
+const PROFILE_WORDS = [
+    'bio', 'biography', 'career', 'complete stats', 'details', 'entity 360', 'overview',
+    'profile', 'record', 'snapshot', 'stats', 'statistics', 'summary',
+];
+export function buildAnalysisQuestionPlan(question, followUp) {
+    const cleanQuestion = question.replace(/\s+/g, ' ').trim();
+    const normalizedQuestion = normalizeSearchText(cleanQuestion);
+    const lower = cleanQuestion.toLowerCase();
+    const entities = extractEntities(cleanQuestion);
+    const metricTerms = extractMetricTerms(cleanQuestion);
+    const dimensionTerms = extractDimensionTerms(cleanQuestion);
+    const filterTerms = extractFilterTerms(cleanQuestion, entities);
+    const timeTerms = extractTimeTerms(cleanQuestion);
+    const mode = inferQuestionMode({ question: cleanQuestion, lower, entities, metricTerms, dimensionTerms, followUp });
+    const routeIntent = routeIntentForMode(mode);
+    const outputShape = outputShapeForMode(mode, lower);
+    const shouldConsiderCertifiedExact = certifiedExactIsPlausible(mode, entities);
+    const needsGeneratedSql = generatedSqlIsLikely(mode, shouldConsiderCertifiedExact);
+    const needsResearchWorkspace = researchWorkspaceIsLikely(mode, lower);
+    const searchTerms = uniqueStrings([
+        ...tokenize(cleanQuestion),
+        ...entities.flatMap((entity) => tokenize(entity.text)),
+        ...metricTerms,
+        ...dimensionTerms,
+        ...filterTerms,
+        ...timeTerms,
+        ...modeSearchTerms(mode),
+    ]).filter((term) => !STOP_WORDS.has(term)).slice(0, 36);
+    const searchQueries = buildSearchQueries({
+        question: cleanQuestion,
+        mode,
+        entities,
+        metricTerms,
+        dimensionTerms,
+        filterTerms,
+        timeTerms,
+        searchTerms,
+    });
+    const reasons = buildPlanReasons(mode, entities, metricTerms, dimensionTerms, timeTerms, shouldConsiderCertifiedExact);
+    return {
+        question: cleanQuestion,
+        normalizedQuestion,
+        mode,
+        routeIntent,
+        entities,
+        metricTerms,
+        dimensionTerms,
+        filterTerms,
+        timeTerms,
+        outputShape,
+        needsGeneratedSql,
+        shouldConsiderCertifiedExact,
+        needsResearchWorkspace,
+        searchQueries,
+        searchTerms,
+        confidence: planConfidence(mode, entities, metricTerms, dimensionTerms),
+        reasons,
+    };
+}
+export function certifiedApplicabilityForObject(object, plan) {
+    const reasons = [];
+    if (object.objectType !== 'dql_block' || !isCertifiedObject(object)) {
+        return { objectKey: object.objectKey, name: object.name, kind: 'not_applicable', score: 0, reasons: ['not a certified DQL block'] };
+    }
+    const text = objectSearchText(object);
+    const questionText = plan.normalizedQuestion;
+    const name = normalizeSearchText(object.name);
+    const explicitName = Boolean(name && questionText.includes(name));
+    const exactExample = hasExactExampleQuestion(object, plan.normalizedQuestion);
+    const metricMatch = scoreTerms(text, plan.metricTerms);
+    const dimensionMatch = scoreTerms(text, plan.dimensionTerms);
+    const searchMatch = scoreTerms(text, plan.searchTerms);
+    const directionCompatible = rankingDirectionCompatible(plan.question, directionalTextForObject(object));
+    const asksDifferentGrain = plan.needsGeneratedSql || plan.entities.length > 0 || plan.mode === 'entity_profile';
+    const score = Number(((explicitName ? 45 : 0) +
+        (exactExample ? 55 : 0) +
+        metricMatch.score * 12 +
+        dimensionMatch.score * 8 +
+        searchMatch.score * 3 +
+        (directionCompatible ? 10 : -25) +
+        (isDirectCertifiedQuestion(plan) ? 15 : 0) -
+        (asksDifferentGrain ? 24 : 0)).toFixed(3));
+    if (explicitName)
+        reasons.push('question names this certified block');
+    if (exactExample)
+        reasons.push('question matches a certified example');
+    if (metricMatch.matched.length)
+        reasons.push(`metric terms matched: ${metricMatch.matched.join(', ')}`);
+    if (dimensionMatch.matched.length)
+        reasons.push(`dimension terms matched: ${dimensionMatch.matched.join(', ')}`);
+    if (!directionCompatible)
+        reasons.push('ranking direction conflicts with certified block wording');
+    const hasRankingEvidence = plan.mode !== 'ranking' || Boolean(rankingDirection(text)) || /\b(order\s+by|rank|ranking|limit|top|bottom|leader|leading)\b/i.test(text);
+    const hasMetricEvidence = metricMatch.score > 0 || exactExample || explicitName || plan.metricTerms.length === 0;
+    if ((explicitName || exactExample || score >= 70 || (plan.shouldConsiderCertifiedExact &&
+        score >= 40 &&
+        hasMetricEvidence &&
+        (metricMatch.score > 0 || dimensionMatch.score > 0 || searchMatch.score >= 2))) && directionCompatible && hasRankingEvidence && !asksDifferentGrain) {
+        return {
+            objectKey: object.objectKey,
+            name: object.name,
+            kind: 'exact_answer',
+            score,
+            reasons: reasons.length ? reasons : ['certified block contract matches the requested answer shape'],
+        };
+    }
+    const parameterPolicy = metadataString(object.payload?.parameterPolicy ?? object.payload?.parameter_policy);
+    if (parameterPolicy && /safe_filter|safe_group_by|template/i.test(parameterPolicy) && score >= 58 && directionCompatible) {
+        return {
+            objectKey: object.objectKey,
+            name: object.name,
+            kind: 'safe_parameterized',
+            score,
+            reasons: [...reasons, `certified block declares parameter policy ${parameterPolicy}`],
+        };
+    }
+    if (score >= 28 || metricMatch.score > 0 || dimensionMatch.score > 0) {
+        return {
+            objectKey: object.objectKey,
+            name: object.name,
+            kind: 'context_only',
+            score,
+            reasons: [
+                ...reasons,
+                asksDifferentGrain
+                    ? 'question asks for a different entity, filter, or grain; use certified block as context only'
+                    : 'certified block is relevant but not exact enough for direct execution',
+            ],
+        };
+    }
+    return {
+        objectKey: object.objectKey,
+        name: object.name,
+        kind: 'not_applicable',
+        score,
+        reasons: reasons.length ? reasons : ['low semantic overlap with the requested analysis'],
+    };
+}
+export function scoreMetadataObjectWithAnalysisPlan(object, plan) {
+    const text = objectSearchText(object);
+    const search = scoreTerms(text, plan.searchTerms);
+    const metrics = scoreTerms(text, plan.metricTerms);
+    const dimensions = scoreTerms(text, plan.dimensionTerms);
+    const entity = scoreTerms(text, plan.entities.flatMap((item) => tokenize(item.text)));
+    const sourceShape = scoreSourceShape(object, plan);
+    const certified = certifiedApplicabilityForObject(object, plan);
+    const score = Number((search.score * 2.6 +
+        metrics.score * 7 +
+        dimensions.score * 5 +
+        entity.score * 4 +
+        sourceShape +
+        (certified.kind === 'exact_answer' ? 36 : certified.kind === 'safe_parameterized' ? 28 : certified.kind === 'context_only' ? 14 : 0)).toFixed(3));
+    const reasons = [
+        search.matched.length ? `analysis terms matched: ${search.matched.slice(0, 5).join(', ')}` : '',
+        metrics.matched.length ? `metric terms matched: ${metrics.matched.slice(0, 4).join(', ')}` : '',
+        dimensions.matched.length ? `dimension terms matched: ${dimensions.matched.slice(0, 4).join(', ')}` : '',
+        entity.matched.length ? `entity terms matched: ${entity.matched.slice(0, 4).join(', ')}` : '',
+        sourceShape > 0 ? 'source shape matches requested analytical task' : '',
+        certified.kind !== 'not_applicable' ? `certified applicability: ${certified.kind}` : '',
+    ].filter(Boolean);
+    return { score, reasons };
+}
+export function sortAllowedSqlContextForAnalysisPlan(context, plan, options = {}) {
+    const relations = [...context.relations]
+        .sort((a, b) => scoreAllowedSqlRelationWithAnalysisPlan(b, plan).score - scoreAllowedSqlRelationWithAnalysisPlan(a, plan).score
+        || a.relation.localeCompare(b.relation))
+        .slice(0, options.maxRelations ?? 40);
+    return {
+        relations,
+        sourceBlockSql: context.sourceBlockSql,
+    };
+}
+export function scoreAllowedSqlRelationWithAnalysisPlan(relation, plan) {
+    const text = normalizeSearchText(relationSearchText(relation));
+    const search = scoreTerms(text, plan.searchTerms);
+    const metrics = scoreTerms(text, plan.metricTerms);
+    const dimensions = scoreTerms(text, plan.dimensionTerms);
+    const entities = scoreTerms(text, plan.entities.flatMap((entity) => tokenize(entity.text)));
+    const shape = scoreSourceShape({
+        objectKey: relation.objectKey ?? relation.relation,
+        objectType: 'runtime_table',
+        name: relation.name,
+        fullName: relation.relation,
+        sourceSystem: relation.source,
+        payload: { columns: relation.columns },
+    }, plan);
+    const sourceBonus = relation.source.includes('certified source SQL') ? 14
+        : relation.source.includes('certified block') ? 8
+            : relation.source.includes('runtime') ? 6
+                : 0;
+    const usabilityBonus = generatedSqlUsabilityScore(relation, plan);
+    const columnShapeBonus = relationColumnShapeScore(relation, plan);
+    const score = Number((search.score * 3 +
+        metrics.score * 8 +
+        dimensions.score * 6 +
+        entities.score * 3 +
+        shape +
+        sourceBonus +
+        usabilityBonus +
+        columnShapeBonus +
+        Math.min(relation.columns.length, 24) * 0.2).toFixed(3));
+    const reasons = [
+        search.matched.length ? `analysis terms matched: ${search.matched.slice(0, 5).join(', ')}` : '',
+        metrics.matched.length ? `metric terms matched: ${metrics.matched.slice(0, 4).join(', ')}` : '',
+        dimensions.matched.length ? `dimension terms matched: ${dimensions.matched.slice(0, 4).join(', ')}` : '',
+        entities.matched.length ? `entity terms matched: ${entities.matched.slice(0, 4).join(', ')}` : '',
+        shape > 0 ? 'relation shape matches requested analysis mode' : '',
+        sourceBonus > 0 ? `trusted source context: ${relation.source}` : '',
+        usabilityBonus > 0 ? 'relation has usable columns for generated SQL' : '',
+        usabilityBonus < 0 ? 'relation has no inspected/projected columns for generated SQL' : '',
+        columnShapeBonus > 0 ? 'columns match requested analytical shape' : '',
+        relation.columns.length > 0 ? `${relation.columns.length} inspected/projected columns` : '',
+    ].filter(Boolean);
+    return {
+        relation: relation.relation,
+        name: relation.name,
+        source: relation.source,
+        score,
+        reasons,
+    };
+}
+function generatedSqlUsabilityScore(relation, plan) {
+    if (!plan.needsGeneratedSql)
+        return 0;
+    if (relation.columns.length === 0)
+        return -14;
+    return Math.min(18, 8 + relation.columns.length * 0.8);
+}
+function relationColumnShapeScore(relation, plan) {
+    const columns = relation.columns.map((column) => normalizeSearchText(column.name));
+    if (columns.length === 0)
+        return 0;
+    let score = 0;
+    if (plan.mode === 'entity_profile') {
+        if (columns.some((column) => /\b(player|customer|account|user|member|person|product|vendor|name|title)\b/.test(column))) {
+            score += 7;
+        }
+        if (columns.some((column) => /\b(total|count|score|point|assist|rebound|game|minute|revenue|amount|spend|order|stat|rate|value)\b/.test(column))) {
+            score += 9;
+        }
+    }
+    if (plan.mode === 'ranking' && columns.some((column) => /\b(total|count|score|point|amount|revenue|sales|order|rank|value)\b/.test(column))) {
+        score += 8;
+    }
+    if ((plan.mode === 'trend' || plan.mode === 'diagnose_change') && columns.some((column) => /\b(date|time|day|week|month|quarter|year|season|period)\b/.test(column))) {
+        score += 8;
+    }
+    return score;
+}
+function inferQuestionMode(input) {
+    const { lower } = input;
+    if (followUpKind(input.followUp) === 'drilldown')
+        return 'entity_drilldown';
+    if (/^\s*(run|execute|open)\b/i.test(lower))
+        return 'exact_lookup';
+    if (/\b(trust|rely|certif|certified|lineage|owner|caveat|gap|governance|can .* trust)\b/i.test(lower))
+        return 'trust_review';
+    if (/\b(define|definition|meaning of|what is|what are|what does .+ mean)\b/i.test(lower))
+        return 'definition';
+    if (/\b(anomal|exception|outlier|spike|dip)\b/i.test(lower))
+        return 'anomaly';
+    if (/\b(compare|versus|vs\.?|cohort)\b/i.test(lower))
+        return 'comparison';
+    if (/\b(why|changed?|change|drop|dropped|decline|declined|increase|increased|decrease|decreased|delta|variance|what happened)\b/i.test(lower))
+        return 'diagnose_change';
+    if (/\b(driver|drivers|drove|break\s*down|breakdown|contribute|contribution|top movers?)\b/i.test(lower))
+        return 'driver_breakdown';
+    if (/\b(profile|overview|360|complete\s+(?:stats|statistics|view)|full\s+(?:stats|statistics|view)|all\s+(?:stats|statistics|metrics)|research|reserach)\b/i.test(lower))
+        return 'entity_profile';
+    if (input.entities.length > 0 && (input.metricTerms.length > 0 || /\b(show|list|find|give|provide|performance|activity|history|details)\b/i.test(lower)))
+        return 'entity_drilldown';
+    if (/\b(trend|over time|by\s+(?:day|week|month|quarter|year|season)|daily|weekly|monthly|quarterly|yearly)\b/i.test(lower))
+        return 'trend';
+    if (/\b(top|bottom|best|worst|highest|lowest|least|fewest|minimum|min|maximum|max|rank|ranking|most|leading|leader|leaders)\b/i.test(lower))
+        return 'ranking';
+    if (/\b(block|certified|saved|existing|approved|governed)\b/i.test(lower))
+        return 'exact_lookup';
+    if (isDirectKpiValueQuestion(lower))
+        return 'exact_lookup';
+    if (/\b(show|list|find|which|who|how many|how much|metric|kpi|dashboard|performance|revenue|sales|orders|customers|users)\b/i.test(lower))
+        return 'general_analysis';
+    return 'clarify';
+}
+function routeIntentForMode(mode) {
+    switch (mode) {
+        case 'exact_lookup': return 'exact_certified_lookup';
+        case 'definition': return 'definition_lookup';
+        case 'ranking': return 'ad_hoc_ranking';
+        case 'entity_profile':
+        case 'entity_drilldown': return 'entity_drilldown';
+        case 'trend': return 'segment_compare';
+        case 'comparison': return 'segment_compare';
+        case 'driver_breakdown': return 'driver_breakdown';
+        case 'diagnose_change': return 'diagnose_change';
+        case 'anomaly': return 'anomaly_investigation';
+        case 'trust_review': return 'trust_gap_review';
+        case 'general_analysis': return 'ad_hoc_ranking';
+        case 'clarify': return 'clarify';
+    }
+}
+function certifiedExactIsPlausible(mode, entities) {
+    if (mode === 'exact_lookup' || mode === 'definition')
+        return true;
+    if (mode === 'ranking' || mode === 'general_analysis')
+        return entities.length === 0;
+    return false;
+}
+function generatedSqlIsLikely(mode, certifiedExact) {
+    if (mode === 'clarify' || mode === 'definition' || mode === 'trust_review')
+        return false;
+    return !certifiedExact || ['entity_profile', 'entity_drilldown', 'comparison', 'driver_breakdown', 'diagnose_change', 'anomaly', 'trend'].includes(mode);
+}
+function researchWorkspaceIsLikely(mode, lower) {
+    return ['entity_profile', 'driver_breakdown', 'diagnose_change', 'anomaly', 'trust_review'].includes(mode)
+        || /\b(deep\s+research|research|reserach|investigate|investigation|root cause)\b/i.test(lower);
+}
+function outputShapeForMode(mode, lower) {
+    if (mode === 'entity_profile')
+        return 'profile';
+    if (mode === 'definition' || mode === 'trust_review')
+        return 'narrative';
+    if (/\b(chart|graph|visual|plot)\b/i.test(lower) || mode === 'trend')
+        return 'chart';
+    if (/\b(table|list|show all|complete|full)\b/i.test(lower) || mode === 'ranking' || mode === 'entity_drilldown')
+        return 'table';
+    if (/\bwhat is|how many|how much|total|count|kpi|metric\b/i.test(lower))
+        return 'value';
+    return 'narrative';
+}
+function extractEntities(question) {
+    const entities = [];
+    for (const match of question.matchAll(/["']([^"']{2,120})["']/g)) {
+        entities.push({ text: match[1].trim(), source: 'quoted' });
+    }
+    for (const match of question.matchAll(/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/g)) {
+        entities.push({ text: match[0], source: 'email', typeHint: 'email' });
+    }
+    for (const match of question.matchAll(/\b(?:id|account id|customer id|user id|sku)\s*[:=]?\s*([A-Za-z0-9_.-]{3,80})\b/gi)) {
+        entities.push({ text: match[1].trim(), source: 'id' });
+    }
+    for (const match of question.matchAll(/\b(?:for|where|only|specific|named|called|profile\s+for|research\s+on|reserach\s+on)\s+([A-Z][A-Za-z0-9&.'-]+(?:\s+[A-Z][A-Za-z0-9&.'-]+){0,5})/g)) {
+        entities.push({ text: cleanEntityText(match[1]), source: 'explicit_filter' });
+    }
+    for (const match of question.matchAll(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,4})\b/g)) {
+        const text = cleanEntityText(match[1]);
+        if (text && !/^(SQL|DQL|KPI|ARR|MRR|NBA|AI|LLM)$/.test(text)) {
+            entities.push({ text, source: 'named_entity' });
+        }
+    }
+    return uniqueEntities(entities).slice(0, 8);
+}
+function extractMetricTerms(question) {
+    const lower = question.toLowerCase();
+    const terms = new Set();
+    if (/\b(scorer|scorers|scoring|scored)\b/i.test(lower)) {
+        terms.add('score');
+        terms.add('scoring');
+    }
+    for (const word of METRIC_WORDS) {
+        if (new RegExp(`\\b${escapeRegExp(word)}s?\\b`, 'i').test(lower))
+            terms.add(normalizeTerm(word));
+    }
+    for (const match of lower.matchAll(/\b(total|average|avg|count|sum|min|max)\s+([a-z][a-z0-9_ -]{2,40})/g)) {
+        terms.add(normalizeTerm(`${match[1]} ${match[2]}`));
+        terms.add(normalizeTerm(match[2]));
+    }
+    return uniqueStrings([...terms]).slice(0, 16);
+}
+function extractDimensionTerms(question) {
+    const lower = question.toLowerCase();
+    const terms = new Set();
+    for (const word of DIMENSION_WORDS) {
+        if (new RegExp(`\\b${escapeRegExp(word)}s?\\b`, 'i').test(lower))
+            terms.add(normalizeTerm(word));
+    }
+    for (const match of lower.matchAll(/\bby\s+([a-z][a-z0-9_ -]{1,40})/g)) {
+        const value = match[1].replace(/\b(where|for|with|and|or|from|over|in)\b.*$/i, '').trim();
+        if (value)
+            terms.add(normalizeTerm(value));
+    }
+    return uniqueStrings([...terms]).slice(0, 16);
+}
+function extractFilterTerms(question, entities) {
+    return uniqueStrings([
+        ...entities.flatMap((entity) => tokenize(entity.text)),
+        ...Array.from(question.matchAll(/\b(?:last|this|next|previous|prior|current)\s+(day|week|month|quarter|year|season)\b/gi)).map((match) => match[0].toLowerCase()),
+    ]).slice(0, 16);
+}
+function extractTimeTerms(question) {
+    const terms = [];
+    for (const match of question.matchAll(/\b(?:today|yesterday|ytd|mtd|qtd|wtd|last\s+\w+|this\s+\w+|next\s+\w+|previous\s+\w+|prior\s+\w+|\d{4})\b/gi)) {
+        terms.push(match[0].toLowerCase());
+    }
+    for (const word of ['date', 'day', 'week', 'month', 'quarter', 'year', 'season', 'period']) {
+        if (new RegExp(`\\b${word}\\b`, 'i').test(question))
+            terms.push(word);
+    }
+    return uniqueStrings(terms).slice(0, 12);
+}
+function buildSearchQueries(input) {
+    const entityText = input.entities.map((entity) => entity.text).join(' ');
+    const profileTerms = input.mode === 'entity_profile' ? PROFILE_WORDS.join(' ') : '';
+    return uniqueStrings([
+        input.question,
+        [entityText, ...input.metricTerms, ...input.dimensionTerms].filter(Boolean).join(' '),
+        [...input.metricTerms, ...input.dimensionTerms, ...input.timeTerms].join(' '),
+        [profileTerms, ...input.searchTerms.slice(0, 12)].filter(Boolean).join(' '),
+        input.searchTerms.slice(0, 18).join(' '),
+    ].map((query) => query.replace(/\s+/g, ' ').trim()).filter(Boolean)).slice(0, 5);
+}
+function buildPlanReasons(mode, entities, metrics, dimensions, timeTerms, certifiedExact) {
+    return [
+        `classified as ${mode}`,
+        entities.length ? `entities: ${entities.map((entity) => entity.text).join(', ')}` : '',
+        metrics.length ? `metrics: ${metrics.join(', ')}` : '',
+        dimensions.length ? `dimensions: ${dimensions.join(', ')}` : '',
+        timeTerms.length ? `time context: ${timeTerms.join(', ')}` : '',
+        certifiedExact ? 'certified exact answer is plausible' : 'generated SQL may be needed if no exact certified contract matches',
+    ].filter(Boolean);
+}
+function modeSearchTerms(mode) {
+    switch (mode) {
+        case 'entity_profile': return ['profile', 'summary', 'details', 'stats', 'statistics', 'history'];
+        case 'entity_drilldown': return ['detail', 'filter', 'name', 'id'];
+        case 'ranking': return ['rank', 'top', 'bottom', 'total'];
+        case 'trend': return ['date', 'time', 'month', 'week', 'year', 'trend'];
+        case 'comparison': return ['compare', 'segment', 'cohort'];
+        case 'driver_breakdown': return ['driver', 'breakdown', 'contribution'];
+        case 'diagnose_change': return ['change', 'baseline', 'period', 'date'];
+        case 'anomaly': return ['anomaly', 'exception', 'outlier'];
+        case 'trust_review': return ['lineage', 'owner', 'certified', 'caveat'];
+        default: return [];
+    }
+}
+function scoreSourceShape(object, plan) {
+    const text = objectSearchText(object);
+    let score = 0;
+    if ((object.objectType === 'dbt_model' || object.objectType === 'warehouse_table' || object.objectType === 'runtime_table') && plan.needsGeneratedSql)
+        score += 12;
+    if (plan.mode === 'entity_profile' && /\b(dim|entity|profile|customer|account|user|product|player|vendor|person|member)\b/i.test(text))
+        score += 8;
+    if (plan.mode === 'entity_profile' && /\b(fct|fact|event|transaction|activity|performance|stats|history)\b/i.test(text))
+        score += 8;
+    if (plan.mode === 'trend' && /\b(date|time|day|week|month|quarter|year|season|period)\b/i.test(text))
+        score += 10;
+    if (plan.mode === 'ranking' && /\b(total|amount|score|count|rank|revenue|sales|points|orders)\b/i.test(text))
+        score += 8;
+    return score;
+}
+function relationSearchText(relation) {
+    return [
+        relation.relation,
+        relation.name,
+        relation.source,
+        relation.columns.map((column) => `${column.name} ${column.description ?? ''}`).join(' '),
+    ].join(' ');
+}
+function isDirectCertifiedQuestion(plan) {
+    return plan.mode === 'exact_lookup' || plan.mode === 'definition' || (plan.shouldConsiderCertifiedExact && !plan.needsGeneratedSql);
+}
+function hasExactExampleQuestion(object, normalizedQuestion) {
+    const examples = Array.isArray(object.payload?.examples) ? object.payload.examples : [];
+    return examples.some((example) => {
+        if (!example || typeof example !== 'object')
+            return false;
+        const question = example.question;
+        return typeof question === 'string' && normalizeSearchText(question) === normalizedQuestion;
+    });
+}
+function rankingDirectionCompatible(question, targetText) {
+    const questionDirection = rankingDirection(question);
+    if (!questionDirection)
+        return true;
+    const targetDirection = rankingDirection(targetText);
+    return !targetDirection || targetDirection === questionDirection;
+}
+function rankingDirection(value) {
+    const lower = value.toLowerCase();
+    const bottom = /\b(bottom|worst|lowest|least|fewest|minimum|min|smallest)\b/.test(lower);
+    const top = /\b(top|best|highest|most|maximum|max|largest|leading|leaders?)\b/.test(lower);
+    if (bottom && !top)
+        return 'bottom';
+    if (top && !bottom)
+        return 'top';
+    return undefined;
+}
+function scoreTerms(text, terms) {
+    const matched = [];
+    let score = 0;
+    for (const term of uniqueStrings(terms.map(normalizeTerm).filter(Boolean))) {
+        if (!term || term.length < 2)
+            continue;
+        const tokens = term.split(/\s+/).filter(Boolean);
+        const hit = tokens.length > 1
+            ? text.includes(term)
+            : new RegExp(`\\b${escapeRegExp(term)}s?\\b`, 'i').test(text);
+        if (!hit)
+            continue;
+        matched.push(term);
+        score += tokens.length > 1 ? 1.4 : 1;
+    }
+    return { score, matched };
+}
+function objectSearchText(object) {
+    return normalizeSearchText([
+        object.objectType,
+        object.objectKey,
+        object.name,
+        object.fullName ?? '',
+        object.domain ?? '',
+        object.owner ?? '',
+        object.status ?? '',
+        object.description ?? '',
+        object.sourceSystem ?? '',
+        JSON.stringify(object.payload ?? {}),
+    ].join(' '));
+}
+function directionalTextForObject(object) {
+    return normalizeSearchText([
+        object.name,
+        object.description ?? '',
+        Array.isArray(object.payload?.tags) ? object.payload.tags.join(' ') : '',
+        typeof object.payload?.sql === 'string' ? object.payload.sql : '',
+    ].join(' '));
+}
+function planConfidence(mode, entities, metrics, dimensions) {
+    let score = mode === 'clarify' ? 0.25 : 0.55;
+    if (entities.length)
+        score += 0.14;
+    if (metrics.length)
+        score += 0.12;
+    if (dimensions.length)
+        score += 0.08;
+    if (mode === 'entity_profile')
+        score += 0.08;
+    return Math.min(0.92, Number(score.toFixed(2)));
+}
+function followUpKind(value) {
+    return value && typeof value === 'object' ? String(value.kind ?? '') : undefined;
+}
+function uniqueEntities(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const text = cleanEntityText(item.text);
+        const key = normalizeSearchText(text);
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ ...item, text });
+    }
+    return out;
+}
+function cleanEntityText(value) {
+    return value
+        .replace(/^(?:can\s+you\s+)?(?:research|reserach|show|find|provide|give|list|tell\s+me|run|execute|open)\s+/i, '')
+        .replace(/\b(profile|stats?|statistics|complete|full|details?|summary|with|and|by|for|from|in|on)\b.*$/i, '')
+        .replace(/[?.!,;:]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function isDirectKpiValueQuestion(lower) {
+    const asksForValue = /\b(what\s+(?:is|was|were|are)|how\s+(?:much|many)|show|report|calculate|give\s+me|tell\s+me)\b/.test(lower);
+    const metricLanguage = /\b(revenue|sales|arr|mrr|bookings|orders|customers|users|churn|retention|conversion|rate|count|total|points|goals|kpi|metric)\b/.test(lower);
+    const customGrain = /\b(by|break\s*down|breakdown|drill|compare|versus|vs\.?|segment|cohort|top|bottom|best|worst|highest|lowest|least|fewest|rank|ranking|most|why|changed?|driver|anomal|exception)\b/.test(lower);
+    return asksForValue && metricLanguage && !customGrain;
+}
+function tokenize(value) {
+    const tokens = new Set();
+    for (const raw of normalizeSearchText(value).split(/\s+/)) {
+        const normalized = normalizeTerm(raw);
+        if (!normalized || normalized.length < 2 || STOP_WORDS.has(normalized))
+            continue;
+        tokens.add(normalized);
+    }
+    return [...tokens];
+}
+function normalizeSearchText(value) {
+    return value.toLowerCase().replace(/[_-]+/g, ' ').replace(/[^a-z0-9@. ]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function normalizeTerm(value) {
+    const clean = normalizeSearchText(value);
+    if (clean.endsWith('ies') && clean.length > 4)
+        return `${clean.slice(0, -3)}y`;
+    if (clean.endsWith('s') && clean.length > 4)
+        return clean.slice(0, -1);
+    return clean;
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const clean = value.replace(/\s+/g, ' ').trim();
+        if (!clean)
+            continue;
+        const key = clean.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(clean);
+    }
+    return out;
+}
+function isCertifiedObject(object) {
+    return object.status === 'certified' || object.status === 'approved' || object.payload?.certification === 'certified';
+}
+function metadataString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=analysis-planner.js.map