@deepagents/text2sql 0.9.0 → 0.10.1

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

@@ -0,0 +1,1231 @@
+// 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(ctx = createGroundingContext()) {
+    const lines = [];
+    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/groundings/abstract.grounding.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/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/column-values.grounding.ts
+var ColumnValuesGrounding = class extends AbstractGrounding {
+  lowCardinalityLimit;
+  constructor(config = {}) {
+    super("column_values");
+    this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
+  }
+  /**
+   * Get values for native ENUM type columns.
+   * Return undefined if column is not an ENUM type.
+   * Default implementation returns undefined (no native ENUM support).
+   */
+  async collectEnumValues(_tableName, _column) {
+    return void 0;
+  }
+  /**
+   * Parse CHECK constraint for enum-like IN clause.
+   * Extracts values from patterns like:
+   * - CHECK (status IN ('active', 'inactive'))
+   * - CHECK ((status)::text = ANY (ARRAY['a'::text, 'b'::text]))
+   * - CHECK (status = 'active' OR status = 'inactive')
+   */
+  parseCheckConstraint(constraint, columnName) {
+    if (constraint.type !== "CHECK" || !constraint.definition) {
+      return void 0;
+    }
+    if (constraint.columns && !constraint.columns.includes(columnName)) {
+      return void 0;
+    }
+    const def = constraint.definition;
+    const escapedCol = this.escapeRegex(columnName);
+    const colPattern = `(?:\\(?\\(?${escapedCol}\\)?(?:::(?:text|varchar|character varying))?\\)?)`;
+    const inMatch = def.match(
+      new RegExp(`${colPattern}\\s+IN\\s*\\(([^)]+)\\)`, "i")
+    );
+    if (inMatch) {
+      return this.extractStringValues(inMatch[1]);
+    }
+    const anyMatch = def.match(
+      new RegExp(
+        `${colPattern}\\s*=\\s*ANY\\s*\\(\\s*(?:ARRAY)?\\s*\\[([^\\]]+)\\]`,
+        "i"
+      )
+    );
+    if (anyMatch) {
+      return this.extractStringValues(anyMatch[1]);
+    }
+    const orPattern = new RegExp(
+      `\\b${this.escapeRegex(columnName)}\\b\\s*=\\s*'([^']*)'`,
+      "gi"
+    );
+    const orMatches = [...def.matchAll(orPattern)];
+    if (orMatches.length >= 2) {
+      return orMatches.map((m) => m[1]);
+    }
+    return void 0;
+  }
+  /**
+   * Extract string values from a comma-separated list.
+   */
+  extractStringValues(input) {
+    const values = [];
+    const matches = input.matchAll(/'([^']*)'/g);
+    for (const match of matches) {
+      values.push(match[1]);
+    }
+    return values.length > 0 ? values : void 0;
+  }
+  /**
+   * Escape special regex characters in a string.
+   */
+  escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  /**
+   * Get the table from context by name.
+   */
+  getTable(ctx, name) {
+    return ctx.tables.find((t) => t.name === name);
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with values.
+   */
+  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) {
+        try {
+          const result = await this.resolveColumnValues(
+            container.name,
+            column,
+            table?.constraints
+          );
+          if (result) {
+            column.kind = result.kind;
+            column.values = result.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting column values for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  /**
+   * Resolve column values from all sources in priority order.
+   */
+  async resolveColumnValues(tableName, column, constraints) {
+    const enumValues = await this.collectEnumValues(tableName, column);
+    if (enumValues?.length) {
+      return { kind: "Enum", values: enumValues };
+    }
+    if (constraints) {
+      for (const constraint of constraints) {
+        const checkValues = this.parseCheckConstraint(constraint, column.name);
+        if (checkValues?.length) {
+          return { kind: "Enum", values: checkValues };
+        }
+      }
+    }
+    const lowCardValues = await this.collectLowCardinality(tableName, column);
+    if (lowCardValues?.length) {
+      return { kind: "LowCardinality", values: lowCardValues };
+    }
+    return void 0;
+  }
+  #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 reportAgent = agent({
+  name: "db-report-agent",
+  model: groq("openai/gpt-oss-20b"),
+  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);
+      }
+    })
+  }
+});
+
+// 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 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 indexes = 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}${indexes}${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/sqlite/column-stats.sqlite.grounding.ts
+var SqliteColumnStatsGrounding = 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 tableIdentifier = this.#adapter.quoteIdentifier(tableName);
+    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const sql = `
+      SELECT
+        MIN(${columnIdentifier}) AS min_value,
+        MAX(${columnIdentifier}) 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 = this.#normalizeValue(rows[0]?.min_value);
+    const max = this.#normalizeValue(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/.test(
+      normalized
+    );
+  }
+  #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/sqlite/info.sqlite.grounding.ts
+var SqliteInfoGrounding = class extends InfoGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectInfo() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT sqlite_version() AS version"
+    );
+    return {
+      dialect: "sqlite",
+      version: rows[0]?.version,
+      details: {
+        parameterPlaceholder: "?"
+      }
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/column-values.sqlite.grounding.ts
+var SqliteColumnValuesGrounding = class extends ColumnValuesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectLowCardinality(tableName, column) {
+    const tableIdentifier = this.#adapter.quoteIdentifier(tableName);
+    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const limit = this.lowCardinalityLimit + 1;
+    const sql = `
+      SELECT DISTINCT ${columnIdentifier} AS value
+      FROM ${tableIdentifier}
+      WHERE ${columnIdentifier} IS NOT NULL
+      LIMIT ${limit}
+    `;
+    const rows = await this.#adapter.runQuery(sql);
+    if (!rows.length || rows.length > this.lowCardinalityLimit) {
+      return void 0;
+    }
+    const values = [];
+    for (const row of rows) {
+      const formatted = this.#normalizeValue(row.value);
+      if (formatted == null) {
+        return void 0;
+      }
+      values.push(formatted);
+    }
+    return values.length ? values : void 0;
+  }
+  #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/sqlite/row-count.sqlite.grounding.ts
+var SqliteRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getRowCount(tableName) {
+    const rows = await this.#adapter.runQuery(
+      `SELECT COUNT(*) as count FROM ${this.#adapter.quoteIdentifier(tableName)}`
+    );
+    return this.#adapter.toNumber(rows[0]?.count);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/sqlite.ts
+var SQL_ERROR_MAP = [
+  {
+    pattern: /^no such table: .+$/,
+    type: "MISSING_TABLE",
+    hint: "Check the database schema for the correct table name. The table you referenced does not exist."
+  },
+  {
+    pattern: /^no such column: .+$/,
+    type: "INVALID_COLUMN",
+    hint: "Check the table schema for correct column names. The column may not exist or is ambiguous (exists in multiple joined tables)."
+  },
+  {
+    pattern: /^ambiguous column name: .+$/,
+    type: "INVALID_COLUMN",
+    hint: "Check the table schema for correct column names. The column may not exist or is ambiguous (exists in multiple joined tables)."
+  },
+  {
+    pattern: /^near ".+": syntax error$/,
+    type: "SYNTAX_ERROR",
+    hint: "There is a SQL syntax error. Review the query structure, keywords, and punctuation."
+  },
+  {
+    pattern: /^no tables specified$/,
+    type: "SYNTAX_ERROR",
+    hint: "There is a SQL syntax error. Review the query structure, keywords, and punctuation."
+  },
+  {
+    pattern: /^attempt to write a readonly database$/,
+    type: "CONSTRAINT_ERROR",
+    hint: "A database constraint was violated. This should not happen with read-only queries."
+  }
+];
+function formatError(sql, error) {
+  const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error occurred";
+  const errorInfo = SQL_ERROR_MAP.find((it) => it.pattern.test(errorMessage));
+  if (!errorInfo) {
+    return {
+      error: errorMessage,
+      error_type: "UNKNOWN_ERROR",
+      suggestion: "Review the query and try again",
+      sql_attempted: sql
+    };
+  }
+  return {
+    error: errorMessage,
+    error_type: errorInfo.type,
+    suggestion: errorInfo.hint,
+    sql_attempted: sql
+  };
+}
+var Sqlite = class extends Adapter {
+  #options;
+  grounding;
+  defaultSchema = void 0;
+  systemSchemas = [];
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("Sqlite adapter requires an execute function.");
+    }
+    this.#options = options;
+    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(formatError(sql, error));
+    }
+  }
+  #quoteIdentifier(name) {
+    return `'${name.replace(/'/g, "''")}'`;
+  }
+  async runQuery(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(
+      "Sqlite adapter execute() must return an array of rows or an object with a rows array when introspecting."
+    );
+  }
+  quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+  }
+  escape(value) {
+    return value.replace(/"/g, '""');
+  }
+  buildSampleRowsQuery(tableName, columns, limit) {
+    const columnList = columns?.length ? columns.map((c) => this.quoteIdentifier(c)).join(", ") : "*";
+    return `SELECT ${columnList} FROM ${this.quoteIdentifier(tableName)} LIMIT ${limit}`;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/table.sqlite.grounding.ts
+var SqliteTableGrounding = class extends TableGrounding {
+  #adapter;
+  #relationshipCache = null;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getAllTableNames() {
+    const rows = await this.#adapter.runQuery(`SELECT name FROM sqlite_master WHERE type='table' ORDER BY name`);
+    return rows.map((row) => row.name).filter(
+      (name) => typeof name === "string" && !name.startsWith("sqlite_")
+    );
+  }
+  async getTable(tableName) {
+    const columns = await this.#adapter.runQuery(
+      `PRAGMA table_info(${this.#quoteIdentifier(tableName)})`
+    );
+    return {
+      name: tableName,
+      rawName: tableName,
+      columns: columns.map((col) => ({
+        name: col.name ?? "unknown",
+        type: col.type ?? "unknown"
+      }))
+    };
+  }
+  async findOutgoingRelations(tableName) {
+    const rows = await this.#adapter.runQuery(
+      `PRAGMA foreign_key_list(${this.#quoteIdentifier(tableName)})`
+    );
+    const groups = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (row.id == null || row.table == null || row.from == null || row.to == null) {
+        continue;
+      }
+      const id = Number(row.id);
+      const existing = groups.get(id);
+      if (!existing) {
+        groups.set(id, {
+          table: tableName,
+          from: [String(row.from)],
+          referenced_table: String(row.table),
+          to: [String(row.to)]
+        });
+      } else {
+        existing.from.push(String(row.from));
+        existing.to.push(String(row.to));
+      }
+    }
+    return Array.from(groups.values());
+  }
+  async findIncomingRelations(tableName) {
+    if (!this.#relationshipCache) {
+      this.#relationshipCache = await this.#loadAllRelationships();
+    }
+    return this.#relationshipCache.filter(
+      (r) => r.referenced_table === tableName
+    );
+  }
+  async #loadAllRelationships() {
+    const allNames = await this.getAllTableNames();
+    const results = [];
+    for (const name of allNames) {
+      results.push(...await this.findOutgoingRelations(name));
+    }
+    return results;
+  }
+  #quoteIdentifier(name) {
+    return `'${name.replace(/'/g, "''")}'`;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/index.ts
+function tables(config = {}) {
+  return (adapter) => new SqliteTableGrounding(adapter, config);
+}
+function info(config = {}) {
+  return (adapter) => new SqliteInfoGrounding(adapter, config);
+}
+function columnStats(config = {}) {
+  return (adapter) => {
+    return new SqliteColumnStatsGrounding(adapter, config);
+  };
+}
+function columnValues(config = {}) {
+  return (adapter) => {
+    return new SqliteColumnValuesGrounding(adapter, config);
+  };
+}
+function rowCount(config = {}) {
+  return (adapter) => {
+    return new SqliteRowCountGrounding(adapter, config);
+  };
+}
+
+// packages/text2sql/src/lib/adapters/spreadsheet/spreadsheet.ts
+import { DatabaseSync } from "node:sqlite";
+
+// packages/text2sql/src/lib/adapters/spreadsheet/parser.ts
+import * as path from "node:path";
+import XLSX from "xlsx";
+function parseFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  let workbook;
+  try {
+    workbook = XLSX.readFile(filePath, {
+      cellDates: true
+      // Parse dates as Date objects
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read spreadsheet "${filePath}": ${message}`);
+  }
+  const sheets = [];
+  for (const sheetName of workbook.SheetNames) {
+    const sheet = workbook.Sheets[sheetName];
+    const rows = XLSX.utils.sheet_to_json(sheet);
+    if (rows.length === 0) {
+      continue;
+    }
+    const tableName = ext === ".csv" || ext === ".tsv" ? getTableNameFromFile(filePath) : sanitizeTableName(sheetName);
+    const columns = inferColumns(rows);
+    if (columns.length === 0) {
+      continue;
+    }
+    sheets.push({
+      name: tableName,
+      columns,
+      rows
+    });
+  }
+  if (sheets.length === 0) {
+    throw new Error(
+      `No valid sheets found in "${filePath}". All sheets are empty or have no columns.`
+    );
+  }
+  return sheets;
+}
+function getTableNameFromFile(filePath) {
+  const basename2 = path.basename(filePath, path.extname(filePath));
+  return sanitizeTableName(basename2);
+}
+function sanitizeIdentifier(name) {
+  let sanitized = name.toLowerCase();
+  sanitized = sanitized.replace(/[^a-z0-9_]/g, "_");
+  sanitized = sanitized.replace(/_+/g, "_");
+  sanitized = sanitized.replace(/^_+|_+$/g, "");
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+  if (!sanitized) {
+    return "column";
+  }
+  return sanitized.slice(0, 64);
+}
+var sanitizeTableName = sanitizeIdentifier;
+function inferColumns(rows) {
+  if (rows.length === 0) {
+    return [];
+  }
+  const keySet = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      keySet.add(key);
+    }
+  }
+  if (keySet.size === 0) {
+    return [];
+  }
+  const rawNames = Array.from(keySet);
+  const dedupedNames = deduplicateColumnNames(rawNames);
+  return dedupedNames.map((name, idx) => {
+    const originalKey = rawNames[idx];
+    const values = rows.map((row) => row[originalKey]);
+    const type = inferColumnType(values);
+    return { name, originalKey, type };
+  });
+}
+function deduplicateColumnNames(names) {
+  const seen = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const rawName of names) {
+    let name = sanitizeTableName(rawName);
+    if (!name) {
+      name = "column";
+    }
+    const count = seen.get(name) ?? 0;
+    if (count > 0) {
+      result.push(`${name}_${count + 1}`);
+    } else {
+      result.push(name);
+    }
+    seen.set(name, count + 1);
+  }
+  return result;
+}
+function inferColumnType(values) {
+  let hasInteger = false;
+  let hasReal = false;
+  for (const value of values) {
+    if (value == null || value === "") {
+      continue;
+    }
+    if (value instanceof Date) {
+      return "TEXT";
+    }
+    if (typeof value === "number") {
+      if (Number.isInteger(value)) {
+        hasInteger = true;
+      } else {
+        hasReal = true;
+      }
+    } else if (typeof value === "boolean") {
+      hasInteger = true;
+    } else {
+      return "TEXT";
+    }
+  }
+  if (hasReal) {
+    return "REAL";
+  }
+  if (hasInteger) {
+    return "INTEGER";
+  }
+  return "TEXT";
+}
+
+// packages/text2sql/src/lib/adapters/spreadsheet/spreadsheet.ts
+var Spreadsheet = class extends Sqlite {
+  #db;
+  constructor(options) {
+    const sheets = parseFile(options.file);
+    const dbPath = options.database ?? ":memory:";
+    const db = new DatabaseSync(dbPath);
+    for (const sheet of sheets) {
+      const createSQL = createTableSQL(sheet);
+      db.exec(createSQL);
+      loadData(db, sheet);
+    }
+    super({
+      execute: (sql) => db.prepare(sql).all(),
+      grounding: options.grounding
+    });
+    this.#db = db;
+  }
+  /**
+   * Close the underlying SQLite database.
+   * Call this when done to release resources.
+   */
+  close() {
+    this.#db.close();
+  }
+};
+function createTableSQL(sheet) {
+  if (sheet.columns.length === 0) {
+    throw new Error(`Cannot create table "${sheet.name}" with no columns.`);
+  }
+  const columns = sheet.columns.map((col) => `"${escapeIdentifier(col.name)}" ${col.type}`).join(", ");
+  return `CREATE TABLE "${escapeIdentifier(sheet.name)}" (${columns})`;
+}
+function loadData(db, sheet) {
+  if (sheet.rows.length === 0) {
+    return;
+  }
+  const columns = sheet.columns.map((c) => `"${escapeIdentifier(c.name)}"`).join(", ");
+  const placeholders = sheet.columns.map(() => "?").join(", ");
+  const insertSQL = `INSERT INTO "${escapeIdentifier(sheet.name)}" (${columns}) VALUES (${placeholders})`;
+  const stmt = db.prepare(insertSQL);
+  db.exec("BEGIN TRANSACTION");
+  try {
+    for (const row of sheet.rows) {
+      const values = sheet.columns.map((col) => {
+        const rawValue = row[col.originalKey];
+        return convertValue(rawValue, col.type);
+      });
+      stmt.run(...values);
+    }
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+function convertValue(value, type) {
+  if (value == null || value === "") {
+    return null;
+  }
+  if (value instanceof Date) {
+    return value.toISOString().split("T")[0];
+  }
+  switch (type) {
+    case "INTEGER": {
+      const num = Number(value);
+      if (isNaN(num)) {
+        return null;
+      }
+      return Math.floor(num);
+    }
+    case "REAL": {
+      const num = Number(value);
+      if (isNaN(num)) {
+        return null;
+      }
+      return num;
+    }
+    case "TEXT":
+    default: {
+      if (typeof value === "boolean") {
+        return value ? "true" : "false";
+      }
+      if (typeof value === "object") {
+        return JSON.stringify(value);
+      }
+      return String(value);
+    }
+  }
+}
+function escapeIdentifier(name) {
+  return name.replace(/"/g, '""');
+}
+export {
+  Spreadsheet,
+  columnStats,
+  columnValues,
+  info,
+  parseFile,
+  rowCount,
+  sanitizeIdentifier,
+  sanitizeTableName,
+  tables
+};
+//# sourceMappingURL=index.js.map