@duckcodeailabs/dql-agent 1.13.4 → 1.13.5

package/dist/router.d.ts

@@ -16,7 +16,7 @@
  */
 import type { AgentRunRequest, AgentRouter } from "./agent-run-engine.js";
 import type { MetadataAgentIntent } from "./metadata/catalog.js";
-import { type AgentMeaningResolver, type AgentRetrievalEvidence, type MeaningResolution } from "./meaning-resolution.js";
+import { type AgentEvidenceCandidate, type AgentMeaningResolver, type AgentRetrievalEvidence, type MeaningResolution } from "./meaning-resolution.js";
 import { type ResolvedAnalyticalPlan } from "./resolved-analytical-plan.js";
 /** The router's fine-grained classification of a turn. */
 export interface RouterClassification {
@@ -65,6 +65,35 @@ export interface HybridRouterOptions {
  */
 declare function intentForCategory(category: RouterClassification["category"]): MetadataAgentIntent | undefined;
 declare function parseMeaningResolution(raw: string): MeaningResolution | undefined;
+/**
+ * A candidate's `definition` is sometimes the raw semantic-layer record —
+ * `label: customers\naggregation: count_distinct\ntable: "..."\nexpr: customer_id`.
+ * Dumping that into a question asks a business user to disambiguate by reading
+ * YAML. Turn a recognisable key/value record into one plain sentence; leave
+ * genuine authored prose alone.
+ */
+export declare function humanizeCandidateDefinition(definition: string | undefined): string | undefined;
+/**
+ * Reduce retrieval output to genuinely DIFFERENT governed meanings.
+ *
+ * Two collapses, both provable from the semantic registry rather than guessed:
+ *  - A simple metric, the measure it wraps, and the model that holds them are
+ *    one meaning. Offering all three asks a person to choose between a thing
+ *    and its own wrapper.
+ *  - An entity is a join key, not an answer. When the question asks for an
+ *    attribute ("customer names") and a dimension matched, entities are not
+ *    candidate readings of it at all.
+ */
+export declare function collapseRedundantGovernedCandidates(question: string, candidates: AgentEvidenceCandidate[]): AgentEvidenceCandidate[];
+/**
+ * The governed meaning to run when nothing proved a single exact reading.
+ *
+ * DQL commits to the best-ranked interpretation and discloses it through the
+ * route label, instead of stopping to ask. Asking on every multi-candidate
+ * question made ordinary lookups feel like an interrogation, and most of those
+ * questions had no real ambiguity behind them.
+ */
+export declare function bestGovernedInterpretation(question: string, candidates: AgentEvidenceCandidate[]): AgentEvidenceCandidate | undefined;
 /**
  * Build a retrieval-first hybrid router. Narrow conversational/app preflight is
  * deterministic. Every other turn loads structured evidence before any

package/dist/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAQL,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,+BAA+B,CAAC;AAWvC,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EACJ,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,WAAW,GACX,KAAK,GACL,SAAS,CAAC;IACd,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEtB,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3E;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,sBAAsB,GAAG,SAAS,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAC7H,iFAAiF;IACjF,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD;;;;GAIG;AACH,iBAAS,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,GAAG,mBAAmB,GAAG,SAAS,CAWtG;AAkPD,iBAAS,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAuE1E;AA8mBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAqOjF;AAED,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAQL,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,+BAA+B,CAAC;AAWvC,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EACJ,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,WAAW,GACX,KAAK,GACL,SAAS,CAAC;IACd,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEtB,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3E;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,sBAAsB,GAAG,SAAS,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAC7H,iFAAiF;IACjF,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAClD,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD;;;;GAIG;AACH,iBAAS,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,GAAG,mBAAmB,GAAG,SAAS,CAWtG;AAkPD,iBAAS,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAuE1E;AAwdD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAuB9F;AAsQD;;;;;;;;;;GAUG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAAE,GACnC,sBAAsB,EAAE,CA8B1B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,sBAAsB,EAAE,GACnC,sBAAsB,GAAG,SAAS,CAYpC;AAidD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAiTjF;AAgCD,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC"}