@deepagents/text2sql 0.10.1 → 0.11.0

package/dist/lib/adapters/mysql/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);
+        }
       }
-      return `<${tag}>
-${description}
-</${tag}>`;
-    }).join("\n");
+    }
+    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 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,26 +340,22 @@ 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;
   }
 };
 
@@ -128,7 +363,7 @@ var ColumnStatsGrounding = class extends AbstractGrounding {
 var ColumnValuesGrounding = class extends AbstractGrounding {
   lowCardinalityLimit;
   constructor(config = {}) {
-    super("column_values");
+    super("columnValues");
     this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
   }
   /**
@@ -146,14 +381,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(
@@ -211,107 +446,101 @@ 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/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.
@@ -319,17 +548,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");
   }
 };
 
@@ -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/mysql/column-stats.mysql.grounding.ts
@@ -727,14 +791,14 @@ var MysqlColumnStatsGrounding = 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 { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const database = schema || await this.#getCurrentDatabase();
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table)}`;
-    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table2)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
     try {
       const rows = await this.#adapter.runQuery(`
         SELECT
@@ -801,15 +865,15 @@ var MysqlColumnValuesGrounding = class extends ColumnValuesGrounding {
   /**
    * Detect native MySQL ENUM types and extract their values.
    */
-  async collectEnumValues(tableName, column) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+  async collectEnumValues(tableName, column2) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const database = schema || await this.#getCurrentDatabase();
     const rows = await this.#adapter.runQuery(`
       SELECT COLUMN_TYPE
       FROM INFORMATION_SCHEMA.COLUMNS
       WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        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)}'
     `);
     const columnType = rows[0]?.COLUMN_TYPE;
     if (!columnType) return void 0;
@@ -820,11 +884,11 @@ var MysqlColumnValuesGrounding = class extends ColumnValuesGrounding {
   /**
    * Collect distinct values for low cardinality columns.
    */
-  async collectLowCardinality(tableName, column) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+  async collectLowCardinality(tableName, column2) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const database = schema || await this.#getCurrentDatabase();
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table)}`;
-    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table2)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
     const limit = this.lowCardinalityLimit + 1;
     try {
       const rows = await this.#adapter.runQuery(`
@@ -901,7 +965,7 @@ var MysqlConstraintGrounding = 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 database = schema || await this.#getCurrentDatabase();
     const constraints2 = [];
     const constraintRows = await this.#adapter.runQuery(`
@@ -918,7 +982,7 @@ var MysqlConstraintGrounding = class extends ConstraintGrounding {
         AND tc.TABLE_SCHEMA = kcu.TABLE_SCHEMA
         AND tc.TABLE_NAME = kcu.TABLE_NAME
       WHERE tc.TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND tc.TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND tc.TABLE_NAME = '${this.#adapter.escapeString(table2)}'
         AND tc.CONSTRAINT_TYPE IN ('PRIMARY KEY', 'UNIQUE', 'FOREIGN KEY')
       ORDER BY tc.CONSTRAINT_NAME, kcu.ORDINAL_POSITION
     `);
@@ -961,7 +1025,7 @@ var MysqlConstraintGrounding = class extends ConstraintGrounding {
       SELECT COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT
       FROM INFORMATION_SCHEMA.COLUMNS
       WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table2)}'
     `);
     const pkConstraint = constraints2.find((c) => c.type === "PRIMARY_KEY");
     const pkColumns = new Set(pkConstraint?.columns ?? []);
@@ -993,7 +1057,7 @@ var MysqlConstraintGrounding = class extends ConstraintGrounding {
         SELECT CONSTRAINT_NAME, TABLE_NAME
         FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS
         WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-          AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+          AND TABLE_NAME = '${this.#adapter.escapeString(table2)}'
           AND CONSTRAINT_TYPE = 'CHECK'
       `);
       const checkTableMap = new Map(
@@ -1001,7 +1065,7 @@ var MysqlConstraintGrounding = class extends ConstraintGrounding {
       );
       for (const row of checkRows) {
         if (!row.CONSTRAINT_NAME) continue;
-        if (checkTableMap.get(row.CONSTRAINT_NAME) !== table) continue;
+        if (checkTableMap.get(row.CONSTRAINT_NAME) !== table2) continue;
         constraints2.push({
           name: row.CONSTRAINT_NAME,
           type: "CHECK",
@@ -1040,7 +1104,7 @@ var MysqlIndexesGrounding = class extends IndexesGrounding {
     this.#adapter = adapter;
   }
   async getIndexes(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const database = schema || await this.#getCurrentDatabase();
     const rows = await this.#adapter.runQuery(`
       SELECT
@@ -1051,24 +1115,24 @@ var MysqlIndexesGrounding = class extends IndexesGrounding {
         SEQ_IN_INDEX
       FROM INFORMATION_SCHEMA.STATISTICS
       WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table2)}'
       ORDER BY INDEX_NAME, SEQ_IN_INDEX
     `);
     const indexMap = /* @__PURE__ */ new Map();
     for (const row of rows) {
       if (!row.INDEX_NAME) continue;
-      let index = indexMap.get(row.INDEX_NAME);
-      if (!index) {
-        index = {
+      let index2 = indexMap.get(row.INDEX_NAME);
+      if (!index2) {
+        index2 = {
           name: row.INDEX_NAME,
           columns: [],
           unique: row.NON_UNIQUE === 0,
           type: row.INDEX_TYPE ?? void 0
         };
-        indexMap.set(row.INDEX_NAME, index);
+        indexMap.set(row.INDEX_NAME, index2);
       }
       if (row.COLUMN_NAME) {
-        index.columns.push(row.COLUMN_NAME);
+        index2.columns.push(row.COLUMN_NAME);
       }
     }
     return Array.from(indexMap.values());
@@ -1209,8 +1273,8 @@ var Mysql = 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}`;
   }
@@ -1245,9 +1309,9 @@ var MysqlRowCountGrounding = class extends RowCountGrounding {
     this.#adapter = adapter;
   }
   async getRowCount(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const database = schema || await this.#getCurrentDatabase();
-    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table)}`;
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table2)}`;
     try {
       const rows = await this.#adapter.runQuery(`SELECT COUNT(*) AS count FROM ${tableIdentifier}`);
       return this.#toNumber(rows[0]?.count);
@@ -1296,19 +1360,19 @@ var MysqlTableGrounding = 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 database = schema || await this.#getCurrentDatabase();
     const columns = await this.#adapter.runQuery(`
       SELECT COLUMN_NAME, DATA_TYPE, COLUMN_TYPE
       FROM INFORMATION_SCHEMA.COLUMNS
       WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table2)}'
       ORDER BY ORDINAL_POSITION
     `);
     return {
       name: tableName,
       schema: database,
-      rawName: table,
+      rawName: table2,
       columns: columns.map((col) => ({
         name: col.COLUMN_NAME ?? "unknown",
         type: col.DATA_TYPE ?? "unknown"
@@ -1316,7 +1380,7 @@ var MysqlTableGrounding = class extends TableGrounding {
     };
   }
   async findOutgoingRelations(tableName) {
-    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const database = schema || await this.#getCurrentDatabase();
     const rows = await this.#adapter.runQuery(`
       SELECT
@@ -1329,14 +1393,14 @@ var MysqlTableGrounding = class extends TableGrounding {
         kcu.REFERENCED_COLUMN_NAME
       FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
       WHERE kcu.TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND kcu.TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND kcu.TABLE_NAME = '${this.#adapter.escapeString(table2)}'
         AND kcu.REFERENCED_TABLE_NAME IS NOT NULL
       ORDER BY kcu.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 database = schema || await this.#getCurrentDatabase();
     const rows = await this.#adapter.runQuery(`
       SELECT
@@ -1349,7 +1413,7 @@ var MysqlTableGrounding = class extends TableGrounding {
         kcu.REFERENCED_COLUMN_NAME
       FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
       WHERE kcu.REFERENCED_TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND kcu.REFERENCED_TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND kcu.REFERENCED_TABLE_NAME = '${this.#adapter.escapeString(table2)}'
       ORDER BY kcu.CONSTRAINT_NAME, kcu.ORDINAL_POSITION
     `);
     return this.#groupRelationships(rows);
@@ -1363,15 +1427,15 @@ var MysqlTableGrounding = class extends TableGrounding {
       const schema = row.TABLE_SCHEMA ?? "";
       const referencedSchema = row.REFERENCED_TABLE_SCHEMA ?? "";
       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.REFERENCED_TABLE_NAME}`,
         to: []
       };
-      relationship.from.push(row.COLUMN_NAME ?? "unknown");
-      relationship.to.push(row.REFERENCED_COLUMN_NAME ?? "unknown");
-      relationships.set(key, relationship);
+      relationship2.from.push(row.COLUMN_NAME ?? "unknown");
+      relationship2.to.push(row.REFERENCED_COLUMN_NAME ?? "unknown");
+      relationships.set(key, relationship2);
     }
     return Array.from(relationships.values());
   }
@@ -1395,7 +1459,7 @@ var MysqlTableGrounding = class extends TableGrounding {
 var ViewGrounding = class extends AbstractGrounding {
   #filter;
   constructor(config = {}) {
-    super("views");
+    super("view");
     this.#filter = config.filter;
   }
   /**
@@ -1408,42 +1472,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.
@@ -1485,25 +1513,25 @@ var MysqlViewGrounding = class extends ViewGrounding {
     return rows.map((r) => r.name);
   }
   async getView(viewName) {
-    const { schema, table } = this.#adapter.parseTableName(viewName);
+    const { schema, table: table2 } = this.#adapter.parseTableName(viewName);
     const database = schema || await this.#getCurrentDatabase();
     const columns = await this.#adapter.runQuery(`
       SELECT COLUMN_NAME, DATA_TYPE
       FROM INFORMATION_SCHEMA.COLUMNS
       WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table2)}'
       ORDER BY ORDINAL_POSITION
     `);
     const viewRows = await this.#adapter.runQuery(`
       SELECT VIEW_DEFINITION
       FROM INFORMATION_SCHEMA.VIEWS
       WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
-        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table2)}'
     `);
     return {
       name: viewName,
       schema: database,
-      rawName: table,
+      rawName: table2,
       definition: viewRows[0]?.VIEW_DEFINITION ?? void 0,
       columns: columns.map((col) => ({
         name: col.COLUMN_NAME ?? "unknown",