@deepagents/text2sql 0.10.2 → 0.11.0

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

@@ -1,3 +1,94 @@
+// packages/text2sql/src/lib/fragments/schema.ts
+function dialectInfo(input) {
+  return {
+    name: "dialectInfo",
+    data: {
+      dialect: input.dialect,
+      ...input.version && { version: input.version },
+      ...input.database && { database: input.database }
+    }
+  };
+}
+function table(input) {
+  return {
+    name: "table",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      ...input.rowCount != null && { rowCount: input.rowCount },
+      ...input.sizeHint && { sizeHint: input.sizeHint },
+      columns: input.columns,
+      ...input.indexes?.length && { indexes: input.indexes },
+      ...input.constraints?.length && { constraints: input.constraints }
+    }
+  };
+}
+function column(input) {
+  return {
+    name: "column",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.pk && { pk: true },
+      ...input.fk && { fk: input.fk },
+      ...input.unique && { unique: true },
+      ...input.notNull && { notNull: true },
+      ...input.default && { default: input.default },
+      ...input.indexed && { indexed: true },
+      ...input.values?.length && { values: input.values },
+      ...input.stats && { stats: input.stats }
+    }
+  };
+}
+function index(input) {
+  return {
+    name: "index",
+    data: {
+      name: input.name,
+      columns: input.columns,
+      ...input.unique && { unique: true },
+      ...input.type && { type: input.type }
+    }
+  };
+}
+function constraint(input) {
+  return {
+    name: "constraint",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.columns?.length && { columns: input.columns },
+      ...input.definition && { definition: input.definition },
+      ...input.defaultValue && { defaultValue: input.defaultValue },
+      ...input.referencedTable && { referencedTable: input.referencedTable },
+      ...input.referencedColumns?.length && {
+        referencedColumns: input.referencedColumns
+      }
+    }
+  };
+}
+function view(input) {
+  return {
+    name: "view",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      columns: input.columns,
+      ...input.definition && { definition: input.definition }
+    }
+  };
+}
+function relationship(input) {
+  return {
+    name: "relationship",
+    data: {
+      from: input.from,
+      to: input.to,
+      ...input.cardinality && { cardinality: input.cardinality }
+    }
+  };
+}
+
 // packages/text2sql/src/lib/adapters/groundings/context.ts
 function createGroundingContext() {
   return {
@@ -10,24 +101,169 @@ function createGroundingContext() {
 
 // packages/text2sql/src/lib/adapters/adapter.ts
 var Adapter = class {
+  /**
+   * Introspect the database schema and return context fragments.
+   *
+   * Executes all configured groundings to populate the context, then
+   * generates fragments from the complete context data.
+   *
+   * @param ctx - Optional grounding context for sharing state between groundings
+   * @returns Array of context fragments representing the database schema
+   */
   async introspect(ctx = createGroundingContext()) {
-    const lines = [];
     for (const fn of this.grounding) {
       const grounding = fn(this);
-      lines.push({
-        tag: grounding.tag,
-        fn: await grounding.execute(ctx)
-      });
+      await grounding.execute(ctx);
+    }
+    return this.#toSchemaFragments(ctx);
+  }
+  /**
+   * Convert complete grounding context to schema fragments.
+   * Called after all groundings have populated ctx with data.
+   */
+  #toSchemaFragments(ctx) {
+    const fragments = [];
+    if (ctx.info) {
+      fragments.push(
+        dialectInfo({
+          dialect: ctx.info.dialect,
+          version: ctx.info.version,
+          database: ctx.info.database
+        })
+      );
+    }
+    for (const t of ctx.tables) {
+      fragments.push(this.#tableToFragment(t));
+    }
+    for (const v of ctx.views) {
+      fragments.push(this.#viewToFragment(v));
+    }
+    const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
+    for (const rel of ctx.relationships) {
+      const sourceTable = tableMap.get(rel.table);
+      const targetTable = tableMap.get(rel.referenced_table);
+      fragments.push(
+        this.#relationshipToFragment(rel, sourceTable, targetTable)
+      );
     }
-    return lines.map(({ fn, tag }) => {
-      const description = fn();
-      if (description === null) {
-        return "";
+    if (ctx.report) {
+      fragments.push({ name: "businessContext", data: ctx.report });
+    }
+    return fragments;
+  }
+  /**
+   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
+   */
+  #tableToFragment(t) {
+    const pkConstraint = t.constraints?.find((c) => c.type === "PRIMARY_KEY");
+    const pkColumns = new Set(pkConstraint?.columns ?? []);
+    const notNullColumns = new Set(
+      t.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
+    );
+    const defaultByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "DEFAULT") ?? []) {
+      for (const col of c.columns ?? []) {
+        if (c.defaultValue != null) {
+          defaultByColumn.set(col, c.defaultValue);
+        }
+      }
+    }
+    const uniqueColumns = new Set(
+      t.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
+    );
+    const fkByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "FOREIGN_KEY") ?? []) {
+      const cols = c.columns ?? [];
+      const refCols = c.referencedColumns ?? [];
+      for (let i = 0; i < cols.length; i++) {
+        const refCol = refCols[i] ?? refCols[0] ?? cols[i];
+        fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
+      }
+    }
+    const columnFragments = t.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        pk: pkColumns.has(col.name) || void 0,
+        fk: fkByColumn.get(col.name),
+        unique: uniqueColumns.has(col.name) || void 0,
+        notNull: notNullColumns.has(col.name) || void 0,
+        default: defaultByColumn.get(col.name),
+        indexed: col.isIndexed || void 0,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    const indexFragments = (t.indexes ?? []).map(
+      (idx) => index({
+        name: idx.name,
+        columns: idx.columns,
+        unique: idx.unique,
+        type: idx.type
+      })
+    );
+    const constraintFragments = (t.constraints ?? []).filter(
+      (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).map(
+      (c) => constraint({
+        name: c.name,
+        type: c.type,
+        columns: c.columns,
+        definition: c.definition
+      })
+    );
+    return table({
+      name: t.name,
+      schema: t.schema,
+      rowCount: t.rowCount,
+      sizeHint: t.sizeHint,
+      columns: columnFragments,
+      indexes: indexFragments.length > 0 ? indexFragments : void 0,
+      constraints: constraintFragments.length > 0 ? constraintFragments : void 0
+    });
+  }
+  /**
+   * Convert a View to a view fragment with nested column fragments.
+   */
+  #viewToFragment(v) {
+    const columnFragments = v.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    return view({
+      name: v.name,
+      schema: v.schema,
+      columns: columnFragments,
+      definition: v.definition
+    });
+  }
+  /**
+   * Convert a Relationship to a relationship fragment.
+   * Infers cardinality from row counts if available.
+   */
+  #relationshipToFragment(rel, sourceTable, targetTable) {
+    const sourceCount = sourceTable?.rowCount;
+    const targetCount = targetTable?.rowCount;
+    let cardinality;
+    if (sourceCount != null && targetCount != null && targetCount > 0) {
+      const ratio = sourceCount / targetCount;
+      if (ratio > 5) {
+        cardinality = "many-to-one";
+      } else if (ratio < 1.2 && ratio > 0.8) {
+        cardinality = "one-to-one";
+      } else if (ratio < 0.2) {
+        cardinality = "one-to-many";
       }
-      return `<${tag}>
-${description}
-</${tag}>`;
-    }).join("\n");
+    }
+    return relationship({
+      from: { table: rel.table, columns: rel.from },
+      to: { table: rel.referenced_table, columns: rel.to },
+      cardinality
+    });
   }
   /**
    * Convert unknown database value to number.
@@ -83,16 +319,19 @@ ${description}
 
 // packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
 var AbstractGrounding = class {
-  tag;
-  constructor(tag) {
-    this.tag = tag;
+  /**
+   * Grounding identifier for debugging/logging.
+   */
+  name;
+  constructor(name) {
+    this.name = name;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
 var ColumnStatsGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("column_stats");
+    super("columnStats");
   }
   /**
    * Execute the grounding process.
@@ -101,79 +340,73 @@ var ColumnStatsGrounding = class extends AbstractGrounding {
   async execute(ctx) {
     const allContainers = [...ctx.tables, ...ctx.views];
     for (const container of allContainers) {
-      for (const column of container.columns) {
+      for (const column2 of container.columns) {
         try {
-          const stats = await this.collectStats(container.name, column);
+          const stats = await this.collectStats(container.name, column2);
           if (stats) {
-            column.stats = stats;
+            column2.stats = stats;
           }
         } catch (error) {
           console.warn(
             "Error collecting stats for",
             container.name,
-            column.name,
+            column2.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");
+    super("constraint");
   }
   /**
    * Execute the grounding process.
    * Annotates tables in ctx.tables with their constraints.
    */
   async execute(ctx) {
-    for (const table of ctx.tables) {
+    for (const table2 of ctx.tables) {
       try {
-        table.constraints = await this.getConstraints(table.name);
+        table2.constraints = await this.getConstraints(table2.name);
       } catch (error) {
-        console.warn("Error collecting constraints for", table.name, error);
+        console.warn("Error collecting constraints for", table2.name, error);
       }
     }
-    return () => null;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
 var IndexesGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("indexes");
+    super("index");
   }
   /**
    * 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;
+    for (const table2 of ctx.tables) {
+      table2.indexes = await this.getIndexes(table2.name);
+      for (const index2 of table2.indexes ?? []) {
+        for (const colName of index2.columns) {
+          const column2 = table2.columns.find((c) => c.name === colName);
+          if (column2) {
+            column2.isIndexed = true;
           }
         }
       }
     }
-    return () => null;
   }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
 var InfoGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("dialect_info");
+    super("dialectInfo");
   }
   /**
    * Execute the grounding process.
@@ -181,17 +414,6 @@ var InfoGrounding = class extends AbstractGrounding {
    */
   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");
   }
 };
 
@@ -199,7 +421,7 @@ var InfoGrounding = class extends AbstractGrounding {
 var ColumnValuesGrounding = class extends AbstractGrounding {
   lowCardinalityLimit;
   constructor(config = {}) {
-    super("column_values");
+    super("columnValues");
     this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
   }
   /**
@@ -217,14 +439,14 @@ var ColumnValuesGrounding = class extends AbstractGrounding {
    * - CHECK ((status)::text = ANY (ARRAY['a'::text, 'b'::text]))
    * - CHECK (status = 'active' OR status = 'inactive')
    */
-  parseCheckConstraint(constraint, columnName) {
-    if (constraint.type !== "CHECK" || !constraint.definition) {
+  parseCheckConstraint(constraint2, columnName) {
+    if (constraint2.type !== "CHECK" || !constraint2.definition) {
       return void 0;
     }
-    if (constraint.columns && !constraint.columns.includes(columnName)) {
+    if (constraint2.columns && !constraint2.columns.includes(columnName)) {
       return void 0;
     }
-    const def = constraint.definition;
+    const def = constraint2.definition;
     const escapedCol = this.escapeRegex(columnName);
     const colPattern = `(?:\\(?\\(?${escapedCol}\\)?(?:::(?:text|varchar|character varying))?\\)?)`;
     const inMatch = def.match(
@@ -282,55 +504,51 @@ var ColumnValuesGrounding = class extends AbstractGrounding {
   async execute(ctx) {
     const allContainers = [...ctx.tables, ...ctx.views];
     for (const container of allContainers) {
-      const table = this.getTable(ctx, container.name);
-      for (const column of container.columns) {
+      const table2 = this.getTable(ctx, container.name);
+      for (const column2 of container.columns) {
         try {
           const result = await this.resolveColumnValues(
             container.name,
-            column,
-            table?.constraints
+            column2,
+            table2?.constraints
           );
           if (result) {
-            column.kind = result.kind;
-            column.values = result.values;
+            column2.kind = result.kind;
+            column2.values = result.values;
           }
         } catch (error) {
           console.warn(
             "Error collecting column values for",
             container.name,
-            column.name,
+            column2.name,
             error
           );
         }
       }
     }
-    return () => this.#describe();
   }
   /**
    * Resolve column values from all sources in priority order.
    */
-  async resolveColumnValues(tableName, column, constraints2) {
-    const enumValues = await this.collectEnumValues(tableName, column);
+  async resolveColumnValues(tableName, column2, constraints2) {
+    const enumValues = await this.collectEnumValues(tableName, column2);
     if (enumValues?.length) {
       return { kind: "Enum", values: enumValues };
     }
     if (constraints2) {
-      for (const constraint of constraints2) {
-        const checkValues = this.parseCheckConstraint(constraint, column.name);
+      for (const constraint2 of constraints2) {
+        const checkValues = this.parseCheckConstraint(constraint2, column2.name);
         if (checkValues?.length) {
           return { kind: "Enum", values: checkValues };
         }
       }
     }
-    const lowCardValues = await this.collectLowCardinality(tableName, column);
+    const lowCardValues = await this.collectLowCardinality(tableName, column2);
     if (lowCardValues?.length) {
       return { kind: "LowCardinality", values: lowCardValues };
     }
     return void 0;
   }
-  #describe() {
-    return null;
-  }
 };
 
 // packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
@@ -402,7 +620,7 @@ var ReportGrounding = class extends AbstractGrounding {
       const cached = await this.#cache.get();
       if (cached) {
         ctx.report = cached;
-        return () => cached;
+        return;
       }
     }
     const report2 = await this.#generateReport();
@@ -410,7 +628,6 @@ var ReportGrounding = class extends AbstractGrounding {
     if (this.#cache) {
       await this.#cache.set(report2);
     }
-    return () => report2;
   }
   async #generateReport() {
     const { text } = await generate(
@@ -429,21 +646,20 @@ var ReportGrounding = class extends AbstractGrounding {
 // packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
 var RowCountGrounding = class extends AbstractGrounding {
   constructor(config = {}) {
-    super("row_counts");
+    super("rowCount");
   }
   /**
    * 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);
+    for (const table2 of ctx.tables) {
+      const count = await this.getRowCount(table2.name);
       if (count != null) {
-        table.rowCount = count;
-        table.sizeHint = this.#classifyRowCount(count);
+        table2.rowCount = count;
+        table2.sizeHint = this.#classifyRowCount(count);
       }
     }
-    return () => null;
   }
   /**
    * Classify row count into a size hint category.
@@ -458,13 +674,12 @@ var RowCountGrounding = class extends AbstractGrounding {
 };
 
 // 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");
+    super("table");
     this.#filter = config.filter;
     this.#forward = config.forward;
     this.#backward = config.backward;
@@ -482,7 +697,7 @@ var TableGrounding = class extends AbstractGrounding {
         seedTables.map((name) => this.getTable(name))
       );
       ctx.tables.push(...tables3);
-      return () => this.#describeTables(tables3);
+      return;
     }
     const tables2 = {};
     const allRelationships = [];
@@ -538,7 +753,6 @@ var TableGrounding = class extends AbstractGrounding {
     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.
@@ -568,156 +782,6 @@ var TableGrounding = class extends AbstractGrounding {
       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 notNullColumns = new Set(
-        table.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
-      );
-      const defaultByColumn = /* @__PURE__ */ new Map();
-      for (const c of table.constraints?.filter(
-        (c2) => c2.type === "DEFAULT"
-      ) ?? []) {
-        for (const col of c.columns ?? []) {
-          if (c.defaultValue != null) {
-            defaultByColumn.set(col, c.defaultValue);
-          }
-        }
-      }
-      const uniqueColumns = new Set(
-        table.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
-      );
-      const fkByColumn = /* @__PURE__ */ new Map();
-      for (const c of table.constraints?.filter(
-        (c2) => c2.type === "FOREIGN_KEY"
-      ) ?? []) {
-        const cols = c.columns ?? [];
-        const refCols = c.referencedColumns ?? [];
-        for (let i = 0; i < cols.length; i++) {
-          const refCol = refCols[i] ?? refCols[0] ?? cols[i];
-          fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
-        }
-      }
-      const columns = table.columns.map((column) => {
-        const annotations = [];
-        const isPrimaryKey = pkColumns.has(column.name);
-        if (isPrimaryKey) {
-          annotations.push("PK");
-        }
-        if (fkByColumn.has(column.name)) {
-          annotations.push(`FK -> ${fkByColumn.get(column.name)}`);
-        }
-        if (uniqueColumns.has(column.name)) {
-          annotations.push("UNIQUE");
-        }
-        if (notNullColumns.has(column.name)) {
-          annotations.push("NOT NULL");
-        }
-        if (defaultByColumn.has(column.name)) {
-          annotations.push(`DEFAULT: ${defaultByColumn.get(column.name)}`);
-        }
-        if (column.isIndexed && !isPrimaryKey) {
-          annotations.push("Indexed");
-        }
-        if (column.kind === "Enum" && column.values?.length) {
-          annotations.push(`Enum: ${column.values.join(", ")}`);
-        } else 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")}` : "";
-      const multiColumnUniques = table.constraints?.filter(
-        (c) => c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
-      ) ?? [];
-      const uniqueConstraints = multiColumnUniques.length ? `
-  Unique Constraints:
-${multiColumnUniques.map((c) => `    - ${c.name}: (${c.columns?.join(", ")})`).join("\n")}` : "";
-      const checkConstraints = table.constraints?.filter((c) => c.type === "CHECK") ?? [];
-      const checks = checkConstraints.length ? `
-  Check Constraints:
-${checkConstraints.map((c) => `    - ${c.name}: ${c.definition}`).join("\n")}` : "";
-      return `- Table: ${table.name}${rowCountInfo}
-  Columns:
-${columns}${indexes2}${uniqueConstraints}${checks}`;
-    }).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
@@ -727,13 +791,13 @@ var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
     super(config);
     this.#adapter = adapter;
   }
-  async collectStats(tableName, column) {
-    if (!this.#shouldCollectStats(column.type)) {
+  async collectStats(tableName, column2) {
+    if (!this.#shouldCollectStats(column2.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 { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
     const sql = `
       SELECT
         MIN(${columnIdentifier})::text AS min_value,
@@ -776,7 +840,7 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
     this.#adapter = adapter;
   }
   async getConstraints(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const constraints2 = [];
     const constraintRows = await this.#adapter.runQuery(`
       SELECT
@@ -797,7 +861,7 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
       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 rel.relname = '${this.#adapter.escapeString(table2)}'
         AND con.contype IN ('p', 'f', 'c', 'u')
       ORDER BY con.conname, key.ord
     `);
@@ -860,21 +924,21 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
         is_nullable
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
-        AND table_name = '${this.#adapter.escapeString(table)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
     `);
     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`,
+          name: `${table2}_${col.column_name}_notnull`,
           type: "NOT_NULL",
           columns: [col.column_name]
         });
       }
       if (col.column_default != null) {
         constraints2.push({
-          name: `${table}_${col.column_name}_default`,
+          name: `${table2}_${col.column_name}_default`,
           type: "DEFAULT",
           columns: [col.column_name],
           defaultValue: col.column_default
@@ -895,7 +959,7 @@ var PostgresIndexesGrounding = class extends IndexesGrounding {
     this.#schemas = config.schemas;
   }
   async getIndexes(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT
         i.relname AS index_name,
@@ -910,7 +974,7 @@ var PostgresIndexesGrounding = class extends IndexesGrounding {
       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)}'
+        AND t.relname = '${this.#adapter.escapeString(table2)}'
       ORDER BY i.relname, array_position(ix.indkey, a.attnum)
     `);
     return this.#groupIndexes(rows);
@@ -999,18 +1063,18 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
     }
     this.#enumCacheLoaded = true;
   }
-  async collectEnumValues(tableName, column) {
-    if (column.type.toLowerCase() !== "user-defined") {
+  async collectEnumValues(tableName, column2) {
+    if (column2.type.toLowerCase() !== "user-defined") {
       return void 0;
     }
     await this.#loadEnumCache();
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT udt_name, udt_schema
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
-        AND table_name = '${this.#adapter.escapeString(table)}'
-        AND column_name = '${this.#adapter.escapeString(column.name)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
+        AND column_name = '${this.#adapter.escapeString(column2.name)}'
     `);
     if (!rows.length) {
       return void 0;
@@ -1020,10 +1084,10 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
     const values = this.#enumCache.get(fullKey) ?? this.#enumCache.get(udt_name);
     return values?.length ? values : void 0;
   }
-  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);
+  async collectLowCardinality(tableName, column2) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
     const limit = this.lowCardinalityLimit + 1;
     const sql = `
       SELECT DISTINCT ${columnIdentifier}::text AS value
@@ -1132,8 +1196,8 @@ var Postgres = class extends Adapter {
     return value.replace(/"/g, '""');
   }
   buildSampleRowsQuery(tableName, columns, limit) {
-    const { schema, table } = this.parseTableName(tableName);
-    const tableIdentifier = schema ? `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table)}` : this.quoteIdentifier(table);
+    const { schema, table: table2 } = this.parseTableName(tableName);
+    const tableIdentifier = schema ? `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table2)}` : this.quoteIdentifier(table2);
     const columnList = columns?.length ? columns.map((c) => this.quoteIdentifier(c)).join(", ") : "*";
     return `SELECT ${columnList} FROM ${tableIdentifier} LIMIT ${limit}`;
   }
@@ -1160,17 +1224,17 @@ var Postgres = class extends Adapter {
       const schema = row.table_schema ?? "public";
       const tableName = row.table_name;
       const qualifiedName = `${schema}.${tableName}`;
-      const table = tables2.get(qualifiedName) ?? {
+      const table2 = tables2.get(qualifiedName) ?? {
         name: qualifiedName,
         schema,
         rawName: tableName,
         columns: []
       };
-      table.columns.push({
+      table2.columns.push({
         name: row.column_name ?? "unknown",
         type: row.data_type ?? "unknown"
       });
-      tables2.set(qualifiedName, table);
+      tables2.set(qualifiedName, table2);
     }
     return Array.from(tables2.values());
   }
@@ -1205,26 +1269,26 @@ var Postgres = class extends Adapter {
       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) ?? {
+      const relationship2 = 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);
+      relationship2.from.push(row.column_name ?? "unknown");
+      relationship2.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship2);
     }
     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);
+      const table2 = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table2);
       onProgress?.({
         phase: "row_counts",
-        message: `Counting rows in ${table.name}...`,
+        message: `Counting rows in ${table2.name}...`,
         current: i + 1,
         total
       });
@@ -1232,8 +1296,8 @@ var Postgres = class extends Adapter {
         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);
+          table2.rowCount = rowCount2;
+          table2.sizeHint = this.#classifyRowCount(rowCount2);
         }
       } catch {
         continue;
@@ -1250,7 +1314,7 @@ var Postgres = class extends Adapter {
     if (!tables2.length) {
       return;
     }
-    const tableMap = new Map(tables2.map((table) => [table.name, table]));
+    const tableMap = new Map(tables2.map((table2) => [table2.name, table2]));
     const rows = await this.#runIntrospectionQuery(`
       SELECT
         n.nspname AS table_schema,
@@ -1279,32 +1343,32 @@ var Postgres = class extends Adapter {
       }
       const schema = row.table_schema ?? "public";
       const tableKey = `${schema}.${row.table_name}`;
-      const table = tableMap.get(tableKey);
-      if (!table) {
+      const table2 = tableMap.get(tableKey);
+      if (!table2) {
         continue;
       }
       const indexKey = `${tableKey}:${row.index_name}`;
-      let index = indexMap.get(indexKey);
-      if (!index) {
-        index = {
+      let index2 = indexMap.get(indexKey);
+      if (!index2) {
+        index2 = {
           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 = [];
+        indexMap.set(indexKey, index2);
+        if (!table2.indexes) {
+          table2.indexes = [];
         }
-        table.indexes.push(index);
+        table2.indexes.push(index2);
       }
       if (row.column_name) {
-        index.columns.push(row.column_name);
-        const column = table.columns.find(
+        index2.columns.push(row.column_name);
+        const column2 = table2.columns.find(
           (col) => col.name === row.column_name
         );
-        if (column) {
-          column.isIndexed = true;
+        if (column2) {
+          column2.isIndexed = true;
         }
       }
     }
@@ -1315,19 +1379,19 @@ var Postgres = class extends Adapter {
     }
     const total = tables2.length;
     for (let i = 0; i < tables2.length; i++) {
-      const table = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table);
+      const table2 = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table2);
       onProgress?.({
         phase: "column_stats",
-        message: `Collecting stats for ${table.name}...`,
+        message: `Collecting stats for ${table2.name}...`,
         current: i + 1,
         total
       });
-      for (const column of table.columns) {
-        if (!this.#shouldCollectStats(column.type)) {
+      for (const column2 of table2.columns) {
+        if (!this.#shouldCollectStats(column2.type)) {
           continue;
         }
-        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const columnIdentifier = this.#quoteIdentifier(column2.name);
         const sql = `
           SELECT
             MIN(${columnIdentifier})::text AS min_value,
@@ -1344,7 +1408,7 @@ var Postgres = class extends Adapter {
           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 = {
+            column2.stats = {
               min,
               max,
               nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
@@ -1359,16 +1423,16 @@ var Postgres = class extends Adapter {
   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);
+      const table2 = tables2[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table2);
       onProgress?.({
         phase: "low_cardinality",
-        message: `Analyzing cardinality in ${table.name}...`,
+        message: `Analyzing cardinality in ${table2.name}...`,
         current: i + 1,
         total
       });
-      for (const column of table.columns) {
-        const columnIdentifier = this.#quoteIdentifier(column.name);
+      for (const column2 of table2.columns) {
+        const columnIdentifier = this.#quoteIdentifier(column2.name);
         const limit = LOW_CARDINALITY_LIMIT + 1;
         const sql = `
           SELECT DISTINCT ${columnIdentifier} AS value
@@ -1398,8 +1462,8 @@ var Postgres = class extends Adapter {
         if (shouldSkip || !values.length) {
           continue;
         }
-        column.kind = "LowCardinality";
-        column.values = values;
+        column2.kind = "LowCardinality";
+        column2.values = values;
       }
     }
   }
@@ -1454,19 +1518,19 @@ var Postgres = class extends Adapter {
   #quoteIdentifier(name) {
     return `"${name.replace(/"/g, '""')}"`;
   }
-  #formatQualifiedTableName(table) {
-    if (table.schema && table.rawName) {
-      return `${this.#quoteIdentifier(table.schema)}.${this.#quoteIdentifier(table.rawName)}`;
+  #formatQualifiedTableName(table2) {
+    if (table2.schema && table2.rawName) {
+      return `${this.#quoteIdentifier(table2.schema)}.${this.#quoteIdentifier(table2.rawName)}`;
     }
-    if (table.name.includes(".")) {
-      const [schemaPart, ...rest] = table.name.split(".");
+    if (table2.name.includes(".")) {
+      const [schemaPart, ...rest] = table2.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);
+    return this.#quoteIdentifier(table2.name);
   }
   #toNumber(value) {
     if (typeof value === "number" && Number.isFinite(value)) {
@@ -1536,8 +1600,8 @@ var PostgresRowCountGrounding = class extends RowCountGrounding {
     this.#adapter = adapter;
   }
   async getRowCount(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table)}`;
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
     const rows = await this.#adapter.runQuery(
       `SELECT COUNT(*) as count FROM ${tableIdentifier}`
     );
@@ -1565,18 +1629,18 @@ var PostgresTableGrounding = class extends TableGrounding {
     return rows.map((r) => r.name);
   }
   async getTable(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = 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)}'
+        AND table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY ordinal_position
     `);
     return {
       name: tableName,
       schema,
-      rawName: table,
+      rawName: table2,
       columns: columns.map((col) => ({
         name: col.column_name ?? "unknown",
         type: col.data_type ?? "unknown"
@@ -1584,7 +1648,7 @@ var PostgresTableGrounding = class extends TableGrounding {
     };
   }
   async findOutgoingRelations(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT
         tc.constraint_name,
@@ -1603,13 +1667,13 @@ var PostgresTableGrounding = class extends TableGrounding {
         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)}'
+        AND tc.table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY tc.constraint_name, kcu.ordinal_position
     `);
     return this.#groupRelationships(rows);
   }
   async findIncomingRelations(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const rows = await this.#adapter.runQuery(`
       SELECT
         tc.constraint_name,
@@ -1628,7 +1692,7 @@ var PostgresTableGrounding = class extends TableGrounding {
         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)}'
+        AND ccu.table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY tc.constraint_name, kcu.ordinal_position
     `);
     return this.#groupRelationships(rows);
@@ -1643,15 +1707,15 @@ var PostgresTableGrounding = class extends TableGrounding {
       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) ?? {
+      const relationship2 = 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);
+      relationship2.from.push(row.column_name ?? "unknown");
+      relationship2.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship2);
     }
     return Array.from(relationships.values());
   }
@@ -1661,7 +1725,7 @@ var PostgresTableGrounding = class extends TableGrounding {
 var ViewGrounding = class extends AbstractGrounding {
   #filter;
   constructor(config = {}) {
-    super("views");
+    super("view");
     this.#filter = config.filter;
   }
   /**
@@ -1674,42 +1738,6 @@ var ViewGrounding = class extends AbstractGrounding {
       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.
@@ -1751,24 +1779,24 @@ var PostgresViewGrounding = class extends ViewGrounding {
     return rows.map((r) => r.name);
   }
   async getView(viewName) {
-    const { schema, table: view } = this.#adapter.parseTableName(viewName);
+    const { schema, table: view2 } = 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)}'
+        AND viewname = '${this.#adapter.escapeString(view2)}'
     `);
     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)}'
+        AND table_name = '${this.#adapter.escapeString(view2)}'
       ORDER BY ordinal_position
     `);
     return {
       name: viewName,
       schema,
-      rawName: view,
+      rawName: view2,
       definition: defRows[0]?.definition ?? void 0,
       columns: columns.map((col) => ({
         name: col.column_name ?? "unknown",