@duckcodeailabs/dql-agent 1.6.20 → 1.6.22

package/dist/narrate.js

@@ -0,0 +1,263 @@
+/**
+ * Narrate service — turns a *grounded, executed* query result into a stakeholder
+ * story: a summary, key findings, an optional recommendation, and optional
+ * per-item (per-tile) insight captions.
+ *
+ * It is provider-agnostic by design (mirrors `createLlmAgentRunPlanner`): callers
+ * inject a plain text completion (`NarrateCompletion`); any parse/transport
+ * failure — or no injected LLM at all — falls back to a deterministic narration
+ * computed from the rows (totals, leader, concentration, range). That keeps
+ * Research and App storytelling fast, offline, and always-grounded: narration
+ * only ever describes data the loop already executed against governed sources.
+ */
+export async function narrateResult(input, options = {}) {
+    const deterministic = deterministicNarrate(input, options.maxFindings ?? 4);
+    if (!options.complete)
+        return deterministic;
+    try {
+        const raw = await options.complete({
+            system: buildNarrateSystemPrompt(input.reviewRequired ?? false),
+            user: buildNarrateUserPrompt(input),
+            signal: options.signal,
+        });
+        const parsed = parseNarration(raw);
+        if (parsed) {
+            return {
+                summary: parsed.summary ?? deterministic.summary,
+                keyFindings: parsed.keyFindings?.length ? parsed.keyFindings : deterministic.keyFindings,
+                recommendation: parsed.recommendation ?? deterministic.recommendation,
+                // Per-item captions are computed deterministically from each tile's rows
+                // unless the model supplied them; keep deterministic as the floor.
+                perItemInsight: { ...deterministic.perItemInsight, ...(parsed.perItemInsight ?? {}) },
+                source: "llm",
+            };
+        }
+    }
+    catch {
+        // fall through to deterministic
+    }
+    return deterministic;
+}
+// ---------- deterministic narration ----------
+function deterministicNarrate(input, maxFindings) {
+    const result = input.result;
+    const rows = result?.rows ?? [];
+    const perItemInsight = buildPerItemInsight(input.items);
+    if (rows.length === 0) {
+        return {
+            summary: `No rows were returned for "${truncate(input.question, 80)}".`,
+            keyFindings: [],
+            perItemInsight,
+            source: "deterministic",
+        };
+    }
+    const { label, value } = pickColumns(result);
+    const findings = [];
+    if (value) {
+        const ranked = [...rows]
+            .map((row) => ({ label: label ? formatCell(row[label]) : "row", value: toNumber(row[value]) }))
+            .filter((entry) => entry.value !== undefined);
+        ranked.sort((a, b) => b.value - a.value);
+        const total = ranked.reduce((sum, entry) => sum + entry.value, 0);
+        const top = ranked[0];
+        let summary = `${rows.length} ${label ?? "row"}${rows.length === 1 ? "" : "s"} analyzed`;
+        if (top) {
+            summary += `: ${top.label} leads ${value} at ${formatNumber(top.value)}`;
+            if (total > 0)
+                summary += ` (${formatPct(top.value / total)})`;
+            summary += ".";
+            findings.push(`${top.label} is the largest ${label ?? "entry"} at ${formatNumber(top.value)}${total > 0 ? ` (${formatPct(top.value / total)} of ${value})` : ""}.`);
+        }
+        if (total > 0 && ranked.length >= 3) {
+            const topThree = ranked.slice(0, 3).reduce((sum, entry) => sum + entry.value, 0);
+            findings.push(`Top 3 ${label ?? "entries"} are ${formatPct(topThree / total)} of ${value} — concentration to watch.`);
+        }
+        const bottom = ranked[ranked.length - 1];
+        if (bottom && ranked.length >= 4 && bottom.label !== top?.label) {
+            findings.push(`${bottom.label} is the smallest at ${formatNumber(bottom.value)}.`);
+        }
+    }
+    else {
+        findings.push(`${rows.length} rows returned across columns: ${(result?.columns ?? []).slice(0, 6).join(", ")}.`);
+    }
+    return {
+        summary: findings[0] ? findings[0] : `${rows.length} rows returned for "${truncate(input.question, 80)}".`,
+        keyFindings: findings.slice(0, maxFindings),
+        perItemInsight,
+        source: "deterministic",
+    };
+}
+function buildPerItemInsight(items) {
+    if (!items?.length)
+        return undefined;
+    const out = {};
+    for (const item of items) {
+        const rows = item.result?.rows ?? [];
+        if (rows.length === 0)
+            continue;
+        const { label, value } = pickColumns(item.result);
+        if (!value) {
+            out[item.id] = `${rows.length} rows.`;
+            continue;
+        }
+        const ranked = rows
+            .map((row) => ({ label: label ? formatCell(row[label]) : "row", value: toNumber(row[value]) }))
+            .filter((entry) => entry.value !== undefined);
+        ranked.sort((a, b) => b.value - a.value);
+        const total = ranked.reduce((sum, entry) => sum + entry.value, 0);
+        const top = ranked[0];
+        if (!top)
+            continue;
+        out[item.id] = total > 0
+            ? `${top.label} leads at ${formatNumber(top.value)} (${formatPct(top.value / total)}).`
+            : `${top.label} leads at ${formatNumber(top.value)}.`;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function pickColumns(result) {
+    const columns = result.columns ?? [];
+    const sample = result.rows?.[0] ?? {};
+    let value;
+    let label;
+    for (const column of columns) {
+        if (value === undefined && toNumber(sample[column]) !== undefined)
+            value = column;
+    }
+    for (const column of columns) {
+        if (column !== value && typeof sample[column] === "string") {
+            label = column;
+            break;
+        }
+    }
+    if (!label)
+        label = columns.find((column) => column !== value);
+    return { label, value };
+}
+// ---------- LLM path ----------
+function buildNarrateSystemPrompt(reviewRequired) {
+    return [
+        "You explain analytics results to a business stakeholder in plain terms.",
+        "Given a question and the executed result, write a short story: a one-sentence summary, 2-4 key",
+        "findings (numbers + what they mean), and an optional one-line recommendation.",
+        "Only describe what the data shows — never invent numbers or sources.",
+        reviewRequired
+            ? "This result is review-required (uncertified); keep claims cautious and directional."
+            : "This result is from certified, governed data.",
+        "Respond with ONLY a JSON object, no prose, no code fences:",
+        '{"summary": string, "keyFindings": string[], "recommendation"?: string}',
+    ].join("\n");
+}
+function buildNarrateUserPrompt(input) {
+    const lines = [];
+    lines.push(`Question: ${input.question}`);
+    if (input.intent)
+        lines.push(`Intent: ${input.intent}`);
+    if (input.evidence?.length)
+        lines.push(`Governed sources: ${input.evidence.join(", ")}`);
+    if (input.result) {
+        lines.push(`Columns: ${input.result.columns.join(", ")}`);
+        const sample = input.result.rows.slice(0, 20);
+        lines.push(`Rows (up to 20): ${JSON.stringify(sample)}`);
+    }
+    lines.push("Return the narration as JSON.");
+    return lines.join("\n");
+}
+function parseNarration(raw) {
+    const parsed = extractJsonObject(raw);
+    if (!parsed || typeof parsed !== "object")
+        return undefined;
+    const record = parsed;
+    const summary = typeof record.summary === "string" && record.summary.trim() ? record.summary.trim() : undefined;
+    const keyFindings = Array.isArray(record.keyFindings)
+        ? record.keyFindings.filter((value) => typeof value === "string" && value.trim().length > 0)
+        : undefined;
+    if (!summary && !keyFindings?.length)
+        return undefined;
+    const recommendation = typeof record.recommendation === "string" && record.recommendation.trim()
+        ? record.recommendation.trim()
+        : undefined;
+    let perItemInsight;
+    if (record.perItemInsight && typeof record.perItemInsight === "object" && !Array.isArray(record.perItemInsight)) {
+        perItemInsight = {};
+        for (const [key, val] of Object.entries(record.perItemInsight)) {
+            if (typeof val === "string" && val.trim())
+                perItemInsight[key] = val.trim();
+        }
+    }
+    return { summary, keyFindings, recommendation, perItemInsight };
+}
+function extractJsonObject(raw) {
+    const trimmed = raw.trim().replace(/^```(?:json)?/i, "").replace(/```$/i, "").trim();
+    const start = trimmed.indexOf("{");
+    if (start < 0)
+        return undefined;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < trimmed.length; i += 1) {
+        const char = trimmed[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === "{")
+            depth += 1;
+        else if (char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(trimmed.slice(start, i + 1));
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+// ---------- formatting (rounded; no float artifacts on screen) ----------
+function toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "bigint")
+        return Number(value);
+    if (typeof value === "string") {
+        const cleaned = value.replace(/[$,%\s]/g, "");
+        const parsed = Number(cleaned);
+        return Number.isFinite(parsed) && cleaned.length > 0 ? parsed : undefined;
+    }
+    return undefined;
+}
+function formatNumber(value) {
+    const abs = Math.abs(value);
+    if (abs >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(1)}M`;
+    if (abs >= 1_000)
+        return `${(value / 1_000).toFixed(1)}K`;
+    return Number.isInteger(value) ? String(value) : value.toFixed(2);
+}
+function formatPct(ratio) {
+    return `${Math.round(ratio * 100)}%`;
+}
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "—";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "bigint")
+        return String(value);
+    return String(value);
+}
+function truncate(text, max) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+//# sourceMappingURL=narrate.js.map

package/dist/narrate.js.map

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

package/dist/propose/build-from-prompt.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Unified AI BUILD engine (spec 14, part B) — ONE engine, two targets.
+ *
+ * `buildFromPrompt` turns a natural-language prompt into either:
+ *   - target:'cell'  → a SQL snippet for an ad-hoc notebook cell (writes nothing).
+ *   - target:'block' → a COMPLETE governance DRAFT written to disk via
+ *                       `upsertProposedDraft`, with its Certifier verdict stored.
+ *
+ * It deliberately does NOT route through the governed Q&A answer-loop
+ * (`answer()` / `ask_dql`). Building is a different intent: it must not leak the
+ * answer-loop's self-correction reasoning, evidence tiers, or reviewStatus. We
+ * reuse the lighter plumbing instead:
+ *   - `pickProvider` / `provider.generate` for AI content (optional),
+ *   - `loadDbtArtifacts` for offline schema grounding,
+ *   - `deriveSemanticDraftName` for a semantic block name,
+ *   - `resolveLocalOwner` so a draft is never born without an owner,
+ *   - `upsertProposedDraft` + `Certifier` for the draft + stored verdict.
+ *
+ * Principles enforced here:
+ *   - AI drafts, humans certify: a block is ALWAYS `status: "draft"`; this engine
+ *     never writes `certified`.
+ *   - Structure deterministic, content AI-optional: with no provider, the cell
+ *     target returns a deterministic templated SELECT (or a helpful message in
+ *     `explanation`) and the block target falls back to deterministic content.
+ *     It never crashes on the offline path.
+ */
+import { type ExecutionProbe, type BlockReflection } from './reflect-block.js';
+import type { KGNode } from '../kg/types.js';
+import type { Skill } from '../skills/loader.js';
+import type { AgentProvider } from '../providers/types.js';
+import { blockSlug } from './write-draft.js';
+export interface BuildFromPromptContext {
+    /** Current SQL in the focused cell (for refine/extend prompts). */
+    cellSql?: string;
+    /** A selected fragment the user highlighted. */
+    selection?: string;
+}
+/** Build mode (spec 17, part A). `edit` updates an existing block in place. */
+export type BuildMode = 'create' | 'edit';
+/** The chosen route surfaced on the build response (spec 17, part C). */
+export interface BuildRoute {
+    tier: 'certified_block' | 'semantic_metric' | 'generated_sql' | 'business_context' | 'no_answer';
+    label: string;
+    ref?: string;
+}
+export interface BuildFromPromptOptions {
+    projectRoot: string;
+    prompt: string;
+    context?: BuildFromPromptContext;
+    target: 'cell' | 'block';
+    /**
+     * Build mode (spec 17, part A). `'create'` (default) writes a NEW deduped
+     * draft. `'edit'` loads the existing block at `blockPath`, applies the user's
+     * change, and writes back to the SAME path. Edit mode is only meaningful for
+     * `target: 'block'`.
+     */
+    mode?: BuildMode;
+    /**
+     * Project-relative (or absolute) path of the block to edit. REQUIRED in edit
+     * mode. The updated block is written back to exactly this path.
+     */
+    blockPath?: string;
+    /** Explicit owner; when absent the local OSS owner is resolved + stamped. */
+    owner?: string;
+    /**
+     * Provider override (mainly for tests). When omitted the engine picks the
+     * first available provider; when none is available it degrades offline.
+     */
+    provider?: AgentProvider;
+    /**
+     * Force the offline/deterministic path even if a provider is configured.
+     * Used by tests for determinism (mirrors `aiEnrichment: 'off'`).
+     */
+    offline?: boolean;
+    /** Optional explicit dbt manifest path (else auto-discovered under the project). */
+    dbtManifestPath?: string;
+    /** Domain for a built block draft. Defaults to `misc`. */
+    domain?: string;
+    /** Active user, for personal-skill selection. */
+    userId?: string;
+    /**
+     * Project + user Skills to inject as business context. When omitted the
+     * engine loads them from `.dql/skills/` itself.
+     */
+    skills?: Skill[];
+    /**
+     * Optional executor for a bounded preview of generated SQL. When supplied,
+     * an execution error triggers the same repair loop a validation miss does.
+     */
+    executeSql?: (sql: string) => Promise<unknown>;
+    /**
+     * Optional execution probe for the reflect-before-certify loop (P2). When
+     * supplied, the agent runs the block's SQL to learn its REAL output columns and
+     * evaluates the declared invariants, so the reflection can reconcile the output
+     * contract and produce a grounded tests verdict before a human reviews it.
+     */
+    executionProbe?: (input: {
+        sql: string;
+        invariants: string[];
+    }) => Promise<ExecutionProbe>;
+}
+/** The Skills that shaped this build (stamped on both targets). */
+export interface AppliedSkill {
+    id: string;
+    description?: string;
+}
+export interface BuildCellResult {
+    target: 'cell';
+    sql: string;
+    explanation?: string;
+    /** Skills that shaped the answer, for UI transparency. */
+    appliedSkills?: AppliedSkill[];
+}
+export interface BuildBlockResult {
+    target: 'block';
+    path: string;
+    name: string;
+    sqlPreview: string;
+    description: string;
+    grain?: string;
+    outputs: string[];
+    examples: string[];
+    certifierVerdict: CertifierVerdict;
+    /** Skills that shaped the answer, for UI transparency. */
+    appliedSkills?: AppliedSkill[];
+    /**
+     * Edit mode only (spec 17, part A): the block's SQL BEFORE the change, so the
+     * UI can render a diff. Absent on a freshly created draft.
+     */
+    previousSql?: string;
+    /** The chosen route for this build (spec 17, part C). */
+    route?: BuildRoute;
+    /** True when this result updated an existing block in place (edit mode). */
+    edited?: boolean;
+    /**
+     * Reflect-before-certify report (P2): what the agent self-checked, what it
+     * auto-fixed (output contract, governance gaps), and what remains for the human.
+     */
+    reflection?: BlockReflection;
+}
+export type BuildFromPromptResult = BuildCellResult | BuildBlockResult;
+export interface CertifierVerdict {
+    blocking: string[];
+    warnings: string[];
+    ready: boolean;
+}
+/** Load metric KG nodes (read-only, best-effort) so the Build path can reuse the
+ * same governed-metric matching the Ask path uses. Returns [] when no KG exists. */
+export declare function loadSemanticMetrics(projectRoot: string): KGNode[];
+/**
+ * Build from a natural-language prompt. ONE engine, two targets:
+ *   - 'cell'  → returns SQL (writes nothing).
+ *   - 'block' → writes a complete DRAFT and returns its path + preview fields.
+ *
+ * `mode: 'edit'` (block target only) updates the existing block at `blockPath`
+ * in place instead of forking a new draft (spec 17, part A).
+ */
+export declare function buildFromPrompt(options: BuildFromPromptOptions): Promise<BuildFromPromptResult>;
+export { blockSlug };
+//# sourceMappingURL=build-from-prompt.d.ts.map

package/dist/propose/build-from-prompt.d.ts.map

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