@pgsage/core 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# @pgsage/core
+
+The pgsage SDK. All pipeline stages from schema retrieval to natural-language explanation, plus the `createAgent()` entrypoint that wires them together.
+
+---
+
+## Installation
+
+```sh
+pnpm add @pgsage/core
+```
+
+Requires `ANTHROPIC_API_KEY` and `VOYAGE_API_KEY` in the environment.
+
+---
+
+## Quick Example
+
+```ts
+import {
+  createAgent,
+  createPool,
+  createReadonlyPool,
+  VoyageEmbeddingProvider,
+} from "@pgsage/core";
+
+const agent = createAgent({
+  pool: createPool(process.env.DATABASE_URL!),
+  readonlyPool: createReadonlyPool(process.env.DATABASE_READONLY_URL!),
+  embedder: new VoyageEmbeddingProvider({ apiKey: process.env.VOYAGE_API_KEY! }),
+});
+
+const response = await agent.query("Top 5 counties by median household income", {
+  onProgress: (step, label) => console.log(`[${step}] ${label}`),
+});
+
+console.log(response.answer);      // "The highest median household income is..."
+console.log(response.sql);         // the generated SELECT query
+console.log(response.rows);        // result rows
+console.log(response.displayHint); // suggested visualization layout
+console.log(response.assumptions); // interpretive assumptions
+```
+
+---
+
+## Pipeline Stages
+
+| Module | Exported via | Description |
+|--------|-------------|-------------|
+| `retriever` | `@pgsage/core` | pgvector similarity search over schema embeddings |
+| `planner` | `@pgsage/core` | Claude LLM → SQL + assumptions + `displayHint` |
+| `validator` | `@pgsage/core` | AST safety check — rejects writes, DDL, multi-statement |
+| `estimator` | `@pgsage/core` | `EXPLAIN FORMAT JSON` cost check before execution |
+| `executor` | `@pgsage/core` | Read-only pool execution with row limit and statement timeout |
+| `corrector` | `@pgsage/core` | Retry loop — re-plans with error context on failure |
+| `explainer` | `@pgsage/core` | Claude LLM → concise natural-language answer from result rows |
+| `orchestrator` | `@pgsage/core` | `createAgent()` — wires all stages into a single `query()` call |
+
+Each module is also accessible as a namespace export:
+
+```ts
+import { validator, estimator, executor } from "@pgsage/core";
+
+const { valid, reason } = validator.validate(sql);
+const { exceedsThreshold, planCost } = await estimator.createEstimator({ pool }).estimate(sql);
+const { rows, fields, truncated } = await executor.createExecutor({ pool }).execute(sql);
+```
+
+---
+
+## Configuration
+
+`createAgent(config: OrchestratorConfig)` accepts:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `pool` | `pg.Pool` | required | Read-write pool (retrieval, EXPLAIN) |
+| `readonlyPool` | `pg.Pool` | required | Read-only pool (query execution) |
+| `embedder` | `EmbeddingProvider` | required | Embedding provider for pgvector search |
+| `model` | `string` | `"anthropic/claude-sonnet-4-6"` | Mastra model string for the planner |
+| `explainerModel` | `string` | same as `model` | Model for the explainer stage |
+| `topK` | `number` | `10` | Schema chunks to retrieve |
+| `costThreshold` | `number` | `1_000_000` | Max EXPLAIN cost before rejection |
+| `rowThreshold` | `number` | `500_000` | Max EXPLAIN rows before rejection |
+| `rowLimit` | `number` | `500` | Max rows returned by the executor |
+| `statementTimeout` | `number` | `30_000` | Statement timeout in ms |
+| `maxRetries` | `number` | `3` | Max self-correction retries |
+
+---
+
+## Key Types
+
+```ts
+// The response from agent.query()
+interface QueryResponse {
+  answer: string;                          // LLM-generated natural-language answer
+  sql: string;                             // The executed SELECT query
+  assumptions: string[];                   // Planner's interpretive assumptions
+  displayHint: DisplayHint;               // "big" | "statrow" | "bar" | "grouped" | "table"
+  rows: Record<string, unknown>[];         // Result rows
+  rowCount: number;
+  fields: string[];                        // Column names
+  truncated: boolean;                      // True if rowLimit was hit
+  attempts: { sql: string; error: string }[]; // Self-correction history
+}
+
+// Per-request options for query()
+interface QueryOptions {
+  onProgress?: (step: number, label: string) => void;
+  // Steps: 0=Searching schema, 1=Generating SQL, 2=Validating & executing,
+  //        3=Correcting query (retry only), 4=Summarizing results
+}
+
+// Suggested visualization layout
+type DisplayHint = "big" | "statrow" | "bar" | "grouped" | "table";
+```
+
+---
+
+## Testing
+
+```sh
+pnpm --filter @pgsage/core test
+```
+
+204 unit tests, 11 integration tests (require Docker + API keys, skipped by default).

package/dist/corrector/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Corrector
+ *
+ * Error-driven re-planning loop: on execution error or a suspicious zero-row
+ * result, re-invokes the planner with the failure context appended to the
+ * prompt (via PlanOptions.errorContext), capped at maxRetries attempts.
+ *
+ * Zero-row heuristic: zero rows from a broad aggregation (no WHERE clause
+ * with specific values) is flagged as a likely query bug and triggers a retry.
+ * Zero rows from a query with specific WHERE filters is treated as a
+ * legitimately empty result and returned as-is.
+ */
+import type { Planner, PlanResult, PriorAttempt } from "../planner/index.js";
+import type { RetrievedSchemaChunk } from "../retriever/index.js";
+import type { ExecutionResult } from "../executor/index.js";
+export interface CorrectorConfig {
+    /** The planner instance used to generate correction attempts. */
+    planner: Planner;
+    /**
+     * Maximum number of re-plan attempts before giving up.
+     * Default: 3.
+     */
+    maxRetries?: number;
+}
+export interface CorrectionResult {
+    /** The final PlanResult (may be the original if no correction was needed). */
+    plan: PlanResult;
+    /**
+     * All prior attempts including failures, in order. Empty when the first
+     * plan succeeded.
+     */
+    attempts: PriorAttempt[];
+    /** True when the corrector gave up after maxRetries without a clean result. */
+    exhausted: boolean;
+}
+export interface Corrector {
+    /**
+     * Given a question, schema context, and an initial plan result, run the
+     * plan through validation/execution and re-plan on failure up to maxRetries.
+     *
+     * The `execute` callback encapsulates the validate → estimate → execute
+     * pipeline. It should throw on SQL errors (rejected promise) or resolve
+     * to an ExecutionResult. The corrector decides whether a zero-row result
+     * warrants a retry based on the zero-row heuristic.
+     */
+    correct(question: string, context: RetrievedSchemaChunk[], initialPlan: PlanResult, execute: (sql: string) => Promise<ExecutionResult>): Promise<CorrectionResult>;
+}
+/**
+ * Returns true when a zero-row result is likely a query bug rather than a
+ * legitimately empty result.
+ *
+ * Heuristic: if the top-level query has no WHERE clause (or the WHERE clause
+ * contains no literal value comparisons), a zero-row result from what should
+ * be an aggregation or full-table query is suspicious. If there are specific
+ * literal filters (WHERE county_name = 'Providence County'), the empty result
+ * is more likely legitimate.
+ *
+ * Conservatively returns false (don't retry) when parsing fails.
+ */
+export declare function isLikelyZeroRowBug(sql: string): boolean;
+/**
+ * Create a Corrector that wraps a Planner in a retry loop.
+ *
+ * @example
+ * ```ts
+ * const corrector = createCorrector({ planner, maxRetries: 3 });
+ * const result = await corrector.correct(question, context, initialPlan, executeFn);
+ * if (result.exhausted) throw new Error("Could not produce a valid query.");
+ * ```
+ */
+export declare function createCorrector(config: CorrectorConfig): Corrector;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/corrector/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAO5D,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,IAAI,EAAE,UAAU,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB;;;;;;;;OAQG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAAE,EAC/B,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,GACjD,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAyBvD;AAQD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA0DlE"}

package/dist/corrector/index.js

@@ -0,0 +1,113 @@
+/**
+ * Corrector
+ *
+ * Error-driven re-planning loop: on execution error or a suspicious zero-row
+ * result, re-invokes the planner with the failure context appended to the
+ * prompt (via PlanOptions.errorContext), capped at maxRetries attempts.
+ *
+ * Zero-row heuristic: zero rows from a broad aggregation (no WHERE clause
+ * with specific values) is flagged as a likely query bug and triggers a retry.
+ * Zero rows from a query with specific WHERE filters is treated as a
+ * legitimately empty result and returned as-is.
+ */
+import { parse } from "pgsql-ast-parser";
+// ---------------------------------------------------------------------------
+// Zero-row heuristic
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when a zero-row result is likely a query bug rather than a
+ * legitimately empty result.
+ *
+ * Heuristic: if the top-level query has no WHERE clause (or the WHERE clause
+ * contains no literal value comparisons), a zero-row result from what should
+ * be an aggregation or full-table query is suspicious. If there are specific
+ * literal filters (WHERE county_name = 'Providence County'), the empty result
+ * is more likely legitimate.
+ *
+ * Conservatively returns false (don't retry) when parsing fails.
+ */
+export function isLikelyZeroRowBug(sql) {
+    try {
+        const stmts = parse(sql);
+        const stmt = stmts[0];
+        if (!stmt)
+            return false;
+        // Unwrap WITH statements to their inner SELECT
+        const selectStmt = stmt.type === "with"
+            ? stmt.in
+            : stmt.type === "select"
+                ? stmt
+                : null;
+        if (!selectStmt || selectStmt.type !== "select")
+            return false;
+        // If there's no WHERE clause at all, a zero-row result is suspicious
+        if (!("where" in selectStmt) || selectStmt.where == null)
+            return true;
+        // If there IS a WHERE clause, conservatively trust it — the result may
+        // legitimately be empty for those specific filter values.
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Create a Corrector that wraps a Planner in a retry loop.
+ *
+ * @example
+ * ```ts
+ * const corrector = createCorrector({ planner, maxRetries: 3 });
+ * const result = await corrector.correct(question, context, initialPlan, executeFn);
+ * if (result.exhausted) throw new Error("Could not produce a valid query.");
+ * ```
+ */
+export function createCorrector(config) {
+    const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    return {
+        async correct(question, context, initialPlan, execute) {
+            const attempts = [];
+            let currentPlan = initialPlan;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                // Attempt execution of the current plan
+                let execResult;
+                try {
+                    execResult = await execute(currentPlan.sql);
+                }
+                catch (err) {
+                    // Execution error — record the attempt and re-plan if retries remain
+                    const error = err instanceof Error ? err.message : String(err);
+                    attempts.push({ sql: currentPlan.sql, error });
+                    if (attempt >= maxRetries) {
+                        return { plan: currentPlan, attempts, exhausted: true };
+                    }
+                    currentPlan = await config.planner.plan(question, context, {
+                        errorContext: attempts,
+                    });
+                    continue;
+                }
+                // Execution succeeded — check the zero-row heuristic
+                if (execResult.rowCount === 0 && isLikelyZeroRowBug(currentPlan.sql)) {
+                    const error = "Query returned 0 rows from a query with no WHERE filters — " +
+                        "this is likely a schema mismatch or incorrect table reference.";
+                    attempts.push({ sql: currentPlan.sql, error });
+                    if (attempt >= maxRetries) {
+                        return { plan: currentPlan, attempts, exhausted: true };
+                    }
+                    currentPlan = await config.planner.plan(question, context, {
+                        errorContext: attempts,
+                    });
+                    continue;
+                }
+                // Clean result — return it (with any accumulated prior attempts)
+                return { plan: currentPlan, attempts, exhausted: false };
+            }
+            // Should be unreachable but TypeScript needs it
+            return { plan: currentPlan, attempts, exhausted: true };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/corrector/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/corrector/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AA8CzC,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,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,+CAA+C;QAC/C,MAAM,UAAU,GACd,IAAI,CAAC,IAAI,KAAK,MAAM;YAClB,CAAC,CAAC,IAAI,CAAC,EAAE;YACT,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;gBACtB,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,IAAI,CAAC;QAEb,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAE9D,qEAAqE;QACrE,IAAI,CAAC,CAAC,OAAO,IAAI,UAAU,CAAC,IAAI,UAAU,CAAC,KAAK,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEtE,uEAAuE;QACvE,0DAA0D;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAE5D,OAAO;QACL,KAAK,CAAC,OAAO,CACX,QAAgB,EAChB,OAA+B,EAC/B,WAAuB,EACvB,OAAkD;YAElD,MAAM,QAAQ,GAAmB,EAAE,CAAC;YACpC,IAAI,WAAW,GAAG,WAAW,CAAC;YAE9B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;gBACvD,wCAAwC;gBACxC,IAAI,UAA2B,CAAC;gBAChC,IAAI,CAAC;oBACH,UAAU,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAC9C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,qEAAqE;oBACrE,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;oBAE/C,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;wBAC1B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;oBAC1D,CAAC;oBAED,WAAW,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE;wBACzD,YAAY,EAAE,QAAQ;qBACvB,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBAED,qDAAqD;gBACrD,IAAI,UAAU,CAAC,QAAQ,KAAK,CAAC,IAAI,kBAAkB,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;oBACrE,MAAM,KAAK,GACT,6DAA6D;wBAC7D,gEAAgE,CAAC;oBACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;oBAE/C,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;wBAC1B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;oBAC1D,CAAC;oBAED,WAAW,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE;wBACzD,YAAY,EAAE,QAAQ;qBACvB,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBAED,iEAAiE;gBACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;YAC3D,CAAC;YAED,gDAAgD;YAChD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC1D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/db/index.d.ts

@@ -0,0 +1,3 @@
+export { createPool, createReadonlyPool } from "./pool.js";
+export type { PoolOptions } from "./pool.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/db/index.js

@@ -0,0 +1,2 @@
+export { createPool, createReadonlyPool } from "./pool.js";
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC"}

package/dist/db/pool.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared pg Pool factory.
+ *
+ * All stages that need a database connection should create their pool through
+ * one of these factories so that connection defaults are applied consistently
+ * across the SDK.
+ *
+ * pg is a peerDependency of @pgsage/core — the caller is responsible for
+ * installing it.  We import via a type-only import so that the factory
+ * signature is typed at build time without bundling pg.
+ */
+declare const Pool: typeof import("pg").Pool;
+export interface PoolOptions {
+    /** Maximum number of connections in the pool. Default: 5. */
+    max?: number;
+    /**
+     * Milliseconds a client may sit idle before being closed.
+     * Default: 30 000 ms.
+     */
+    idleTimeoutMillis?: number;
+    /**
+     * Milliseconds to wait for a connection before throwing.
+     * Default: 5 000 ms.
+     */
+    connectionTimeoutMillis?: number;
+    /**
+     * Per-query statement timeout in milliseconds.
+     * Passed as a SET option on every acquired client.
+     * Default: 30 000 ms.
+     */
+    statementTimeout?: number;
+}
+/**
+ * Create a read-write pool for admin operations (migrations, loaders,
+ * introspection, embedding indexing).
+ */
+export declare function createPool(connectionString: string, options?: PoolOptions): InstanceType<typeof Pool>;
+/**
+ * Create a read-only pool for the executor stage.
+ * Identical to createPool but semantically scoped to a read-only role
+ * connection string — no additional restrictions are enforced here beyond
+ * what the DB role itself restricts.
+ */
+export declare function createReadonlyPool(connectionString: string, options?: PoolOptions): InstanceType<typeof Pool>;
+export {};
+//# sourceMappingURL=pool.d.ts.map

package/dist/db/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/db/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,QAAA,MAAQ,IAAI,0BAAO,CAAC;AAEpB,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAaD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,WAAgB,GACxB,YAAY,CAAC,OAAO,IAAI,CAAC,CAS3B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,WAAgB,GACxB,YAAY,CAAC,OAAO,IAAI,CAAC,CAE3B"}

package/dist/db/pool.js

@@ -0,0 +1,46 @@
+/**
+ * Shared pg Pool factory.
+ *
+ * All stages that need a database connection should create their pool through
+ * one of these factories so that connection defaults are applied consistently
+ * across the SDK.
+ *
+ * pg is a peerDependency of @pgsage/core — the caller is responsible for
+ * installing it.  We import via a type-only import so that the factory
+ * signature is typed at build time without bundling pg.
+ */
+import pg from "pg";
+const { Pool } = pg;
+const DEFAULTS = {
+    max: 5,
+    idleTimeoutMillis: 30_000,
+    connectionTimeoutMillis: 5_000,
+    statementTimeout: 30_000,
+};
+function applyDefaults(options = {}) {
+    return { ...DEFAULTS, ...options };
+}
+/**
+ * Create a read-write pool for admin operations (migrations, loaders,
+ * introspection, embedding indexing).
+ */
+export function createPool(connectionString, options = {}) {
+    const opts = applyDefaults(options);
+    return new Pool({
+        connectionString,
+        max: opts.max,
+        idleTimeoutMillis: opts.idleTimeoutMillis,
+        connectionTimeoutMillis: opts.connectionTimeoutMillis,
+        options: `--statement_timeout=${opts.statementTimeout}`,
+    });
+}
+/**
+ * Create a read-only pool for the executor stage.
+ * Identical to createPool but semantically scoped to a read-only role
+ * connection string — no additional restrictions are enforced here beyond
+ * what the DB role itself restricts.
+ */
+export function createReadonlyPool(connectionString, options = {}) {
+    return createPool(connectionString, options);
+}
+//# sourceMappingURL=pool.js.map

package/dist/db/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/db/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAuBpB,MAAM,QAAQ,GAA0B;IACtC,GAAG,EAAE,CAAC;IACN,iBAAiB,EAAE,MAAM;IACzB,uBAAuB,EAAE,KAAK;IAC9B,gBAAgB,EAAE,MAAM;CACzB,CAAC;AAEF,SAAS,aAAa,CAAC,UAAuB,EAAE;IAC9C,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,gBAAwB,EACxB,UAAuB,EAAE;IAEzB,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,IAAI,IAAI,CAAC;QACd,gBAAgB;QAChB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;QACzC,uBAAuB,EAAE,IAAI,CAAC,uBAAuB;QACrD,OAAO,EAAE,uBAAuB,IAAI,CAAC,gBAAgB,EAAE;KACxD,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,gBAAwB,EACxB,UAAuB,EAAE;IAEzB,OAAO,UAAU,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/dist/embeddings/index.d.ts

@@ -0,0 +1,4 @@
+export type { EmbeddingInputType, EmbeddingProvider, EmbeddingResult } from "./types.js";
+export { VoyageEmbeddingProvider, VoyageApiError } from "./voyage.js";
+export type { VoyageConfig, VoyageModel } from "./voyage.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/embeddings/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/embeddings/index.js

@@ -0,0 +1,2 @@
+export { VoyageEmbeddingProvider, VoyageApiError } from "./voyage.js";
+//# sourceMappingURL=index.js.map

package/dist/embeddings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embeddings/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/embeddings/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * EmbeddingProvider — provider-agnostic interface for text embedding.
+ *
+ * The retriever depends on this interface rather than any concrete
+ * implementation so that alternative providers (OpenAI, Cohere, local
+ * models, etc.) can be substituted without modifying retriever logic.
+ *
+ * Contract:
+ *  - embed() returns one embedding vector per input text, in the same order.
+ *  - All vectors returned by a single provider instance have the same length
+ *    (equal to `dimensions`).
+ *  - inputType is a hint to the provider; providers that do not distinguish
+ *    query vs document may safely ignore it.
+ */
+export type EmbeddingInputType = "query" | "document";
+export interface EmbeddingResult {
+    /** One float32 vector per input text, in input order. */
+    embeddings: number[][];
+    /** Total tokens consumed (for cost tracking / logging). */
+    totalTokens: number;
+    /** The model identifier that produced these embeddings. */
+    model: string;
+}
+export interface EmbeddingProvider {
+    /**
+     * Embed one or more texts.
+     *
+     * @param texts      Non-empty array of strings to embed.
+     * @param inputType  Optional hint: 'document' for corpus content,
+     *                   'query' for user questions.  Allows providers like
+     *                   Voyage to prepend retrieval-optimised prompts.
+     */
+    embed(this: void, texts: string[], inputType?: EmbeddingInputType): Promise<EmbeddingResult>;
+    /** Number of dimensions in each returned vector. */
+    readonly dimensions: number;
+    /** Human-readable model identifier (e.g. 'voyage-4-lite'). */
+    readonly modelId: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/embeddings/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,UAAU,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IACvB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE7F,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/embeddings/types.js

@@ -0,0 +1,16 @@
+/**
+ * EmbeddingProvider — provider-agnostic interface for text embedding.
+ *
+ * The retriever depends on this interface rather than any concrete
+ * implementation so that alternative providers (OpenAI, Cohere, local
+ * models, etc.) can be substituted without modifying retriever logic.
+ *
+ * Contract:
+ *  - embed() returns one embedding vector per input text, in the same order.
+ *  - All vectors returned by a single provider instance have the same length
+ *    (equal to `dimensions`).
+ *  - inputType is a hint to the provider; providers that do not distinguish
+ *    query vs document may safely ignore it.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/embeddings/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/embeddings/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/embeddings/voyage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import type { EmbeddingInputType, EmbeddingProvider, EmbeddingResult } from "./types.js";
+export type VoyageModel = "voyage-4-large" | "voyage-4" | "voyage-4-lite" | "voyage-4-nano" | (string & {});
+export interface VoyageConfig {
+    /** Voyage AI API key. Required. */
+    apiKey: string;
+    /** Model to use. Default: 'voyage-4-lite'. */
+    model?: VoyageModel;
+    /** API base URL. Default: 'https://api.voyageai.com/v1'. */
+    baseUrl?: string;
+    /**
+     * Output embedding dimensions.
+     * Voyage 4-series supports 256 | 512 | 1024 | 2048.
+     * Default: 1024 (matches schema_embeddings column).
+     */
+    dimensions?: number;
+    /**
+     * Maximum number of texts per API request.
+     * Voyage allows up to 1 000; we default to 128 to stay well under
+     * the per-request token limits for all model tiers.
+     */
+    maxTextsPerBatch?: number;
+    /**
+     * Whether to truncate texts that exceed the model's context length.
+     * Default: true.
+     */
+    truncation?: boolean;
+    /**
+     * Per-request timeout in milliseconds (via AbortSignal.timeout).
+     * Default: 30 000 ms.
+     */
+    requestTimeoutMs?: number;
+    /** Maximum retry attempts on 429 / 5xx responses. Default: 3. */
+    maxRetries?: number;
+}
+export declare class VoyageApiError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    readonly attempt: number;
+    constructor(status: number, detail: string, attempt: number);
+}
+export declare class VoyageEmbeddingProvider implements EmbeddingProvider {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly _dimensions;
+    private readonly maxTextsPerBatch;
+    private readonly truncation;
+    private readonly requestTimeoutMs;
+    private readonly maxRetries;
+    constructor(config: VoyageConfig);
+    get dimensions(): number;
+    get modelId(): string;
+    embed(texts: string[], inputType?: EmbeddingInputType): Promise<EmbeddingResult>;
+    private embedBatch;
+}
+//# sourceMappingURL=voyage.d.ts.map

package/dist/embeddings/voyage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voyage.d.ts","sourceRoot":"","sources":["../../src/embeddings/voyage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMzF,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,UAAU,GACV,eAAe,GACf,eAAe,GACf,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAmCD,qBAAa,cAAe,SAAQ,KAAK;aAErB,MAAM,EAAE,MAAM;aACd,MAAM,EAAE,MAAM;aACd,OAAO,EAAE,MAAM;gBAFf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM;CAKlC;AAgBD,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,YAAY;IAahC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;YAyBxE,UAAU;CAmEzB"}