@duckcodeailabs/dql-agent 1.7.1 → 1.8.0

package/dist/meaning-resolution.js

@@ -0,0 +1,155 @@
+/**
+ * Compact, provider-agnostic evidence contracts for retrieval-first routing.
+ *
+ * Retrieval owns recall and ranking. The meaning resolver sees only this bounded
+ * package and may reference only IDs contained in it. Execution remains owned by
+ * the host after it validates the selected candidates and route.
+ */
+const TRUST_ORDER = {
+    certified: 4,
+    semantic: 3,
+    governed_sql: 2,
+    exploratory: 1,
+};
+const COMPATIBILITY_ORDER = {
+    compatible: 4,
+    partial: 3,
+    unknown: 2,
+    incompatible: 1,
+};
+/**
+ * Produce the bounded evidence package sent to the resolver. Relevance remains
+ * primary; trust is only a tie-breaker, so an unrelated certified block cannot
+ * displace a materially better semantic match.
+ */
+export function buildMeaningEvidencePackage(evidence, maxCandidates = 12) {
+    const limit = Math.max(1, Math.min(20, Math.floor(maxCandidates)));
+    const perTierLimit = Math.max(2, Math.ceil(limit / 2));
+    const tierCounts = new Map();
+    return evidence.candidates
+        .filter((candidate) => candidate.eligible !== false)
+        .sort(compareCandidates)
+        .filter((candidate) => {
+        const count = tierCounts.get(candidate.trustTier) ?? 0;
+        if (count >= perTierLimit)
+            return false;
+        tierCounts.set(candidate.trustTier, count + 1);
+        return true;
+    })
+        .slice(0, limit);
+}
+function compareCandidates(left, right) {
+    return Number(Boolean(right.exactMatch)) - Number(Boolean(left.exactMatch))
+        || clamp01(right.relevanceScore) - clamp01(left.relevanceScore)
+        || COMPATIBILITY_ORDER[right.compatibility] - COMPATIBILITY_ORDER[left.compatibility]
+        || TRUST_ORDER[right.trustTier] - TRUST_ORDER[left.trustTier]
+        || left.id.localeCompare(right.id);
+}
+function clamp01(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+}
+/** Match only explicit qualified references; ordinary names still use resolution. */
+export function findExplicitEvidenceReference(question, candidates) {
+    const refs = new Set();
+    for (const match of question.matchAll(/@(metric|block|model|table|column)\(([^)]+)\)/gi)) {
+        refs.add(normalizeRef(match[2]));
+    }
+    for (const candidate of candidates) {
+        if (question.includes(candidate.id))
+            refs.add(normalizeRef(candidate.id));
+    }
+    if (refs.size === 0)
+        return undefined;
+    const matches = candidates.filter((candidate) => {
+        const candidateRefs = [candidate.id, candidate.name, ...(candidate.aliases ?? [])].map(normalizeRef);
+        return candidateRefs.some((ref) => refs.has(ref));
+    });
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function normalizeRef(value) {
+    return value.trim().toLowerCase().replace(/[`"']/g, "");
+}
+/** Validate that a resolver cannot invent or select ineligible evidence. */
+export function validateMeaningResolution(value, candidates) {
+    const byId = new Map(candidates.map((candidate) => [candidate.id, candidate]));
+    const referencedIds = [
+        ...value.selectedConceptIds,
+        ...(value.recommendedExecutionId ? [value.recommendedExecutionId] : []),
+        ...value.rejectedCandidates.map((candidate) => candidate.id),
+    ];
+    const invented = referencedIds.find((id) => !byId.has(id));
+    if (invented)
+        return { ok: false, reason: `The resolver referenced evidence that was not retrieved: ${invented}` };
+    if (value.confidence !== "low" && value.selectedConceptIds.length === 0) {
+        return { ok: false, reason: "A medium/high-confidence resolution must select at least one retrieved concept." };
+    }
+    const selected = value.selectedConceptIds.map((id) => byId.get(id));
+    if (selected.some((candidate) => candidate.eligible === false || candidate.compatibility === "incompatible")) {
+        return { ok: false, reason: "The resolver selected ineligible or incompatible evidence." };
+    }
+    const rejectedIds = new Set(value.rejectedCandidates.map((candidate) => candidate.id));
+    if (value.selectedConceptIds.some((id) => rejectedIds.has(id))) {
+        return { ok: false, reason: "The resolver both selected and rejected the same evidence." };
+    }
+    const executionId = value.recommendedExecutionId ?? value.selectedConceptIds[0];
+    if (executionId) {
+        const execution = byId.get(executionId);
+        if (execution.eligible === false || execution.compatibility === "incompatible") {
+            return { ok: false, reason: "The recommended execution evidence is ineligible or incompatible." };
+        }
+        if (value.recommendedRoute === "certified" && execution.kind !== "certified_block") {
+            return { ok: false, reason: "A certified route must reference a certified block." };
+        }
+        if (value.recommendedRoute === "certified" && execution.compatibility !== "compatible") {
+            return { ok: false, reason: "A certified route requires a deterministically compatible block fit." };
+        }
+        if (value.recommendedRoute === "semantic" && execution.kind !== "semantic_metric" && execution.kind !== "semantic_member") {
+            return { ok: false, reason: "A semantic route must reference semantic evidence." };
+        }
+        if (value.recommendedRoute === "semantic" && execution.compatibility !== "compatible") {
+            return { ok: false, reason: "A semantic route requires deterministic measure, grain, and dimension compatibility." };
+        }
+    }
+    return { ok: true, resolution: value };
+}
+export function routeForEvidenceCandidate(candidate) {
+    if (candidate.kind === "certified_block" && candidate.compatibility === "compatible")
+        return "certified";
+    if ((candidate.kind === "semantic_metric" || candidate.kind === "semantic_member") && candidate.compatibility === "compatible") {
+        return "semantic";
+    }
+    return candidate.trustTier === "governed_sql" ? "governed_sql" : "exploratory";
+}
+export function questionTypeFromText(question) {
+    if (/\b(why|root ?cause|diagnos|driver|what (?:caused|changed|happened)|anomal)\b/i.test(question))
+        return "diagnosis";
+    if (/\b(research|investigate|deep ?dive)\b/i.test(question))
+        return "research";
+    if (/\b(top|bottom|highest|lowest|rank)\b/i.test(question))
+        return "ranking";
+    if (/\b(trend|over time|month over month|year over year|mom|yoy|by (?:day|week|month|quarter|year))\b/i.test(question))
+        return "trend";
+    if (/\b(compare|versus|vs\.?|difference between)\b/i.test(question))
+        return "comparison";
+    // "What is total revenue?" asks for a data value, not a definition. This
+    // distinction matters because definition paths may intentionally bypass
+    // execution-shape checks for glossary/certified descriptions.
+    if (/\b(total|sum|count|number of|average|avg|minimum|maximum|across all|overall)\b/i.test(question)
+        && /\b(what (?:is|was|were|are)|how (?:much|many)|show|report|calculate|give|tell)\b/i.test(question))
+        return "value";
+    if (/^\s*(what (?:is|are|does)|define|definition|meaning of)\b/i.test(question))
+        return "definition";
+    return "value";
+}
+export function defaultQueryIntent(evidence) {
+    return {
+        measures: evidence.parsedIntent?.measures ?? [],
+        dimensions: evidence.parsedIntent?.dimensions ?? [],
+        filters: evidence.parsedIntent?.filters ?? [],
+        ...(evidence.parsedIntent?.timeRange ? { timeRange: evidence.parsedIntent.timeRange } : {}),
+        ...(evidence.parsedIntent?.timeGrain ? { timeGrain: evidence.parsedIntent.timeGrain } : {}),
+        ...(evidence.parsedIntent?.order ? { order: evidence.parsedIntent.order } : {}),
+        ...(evidence.parsedIntent?.limit !== undefined ? { limit: evidence.parsedIntent.limit } : {}),
+    };
+}
+//# sourceMappingURL=meaning-resolution.js.map

package/dist/meaning-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meaning-resolution.js","sourceRoot":"","sources":["../src/meaning-resolution.ts"],"names":[],"mappings":"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"}

package/dist/metadata/analysis-planner.d.ts

@@ -1,16 +1,30 @@
 import type { MetadataAgentIntent, MetadataAllowedSqlContext, MetadataObject } from './catalog.js';
-export type AnalysisQuestionMode = 'exact_lookup' | 'definition' | 'ranking' | 'entity_profile' | 'entity_drilldown' | 'trend' | 'comparison' | 'driver_breakdown' | 'diagnose_change' | 'anomaly' | 'trust_review' | 'general_analysis' | 'clarify';
+export type AnalysisQuestionMode = 'exact_lookup' | 'definition' | 'list_by_dimension' | 'ranking' | 'entity_profile' | 'entity_drilldown' | 'trend' | 'comparison' | 'driver_breakdown' | 'diagnose_change' | 'anomaly' | 'trust_review' | 'general_analysis' | 'clarify';
 export interface AnalysisEntityMention {
     text: string;
     source: 'quoted' | 'named_entity' | 'explicit_filter' | 'email' | 'id';
     typeHint?: string;
 }
+/**
+ * A phrase that may be a stored member value rather than a metadata object.
+ * Keep the original phrase intact so later, field-scoped value resolution can
+ * distinguish `Melissa Lopez` (a customer_name value) from `customer` (an
+ * entity) and `revenue` (a metric). AGT-005/AGT-009.
+ */
+export interface AnalysisValueMention {
+    text: string;
+    normalizedText: string;
+    source: AnalysisEntityMention['source'];
+    syntacticRole: 'filter_value' | 'entity_identifier' | 'unknown';
+    typeHint?: string;
+}
 export interface AnalysisQuestionPlan {
     question: string;
     normalizedQuestion: string;
     mode: AnalysisQuestionMode;
     routeIntent: MetadataAgentIntent;
     entities: AnalysisEntityMention[];
+    valueMentions: AnalysisValueMention[];
     metricTerms: string[];
     dimensionTerms: string[];
     filterTerms: string[];

package/dist/metadata/analysis-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-planner.d.ts","sourceRoot":"","sources":["../../src/metadata/analysis-planner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analysis-planner.d.ts","sourceRoot":"","sources":["../../src/metadata/analysis-planner.ts"],"names":[],"mappings":"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"}