@duckcodeailabs/dql-agent 1.14.3-rc.1 → 1.14.4

package/dist/router.d.ts

@@ -1,9 +1,26 @@
 import { type AnswerAssumption } from './agentic/assumptions.js';
+/**
+ * Hybrid router — deterministic-first, LLM-assisted for the ambiguous middle.
+ *
+ * The engine already routes deterministically via {@link decideAgentAction}. That
+ * cascade is fast, offline, and confident for the clear cases (a strong certified
+ * match, an explicit "build me a dashboard", an obvious greeting). But paraphrased
+ * or implicit analytical asks land at low confidence and misroute — which is why
+ * users end up clicking "Dig deeper" by hand.
+ *
+ * This router keeps the deterministic decision when it is confident (>= the
+ * threshold) — so certified fast paths and greetings stay 0-LLM — and only spends
+ * ONE cheap classification call when the heuristics are unsure. The completion is
+ * injected (provider-agnostic, like the planner and narrator); any failure falls
+ * back to the deterministic decision unchanged. Results are cached so a repeated
+ * question never pays twice.
+ */
+import { type IntentDecision } from "./intent-controller.js";
 import type { AgentRunRequest, AgentRouter } from "./agent-run-engine.js";
 import type { MetadataAgentIntent } from "./metadata/catalog.js";
-import { type AgentEvidenceCandidate, type AgentMeaningResolver, type AgentRetrievalEvidence, type MeaningResolution } from "./meaning-resolution.js";
+import { type AgentEvidenceCandidate, type AgentMeaningResolver, type AgentRelationshipSafetyEvidence, type AgentRetrievalEvidence, type MeaningResolution } from "./meaning-resolution.js";
 import { type ResolvedAnalyticalPlan } from "./resolved-analytical-plan.js";
-import { type AnalyticalRequirementSeedV1 } from './analytical-orchestration.js';
+import { type AnalyticalProgram, type AnalyticalRequirementSetV1, type AnalyticalRequirementSeedV1 } from './analytical-orchestration.js';
 /** The router's fine-grained classification of a turn. */
 export interface RouterClassification {
     category: "conversational" | "capability" | "general_knowledge" | "data_lookup" | "data_analysis" | "authoring" | "app" | "unclear";
@@ -67,7 +84,82 @@ export interface HybridRouterOptions {
  * decision — routing itself keys off `action`/`category`.
  */
 declare function intentForCategory(category: RouterClassification["category"]): MetadataAgentIntent | undefined;
+export declare function buildMeaningSystemPrompt(): string;
+export declare function buildMeaningUserPrompt(request: AgentRunRequest, evidence: AgentRetrievalEvidence, candidates: AgentEvidenceCandidate[], requirementSeed: AnalyticalRequirementSeedV1): string;
 declare function parseMeaningResolution(raw: string, requirementSeed?: AnalyticalRequirementSeedV1): MeaningResolution | undefined;
+/**
+ * Persist the immutable snapshot's candidate lifecycle for either the legacy
+ * router or AskAnalystRuntimeV1. This is an observability projection only: it
+ * cannot retrieve, rank, admit, or alter a program.
+ */
+export declare function recordAskCandidateLifecycleV1(request: AgentRunRequest, evidence: AgentRetrievalEvidence, candidates: AgentEvidenceCandidate[], packageCandidates: AgentEvidenceCandidate[]): void;
+/**
+ * The only reusable relationship-proof classification for a snapshot card.
+ *
+ * `governed` is deliberately stricter than `exploratory`: the latter may
+ * close a review-required raw-SQL path, but it must never acquire governed
+ * trust merely because its fanout happens to be safe.  Callers still need to
+ * retain the original raw proof and revalidate it at compiler freeze time.
+ */
+export type RelationshipSafetyProofClassV1 = 'governed' | 'exploratory';
+/**
+ * The canonical, one-to-one proof mapping for a relationship evidence card.
+ *
+ * `relationshipEvidence` is deliberately rewritten to the safety record's
+ * canonical ID.  A retrieval card may use an approved alias, but a synthetic
+ * planner path must never serialize an arbitrary collection of raw aliases or
+ * neighboring proof records.
+ */
+export interface RelationshipSafetyProofSelectionV1 {
+    proofClass: RelationshipSafetyProofClassV1;
+    relationshipEvidence: string[];
+    relationshipSafety: AgentRelationshipSafetyEvidence[];
+}
+/**
+ * Resolve a card's complete same-snapshot relationship proof set.
+ *
+ * Every evidence edge must map to exactly one structured proof (an alias may
+ * perform that mapping); every supplied proof must be used by an evidence
+ * edge.  This rejects partial cards, unrelated safety records, and aliases
+ * that ambiguously name two proofs before a host-authored path card can carry
+ * them into planner context.  The router/compiler still revalidates the
+ * selected raw edges at freeze time.
+ */
+export declare function relationshipSafetyProofSelectionForCandidateV1(candidate: Pick<AgentEvidenceCandidate, 'relationshipEvidence' | 'relationshipSafety'>): RelationshipSafetyProofSelectionV1 | undefined;
+export declare function relationshipSafetyProofClassForCandidateV1(candidate: Pick<AgentEvidenceCandidate, 'relationshipEvidence' | 'relationshipSafety'>): RelationshipSafetyProofClassV1 | undefined;
+/**
+ * Evaluate an attribution/allocation policy boundary from one immutable
+ * snapshot. AskAnalystRuntimeV1 invokes this before an optional provider
+ * meaning call: a declared denial is neither an ambiguity nor a provider
+ * failure. This helper only evaluates supplied evidence; it never retrieves
+ * additional context or executes a query.
+ */
+export declare function attributionRequiredRelationshipGapDecision(input: {
+    request: AgentRunRequest;
+    base: IntentDecision;
+    evidence: AgentRetrievalEvidence;
+    requirements: AnalyticalRequirementSetV1;
+}): IntentDecision | undefined;
+/**
+ * Compiler-only bridge for AskAnalystRuntimeV1.  The runtime owns question
+ * framing, candidate admission, meaning selection, and the immutable program;
+ * this adapter only validates that selected program against existing safe
+ * certified/MetricFlow/relational/exploratory compilers.  It must never call a
+ * provider, retrieve a new snapshot, or nominate a different business meaning.
+ */
+export declare function compileAskAnalyticalProgramV1(input: {
+    base: IntentDecision;
+    request: AgentRunRequest;
+    evidence: AgentRetrievalEvidence;
+    /** Immutable route-neutral program produced by AskAnalystRuntimeV1. */
+    program: AnalyticalProgram;
+    /** Same-snapshot compiler context, including a bounded physical closure. */
+    executionCandidates?: AgentEvidenceCandidate[];
+    candidates: AgentEvidenceCandidate[];
+    resolution: MeaningResolution;
+    requirements: AnalyticalRequirementSetV1;
+    mode?: ResolvedAnalyticalPlan['mode'];
+}): IntentDecision;
 /**
  * A candidate's `definition` is sometimes the raw semantic-layer record —
  * `label: customers\naggregation: count_distinct\ntable: "..."\nexpr: customer_id`.
@@ -76,6 +168,21 @@ declare function parseMeaningResolution(raw: string, requirementSeed?: Analytica
  * genuine authored prose alone.
  */
 export declare function humanizeCandidateDefinition(definition: string | undefined): string | undefined;
+/**
+ * Bind an already validated runtime meaning selection to the immutable
+ * host-owned analytical frame.  This is intentionally a narrow compiler
+ * adapter: it does not retrieve, rank candidates, call a provider, or change
+ * the runtime program.  Keeping the V2 frame construction here lets the
+ * existing MetricFlow compiler retain its capability/additivity validation
+ * without returning ownership of interpretation to the legacy router.
+ */
+export declare function bindAskAnalystProgramMeaningV1(input: {
+    request: AgentRunRequest;
+    evidence: AgentRetrievalEvidence;
+    candidates: AgentEvidenceCandidate[];
+    requirementSeed: AnalyticalRequirementSeedV1;
+    resolution: MeaningResolution;
+}): MeaningResolution;
 /**
  * Reduce retrieval output to genuinely DIFFERENT governed meanings.
  *

package/dist/router.d.ts.map

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