@pgsage/core 0.1.0

package/dist/embeddings/voyage.js

@@ -0,0 +1,163 @@
+/**
+ * VoyageEmbeddingProvider
+ *
+ * Wraps the Voyage AI REST API (https://api.voyageai.com/v1/embeddings)
+ * using the global fetch available in Node 22+.  No external dependencies.
+ *
+ * Key behaviours:
+ *  - Batches large text arrays into configurable chunks to stay within
+ *    Voyage's per-request token limits.
+ *  - Retries 429 (rate-limit) and 5xx responses with exponential backoff.
+ *  - Maps our EmbeddingInputType to Voyage's input_type param, which causes
+ *    Voyage to prepend retrieval-optimised prompts server-side.
+ *  - Passes output_dimension to enable Matryoshka truncation server-side.
+ */
+// ---------------------------------------------------------------------------
+// Error type
+// ---------------------------------------------------------------------------
+export class VoyageApiError extends Error {
+    status;
+    detail;
+    attempt;
+    constructor(status, detail, attempt) {
+        super(`Voyage API error ${status}: ${detail} (attempt ${attempt})`);
+        this.status = status;
+        this.detail = detail;
+        this.attempt = attempt;
+        this.name = "VoyageApiError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    model: "voyage-4-lite",
+    baseUrl: "https://api.voyageai.com/v1",
+    dimensions: 1024,
+    maxTextsPerBatch: 128,
+    truncation: true,
+    requestTimeoutMs: 30_000,
+    maxRetries: 3,
+};
+export class VoyageEmbeddingProvider {
+    apiKey;
+    model;
+    baseUrl;
+    _dimensions;
+    maxTextsPerBatch;
+    truncation;
+    requestTimeoutMs;
+    maxRetries;
+    constructor(config) {
+        if (!config.apiKey)
+            throw new Error("VoyageEmbeddingProvider: apiKey is required");
+        this.apiKey = config.apiKey;
+        this.model = config.model ?? DEFAULT_CONFIG.model;
+        this.baseUrl = config.baseUrl ?? DEFAULT_CONFIG.baseUrl;
+        this._dimensions = config.dimensions ?? DEFAULT_CONFIG.dimensions;
+        this.maxTextsPerBatch = config.maxTextsPerBatch ?? DEFAULT_CONFIG.maxTextsPerBatch;
+        this.truncation = config.truncation ?? DEFAULT_CONFIG.truncation;
+        this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_CONFIG.requestTimeoutMs;
+        this.maxRetries = config.maxRetries ?? DEFAULT_CONFIG.maxRetries;
+    }
+    get dimensions() {
+        return this._dimensions;
+    }
+    get modelId() {
+        return this.model;
+    }
+    async embed(texts, inputType) {
+        if (texts.length === 0) {
+            return { embeddings: [], totalTokens: 0, model: this.model };
+        }
+        // Split into batches
+        const batches = chunk(texts, this.maxTextsPerBatch);
+        const allEmbeddings = [];
+        let totalTokens = 0;
+        let resolvedModel = this.model;
+        for (const batch of batches) {
+            const result = await this.embedBatch(batch, inputType);
+            allEmbeddings.push(...result.embeddings);
+            totalTokens += result.totalTokens;
+            resolvedModel = result.model;
+        }
+        return { embeddings: allEmbeddings, totalTokens, model: resolvedModel };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    async embedBatch(texts, inputType) {
+        const body = {
+            input: texts,
+            model: this.model,
+            input_type: inputType ?? null,
+            truncation: this.truncation,
+            output_dimension: this._dimensions,
+        };
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            try {
+                const response = await fetch(`${this.baseUrl}/embeddings`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(this.requestTimeoutMs),
+                });
+                if (response.ok) {
+                    const json = (await response.json());
+                    // Sort by index to ensure order matches input (Voyage guarantees
+                    // this, but we sort defensively).
+                    const sorted = [...json.data].sort((a, b) => a.index - b.index);
+                    return {
+                        embeddings: sorted.map((d) => d.embedding),
+                        totalTokens: json.usage.total_tokens,
+                        model: json.model,
+                    };
+                }
+                // Parse the error body
+                const errBody = (await response.json().catch(() => ({
+                    detail: response.statusText,
+                })));
+                lastError = new VoyageApiError(response.status, errBody.detail, attempt);
+                // Only retry on rate-limit or server errors
+                if (!isRetryable(response.status))
+                    throw lastError;
+                // Exponential backoff: 1 s, 2 s, 4 s, …
+                if (attempt < this.maxRetries) {
+                    await sleep(Math.pow(2, attempt - 1) * 1_000);
+                }
+            }
+            catch (err) {
+                if (err instanceof VoyageApiError)
+                    throw err;
+                // Network / timeout errors — wrap and rethrow on final attempt
+                if (attempt === this.maxRetries) {
+                    throw new Error(`Voyage API request failed after ${attempt} attempt(s): ${String(err)}`, { cause: err });
+                }
+                await sleep(Math.pow(2, attempt - 1) * 1_000);
+            }
+        }
+        // Exhausted retries
+        throw lastError ?? new Error("Voyage API: exhausted retries with no error recorded");
+    }
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function chunk(arr, size) {
+    const result = [];
+    for (let i = 0; i < arr.length; i += size) {
+        result.push(arr.slice(i, i + size));
+    }
+    return result;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(status) {
+    return status === 429 || (status >= 500 && status < 600);
+}
+//# sourceMappingURL=voyage.js.map

package/dist/embeddings/voyage.js.map

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

package/dist/estimator/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Estimator
+ *
+ * Wraps `EXPLAIN (FORMAT JSON)` to estimate query cost and row-scan volume
+ * before execution, applying configurable rejection thresholds.
+ *
+ * The estimator is created via a factory function that accepts a pg Pool so
+ * that callers control connection lifecycle. The pool should be a read-write
+ * pool (EXPLAIN does not require write privileges, but the pgsage_readonly
+ * role can run EXPLAIN as well).
+ */
+import type pg from "pg";
+export interface EstimatorConfig {
+    /** pg Pool used to run EXPLAIN queries. */
+    pool: InstanceType<typeof pg.Pool>;
+    /**
+     * Maximum allowed planner cost units before the query is flagged.
+     * PostgreSQL's cost model is unitless but roughly corresponds to sequential
+     * 8 KB page reads. Default: 1_000_000.
+     */
+    costThreshold?: number;
+    /**
+     * Maximum estimated row count before the query is flagged.
+     * Default: 500_000.
+     */
+    rowThreshold?: number;
+}
+export interface CostEstimate {
+    /** Top-level planner "Total Cost" from EXPLAIN (FORMAT JSON). */
+    estimatedCost: number;
+    /** Top-level "Plan Rows" from EXPLAIN (FORMAT JSON). */
+    estimatedRows: number;
+    /** True when estimatedCost > costThreshold OR estimatedRows > rowThreshold. */
+    exceedsThreshold: boolean;
+    /** Human-readable reason when exceedsThreshold is true. */
+    thresholdReason?: string;
+}
+export interface Estimator {
+    estimate(sql: string): Promise<CostEstimate>;
+}
+/**
+ * Create an Estimator that runs `EXPLAIN (FORMAT JSON)` against the provided
+ * pool and compares the result against the configured thresholds.
+ *
+ * @example
+ * ```ts
+ * const estimator = createEstimator({ pool, costThreshold: 100_000 });
+ * const result = await estimator.estimate("SELECT * FROM public.estimates");
+ * if (result.exceedsThreshold) throw new Error(result.thresholdReason);
+ * ```
+ */
+export declare function createEstimator(config: EstimatorConfig): Estimator;
+//# sourceMappingURL=index.d.ts.map

package/dist/estimator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/estimator/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAMzB,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IACnC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC9C;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAkClE"}

package/dist/estimator/index.js

@@ -0,0 +1,57 @@
+/**
+ * Estimator
+ *
+ * Wraps `EXPLAIN (FORMAT JSON)` to estimate query cost and row-scan volume
+ * before execution, applying configurable rejection thresholds.
+ *
+ * The estimator is created via a factory function that accepts a pg Pool so
+ * that callers control connection lifecycle. The pool should be a read-write
+ * pool (EXPLAIN does not require write privileges, but the pgsage_readonly
+ * role can run EXPLAIN as well).
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_COST_THRESHOLD = 1_000_000;
+const DEFAULT_ROW_THRESHOLD = 500_000;
+/**
+ * Create an Estimator that runs `EXPLAIN (FORMAT JSON)` against the provided
+ * pool and compares the result against the configured thresholds.
+ *
+ * @example
+ * ```ts
+ * const estimator = createEstimator({ pool, costThreshold: 100_000 });
+ * const result = await estimator.estimate("SELECT * FROM public.estimates");
+ * if (result.exceedsThreshold) throw new Error(result.thresholdReason);
+ * ```
+ */
+export function createEstimator(config) {
+    const costThreshold = config.costThreshold ?? DEFAULT_COST_THRESHOLD;
+    const rowThreshold = config.rowThreshold ?? DEFAULT_ROW_THRESHOLD;
+    return {
+        async estimate(sql) {
+            const res = await config.pool.query(`EXPLAIN (FORMAT JSON) ${sql}`);
+            const plan = res.rows[0]?.["QUERY PLAN"]?.[0];
+            if (!plan) {
+                throw new Error("EXPLAIN returned no plan rows — the SQL may be invalid.");
+            }
+            const estimatedCost = plan.Plan["Total Cost"];
+            const estimatedRows = plan.Plan["Plan Rows"];
+            const costExceeded = estimatedCost > costThreshold;
+            const rowsExceeded = estimatedRows > rowThreshold;
+            const exceedsThreshold = costExceeded || rowsExceeded;
+            let thresholdReason;
+            if (costExceeded && rowsExceeded) {
+                thresholdReason = `Query exceeds both cost threshold (${estimatedCost.toFixed(2)} > ${costThreshold}) and row threshold (${estimatedRows} > ${rowThreshold}).`;
+            }
+            else if (costExceeded) {
+                thresholdReason = `Query exceeds cost threshold (${estimatedCost.toFixed(2)} > ${costThreshold}).`;
+            }
+            else if (rowsExceeded) {
+                thresholdReason = `Query exceeds row threshold (${estimatedRows} > ${rowThreshold}).`;
+            }
+            return { estimatedCost, estimatedRows, exceedsThreshold, thresholdReason };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/estimator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/estimator/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqDH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,sBAAsB,GAAG,SAAS,CAAC;AACzC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACrE,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAElE,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,GAAW;YACxB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CACjC,yBAAyB,GAAG,EAAE,CAC/B,CAAC;YAEF,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC9C,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;YAC7E,CAAC;YAED,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC9C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAE7C,MAAM,YAAY,GAAG,aAAa,GAAG,aAAa,CAAC;YACnD,MAAM,YAAY,GAAG,aAAa,GAAG,YAAY,CAAC;YAClD,MAAM,gBAAgB,GAAG,YAAY,IAAI,YAAY,CAAC;YAEtD,IAAI,eAAmC,CAAC;YACxC,IAAI,YAAY,IAAI,YAAY,EAAE,CAAC;gBACjC,eAAe,GAAG,sCAAsC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,wBAAwB,aAAa,MAAM,YAAY,IAAI,CAAC;YACjK,CAAC;iBAAM,IAAI,YAAY,EAAE,CAAC;gBACxB,eAAe,GAAG,iCAAiC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,IAAI,CAAC;YACrG,CAAC;iBAAM,IAAI,YAAY,EAAE,CAAC;gBACxB,eAAe,GAAG,gCAAgC,aAAa,MAAM,YAAY,IAAI,CAAC;YACxF,CAAC;YAED,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;QAC7E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/executor/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Executor
+ *
+ * Executes validated, cost-checked SQL against a read-only, pooled, timeout-bound
+ * Postgres connection. The pool provided should use the `pgsage_readonly` role —
+ * that role has no write/DDL grants, acting as a second line of defense behind
+ * the AST validator.
+ *
+ * Automatic row limiting: if the SQL already has a top-level LIMIT clause its
+ * value is left untouched; otherwise a LIMIT is appended. This prevents
+ * runaway result sets that slip past the cost estimator.
+ */
+import type pg from "pg";
+export interface ExecutorConfig {
+    /** pg Pool connected as the read-only role (pgsage_readonly). */
+    pool: InstanceType<typeof pg.Pool>;
+    /**
+     * Maximum number of rows returned. Appended as a LIMIT clause when the
+     * query does not already include one. Default: 500.
+     */
+    rowLimit?: number;
+    /**
+     * Per-query statement timeout in milliseconds, set with SET LOCAL on the
+     * acquired client before executing the query. Default: 30_000 ms.
+     */
+    statementTimeout?: number;
+}
+export interface ExecutionResult {
+    /** The returned rows as plain objects keyed by column name. */
+    rows: Record<string, unknown>[];
+    /** Actual row count returned (after row-limit enforcement). */
+    rowCount: number;
+    /** Column names in result order. */
+    fields: string[];
+    /**
+     * True when the result was capped at rowLimit. The caller should surface
+     * this to the user so they know the result is incomplete.
+     */
+    truncated: boolean;
+}
+export interface Executor {
+    execute(sql: string): Promise<ExecutionResult>;
+}
+/**
+ * Create an Executor that runs SQL on the supplied read-only pool with
+ * automatic statement timeout and row-limit enforcement.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor({ pool: readonlyPool, rowLimit: 200 });
+ * const result = await executor.execute("SELECT * FROM public.estimates");
+ * if (result.truncated) console.warn("Result was truncated to 200 rows");
+ * ```
+ */
+export declare function createExecutor(config: ExecutorConfig): Executor;
+//# sourceMappingURL=index.d.ts.map

package/dist/executor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAMzB,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAChD;AAqCD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAgC/D"}

package/dist/executor/index.js

@@ -0,0 +1,86 @@
+/**
+ * Executor
+ *
+ * Executes validated, cost-checked SQL against a read-only, pooled, timeout-bound
+ * Postgres connection. The pool provided should use the `pgsage_readonly` role —
+ * that role has no write/DDL grants, acting as a second line of defense behind
+ * the AST validator.
+ *
+ * Automatic row limiting: if the SQL already has a top-level LIMIT clause its
+ * value is left untouched; otherwise a LIMIT is appended. This prevents
+ * runaway result sets that slip past the cost estimator.
+ */
+import { parse } from "pgsql-ast-parser";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_ROW_LIMIT = 500;
+const DEFAULT_STATEMENT_TIMEOUT = 30_000;
+/**
+ * Returns true when the top-level SELECT/WITH already has a LIMIT clause so
+ * we don't stack an additional one. Uses the AST parser — if parsing fails
+ * (shouldn't happen after validation) we conservatively assume no LIMIT.
+ */
+function hasTopLevelLimit(sql) {
+    try {
+        const stmts = parse(sql);
+        const stmt = stmts[0];
+        if (!stmt)
+            return false;
+        // select, with, and union shapes all expose a `limit` property at the top
+        // level when they carry one.
+        if ("limit" in stmt && stmt.limit != null)
+            return true;
+        // `with` statements delegate to their `in` clause
+        if (stmt.type === "with" && "limit" in stmt.in && stmt.in.limit != null)
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an Executor that runs SQL on the supplied read-only pool with
+ * automatic statement timeout and row-limit enforcement.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor({ pool: readonlyPool, rowLimit: 200 });
+ * const result = await executor.execute("SELECT * FROM public.estimates");
+ * if (result.truncated) console.warn("Result was truncated to 200 rows");
+ * ```
+ */
+export function createExecutor(config) {
+    const rowLimit = config.rowLimit ?? DEFAULT_ROW_LIMIT;
+    const statementTimeout = config.statementTimeout ?? DEFAULT_STATEMENT_TIMEOUT;
+    return {
+        async execute(sql) {
+            const client = await config.pool.connect();
+            try {
+                // Apply a per-query timeout as an additional guard on top of the pool's
+                // global statement_timeout option.
+                await client.query(`SET LOCAL statement_timeout = ${statementTimeout}`);
+                // Append LIMIT only when the query doesn't already carry one.
+                const limitedSql = hasTopLevelLimit(sql) ? sql : `${sql} LIMIT ${rowLimit}`;
+                const res = await client.query(limitedSql);
+                const rows = res.rows;
+                const fields = res.fields.map((f) => f.name);
+                const truncated = !hasTopLevelLimit(sql) && rows.length >= rowLimit;
+                return {
+                    rows,
+                    rowCount: rows.length,
+                    fields,
+                    truncated,
+                };
+            }
+            finally {
+                client.release();
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/executor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAwCzC,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEzC;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QAExB,0EAA0E;QAC1E,6BAA6B;QAC7B,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEvD,kDAAkD;QAClD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAErF,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACtD,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,yBAAyB,CAAC;IAE9E,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,GAAW;YACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,wEAAwE;gBACxE,mCAAmC;gBACnC,MAAM,MAAM,CAAC,KAAK,CAAC,iCAAiC,gBAAgB,EAAE,CAAC,CAAC;gBAExE,8DAA8D;gBAC9D,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,UAAU,QAAQ,EAAE,CAAC;gBAE5E,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBAE3C,MAAM,IAAI,GAAI,GAAG,CAAC,IAAkC,CAAC;gBACrD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAC7C,MAAM,SAAS,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAC;gBAEpE,OAAO;oBACL,IAAI;oBACJ,QAAQ,EAAE,IAAI,CAAC,MAAM;oBACrB,MAAM;oBACN,SAAS;iBACV,CAAC;YACJ,CAAC;oBAAS,CAAC;gBACT,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/explainer/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Explainer
+ *
+ * Post-execution stage that generates a concise natural-language answer
+ * from the SQL query results. Uses a lightweight LLM call (same Mastra
+ * Agent pattern as the planner) to summarize the data into 1–3 sentences.
+ *
+ * Usage:
+ *   const explainer = createExplainer();
+ *   const answer = await explainer.explain({ question, sql, ... });
+ *   // answer — "Providence County has a median household income of $78,787 (±$1,722)."
+ */
+import { type ExplainerInput } from "./prompt.js";
+export interface ExplainerConfig {
+    /**
+     * Mastra model router string for the explainer LLM call.
+     * @default "anthropic/claude-sonnet-4-6"
+     */
+    model?: string;
+}
+export interface Explainer {
+    /**
+     * Generate a natural-language answer from the query results.
+     *
+     * @param input  The question, SQL, result rows, and metadata.
+     * @returns A concise 1–3 sentence answer string.
+     */
+    explain(input: ExplainerInput): Promise<string>;
+}
+/**
+ * Creates a reusable Explainer that wraps a Mastra Agent.
+ * The Agent is instantiated once and reused across all explain() calls.
+ *
+ * Requires the ANTHROPIC_API_KEY environment variable to be set.
+ */
+export declare function createExplainer(config?: ExplainerConfig): Explainer;
+export { EXPLAINER_SYSTEM_PROMPT, buildExplainerMessage, } from "./prompt.js";
+export type { ExplainerInput } from "./prompt.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/explainer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explainer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD;AA2BD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,SAAS,CAsCvE;AAMD,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/explainer/index.js

@@ -0,0 +1,79 @@
+/**
+ * Explainer
+ *
+ * Post-execution stage that generates a concise natural-language answer
+ * from the SQL query results. Uses a lightweight LLM call (same Mastra
+ * Agent pattern as the planner) to summarize the data into 1–3 sentences.
+ *
+ * Usage:
+ *   const explainer = createExplainer();
+ *   const answer = await explainer.explain({ question, sql, ... });
+ *   // answer — "Providence County has a median household income of $78,787 (±$1,722)."
+ */
+import { Agent } from "@mastra/core/agent";
+import { z } from "zod";
+import { EXPLAINER_SYSTEM_PROMPT, buildExplainerMessage, } from "./prompt.js";
+// ---------------------------------------------------------------------------
+// Zod schema for structured output
+// ---------------------------------------------------------------------------
+const explainerResultSchema = z.object({
+    answer: z
+        .string()
+        .describe("A concise 1–3 sentence natural-language answer to the user's question"),
+});
+// ---------------------------------------------------------------------------
+// Fallback answer (used when rows are empty or the LLM call fails)
+// ---------------------------------------------------------------------------
+function buildFallbackAnswer(input) {
+    if (input.rowCount === 0) {
+        return `No matching data was found for "${input.question}".`;
+    }
+    return `Found ${String(input.rowCount)} result${input.rowCount === 1 ? "" : "s"}.`;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates a reusable Explainer that wraps a Mastra Agent.
+ * The Agent is instantiated once and reused across all explain() calls.
+ *
+ * Requires the ANTHROPIC_API_KEY environment variable to be set.
+ */
+export function createExplainer(config = {}) {
+    const modelId = config.model ?? "anthropic/claude-sonnet-4-6";
+    const agent = new Agent({
+        id: "pgsage-explainer",
+        name: "pgsage-explainer",
+        instructions: EXPLAINER_SYSTEM_PROMPT,
+        model: modelId,
+    });
+    return {
+        async explain(input) {
+            // Short-circuit: no rows → use fallback without an LLM call
+            if (input.rowCount === 0) {
+                return buildFallbackAnswer(input);
+            }
+            try {
+                const userMessage = buildExplainerMessage(input);
+                const result = await agent.generate(userMessage, {
+                    structuredOutput: { schema: explainerResultSchema },
+                });
+                const answer = result.object.answer;
+                // Guard against empty or whitespace-only answers
+                if (!answer || answer.trim().length === 0) {
+                    return buildFallbackAnswer(input);
+                }
+                return answer;
+            }
+            catch {
+                // LLM failure should not break the pipeline — degrade gracefully
+                return buildFallbackAnswer(input);
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Convenience re-exports
+// ---------------------------------------------------------------------------
+export { EXPLAINER_SYSTEM_PROMPT, buildExplainerMessage, } from "./prompt.js";
+//# sourceMappingURL=index.js.map

package/dist/explainer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/explainer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GAEtB,MAAM,aAAa,CAAC;AAwBrB,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,CAAC,uEAAuE,CAAC;CACrF,CAAC,CAAC;AAEH,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E;AAE9E,SAAS,mBAAmB,CAAC,KAAqB;IAChD,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,mCAAmC,KAAK,CAAC,QAAQ,IAAI,CAAC;IAC/D,CAAC;IACD,OAAO,SAAS,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,KAAK,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;AACrF,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAA0B,EAAE;IAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,6BAA6B,CAAC;IAE9D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC;QACtB,EAAE,EAAE,kBAAkB;QACtB,IAAI,EAAE,kBAAkB;QACxB,YAAY,EAAE,uBAAuB;QACrC,KAAK,EAAE,OAAO;KACf,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,KAAqB;YACjC,4DAA4D;YAC5D,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;YACpC,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;gBAEjD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE;oBAC/C,gBAAgB,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE;iBACpD,CAAC,CAAC;gBAEH,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;gBAEpC,iDAAiD;gBACjD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1C,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;gBACpC,CAAC;gBAED,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;gBACjE,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/explainer/prompt.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Explainer prompt utilities
+ *
+ * Contains:
+ *  - EXPLAINER_SYSTEM_PROMPT: instructs the model to produce a concise
+ *    natural-language answer from query results
+ *  - buildExplainerMessage(): formats the question, plan metadata, and
+ *    result rows into a compact user message for the explainer LLM call
+ */
+import type { DisplayHint } from "../planner/index.js";
+export declare const EXPLAINER_SYSTEM_PROMPT = "You are a data analyst summarizing SQL query results in plain English.\n\n## Your task\nGiven the user's original question, the SQL query results (column names + rows),\nand some metadata about the query, produce a concise natural-language answer.\n\n## Rules\n- Answer the question DIRECTLY. Start with the key finding, not \"Based on the data\u2026\" or \"The query returned\u2026\".\n- Reference specific values from the data. Format numbers with proper units:\n  - Currency: $78,787 (with commas, dollar sign)\n  - Percentages: 34.2%\n  - Counts: 1,234,567 (with commas)\n  - Margins of error: \u00B1$1,722 or \u00B12.3%\n- Keep it to 1\u20133 sentences. Be direct and informative.\n- Do NOT repeat the question back.\n- Do NOT list assumptions \u2014 those are displayed separately in the UI.\n- Do NOT say \"the data shows\" or \"according to the results\" \u2014 just state the facts.\n- If the displayHint is \"big\" (single value), state the value and its context clearly.\n- If the displayHint is \"bar\" (ranked list), mention the top entry and give a sense of the range.\n- If the displayHint is \"statrow\" (multiple metrics), briefly cover each metric.\n- If the displayHint is \"grouped\" (comparison), highlight the key comparison.\n- If the displayHint is \"table\" (general), summarize the key pattern or finding.\n- If there are zero rows, say that no matching data was found and briefly suggest why.\n\n## Output format\nRespond with a JSON object:\n{\n  \"answer\": \"<your 1\u20133 sentence answer>\"\n}\nDo not include any text outside the JSON object.";
+export interface ExplainerInput {
+    /** The user's original natural-language question. */
+    question: string;
+    /** The SQL query that was executed. */
+    sql: string;
+    /** Assumptions the planner made (so the explainer avoids repeating them). */
+    assumptions: string[];
+    /** The display hint chosen by the planner. */
+    displayHint: DisplayHint;
+    /** Column names in result order. */
+    fields: string[];
+    /** Result rows (capped to keep token usage low). */
+    rows: Record<string, unknown>[];
+    /** Total row count (may be larger than rows.length if truncated). */
+    rowCount: number;
+    /** Whether the result was truncated. */
+    truncated: boolean;
+}
+/**
+ * Builds the user message for the explainer LLM call.
+ *
+ * Includes the question, display hint, field names, and a compact
+ * representation of the first N rows.
+ */
+export declare function buildExplainerMessage(input: ExplainerInput): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/explainer/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/explainer/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMvD,eAAO,MAAM,uBAAuB,4iDA8Ba,CAAC;AAMlD,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8CAA8C;IAC9C,WAAW,EAAE,WAAW,CAAC;IACzB,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;CACpB;AAQD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAsDnE"}