@duckcodeailabs/dql-agent 1.4.0

package/LICENSE

@@ -0,0 +1,123 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+express or implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+PURPOSE.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law, shall any Contributor
+be liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a result of this
+License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License.
+
+END OF TERMS AND CONDITIONS

package/dist/answer-loop.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Block-first answer loop.
+ *
+ * Stages:
+ *  1) FTS5 search the KG for blocks matching the question. If a strong
+ *     `block` hit exists, return it as a Certified answer (use the block's
+ *     SQL through `query_via_block`-equivalent semantics — caller runs it).
+ *  2) Otherwise, gather context (matching metrics, dimensions, dbt models,
+ *     dashboards, Skills) and ask the LLM to propose SQL. Mark the answer
+ *     Uncertified.
+ *  3) Always cite block ids/git SHAs.
+ *
+ * The loop is *deterministic* — provider invocation is the only stochastic
+ * step. Tests can mock the provider with a canned response and exercise the
+ * full pipeline.
+ */
+import type { KGStore } from './kg/sqlite-fts.js';
+import type { KGNode, KGSearchHit } from './kg/types.js';
+import type { AgentProvider } from './providers/types.js';
+import type { Skill } from './skills/loader.js';
+export type AnswerKind = 'certified' | 'uncertified' | 'no_answer';
+export interface AgentCitation {
+    nodeId: string;
+    kind: KGNode['kind'];
+    name: string;
+    /** Frozen-in-time SHA at the moment of indexing. */
+    gitSha?: string;
+}
+export interface AgentAnswer {
+    kind: AnswerKind;
+    /** Final answer text (NL summary). */
+    text: string;
+    /** Certified path: the matched block — caller runs its SQL. */
+    block?: KGNode;
+    /** Uncertified path: the LLM-proposed SQL the analyst should review. */
+    proposedSql?: string;
+    /** Suggested viz type for the proposed SQL (line/bar/single_value/...). */
+    suggestedViz?: string;
+    citations: AgentCitation[];
+    /** Provider name used (for telemetry / UI badge). */
+    providerUsed?: string;
+    /** Top KG hits the loop considered, useful for the UI's "we considered" panel. */
+    considered: KGSearchHit[];
+}
+export interface AnswerLoopInput {
+    question: string;
+    /** Active user — used for Skills filtering and the "asked by" record. */
+    userId?: string;
+    /** Domain to scope the search. Optional. */
+    domain?: string;
+    /** Caller-supplied provider; the answer-loop never picks one itself. */
+    provider: AgentProvider;
+    /** Live KG store. */
+    kg: KGStore;
+    /** Project + user-level Skills. */
+    skills?: Skill[];
+    /** Hints to prefer specific blocks first (vocabulary mappings from Skills). */
+    blockHints?: string[];
+    /** Optional AbortSignal forwarded to the provider. */
+    signal?: AbortSignal;
+}
+export declare function answer(input: AnswerLoopInput): Promise<AgentAnswer>;
+interface ParsedProposal {
+    text: string;
+    sql?: string;
+    viz?: string;
+}
+/**
+ * Public for tests. Pulls the first ```sql block and an optional Viz: line
+ * out of an LLM response.
+ */
+export declare function parseProposal(raw: string): ParsedProposal;
+export {};
+//# sourceMappingURL=answer-loop.d.ts.map

package/dist/answer-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-loop.d.ts","sourceRoot":"","sources":["../src/answer-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGhD,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,EAAE,aAAa,CAAC;IACxB,qBAAqB;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sDAAsD;IACtD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAKD,wBAAsB,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAqFzE;AA4BD,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAWzD"}

package/dist/answer-loop.js

@@ -0,0 +1,170 @@
+/**
+ * Block-first answer loop.
+ *
+ * Stages:
+ *  1) FTS5 search the KG for blocks matching the question. If a strong
+ *     `block` hit exists, return it as a Certified answer (use the block's
+ *     SQL through `query_via_block`-equivalent semantics — caller runs it).
+ *  2) Otherwise, gather context (matching metrics, dimensions, dbt models,
+ *     dashboards, Skills) and ask the LLM to propose SQL. Mark the answer
+ *     Uncertified.
+ *  3) Always cite block ids/git SHAs.
+ *
+ * The loop is *deterministic* — provider invocation is the only stochastic
+ * step. Tests can mock the provider with a canned response and exercise the
+ * full pipeline.
+ */
+import { buildSkillsPrompt } from './skills/loader.js';
+const CERTIFIED_HIT_THRESHOLD = 0.18;
+const HARD_NEGATIVE_RATIO = 0.5;
+export async function answer(input) {
+    const { question, userId, domain, provider, kg, skills = [], blockHints = [] } = input;
+    const considered = kg.search({
+        query: question,
+        domain,
+        limit: 10,
+    });
+    // Stage 1: certified-block match
+    const blockHits = considered.filter((h) => h.node.kind === 'block');
+    const blockHit = pickCertifiedBlock(blockHits, blockHints, kg);
+    if (blockHit) {
+        return {
+            kind: 'certified',
+            text: composeCertifiedAnswer(blockHit.node, question),
+            block: blockHit.node,
+            citations: [
+                {
+                    nodeId: blockHit.node.nodeId,
+                    kind: blockHit.node.kind,
+                    name: blockHit.node.name,
+                    gitSha: blockHit.node.gitSha,
+                },
+            ],
+            considered,
+            providerUsed: provider.name,
+        };
+    }
+    // Stage 2: uncertified — gather context, ask the LLM
+    const contextNodes = considered.slice(0, 6).map((h) => h.node);
+    const contextBlocks = contextNodes.filter((n) => n.kind === 'block');
+    const contextOther = contextNodes.filter((n) => n.kind !== 'block');
+    const messages = [
+        { role: 'system', content: SYSTEM_PROMPT },
+    ];
+    const skillsPrompt = buildSkillsPrompt(skills, userId ?? null);
+    if (skillsPrompt)
+        messages.push({ role: 'system', content: skillsPrompt });
+    messages.push({
+        role: 'system',
+        content: renderContextPrompt(contextBlocks, contextOther),
+    });
+    messages.push({ role: 'user', content: question });
+    let proposed = '';
+    try {
+        proposed = await provider.generate(messages, { signal: input.signal });
+    }
+    catch (err) {
+        return {
+            kind: 'no_answer',
+            text: `Provider error: ${err.message}`,
+            citations: [],
+            considered,
+            providerUsed: provider.name,
+        };
+    }
+    const parsed = parseProposal(proposed);
+    if (!parsed.sql) {
+        return {
+            kind: 'no_answer',
+            text: parsed.text || 'No answer (the model declined to propose SQL).',
+            citations: [],
+            considered,
+            providerUsed: provider.name,
+        };
+    }
+    return {
+        kind: 'uncertified',
+        text: parsed.text,
+        proposedSql: parsed.sql,
+        suggestedViz: parsed.viz ?? 'table',
+        citations: contextNodes.slice(0, 4).map((n) => ({
+            nodeId: n.nodeId,
+            kind: n.kind,
+            name: n.name,
+            gitSha: n.gitSha,
+        })),
+        considered,
+        providerUsed: provider.name,
+    };
+}
+const SYSTEM_PROMPT = `You are the DQL Analytics Agent.
+
+Rules:
+1. ALWAYS prefer existing certified DQL blocks. The analytics surface marks every
+   answer as Certified or AI-generated/Uncertified.
+2. If you must generate SQL, return it inside a single \`\`\`sql code block.
+3. Provide a one-paragraph natural-language summary BEFORE the SQL block.
+4. Suggest a visualization type from this list, on a line starting with "Viz:":
+   line, bar, area, pie, single_value, table, pivot, kpi.
+5. NEVER fabricate column names that are not present in the supplied schema context.
+6. If the schema is insufficient to answer, say so explicitly and ask a clarifying question.`;
+function renderContextPrompt(blocks, others) {
+    const blockSection = blocks.length > 0
+        ? `## Certified blocks the user already has\n\n${blocks
+            .map((b) => `- \`${b.nodeId}\` (${b.domain ?? 'unscoped'}): ${b.description ?? b.llmContext ?? '(no description)'}`)
+            .join('\n')}`
+        : '## Certified blocks: (none matched)';
+    const otherSection = others.length > 0
+        ? `\n\n## Related semantic + warehouse context\n\n${others
+            .map((n) => `- ${n.kind} \`${n.name}\`${n.domain ? ` (domain: ${n.domain})` : ''}${n.description ? ` — ${n.description}` : ''}`)
+            .join('\n')}`
+        : '';
+    return `${blockSection}${otherSection}`;
+}
+/**
+ * Public for tests. Pulls the first ```sql block and an optional Viz: line
+ * out of an LLM response.
+ */
+export function parseProposal(raw) {
+    const sqlMatch = raw.match(/```sql\s*([\s\S]*?)```/i);
+    const sql = sqlMatch ? sqlMatch[1].trim() : undefined;
+    const vizMatch = raw.match(/^Viz:\s*([a-z_]+)/im);
+    const viz = vizMatch ? vizMatch[1].trim().toLowerCase() : undefined;
+    // Strip the SQL block + Viz line from the prose to keep the summary clean.
+    const text = raw
+        .replace(/```sql[\s\S]*?```/gi, '')
+        .replace(/^Viz:.*$/gim, '')
+        .trim();
+    return { text, sql, viz };
+}
+function pickCertifiedBlock(blockHits, blockHints, kg) {
+    // Hint match wins immediately: the active Skill's vocabulary points the
+    // user at a specific block. We still validate it's certified.
+    for (const hint of blockHints) {
+        const node = kg.getNode(`block:${hint}`);
+        if (node && node.status === 'certified') {
+            return { node, score: 1, snippet: undefined };
+        }
+    }
+    // Otherwise: top FTS5 hit must be certified, exceed the score threshold,
+    // and not have a hard negative ratio in feedback.
+    for (const hit of blockHits) {
+        if (hit.score < CERTIFIED_HIT_THRESHOLD)
+            break;
+        if (hit.node.status !== 'certified')
+            continue;
+        const fb = kg.blockFeedbackScore(hit.node.nodeId);
+        const total = fb.up + fb.down;
+        if (total > 0 && fb.down / total > HARD_NEGATIVE_RATIO)
+            continue;
+        return hit;
+    }
+    return null;
+}
+function composeCertifiedAnswer(block, question) {
+    const desc = block.description ?? block.llmContext ?? '';
+    const tag = block.gitSha ? ` · ${block.gitSha.slice(0, 8)}` : '';
+    return `Answered by certified block **${block.name}**${tag}.\n\n${desc || 'Run the block to see the result.'}`
+        + `\n\n_Question:_ ${question}`;
+}
+//# sourceMappingURL=answer-loop.js.map

package/dist/answer-loop.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Public surface for `@duckcodeailabs/dql-agent`.
+ *
+ * Consumers (CLI, MCP server, notebook UI) typically import:
+ *   - `reindexProject(root)` to rebuild the KG
+ *   - `KGStore` for direct queries
+ *   - `answer({ ... })` for the block-first answer loop
+ *   - the providers (Claude/OpenAI/Gemini/Ollama)
+ */
+import type { DQLManifest } from '@duckcodeailabs/dql-core';
+export { KGStore } from './kg/sqlite-fts.js';
+export type { KGNode, KGEdge, KGNodeKind, KGSearchHit, KGFeedbackRow, KGSearchOptions } from './kg/types.js';
+export { buildKGFromManifest } from './kg/build.js';
+export { loadSkills, parseSkill, buildSkillsPrompt } from './skills/loader.js';
+export type { Skill, SkillLoadResult } from './skills/loader.js';
+export { answer, parseProposal } from './answer-loop.js';
+export type { AgentAnswer, AgentCitation, AnswerKind, AnswerLoopInput } from './answer-loop.js';
+export { ClaudeProvider, OpenAIProvider, GeminiProvider, OllamaProvider, pickProvider, buildProvider, } from './providers/index.js';
+export type { AgentProvider, AgentMessage, ProviderName, ProviderRunOptions } from './providers/index.js';
+/**
+ * Default location for the agent's SQLite KG file.
+ * Mirrors the manifest cache layout under `.dql/cache/`.
+ */
+export declare function defaultKgPath(projectRoot: string): string;
+export interface ReindexOptions {
+    manifest?: DQLManifest;
+    /** Path to the KG sqlite file. Defaults to `.dql/cache/agent-kg.sqlite`. */
+    kgPath?: string;
+    /** Set to false to skip re-loading Skills. */
+    loadSkills?: boolean;
+}
+/**
+ * Rebuild the KG from the project's manifest. Safe to call on every save —
+ * incremental indexing can land later; the wholesale rebuild is fast on the
+ * scale dql projects realistically reach (thousands of nodes).
+ */
+export declare function reindexProject(projectRoot: string, opts?: ReindexOptions): Promise<{
+    nodes: number;
+    edges: number;
+    skills: number;
+}>;
+/**
+ * Promotion suggester — surface uncertified answers that have accumulated
+ * positive feedback so an analyst can certify them as proper blocks.
+ */
+export declare function getPromotionCandidates(projectRoot: string, minUps?: number): Array<{
+    blockId: string;
+    question: string;
+    ups: number;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAO5D,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7G,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAChG,OAAO,EACL,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAC9D,YAAY,EAAE,aAAa,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1G;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B3D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,KAAK,CAAC;IAC7E,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;CAChD,CAAC,CAOD"}

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * Public surface for `@duckcodeailabs/dql-agent`.
+ *
+ * Consumers (CLI, MCP server, notebook UI) typically import:
+ *   - `reindexProject(root)` to rebuild the KG
+ *   - `KGStore` for direct queries
+ *   - `answer({ ... })` for the block-first answer loop
+ *   - the providers (Claude/OpenAI/Gemini/Ollama)
+ */
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { buildManifest } from '@duckcodeailabs/dql-core';
+import { KGStore } from './kg/sqlite-fts.js';
+import { buildKGFromManifest } from './kg/build.js';
+import { loadSkills } from './skills/loader.js';
+export { KGStore } from './kg/sqlite-fts.js';
+export { buildKGFromManifest } from './kg/build.js';
+export { loadSkills, parseSkill, buildSkillsPrompt } from './skills/loader.js';
+export { answer, parseProposal } from './answer-loop.js';
+export { ClaudeProvider, OpenAIProvider, GeminiProvider, OllamaProvider, pickProvider, buildProvider, } from './providers/index.js';
+/**
+ * Default location for the agent's SQLite KG file.
+ * Mirrors the manifest cache layout under `.dql/cache/`.
+ */
+export function defaultKgPath(projectRoot) {
+    return join(projectRoot, '.dql', 'cache', 'agent-kg.sqlite');
+}
+/**
+ * Rebuild the KG from the project's manifest. Safe to call on every save —
+ * incremental indexing can land later; the wholesale rebuild is fast on the
+ * scale dql projects realistically reach (thousands of nodes).
+ */
+export async function reindexProject(projectRoot, opts = {}) {
+    const manifest = opts.manifest ?? loadManifest(projectRoot);
+    const { nodes, edges } = buildKGFromManifest(manifest);
+    // Skills become KG nodes too so the agent can retrieve them.
+    let skills = [];
+    if (opts.loadSkills !== false) {
+        const result = loadSkills(projectRoot);
+        skills = result.skills;
+        for (const s of skills) {
+            nodes.push({
+                nodeId: `skill:${s.id}`,
+                kind: 'skill',
+                name: s.id,
+                description: s.description,
+                llmContext: s.body,
+                sourcePath: s.sourcePath,
+            });
+        }
+    }
+    const kg = new KGStore(opts.kgPath ?? defaultKgPath(projectRoot));
+    try {
+        kg.rebuild(nodes, edges);
+    }
+    finally {
+        kg.close();
+    }
+    return { nodes: nodes.length, edges: edges.length, skills: skills.length };
+}
+/**
+ * Promotion suggester — surface uncertified answers that have accumulated
+ * positive feedback so an analyst can certify them as proper blocks.
+ */
+export function getPromotionCandidates(projectRoot, minUps = 5) {
+    const kg = new KGStore(defaultKgPath(projectRoot));
+    try {
+        return kg.promotionCandidates(minUps);
+    }
+    finally {
+        kg.close();
+    }
+}
+function loadManifest(projectRoot) {
+    // Prefer the on-disk compiled manifest, fall back to a fresh build.
+    const compiled = join(projectRoot, 'dql-manifest.json');
+    if (existsSync(compiled)) {
+        try {
+            return JSON.parse(readFileSync(compiled, 'utf-8'));
+        }
+        catch {
+            // fall through
+        }
+    }
+    return buildManifest({ projectRoot });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/kg/build.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Build the KG node + edge arrays from a compiled DQL manifest.
+ *
+ * Inputs:
+ *   - dql-manifest.json (blocks, dashboards, apps, metrics, dimensions, sources)
+ *   - dbt manifest (already merged into the DQL manifest's dbtImport.dbtDag)
+ *   - project Skills folder (loaded separately by the Skills loader)
+ *
+ * The output is intentionally flat — caller passes it to `KGStore.rebuild()`.
+ */
+import type { DQLManifest } from '@duckcodeailabs/dql-core';
+import type { KGNode, KGEdge } from './types.js';
+export declare function buildKGFromManifest(manifest: DQLManifest): {
+    nodes: KGNode[];
+    edges: KGEdge[];
+};
+//# sourceMappingURL=build.d.ts.map

package/dist/kg/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/kg/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAc,MAAM,YAAY,CAAC;AAE7D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAkHA"}