@pgsage/core 0.1.0

package/dist/retriever/index.js

@@ -0,0 +1,164 @@
+/**
+ * Retriever
+ *
+ * Two responsibilities:
+ *
+ *  1. indexSchema() — converts an IntrospectedSchema into text descriptions,
+ *     embeds them via an EmbeddingProvider, and upserts the results into the
+ *     schema_embeddings table.  Safe to run repeatedly (idempotent via ON
+ *     CONFLICT ... DO UPDATE).
+ *
+ *  2. retrieve() — embeds a natural-language question and performs a pgvector
+ *     cosine similarity search against schema_embeddings, returning the
+ *     top-K most relevant schema chunks.
+ */
+// ---------------------------------------------------------------------------
+// Text description generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a human-readable description of a table suitable for embedding.
+ * Includes: schema/table name, type, row estimate, comment, and a column
+ * summary with types, nullability, PK/FK annotations.
+ */
+export function describeTable(table) {
+    const type = table.tableType === "view" ? "VIEW" : "TABLE";
+    const rowHint = table.estimatedRowCount >= 0
+        ? `, ~${table.estimatedRowCount.toLocaleString()} rows`
+        : "";
+    const header = `${type} ${table.schema}.${table.name}${rowHint}`;
+    const comment = table.comment ? ` — ${table.comment}` : "";
+    const colSummary = table.columns
+        .map((c) => {
+        const parts = [c.name, c.dataType];
+        if (!c.isNullable)
+            parts.push("NOT NULL");
+        if (c.isPrimaryKey)
+            parts.push("PK");
+        const fk = table.foreignKeys.find((fk) => fk.columns.includes(c.name));
+        if (fk)
+            parts.push(`FK→${fk.referencedSchema}.${fk.referencedTable}.${fk.referencedColumns[0]}`);
+        if (c.comment)
+            parts.push(`(${c.comment})`);
+        return parts.join(" ");
+    })
+        .join(", ");
+    return `${header}${comment}. Columns: ${colSummary}.`;
+}
+/**
+ * Generate a human-readable description of a single column suitable for
+ * embedding.  Includes table context, type info, PK/FK annotations, and
+ * comment.
+ */
+export function describeColumn(table, columnIndex) {
+    const col = table.columns[columnIndex];
+    const nullable = col.isNullable ? "nullable" : "NOT NULL";
+    const pkNote = col.isPrimaryKey ? " PRIMARY KEY" : "";
+    const fk = table.foreignKeys.find((fk) => fk.columns.includes(col.name));
+    const fkNote = fk
+        ? ` References ${fk.referencedSchema}.${fk.referencedTable}(${fk.referencedColumns[0]}).`
+        : "";
+    const commentNote = col.comment ? ` ${col.comment}.` : "";
+    const defaultNote = col.defaultValue && !col.defaultValue.startsWith("nextval")
+        ? ` Default: ${col.defaultValue}.`
+        : "";
+    return (`Column ${table.schema}.${table.name}.${col.name}: ` +
+        `${col.dataType}${pkNote}, ${nullable}.` +
+        `${fkNote}${commentNote}${defaultNote} ` +
+        `Part of table ${table.schema}.${table.name}.`).trim();
+}
+// ---------------------------------------------------------------------------
+// indexSchema
+// ---------------------------------------------------------------------------
+/**
+ * Embed an IntrospectedSchema and upsert the results into schema_embeddings.
+ *
+ * Generates one chunk per table and one chunk per column, embeds them all
+ * in batches via the provider, then bulk-upserts into the DB.
+ */
+export async function indexSchema(pool, schema, provider, _options = {}) {
+    if (schema.tables.length === 0) {
+        return { rowsUpserted: 0, totalTokens: 0 };
+    }
+    // Build all (objectType, objectRef, content) tuples
+    const chunks = [];
+    for (const table of schema.tables) {
+        chunks.push({
+            objectType: "table",
+            objectRef: `${table.schema}.${table.name}`,
+            content: describeTable(table),
+        });
+        for (let i = 0; i < table.columns.length; i++) {
+            const col = table.columns[i];
+            chunks.push({
+                objectType: "column",
+                objectRef: `${table.schema}.${table.name}.${col.name}`,
+                content: describeColumn(table, i),
+            });
+        }
+    }
+    // Embed all content strings (provider handles its own batching)
+    const texts = chunks.map((c) => c.content);
+    const embeddingResult = await provider.embed(texts, "document");
+    // Upsert into schema_embeddings
+    const client = await pool.connect();
+    let rowsUpserted = 0;
+    try {
+        await client.query("BEGIN");
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            const vector = embeddingResult.embeddings[i];
+            const vectorLiteral = `[${vector.join(",")}]`;
+            await client.query(`INSERT INTO schema_embeddings (object_type, object_ref, content, embedding)
+         VALUES ($1, $2, $3, $4::vector)
+         ON CONFLICT (object_type, object_ref)
+         DO UPDATE SET
+           content   = EXCLUDED.content,
+           embedding = EXCLUDED.embedding`, [chunk.objectType, chunk.objectRef, chunk.content, vectorLiteral]);
+            rowsUpserted++;
+        }
+        await client.query("COMMIT");
+    }
+    catch (err) {
+        await client.query("ROLLBACK").catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+    return { rowsUpserted, totalTokens: embeddingResult.totalTokens };
+}
+/**
+ * Embed a natural-language question and return the most relevant schema
+ * chunks from schema_embeddings, ranked by cosine similarity.
+ */
+export async function retrieve(pool, question, provider, options = {}) {
+    const { topK = 10, minScore = 0, objectTypes } = options;
+    const embeddingResult = await provider.embed([question], "query");
+    const vector = embeddingResult.embeddings[0];
+    const vectorLiteral = `[${vector.join(",")}]`;
+    const typeFilter = objectTypes && objectTypes.length > 0
+        ? `AND object_type = ANY($3::text[])`
+        : "";
+    const params = [vectorLiteral, topK];
+    if (objectTypes && objectTypes.length > 0)
+        params.push(objectTypes);
+    const result = await pool.query(`SELECT
+       id,
+       object_type,
+       object_ref,
+       content,
+       1 - (embedding <=> $1::vector) AS score
+     FROM schema_embeddings
+     WHERE 1 - (embedding <=> $1::vector) >= ${minScore}
+     ${typeFilter}
+     ORDER BY embedding <=> $1::vector
+     LIMIT $2`, params);
+    return result.rows.map((row) => ({
+        id: row.id,
+        objectType: row.object_type,
+        objectRef: row.object_ref,
+        content: row.content,
+        score: Number(row.score),
+    }));
+}
+//# sourceMappingURL=index.js.map

package/dist/retriever/index.js.map

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

package/dist/validator/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Validator
+ *
+ * AST-level safety check on generated SQL: rejects writes, DDL, multi-statement
+ * payloads, and known-dangerous functions (e.g. pg_sleep). Read-only enforcement
+ * lives here as the first line of defense (the read-only DB role is the second).
+ */
+export interface ValidationResult {
+    valid: boolean;
+    /** Human-readable reason when valid === false. */
+    reason?: string;
+}
+/**
+ * Validate a SQL string for safety. Returns `{ valid: true }` for read-only
+ * SELECT / VALUES / WITH statements that contain no writes, DDL, or dangerous
+ * function calls; returns `{ valid: false, reason }` otherwise.
+ *
+ * Checks performed (in order):
+ * 1. Parse — reject if the SQL cannot be parsed at all.
+ * 2. Single statement — reject multi-statement payloads (`;` separated).
+ * 3. Allowed top-level type — must be `select`, `with`, or `values`.
+ * 4. No write operations inside CTEs (WITH clauses).
+ * 5. No dangerous function calls anywhere in the statement tree.
+ */
+export declare function validate(sql: string): ValidationResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validator/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAqID;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAoEtD"}

package/dist/validator/index.js

@@ -0,0 +1,205 @@
+/**
+ * Validator
+ *
+ * AST-level safety check on generated SQL: rejects writes, DDL, multi-statement
+ * payloads, and known-dangerous functions (e.g. pg_sleep). Read-only enforcement
+ * lives here as the first line of defense (the read-only DB role is the second).
+ */
+import { parse, astVisitor } from "pgsql-ast-parser";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Statement types that are unconditionally forbidden.
+ * The planner should only ever emit a single SELECT, WITH, or VALUES.
+ */
+const BANNED_STATEMENT_TYPES = new Set([
+    "insert",
+    "update",
+    "delete",
+    "drop table",
+    "drop",
+    "truncate table",
+    "create table",
+    "create index",
+    "create extension",
+    "create view",
+    "create materialized view",
+    "refresh materialized view",
+    "create sequence",
+    "create schema",
+    "create enum",
+    "create composite type",
+    "create function",
+    "drop function",
+    "alter table",
+    "alter index",
+    "alter sequence",
+    "alter enum",
+    "begin",
+    "commit",
+    "rollback",
+    "start transaction",
+    "set global",
+    "set timezone",
+    "set names",
+    "tablespace",
+    "do",
+    "raise",
+    "prepare",
+    "deallocate",
+    "comment",
+]);
+/**
+ * PostgreSQL built-in functions that pose security or availability risks.
+ * These are rejected even inside an otherwise valid SELECT.
+ */
+const DANGEROUS_FUNCTIONS = new Set([
+    // Process / availability
+    "pg_sleep",
+    "pg_terminate_backend",
+    "pg_cancel_backend",
+    "pg_reload_conf",
+    "pg_rotate_logfile",
+    "pg_switch_wal",
+    // File system access
+    "pg_read_file",
+    "pg_read_binary_file",
+    "pg_ls_dir",
+    "pg_ls_logdir",
+    "pg_ls_waldir",
+    "pg_ls_archive_statusdir",
+    "pg_ls_tmpdir",
+    "pg_stat_file",
+    "pg_file_write",
+    "pg_file_rename",
+    "pg_file_unlink",
+    // Network / foreign server
+    "dblink",
+    "dblink_connect",
+    "dblink_exec",
+    "dblink_open",
+    // Large object (file-like I/O)
+    "lo_import",
+    "lo_export",
+    "lo_create",
+    "lo_unlink",
+    // Copy (shell-out equivalent)
+    "pg_copy_logical_replication_slot",
+]);
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recursively collect all CTE binding statement types from a WITH statement.
+ * `with recursive` uses a different structure (its `bind` is a SelectFromUnion,
+ * not an array), so only `with` needs the recursive scan.
+ */
+function collectWithBindingTypes(stmt) {
+    const types = [];
+    for (const binding of stmt.bind) {
+        const inner = binding.statement;
+        types.push(inner.type);
+        // Recurse into nested WITH
+        if (inner.type === "with") {
+            types.push(...collectWithBindingTypes(inner));
+        }
+    }
+    return types;
+}
+/**
+ * Walk the full AST of a statement and collect all function call names.
+ * Uses astVisitor for a deep, recursive traversal.
+ */
+function collectFunctionCalls(stmt) {
+    const names = [];
+    const visitor = astVisitor(() => ({
+        call: (call) => {
+            const name = call.function?.name;
+            if (name)
+                names.push(name.toLowerCase());
+            visitor.super().call(call);
+        },
+    }));
+    visitor.statement(stmt);
+    return names;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate a SQL string for safety. Returns `{ valid: true }` for read-only
+ * SELECT / VALUES / WITH statements that contain no writes, DDL, or dangerous
+ * function calls; returns `{ valid: false, reason }` otherwise.
+ *
+ * Checks performed (in order):
+ * 1. Parse — reject if the SQL cannot be parsed at all.
+ * 2. Single statement — reject multi-statement payloads (`;` separated).
+ * 3. Allowed top-level type — must be `select`, `with`, or `values`.
+ * 4. No write operations inside CTEs (WITH clauses).
+ * 5. No dangerous function calls anywhere in the statement tree.
+ */
+export function validate(sql) {
+    // --- 1. Parse ----------------------------------------------------------
+    let statements;
+    try {
+        statements = parse(sql);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `SQL parse error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // --- 2. Single statement -----------------------------------------------
+    if (statements.length === 0) {
+        return { valid: false, reason: "Empty SQL statement: no statements parsed." };
+    }
+    if (statements.length > 1) {
+        return {
+            valid: false,
+            reason: `Multi-statement SQL is not allowed (${statements.length} statements found).`,
+        };
+    }
+    const stmt = statements[0];
+    // --- 3. Allowed top-level statement type --------------------------------
+    if (BANNED_STATEMENT_TYPES.has(stmt.type)) {
+        return {
+            valid: false,
+            reason: `Statement type '${stmt.type}' is not allowed. Only SELECT queries are permitted.`,
+        };
+    }
+    const ALLOWED_TOP_LEVEL = new Set(["select", "with", "with recursive", "values", "union"]);
+    if (!ALLOWED_TOP_LEVEL.has(stmt.type)) {
+        return {
+            valid: false,
+            reason: `Statement type '${stmt.type}' is not allowed. Only SELECT queries are permitted.`,
+        };
+    }
+    // --- 4. No write operations in CTEs ------------------------------------
+    // Only `with` (not `with recursive`) has array-of-bindings; `with recursive`
+    // binds a SelectFromUnion which cannot contain write statements.
+    if (stmt.type === "with") {
+        const innerTypes = collectWithBindingTypes(stmt);
+        for (const innerType of innerTypes) {
+            if (BANNED_STATEMENT_TYPES.has(innerType)) {
+                return {
+                    valid: false,
+                    reason: `Write operation '${innerType}' is not allowed inside a CTE.`,
+                };
+            }
+        }
+    }
+    // --- 5. No dangerous function calls ------------------------------------
+    const calls = collectFunctionCalls(stmt);
+    for (const name of calls) {
+        if (DANGEROUS_FUNCTIONS.has(name)) {
+            return {
+                valid: false,
+                reason: `Function '${name}' is not allowed.`,
+            };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=index.js.map

package/dist/validator/index.js.map

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

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pgsage/core",
+  "version": "0.1.0",
+  "description": "Schema-aware SQL agent SDK: introspection, retrieval, planning, validation, and safe execution.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hownowbrowncow/pgsage.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/hownowbrowncow/pgsage/tree/main/packages/core",
+  "bugs": "https://github.com/hownowbrowncow/pgsage/issues",
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "sql",
+    "ai",
+    "agent",
+    "pgvector",
+    "claude",
+    "anthropic",
+    "natural-language",
+    "embeddings",
+    "text-to-sql",
+    "llm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "pg": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.2.0",
+    "@types/pg": "8.23.1",
+    "pg": "8.23.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "dependencies": {
+    "@mastra/core": "^1.61.0",
+    "pgsql-ast-parser": "^12.0.2",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}