@deepagents/text2sql 0.2.3 → 0.3.0

package/dist/lib/adapters/postgres/index.js

@@ -0,0 +1,1640 @@
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+function createGroundingContext() {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  async introspect() {
+    const lines = [];
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      lines.push({
+        tag: grounding.tag,
+        fn: await grounding.execute(ctx)
+      });
+    }
+    return lines.map(({ fn, tag }) => {
+      const description = fn();
+      if (description === null) {
+        return "";
+      }
+      return `<${tag}>
+${description}
+</${tag}>`;
+    }).join("\n");
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/grounding.ticket.ts
+var AbstractGrounding = class {
+  tag;
+  constructor(tag) {
+    this.tag = tag;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
+var ColumnStatsGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("column_stats");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with statistics.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const stats = await this.collectStats(container.name, column);
+          if (stats) {
+            column.stats = stats;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting stats for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraints");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their constraints.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      try {
+        table.constraints = await this.getConstraints(table.name);
+      } catch (error) {
+        console.warn("Error collecting constraints for", table.name, error);
+      }
+    }
+    return () => null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
+var IndexesGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("indexes");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      table.indexes = await this.getIndexes(table.name);
+      for (const index of table.indexes ?? []) {
+        for (const colName of index.columns) {
+          const column = table.columns.find((c) => c.name === colName);
+          if (column) {
+            column.isIndexed = true;
+          }
+        }
+      }
+    }
+    return () => null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialect_info");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+    const lines = [`Dialect: ${ctx.info.dialect ?? "unknown"}`];
+    if (ctx.info.version) {
+      lines.push(`Version: ${ctx.info.version}`);
+    }
+    if (ctx.info.database) {
+      lines.push(`Database: ${ctx.info.database}`);
+    }
+    if (ctx.info.details && Object.keys(ctx.info.details).length) {
+      lines.push(`Details: ${JSON.stringify(ctx.info.details)}`);
+    }
+    return () => lines.join("\n");
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/low-cardinality.grounding.ts
+var LowCardinalityGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("low_cardinality");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with low cardinality values.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const lowCard = await this.collectLowCardinality(
+            container.name,
+            column
+          );
+          if (lowCard) {
+            column.kind = lowCard.kind;
+            column.values = lowCard.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting low cardinality values for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
+import { groq } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent from "dedent";
+import z from "zod";
+import {
+  agent,
+  generate,
+  toState,
+  user
+} from "@deepagents/agent";
+var ReportGrounding = class extends AbstractGrounding {
+  #adapter;
+  #model;
+  #cache;
+  #forceRefresh;
+  constructor(adapter, config = {}) {
+    super("business_context");
+    this.#adapter = adapter;
+    this.#model = config.model ?? groq("openai/gpt-oss-20b");
+    this.#cache = config.cache;
+    this.#forceRefresh = config.forceRefresh ?? false;
+  }
+  async execute(ctx) {
+    if (!this.#forceRefresh && this.#cache) {
+      const cached = await this.#cache.get();
+      if (cached) {
+        ctx.report = cached;
+        return () => cached;
+      }
+    }
+    const report2 = await this.#generateReport();
+    ctx.report = report2;
+    if (this.#cache) {
+      await this.#cache.set(report2);
+    }
+    return () => report2;
+  }
+  async #generateReport() {
+    const reportAgent = agent({
+      name: "db-report-agent",
+      model: this.#model,
+      prompt: () => dedent`
+        <identity>
+          You are a database analyst expert. Your job is to understand what
+          a database represents and provide business context about it.
+          You have READ-ONLY access to the database.
+        </identity>
+
+        <instructions>
+          Write a business context that helps another agent answer questions accurately.
+
+          For EACH table, do queries ONE AT A TIME:
+          1. SELECT COUNT(*) to get row count
+          2. SELECT * LIMIT 3 to see sample data
+
+          Then write a report with:
+          - What business this database is for
+          - For each table: purpose, row count, and example of what the data looks like
+
+          Include concrete examples like "Track prices are $0.99",
+          "Customer names like 'Luís Gonçalves'", etc.
+
+          Keep it 400-600 words, conversational style.
+        </instructions>
+      `,
+      tools: {
+        query_database: tool({
+          description: "Execute a SELECT query to explore the database and gather insights.",
+          inputSchema: z.object({
+            sql: z.string().describe("The SELECT query to execute"),
+            purpose: z.string().describe(
+              "What insight you are trying to gather with this query"
+            )
+          }),
+          execute: ({ sql }, options) => {
+            const state = toState(options);
+            return state.adapter.execute(sql);
+          }
+        })
+      }
+    });
+    const { text } = await generate(
+      reportAgent,
+      [
+        user(
+          "Please analyze the database and write a contextual report about what this database represents."
+        )
+      ],
+      { adapter: this.#adapter }
+    );
+    return text;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("row_counts");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with row counts and size hints.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      const count = await this.getRowCount(table.name);
+      if (count != null) {
+        table.rowCount = count;
+        table.sizeHint = this.#classifyRowCount(count);
+      }
+    }
+    return () => null;
+  }
+  /**
+   * Classify row count into a size hint category.
+   */
+  #classifyRowCount(count) {
+    if (count < 100) return "tiny";
+    if (count < 1e3) return "small";
+    if (count < 1e4) return "medium";
+    if (count < 1e5) return "large";
+    return "huge";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+import pluralize from "pluralize";
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("tables");
+    this.#filter = config.filter;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered tables and relationships to the context.
+   */
+  async execute(ctx) {
+    const seedTables = await this.applyFilter();
+    const forward = this.#forward;
+    const backward = this.#backward;
+    if (!forward && !backward) {
+      const tables3 = await Promise.all(
+        seedTables.map((name) => this.getTable(name))
+      );
+      ctx.tables.push(...tables3);
+      return () => this.#describeTables(tables3);
+    }
+    const tables2 = {};
+    const allRelationships = [];
+    const seenRelationships = /* @__PURE__ */ new Set();
+    const forwardQueue = [];
+    const backwardQueue = [];
+    const forwardVisited = /* @__PURE__ */ new Set();
+    const backwardVisited = /* @__PURE__ */ new Set();
+    for (const name of seedTables) {
+      if (forward) forwardQueue.push({ name, depth: 0 });
+      if (backward) backwardQueue.push({ name, depth: 0 });
+    }
+    const forwardLimit = forward === true ? Infinity : forward || 0;
+    while (forwardQueue.length > 0) {
+      const item = forwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (forwardVisited.has(name)) continue;
+      forwardVisited.add(name);
+      if (!tables2[name]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!forwardVisited.has(rel.referenced_table)) {
+            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const backwardLimit = backward === true ? Infinity : backward || 0;
+    while (backwardQueue.length > 0) {
+      const item = backwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (backwardVisited.has(name)) continue;
+      backwardVisited.add(name);
+      if (!tables2[name]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!backwardVisited.has(rel.table)) {
+            backwardQueue.push({ name: rel.table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const tablesList = Object.values(tables2);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
+    return () => this.#describeTables(tablesList);
+  }
+  /**
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+  /**
+   * Add a relationship to the collection, deduplicating by key.
+   */
+  addRelationship(rel, all, seen) {
+    const key = `${rel.table}:${rel.from.join(",")}:${rel.referenced_table}:${rel.to.join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      all.push(rel);
+    }
+  }
+  #describeTables(tables2) {
+    if (!tables2.length) {
+      return "Schema unavailable.";
+    }
+    return tables2.map((table) => {
+      const rowCountInfo = table.rowCount != null ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ""}]` : "";
+      const pkConstraint = table.constraints?.find((c) => c.type === "PRIMARY_KEY");
+      const pkColumns = new Set(pkConstraint?.columns ?? []);
+      const columns = table.columns.map((column) => {
+        const annotations = [];
+        const isPrimaryKey = pkColumns.has(column.name);
+        if (isPrimaryKey) {
+          annotations.push("PK");
+        }
+        if (column.isIndexed && !isPrimaryKey) {
+          annotations.push("Indexed");
+        }
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const indexes2 = table.indexes?.length ? `
+  Indexes:
+${table.indexes.map((index) => {
+        const props = [];
+        if (index.unique) {
+          props.push("UNIQUE");
+        }
+        if (index.type) {
+          props.push(index.type);
+        }
+        const propsText = props.length ? ` (${props.join(", ")})` : "";
+        const columnsText = index.columns?.length ? index.columns.join(", ") : "expression";
+        return `    - ${index.name}${propsText}: ${columnsText}`;
+      }).join("\n")}` : "";
+      return `- Table: ${table.name}${rowCountInfo}
+  Columns:
+${columns}${indexes2}`;
+    }).join("\n\n");
+  }
+  #formatTableLabel = (tableName) => {
+    const base = tableName.split(".").pop() ?? tableName;
+    return base.replace(/_/g, " ");
+  };
+  #describeRelationships = (tables2, relationships) => {
+    if (!relationships.length) {
+      return "None detected";
+    }
+    const tableMap = new Map(tables2.map((table) => [table.name, table]));
+    return relationships.map((relationship) => {
+      const sourceLabel = this.#formatTableLabel(relationship.table);
+      const targetLabel = this.#formatTableLabel(
+        relationship.referenced_table
+      );
+      const singularSource = pluralize.singular(sourceLabel);
+      const pluralSource = pluralize.plural(sourceLabel);
+      const singularTarget = pluralize.singular(targetLabel);
+      const pluralTarget = pluralize.plural(targetLabel);
+      const sourceTable = tableMap.get(relationship.table);
+      const targetTable = tableMap.get(relationship.referenced_table);
+      const sourceCount = sourceTable?.rowCount;
+      const targetCount = targetTable?.rowCount;
+      const ratio = sourceCount != null && targetCount != null && targetCount > 0 ? sourceCount / targetCount : null;
+      let cardinality = "each";
+      if (ratio != null) {
+        if (ratio > 5) {
+          cardinality = `many-to-one (\u2248${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 1.2 && ratio > 0.8) {
+          cardinality = `roughly 1:1 (${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 0.2) {
+          cardinality = `one-to-many (${sourceCount} vs ${targetCount})`;
+        }
+      }
+      const mappings = relationship.from.map((fromCol, idx) => {
+        const targetCol = relationship.to[idx] ?? relationship.to[0] ?? fromCol;
+        return `${relationship.table}.${fromCol} -> ${relationship.referenced_table}.${targetCol}`;
+      }).join(", ");
+      return `- ${relationship.table} (${relationship.from.join(", ")}) -> ${relationship.referenced_table} (${relationship.to.join(", ")}) [${cardinality}]`;
+    }).join("\n");
+  };
+};
+
+// packages/text2sql/src/lib/adapters/postgres/column-stats.postgres.grounding.ts
+var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectStats(tableName, column) {
+    if (!this.#shouldCollectStats(column.type)) {
+      return void 0;
+    }
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const sql = `
+      SELECT
+        MIN(${columnIdentifier})::text AS min_value,
+        MAX(${columnIdentifier})::text AS max_value,
+        AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END) AS null_fraction
+      FROM ${tableIdentifier}
+    `;
+    const rows = await this.#adapter.runQuery(sql);
+    if (!rows.length) {
+      return void 0;
+    }
+    const min = rows[0]?.min_value;
+    const max = rows[0]?.max_value;
+    const nullFraction = this.#adapter.toNumber(rows[0]?.null_fraction);
+    if (min == null && max == null && nullFraction == null) {
+      return void 0;
+    }
+    return {
+      min: min ?? void 0,
+      max: max ?? void 0,
+      nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
+    };
+  }
+  #shouldCollectStats(type) {
+    if (!type) {
+      return false;
+    }
+    const normalized = type.toLowerCase();
+    return /int|real|numeric|double|float|decimal|date|time|bool|serial/.test(
+      normalized
+    );
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/constraint.postgres.grounding.ts
+var PostgresConstraintGrounding = class extends ConstraintGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getConstraints(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const constraints2 = [];
+    const constraintRows = await this.#adapter.runQuery(`
+      SELECT
+        con.conname AS constraint_name,
+        con.contype AS constraint_type,
+        pg_get_constraintdef(con.oid) AS definition,
+        a.attname AS column_name,
+        ref_nsp.nspname AS ref_schema,
+        ref_rel.relname AS ref_table,
+        ref_a.attname AS ref_column
+      FROM pg_constraint con
+      JOIN pg_class rel ON rel.oid = con.conrelid
+      JOIN pg_namespace nsp ON nsp.oid = rel.relnamespace
+      LEFT JOIN LATERAL unnest(con.conkey) WITH ORDINALITY AS key(attnum, ord) ON TRUE
+      LEFT JOIN pg_attribute a ON a.attrelid = rel.oid AND a.attnum = key.attnum
+      LEFT JOIN pg_class ref_rel ON ref_rel.oid = con.confrelid
+      LEFT JOIN pg_namespace ref_nsp ON ref_nsp.oid = ref_rel.relnamespace
+      LEFT JOIN LATERAL unnest(con.confkey) WITH ORDINALITY AS ref_key(attnum, ord) ON key.ord = ref_key.ord
+      LEFT JOIN pg_attribute ref_a ON ref_a.attrelid = ref_rel.oid AND ref_a.attnum = ref_key.attnum
+      WHERE nsp.nspname = '${this.#adapter.escapeString(schema)}'
+        AND rel.relname = '${this.#adapter.escapeString(table)}'
+        AND con.contype IN ('p', 'f', 'c', 'u')
+      ORDER BY con.conname, key.ord
+    `);
+    const constraintMap = /* @__PURE__ */ new Map();
+    for (const row of constraintRows) {
+      const existing = constraintMap.get(row.constraint_name);
+      if (existing) {
+        if (row.column_name && !existing.columns.includes(row.column_name)) {
+          existing.columns.push(row.column_name);
+        }
+        if (row.ref_column && !existing.refColumns.includes(row.ref_column)) {
+          existing.refColumns.push(row.ref_column);
+        }
+      } else {
+        constraintMap.set(row.constraint_name, {
+          type: row.constraint_type,
+          definition: row.definition,
+          columns: row.column_name ? [row.column_name] : [],
+          refSchema: row.ref_schema,
+          refTable: row.ref_table,
+          refColumns: row.ref_column ? [row.ref_column] : []
+        });
+      }
+    }
+    for (const [name, data] of constraintMap) {
+      if (data.type === "p") {
+        constraints2.push({
+          name,
+          type: "PRIMARY_KEY",
+          columns: data.columns
+        });
+      } else if (data.type === "f") {
+        const referencedTable = data.refSchema && data.refTable ? `${data.refSchema}.${data.refTable}` : data.refTable ?? void 0;
+        constraints2.push({
+          name,
+          type: "FOREIGN_KEY",
+          columns: data.columns,
+          referencedTable,
+          referencedColumns: data.refColumns
+        });
+      } else if (data.type === "c") {
+        constraints2.push({
+          name,
+          type: "CHECK",
+          definition: data.definition?.replace(/^CHECK\s*\(/i, "").replace(/\)$/, "") || void 0,
+          columns: data.columns.length > 0 ? data.columns : void 0
+        });
+      } else if (data.type === "u") {
+        constraints2.push({
+          name,
+          type: "UNIQUE",
+          columns: data.columns
+        });
+      }
+    }
+    const columnRows = await this.#adapter.runQuery(`
+      SELECT
+        column_name,
+        column_default,
+        is_nullable
+      FROM information_schema.columns
+      WHERE table_schema = '${this.#adapter.escapeString(schema)}'
+        AND table_name = '${this.#adapter.escapeString(table)}'
+    `);
+    for (const col of columnRows) {
+      const pkConstraint = constraints2.find((c) => c.type === "PRIMARY_KEY");
+      const isPkColumn = pkConstraint?.columns?.includes(col.column_name);
+      if (col.is_nullable === "NO" && !isPkColumn) {
+        constraints2.push({
+          name: `${table}_${col.column_name}_notnull`,
+          type: "NOT_NULL",
+          columns: [col.column_name]
+        });
+      }
+      if (col.column_default != null) {
+        constraints2.push({
+          name: `${table}_${col.column_name}_default`,
+          type: "DEFAULT",
+          columns: [col.column_name],
+          defaultValue: col.column_default
+        });
+      }
+    }
+    return constraints2;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/indexes.postgres.grounding.ts
+var PostgresIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  #schemas;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+    this.#schemas = config.schemas;
+  }
+  async getIndexes(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        i.relname AS index_name,
+        a.attname AS column_name,
+        ix.indisunique AS is_unique,
+        am.amname AS index_type,
+        array_position(ix.indkey, a.attnum) AS column_position
+      FROM pg_index ix
+      JOIN pg_class i ON i.oid = ix.indexrelid
+      JOIN pg_class t ON t.oid = ix.indrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+      JOIN pg_am am ON am.oid = i.relam
+      WHERE n.nspname = '${this.#adapter.escapeString(schema)}'
+        AND t.relname = '${this.#adapter.escapeString(table)}'
+      ORDER BY i.relname, array_position(ix.indkey, a.attnum)
+    `);
+    return this.#groupIndexes(rows);
+  }
+  #groupIndexes(rows) {
+    const indexes2 = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.index_name || !row.column_name) continue;
+      const existing = indexes2.get(row.index_name);
+      if (existing) {
+        existing.columns.push(row.column_name);
+      } else {
+        indexes2.set(row.index_name, {
+          name: row.index_name,
+          columns: [row.column_name],
+          unique: row.is_unique,
+          type: row.index_type?.toUpperCase()
+        });
+      }
+    }
+    return Array.from(indexes2.values());
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/info.postgres.grounding.ts
+var PostgresInfoGrounding = class extends InfoGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectInfo() {
+    const [versionRows, dbRows] = await Promise.all([
+      this.#adapter.runQuery(
+        "SELECT version() AS version"
+      ),
+      this.#adapter.runQuery("SELECT current_database() AS db")
+    ]);
+    return {
+      dialect: "postgresql",
+      version: versionRows[0]?.version,
+      database: dbRows[0]?.db
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/low-cardinality.postgres.grounding.ts
+var LOW_CARDINALITY_LIMIT = 20;
+var PostgresLowCardinalityGrounding = class extends LowCardinalityGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectLowCardinality(tableName, column) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const limit = LOW_CARDINALITY_LIMIT + 1;
+    const sql = `
+      SELECT DISTINCT ${columnIdentifier}::text AS value
+      FROM ${tableIdentifier}
+      WHERE ${columnIdentifier} IS NOT NULL
+      LIMIT ${limit}
+    `;
+    const rows = await this.#adapter.runQuery(sql);
+    if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT) {
+      return void 0;
+    }
+    const values = [];
+    for (const row of rows) {
+      if (row.value == null) {
+        return void 0;
+      }
+      values.push(row.value);
+    }
+    if (!values.length) {
+      return void 0;
+    }
+    return { kind: "LowCardinality", values };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/postgres.ts
+var POSTGRES_ERROR_MAP = {
+  "42P01": {
+    type: "MISSING_TABLE",
+    hint: "Check the database schema for the correct table name. Include the schema prefix if necessary."
+  },
+  "42703": {
+    type: "INVALID_COLUMN",
+    hint: "Verify the column exists on the referenced table and use table aliases to disambiguate."
+  },
+  "42601": {
+    type: "SYNTAX_ERROR",
+    hint: "There is a SQL syntax error. Review keywords, punctuation, and the overall query shape."
+  },
+  "42P10": {
+    type: "INVALID_COLUMN",
+    hint: "Columns referenced in GROUP BY/SELECT must exist. Double-check the column names and aliases."
+  },
+  "42883": {
+    type: "INVALID_FUNCTION",
+    hint: "The function or operator you used is not recognized. Confirm its name and argument types."
+  }
+};
+var LOW_CARDINALITY_LIMIT2 = 20;
+function isPostgresError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string";
+}
+function formatPostgresError(sql, error) {
+  const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error occurred";
+  if (isPostgresError(error)) {
+    const metadata = POSTGRES_ERROR_MAP[error.code ?? ""];
+    if (metadata) {
+      return {
+        error: errorMessage,
+        error_type: metadata.type,
+        suggestion: metadata.hint,
+        sql_attempted: sql
+      };
+    }
+  }
+  return {
+    error: errorMessage,
+    error_type: "UNKNOWN_ERROR",
+    suggestion: "Review the query and try again",
+    sql_attempted: sql
+  };
+}
+var Postgres = class extends Adapter {
+  #options;
+  grounding;
+  defaultSchema = "public";
+  systemSchemas = ["pg_catalog", "information_schema"];
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("Postgres adapter requires an execute function.");
+    }
+    this.#options = {
+      ...options,
+      schemas: options.schemas?.length ? options.schemas : void 0
+    };
+    this.grounding = options.grounding;
+  }
+  async execute(sql) {
+    return this.#options.execute(sql);
+  }
+  async validate(sql) {
+    const validator = this.#options.validate ?? (async (text) => {
+      await this.#options.execute(`EXPLAIN ${text}`);
+    });
+    try {
+      return await validator(sql);
+    } catch (error) {
+      return JSON.stringify(formatPostgresError(sql, error));
+    }
+  }
+  async runQuery(sql) {
+    return this.#runIntrospectionQuery(sql);
+  }
+  quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+  }
+  escape(value) {
+    return value.replace(/"/g, '""');
+  }
+  async #loadTables() {
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        c.table_schema,
+        c.table_name,
+        c.column_name,
+        c.data_type
+      FROM information_schema.columns AS c
+      JOIN information_schema.tables AS t
+        ON c.table_schema = t.table_schema
+        AND c.table_name = t.table_name
+      WHERE t.table_type = 'BASE TABLE'
+        ${this.#buildSchemaFilter("c.table_schema")}
+      ORDER BY c.table_schema, c.table_name, c.ordinal_position
+    `);
+    const tables2 = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const tableName = row.table_name;
+      const qualifiedName = `${schema}.${tableName}`;
+      const table = tables2.get(qualifiedName) ?? {
+        name: qualifiedName,
+        schema,
+        rawName: tableName,
+        columns: []
+      };
+      table.columns.push({
+        name: row.column_name ?? "unknown",
+        type: row.data_type ?? "unknown"
+      });
+      tables2.set(qualifiedName, table);
+    }
+    return Array.from(tables2.values());
+  }
+  async #loadRelationships(filterTableNames) {
+    const tableFilter = this.#buildTableNamesFilter(filterTableNames);
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        tc.constraint_name,
+        tc.table_schema,
+        tc.table_name,
+        kcu.column_name,
+        ccu.table_schema AS foreign_table_schema,
+        ccu.table_name AS foreign_table_name,
+        ccu.column_name AS foreign_column_name
+      FROM information_schema.table_constraints AS tc
+      JOIN information_schema.key_column_usage AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      JOIN information_schema.constraint_column_usage AS ccu
+        ON ccu.constraint_name = tc.constraint_name
+        AND ccu.table_schema = tc.table_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        ${this.#buildSchemaFilter("tc.table_schema")}
+        ${tableFilter}
+      ORDER BY tc.table_schema, tc.table_name, tc.constraint_name, kcu.ordinal_position
+    `);
+    const relationships = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name || !row.foreign_table_name || !row.constraint_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const referencedSchema = row.foreign_table_schema ?? "public";
+      const key = `${schema}.${row.table_name}:${row.constraint_name}`;
+      const relationship = relationships.get(key) ?? {
+        table: `${schema}.${row.table_name}`,
+        from: [],
+        referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
+        to: []
+      };
+      relationship.from.push(row.column_name ?? "unknown");
+      relationship.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship);
+    }
+    return Array.from(relationships.values());
+  }
+  async #annotateRowCounts(tables2, onProgress) {
+    const total = tables2.length;
+    for (let i = 0; i < tables2.length; i++) {
+      const table = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "row_counts",
+        message: `Counting rows in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      try {
+        const rows = await this.#runIntrospectionQuery(`SELECT COUNT(*) as count FROM ${tableIdentifier}`);
+        const rowCount2 = this.#toNumber(rows[0]?.count);
+        if (rowCount2 != null) {
+          table.rowCount = rowCount2;
+          table.sizeHint = this.#classifyRowCount(rowCount2);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  /**
+   * @deprecated Primary keys are now handled via constraints grounding.
+   * This method is kept for backward compatibility but does nothing.
+   */
+  async #annotatePrimaryKeys(_tables) {
+  }
+  async #annotateIndexes(tables2) {
+    if (!tables2.length) {
+      return;
+    }
+    const tableMap = new Map(tables2.map((table) => [table.name, table]));
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        n.nspname AS table_schema,
+        t.relname AS table_name,
+        i.relname AS index_name,
+        a.attname AS column_name,
+        ix.indisunique,
+        ix.indisprimary,
+        ix.indisclustered,
+        am.amname AS method
+      FROM pg_index ix
+      JOIN pg_class t ON t.oid = ix.indrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      JOIN pg_class i ON i.oid = ix.indexrelid
+      JOIN pg_am am ON am.oid = i.relam
+      LEFT JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS key(attnum, ordinality) ON TRUE
+      LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = key.attnum
+      WHERE t.relkind = 'r'
+        ${this.#buildSchemaFilter("n.nspname")}
+      ORDER BY n.nspname, t.relname, i.relname, key.ordinality
+    `);
+    const indexMap = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name || !row.index_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const tableKey = `${schema}.${row.table_name}`;
+      const table = tableMap.get(tableKey);
+      if (!table) {
+        continue;
+      }
+      const indexKey = `${tableKey}:${row.index_name}`;
+      let index = indexMap.get(indexKey);
+      if (!index) {
+        index = {
+          name: row.index_name,
+          columns: [],
+          unique: Boolean(row.indisunique ?? false),
+          type: row.indisclustered ? "clustered" : row.method ?? void 0
+        };
+        indexMap.set(indexKey, index);
+        if (!table.indexes) {
+          table.indexes = [];
+        }
+        table.indexes.push(index);
+      }
+      if (row.column_name) {
+        index.columns.push(row.column_name);
+        const column = table.columns.find(
+          (col) => col.name === row.column_name
+        );
+        if (column) {
+          column.isIndexed = true;
+        }
+      }
+    }
+  }
+  async #annotateColumnStats(tables2, onProgress) {
+    if (!tables2.length) {
+      return;
+    }
+    const total = tables2.length;
+    for (let i = 0; i < tables2.length; i++) {
+      const table = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "column_stats",
+        message: `Collecting stats for ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        if (!this.#shouldCollectStats(column.type)) {
+          continue;
+        }
+        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const sql = `
+          SELECT
+            MIN(${columnIdentifier})::text AS min_value,
+            MAX(${columnIdentifier})::text AS max_value,
+            AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END)::float AS null_fraction
+          FROM ${tableIdentifier}
+        `;
+        try {
+          const rows = await this.#runIntrospectionQuery(sql);
+          if (!rows.length) {
+            continue;
+          }
+          const min = rows[0]?.min_value ?? void 0;
+          const max = rows[0]?.max_value ?? void 0;
+          const nullFraction = this.#toNumber(rows[0]?.null_fraction);
+          if (min != null || max != null || nullFraction != null) {
+            column.stats = {
+              min,
+              max,
+              nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
+            };
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+  async #annotateLowCardinalityColumns(tables2, onProgress) {
+    const total = tables2.length;
+    for (let i = 0; i < tables2.length; i++) {
+      const table = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "low_cardinality",
+        message: `Analyzing cardinality in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const limit = LOW_CARDINALITY_LIMIT2 + 1;
+        const sql = `
+          SELECT DISTINCT ${columnIdentifier} AS value
+          FROM ${tableIdentifier}
+          WHERE ${columnIdentifier} IS NOT NULL
+          LIMIT ${limit}
+        `;
+        let rows = [];
+        try {
+          rows = await this.#runIntrospectionQuery(sql);
+        } catch {
+          continue;
+        }
+        if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT2) {
+          continue;
+        }
+        const values = [];
+        let shouldSkip = false;
+        for (const row of rows) {
+          const formatted = this.#normalizeValue(row.value);
+          if (formatted == null) {
+            shouldSkip = true;
+            break;
+          }
+          values.push(formatted);
+        }
+        if (shouldSkip || !values.length) {
+          continue;
+        }
+        column.kind = "LowCardinality";
+        column.values = values;
+      }
+    }
+  }
+  #buildSchemaFilter(columnName) {
+    if (this.#options.schemas && this.#options.schemas.length > 0) {
+      const values = this.#options.schemas.map((schema) => `'${schema.replace(/'/g, "''")}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    return `AND ${columnName} NOT IN ('pg_catalog', 'information_schema')`;
+  }
+  /**
+   * Build a filter for table names (qualified as schema.table).
+   * Matches if either the source table or referenced table is in the list.
+   */
+  #buildTableNamesFilter(tableNames) {
+    if (!tableNames || tableNames.length === 0) {
+      return "";
+    }
+    const conditions = [];
+    for (const name of tableNames) {
+      if (name.includes(".")) {
+        const [schema, ...rest] = name.split(".");
+        const tableName = rest.join(".");
+        const escapedSchema = schema.replace(/'/g, "''");
+        const escapedTable = tableName.replace(/'/g, "''");
+        conditions.push(
+          `(tc.table_schema = '${escapedSchema}' AND tc.table_name = '${escapedTable}')`
+        );
+        conditions.push(
+          `(ccu.table_schema = '${escapedSchema}' AND ccu.table_name = '${escapedTable}')`
+        );
+      } else {
+        const escaped = name.replace(/'/g, "''");
+        conditions.push(`tc.table_name = '${escaped}'`);
+        conditions.push(`ccu.table_name = '${escaped}'`);
+      }
+    }
+    return `AND (${conditions.join(" OR ")})`;
+  }
+  async #runIntrospectionQuery(sql) {
+    const result = await this.#options.execute(sql);
+    if (Array.isArray(result)) {
+      return result;
+    }
+    if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
+      return result.rows;
+    }
+    throw new Error(
+      "Postgres adapter execute() must return an array of rows or an object with a rows array when introspecting."
+    );
+  }
+  #quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+  }
+  #formatQualifiedTableName(table) {
+    if (table.schema && table.rawName) {
+      return `${this.#quoteIdentifier(table.schema)}.${this.#quoteIdentifier(table.rawName)}`;
+    }
+    if (table.name.includes(".")) {
+      const [schemaPart, ...rest] = table.name.split(".");
+      const tablePart = rest.join(".") || schemaPart;
+      if (rest.length === 0) {
+        return this.#quoteIdentifier(schemaPart);
+      }
+      return `${this.#quoteIdentifier(schemaPart)}.${this.#quoteIdentifier(tablePart)}`;
+    }
+    return this.#quoteIdentifier(table.name);
+  }
+  #toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+  }
+  #shouldCollectStats(type) {
+    if (!type) {
+      return false;
+    }
+    const normalized = type.toLowerCase();
+    return /int|numeric|decimal|double|real|money|date|time|timestamp|bool/.test(
+      normalized
+    );
+  }
+  #classifyRowCount(count) {
+    if (count < 100) {
+      return "tiny";
+    }
+    if (count < 1e3) {
+      return "small";
+    }
+    if (count < 1e4) {
+      return "medium";
+    }
+    if (count < 1e5) {
+      return "large";
+    }
+    return "huge";
+  }
+  #normalizeValue(value) {
+    if (value === null || value === void 0) {
+      return null;
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+      return String(value);
+    }
+    if (typeof value === "boolean") {
+      return value ? "true" : "false";
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) {
+      return value.toString("utf-8");
+    }
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/row-count.postgres.grounding.ts
+var PostgresRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getRowCount(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
+    const rows = await this.#adapter.runQuery(
+      `SELECT COUNT(*) as count FROM ${tableIdentifier}`
+    );
+    return this.#adapter.toNumber(rows[0]?.count);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/table.postgres.grounding.ts
+var PostgresTableGrounding = class extends TableGrounding {
+  #adapter;
+  #schemas;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+    this.#schemas = config.schemas;
+  }
+  async getAllTableNames() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT DISTINCT table_schema || '.' || table_name AS name
+      FROM information_schema.tables
+      WHERE table_type = 'BASE TABLE'
+        ${this.#adapter.buildSchemaFilter("table_schema", this.#schemas)}
+      ORDER BY name
+    `);
+    return rows.map((r) => r.name);
+  }
+  async getTable(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const columns = await this.#adapter.runQuery(`
+      SELECT column_name, data_type
+      FROM information_schema.columns
+      WHERE table_schema = '${this.#adapter.escapeString(schema)}'
+        AND table_name = '${this.#adapter.escapeString(table)}'
+      ORDER BY ordinal_position
+    `);
+    return {
+      name: tableName,
+      schema,
+      rawName: table,
+      columns: columns.map((col) => ({
+        name: col.column_name ?? "unknown",
+        type: col.data_type ?? "unknown"
+      }))
+    };
+  }
+  async findOutgoingRelations(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        tc.constraint_name,
+        tc.table_schema,
+        tc.table_name,
+        kcu.column_name,
+        ccu.table_schema AS foreign_table_schema,
+        ccu.table_name AS foreign_table_name,
+        ccu.column_name AS foreign_column_name
+      FROM information_schema.table_constraints AS tc
+      JOIN information_schema.key_column_usage AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      JOIN information_schema.constraint_column_usage AS ccu
+        ON ccu.constraint_name = tc.constraint_name
+        AND ccu.table_schema = tc.table_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        AND tc.table_schema = '${this.#adapter.escapeString(schema)}'
+        AND tc.table_name = '${this.#adapter.escapeString(table)}'
+      ORDER BY tc.constraint_name, kcu.ordinal_position
+    `);
+    return this.#groupRelationships(rows);
+  }
+  async findIncomingRelations(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        tc.constraint_name,
+        tc.table_schema,
+        tc.table_name,
+        kcu.column_name,
+        ccu.table_schema AS foreign_table_schema,
+        ccu.table_name AS foreign_table_name,
+        ccu.column_name AS foreign_column_name
+      FROM information_schema.table_constraints AS tc
+      JOIN information_schema.key_column_usage AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      JOIN information_schema.constraint_column_usage AS ccu
+        ON ccu.constraint_name = tc.constraint_name
+        AND ccu.table_schema = tc.table_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        AND ccu.table_schema = '${this.#adapter.escapeString(schema)}'
+        AND ccu.table_name = '${this.#adapter.escapeString(table)}'
+      ORDER BY tc.constraint_name, kcu.ordinal_position
+    `);
+    return this.#groupRelationships(rows);
+  }
+  #groupRelationships(rows) {
+    const relationships = /* @__PURE__ */ new Map();
+    const defaultSchema = this.#adapter.defaultSchema ?? "public";
+    for (const row of rows) {
+      if (!row.table_name || !row.foreign_table_name || !row.constraint_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? defaultSchema;
+      const referencedSchema = row.foreign_table_schema ?? defaultSchema;
+      const key = `${schema}.${row.table_name}:${row.constraint_name}`;
+      const relationship = relationships.get(key) ?? {
+        table: `${schema}.${row.table_name}`,
+        from: [],
+        referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
+        to: []
+      };
+      relationship.from.push(row.column_name ?? "unknown");
+      relationship.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship);
+    }
+    return Array.from(relationships.values());
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  constructor(config = {}) {
+    super("views");
+    this.#filter = config.filter;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered views to the context.
+   */
+  async execute(ctx) {
+    const viewNames = await this.applyFilter();
+    const views2 = await Promise.all(
+      viewNames.map((name) => this.getView(name))
+    );
+    ctx.views.push(...views2);
+    return () => this.#describe(views2);
+  }
+  #describe(views2) {
+    if (!views2.length) {
+      return "No views available.";
+    }
+    return views2.map((view) => {
+      const columns = view.columns.map((column) => {
+        const annotations = [];
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const definition = view.definition ? `
+  Definition: ${view.definition.length > 200 ? view.definition.slice(0, 200) + "..." : view.definition}` : "";
+      return `- View: ${view.name}${definition}
+  Columns:
+${columns}`;
+    }).join("\n\n");
+  }
+  /**
+   * Apply the filter to get view names.
+   * If filter is an explicit array, skip querying all view names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllViewNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/view.postgres.grounding.ts
+var PostgresViewGrounding = class extends ViewGrounding {
+  #adapter;
+  #schemas;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+    this.#schemas = config.schemas;
+  }
+  async getAllViewNames() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT table_schema || '.' || table_name AS name
+      FROM information_schema.views
+      WHERE 1=1
+        ${this.#adapter.buildSchemaFilter("table_schema", this.#schemas)}
+      ORDER BY name
+    `);
+    return rows.map((r) => r.name);
+  }
+  async getView(viewName) {
+    const { schema, table: view } = this.#adapter.parseTableName(viewName);
+    const defRows = await this.#adapter.runQuery(`
+      SELECT definition
+      FROM pg_views
+      WHERE schemaname = '${this.#adapter.escapeString(schema)}'
+        AND viewname = '${this.#adapter.escapeString(view)}'
+    `);
+    const columns = await this.#adapter.runQuery(`
+      SELECT column_name, data_type
+      FROM information_schema.columns
+      WHERE table_schema = '${this.#adapter.escapeString(schema)}'
+        AND table_name = '${this.#adapter.escapeString(view)}'
+      ORDER BY ordinal_position
+    `);
+    return {
+      name: viewName,
+      schema,
+      rawName: view,
+      definition: defRows[0]?.definition ?? void 0,
+      columns: columns.map((col) => ({
+        name: col.column_name ?? "unknown",
+        type: col.data_type ?? "unknown"
+      }))
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/postgres/index.ts
+function tables(config = {}) {
+  return (adapter) => new PostgresTableGrounding(adapter, config);
+}
+function info(config = {}) {
+  return (adapter) => new PostgresInfoGrounding(adapter, config);
+}
+function views(config = {}) {
+  return (adapter) => {
+    return new PostgresViewGrounding(adapter, config);
+  };
+}
+function columnStats(config = {}) {
+  return (adapter) => {
+    return new PostgresColumnStatsGrounding(adapter, config);
+  };
+}
+function lowCardinality(config = {}) {
+  return (adapter) => {
+    return new PostgresLowCardinalityGrounding(adapter, config);
+  };
+}
+function indexes(config = {}) {
+  return (adapter) => {
+    return new PostgresIndexesGrounding(adapter, config);
+  };
+}
+function rowCount(config = {}) {
+  return (adapter) => {
+    return new PostgresRowCountGrounding(adapter, config);
+  };
+}
+function constraints(config = {}) {
+  return (adapter) => {
+    return new PostgresConstraintGrounding(adapter, config);
+  };
+}
+function report(config = {}) {
+  return (adapter) => new ReportGrounding(adapter, config);
+}
+var postgres_default = {
+  tables,
+  info,
+  views,
+  columnStats,
+  lowCardinality,
+  indexes,
+  rowCount,
+  constraints,
+  report,
+  Postgres
+};
+export {
+  Postgres,
+  columnStats,
+  constraints,
+  postgres_default as default,
+  formatPostgresError,
+  indexes,
+  info,
+  lowCardinality,
+  report,
+  rowCount,
+  tables,
+  views
+};
+//# sourceMappingURL=index.js.map