@deepagents/text2sql 0.2.3 → 0.3.1

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

@@ -0,0 +1,1219 @@
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+function createGroundingContext() {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  async introspect() {
+    const lines = [];
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      lines.push({
+        tag: grounding.tag,
+        fn: await grounding.execute(ctx)
+      });
+    }
+    return lines.map(({ fn, tag }) => {
+      const description = fn();
+      if (description === null) {
+        return "";
+      }
+      return `<${tag}>
+${description}
+</${tag}>`;
+    }).join("\n");
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/grounding.ticket.ts
+var AbstractGrounding = class {
+  tag;
+  constructor(tag) {
+    this.tag = tag;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
+var ColumnStatsGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("column_stats");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with statistics.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const stats = await this.collectStats(container.name, column);
+          if (stats) {
+            column.stats = stats;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting stats for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraints");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their constraints.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      try {
+        table.constraints = await this.getConstraints(table.name);
+      } catch (error) {
+        console.warn("Error collecting constraints for", table.name, error);
+      }
+    }
+    return () => null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
+var IndexesGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("indexes");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      table.indexes = await this.getIndexes(table.name);
+      for (const index of table.indexes ?? []) {
+        for (const colName of index.columns) {
+          const column = table.columns.find((c) => c.name === colName);
+          if (column) {
+            column.isIndexed = true;
+          }
+        }
+      }
+    }
+    return () => null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialect_info");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+    const lines = [`Dialect: ${ctx.info.dialect ?? "unknown"}`];
+    if (ctx.info.version) {
+      lines.push(`Version: ${ctx.info.version}`);
+    }
+    if (ctx.info.database) {
+      lines.push(`Database: ${ctx.info.database}`);
+    }
+    if (ctx.info.details && Object.keys(ctx.info.details).length) {
+      lines.push(`Details: ${JSON.stringify(ctx.info.details)}`);
+    }
+    return () => lines.join("\n");
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/low-cardinality.grounding.ts
+var LowCardinalityGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("low_cardinality");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with low cardinality values.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const lowCard = await this.collectLowCardinality(
+            container.name,
+            column
+          );
+          if (lowCard) {
+            column.kind = lowCard.kind;
+            column.values = lowCard.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting low cardinality values for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
+import { groq } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent from "dedent";
+import z from "zod";
+import {
+  agent,
+  generate,
+  toState,
+  user
+} from "@deepagents/agent";
+var ReportGrounding = class extends AbstractGrounding {
+  #adapter;
+  #model;
+  #cache;
+  #forceRefresh;
+  constructor(adapter, config = {}) {
+    super("business_context");
+    this.#adapter = adapter;
+    this.#model = config.model ?? groq("openai/gpt-oss-20b");
+    this.#cache = config.cache;
+    this.#forceRefresh = config.forceRefresh ?? false;
+  }
+  async execute(ctx) {
+    if (!this.#forceRefresh && this.#cache) {
+      const cached = await this.#cache.get();
+      if (cached) {
+        ctx.report = cached;
+        return () => cached;
+      }
+    }
+    const report2 = await this.#generateReport();
+    ctx.report = report2;
+    if (this.#cache) {
+      await this.#cache.set(report2);
+    }
+    return () => report2;
+  }
+  async #generateReport() {
+    const reportAgent = agent({
+      name: "db-report-agent",
+      model: this.#model,
+      prompt: () => dedent`
+        <identity>
+          You are a database analyst expert. Your job is to understand what
+          a database represents and provide business context about it.
+          You have READ-ONLY access to the database.
+        </identity>
+
+        <instructions>
+          Write a business context that helps another agent answer questions accurately.
+
+          For EACH table, do queries ONE AT A TIME:
+          1. SELECT COUNT(*) to get row count
+          2. SELECT * LIMIT 3 to see sample data
+
+          Then write a report with:
+          - What business this database is for
+          - For each table: purpose, row count, and example of what the data looks like
+
+          Include concrete examples like "Track prices are $0.99",
+          "Customer names like 'Luís Gonçalves'", etc.
+
+          Keep it 400-600 words, conversational style.
+        </instructions>
+      `,
+      tools: {
+        query_database: tool({
+          description: "Execute a SELECT query to explore the database and gather insights.",
+          inputSchema: z.object({
+            sql: z.string().describe("The SELECT query to execute"),
+            purpose: z.string().describe(
+              "What insight you are trying to gather with this query"
+            )
+          }),
+          execute: ({ sql }, options) => {
+            const state = toState(options);
+            return state.adapter.execute(sql);
+          }
+        })
+      }
+    });
+    const { text } = await generate(
+      reportAgent,
+      [
+        user(
+          "Please analyze the database and write a contextual report about what this database represents."
+        )
+      ],
+      { adapter: this.#adapter }
+    );
+    return text;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("row_counts");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with row counts and size hints.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      const count = await this.getRowCount(table.name);
+      if (count != null) {
+        table.rowCount = count;
+        table.sizeHint = this.#classifyRowCount(count);
+      }
+    }
+    return () => null;
+  }
+  /**
+   * Classify row count into a size hint category.
+   */
+  #classifyRowCount(count) {
+    if (count < 100) return "tiny";
+    if (count < 1e3) return "small";
+    if (count < 1e4) return "medium";
+    if (count < 1e5) return "large";
+    return "huge";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+import pluralize from "pluralize";
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("tables");
+    this.#filter = config.filter;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered tables and relationships to the context.
+   */
+  async execute(ctx) {
+    const seedTables = await this.applyFilter();
+    const forward = this.#forward;
+    const backward = this.#backward;
+    if (!forward && !backward) {
+      const tables3 = await Promise.all(
+        seedTables.map((name) => this.getTable(name))
+      );
+      ctx.tables.push(...tables3);
+      return () => this.#describeTables(tables3);
+    }
+    const tables2 = {};
+    const allRelationships = [];
+    const seenRelationships = /* @__PURE__ */ new Set();
+    const forwardQueue = [];
+    const backwardQueue = [];
+    const forwardVisited = /* @__PURE__ */ new Set();
+    const backwardVisited = /* @__PURE__ */ new Set();
+    for (const name of seedTables) {
+      if (forward) forwardQueue.push({ name, depth: 0 });
+      if (backward) backwardQueue.push({ name, depth: 0 });
+    }
+    const forwardLimit = forward === true ? Infinity : forward || 0;
+    while (forwardQueue.length > 0) {
+      const item = forwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (forwardVisited.has(name)) continue;
+      forwardVisited.add(name);
+      if (!tables2[name]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!forwardVisited.has(rel.referenced_table)) {
+            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const backwardLimit = backward === true ? Infinity : backward || 0;
+    while (backwardQueue.length > 0) {
+      const item = backwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (backwardVisited.has(name)) continue;
+      backwardVisited.add(name);
+      if (!tables2[name]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!backwardVisited.has(rel.table)) {
+            backwardQueue.push({ name: rel.table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const tablesList = Object.values(tables2);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
+    return () => this.#describeTables(tablesList);
+  }
+  /**
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+  /**
+   * Add a relationship to the collection, deduplicating by key.
+   */
+  addRelationship(rel, all, seen) {
+    const key = `${rel.table}:${rel.from.join(",")}:${rel.referenced_table}:${rel.to.join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      all.push(rel);
+    }
+  }
+  #describeTables(tables2) {
+    if (!tables2.length) {
+      return "Schema unavailable.";
+    }
+    return tables2.map((table) => {
+      const rowCountInfo = table.rowCount != null ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ""}]` : "";
+      const pkConstraint = table.constraints?.find((c) => c.type === "PRIMARY_KEY");
+      const pkColumns = new Set(pkConstraint?.columns ?? []);
+      const columns = table.columns.map((column) => {
+        const annotations = [];
+        const isPrimaryKey = pkColumns.has(column.name);
+        if (isPrimaryKey) {
+          annotations.push("PK");
+        }
+        if (column.isIndexed && !isPrimaryKey) {
+          annotations.push("Indexed");
+        }
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const indexes2 = table.indexes?.length ? `
+  Indexes:
+${table.indexes.map((index) => {
+        const props = [];
+        if (index.unique) {
+          props.push("UNIQUE");
+        }
+        if (index.type) {
+          props.push(index.type);
+        }
+        const propsText = props.length ? ` (${props.join(", ")})` : "";
+        const columnsText = index.columns?.length ? index.columns.join(", ") : "expression";
+        return `    - ${index.name}${propsText}: ${columnsText}`;
+      }).join("\n")}` : "";
+      return `- Table: ${table.name}${rowCountInfo}
+  Columns:
+${columns}${indexes2}`;
+    }).join("\n\n");
+  }
+  #formatTableLabel = (tableName) => {
+    const base = tableName.split(".").pop() ?? tableName;
+    return base.replace(/_/g, " ");
+  };
+  #describeRelationships = (tables2, relationships) => {
+    if (!relationships.length) {
+      return "None detected";
+    }
+    const tableMap = new Map(tables2.map((table) => [table.name, table]));
+    return relationships.map((relationship) => {
+      const sourceLabel = this.#formatTableLabel(relationship.table);
+      const targetLabel = this.#formatTableLabel(
+        relationship.referenced_table
+      );
+      const singularSource = pluralize.singular(sourceLabel);
+      const pluralSource = pluralize.plural(sourceLabel);
+      const singularTarget = pluralize.singular(targetLabel);
+      const pluralTarget = pluralize.plural(targetLabel);
+      const sourceTable = tableMap.get(relationship.table);
+      const targetTable = tableMap.get(relationship.referenced_table);
+      const sourceCount = sourceTable?.rowCount;
+      const targetCount = targetTable?.rowCount;
+      const ratio = sourceCount != null && targetCount != null && targetCount > 0 ? sourceCount / targetCount : null;
+      let cardinality = "each";
+      if (ratio != null) {
+        if (ratio > 5) {
+          cardinality = `many-to-one (\u2248${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 1.2 && ratio > 0.8) {
+          cardinality = `roughly 1:1 (${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 0.2) {
+          cardinality = `one-to-many (${sourceCount} vs ${targetCount})`;
+        }
+      }
+      const mappings = relationship.from.map((fromCol, idx) => {
+        const targetCol = relationship.to[idx] ?? relationship.to[0] ?? fromCol;
+        return `${relationship.table}.${fromCol} -> ${relationship.referenced_table}.${targetCol}`;
+      }).join(", ");
+      return `- ${relationship.table} (${relationship.from.join(", ")}) -> ${relationship.referenced_table} (${relationship.to.join(", ")}) [${cardinality}]`;
+    }).join("\n");
+  };
+};
+
+// packages/text2sql/src/lib/adapters/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/constraint.sqlite.grounding.ts
+var SqliteConstraintGrounding = class extends ConstraintGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getConstraints(tableName) {
+    const constraints2 = [];
+    const columns = await this.#adapter.runQuery(
+      `PRAGMA table_info(${this.#quoteIdentifier(tableName)})`
+    );
+    const pkColumns = columns.filter((col) => col.pk > 0).sort((a, b) => a.pk - b.pk).map((col) => col.name);
+    if (pkColumns.length > 0) {
+      constraints2.push({
+        name: `${tableName}_pkey`,
+        type: "PRIMARY_KEY",
+        columns: pkColumns
+      });
+    }
+    for (const col of columns) {
+      if (col.notnull === 1 && col.pk === 0) {
+        constraints2.push({
+          name: `${tableName}_${col.name}_notnull`,
+          type: "NOT_NULL",
+          columns: [col.name]
+        });
+      }
+      if (col.dflt_value != null) {
+        constraints2.push({
+          name: `${tableName}_${col.name}_default`,
+          type: "DEFAULT",
+          columns: [col.name],
+          defaultValue: col.dflt_value
+        });
+      }
+    }
+    const fkRows = await this.#adapter.runQuery(
+      `PRAGMA foreign_key_list(${this.#quoteIdentifier(tableName)})`
+    );
+    const fkGroups = /* @__PURE__ */ new Map();
+    for (const row of fkRows) {
+      const group = fkGroups.get(row.id) ?? [];
+      group.push(row);
+      fkGroups.set(row.id, group);
+    }
+    for (const [id, rows] of fkGroups) {
+      rows.sort((a, b) => a.seq - b.seq);
+      constraints2.push({
+        name: `${tableName}_fkey_${id}`,
+        type: "FOREIGN_KEY",
+        columns: rows.map((r) => r.from),
+        referencedTable: rows[0].table,
+        referencedColumns: rows.map((r) => r.to)
+      });
+    }
+    const ddlRows = await this.#adapter.runQuery(
+      `SELECT sql FROM sqlite_master WHERE type='table' AND name=${this.#quoteIdentifier(tableName)}`
+    );
+    if (ddlRows[0]?.sql) {
+      const checkConstraints = this.#parseCheckConstraints(ddlRows[0].sql, tableName);
+      constraints2.push(...checkConstraints);
+    }
+    return constraints2;
+  }
+  #parseCheckConstraints(ddl, tableName) {
+    const constraints2 = [];
+    const checkRegex = /(?:CONSTRAINT\s+["'`]?(\w+)["'`]?\s+)?CHECK\s*\(([^)]+)\)/gi;
+    let match;
+    let index = 0;
+    while ((match = checkRegex.exec(ddl)) !== null) {
+      const name = match[1] || `${tableName}_check_${index}`;
+      const definition = match[2]?.trim();
+      if (definition) {
+        constraints2.push({
+          name,
+          type: "CHECK",
+          definition
+        });
+        index++;
+      }
+    }
+    const uniqueRegex = /(?:CONSTRAINT\s+["'`]?(\w+)["'`]?\s+)?UNIQUE\s*\(([^)]+)\)/gi;
+    let uniqueIndex = 0;
+    while ((match = uniqueRegex.exec(ddl)) !== null) {
+      const name = match[1] || `${tableName}_unique_${uniqueIndex}`;
+      const columnsStr = match[2]?.trim();
+      if (columnsStr) {
+        const columns = columnsStr.split(",").map((c) => c.trim().replace(/["'`]/g, ""));
+        constraints2.push({
+          name,
+          type: "UNIQUE",
+          columns
+        });
+        uniqueIndex++;
+      }
+    }
+    return constraints2;
+  }
+  #quoteIdentifier(name) {
+    return `'${name.replace(/'/g, "''")}'`;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/indexes.sqlite.grounding.ts
+var SqliteIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getIndexes(tableName) {
+    const indexListRows = await this.#adapter.runQuery(
+      `PRAGMA index_list(${this.#quoteIdentifier(tableName)})`
+    );
+    const indexes2 = [];
+    for (const indexRow of indexListRows) {
+      if (!indexRow.name) continue;
+      const indexInfoRows = await this.#adapter.runQuery(
+        `PRAGMA index_info(${this.#quoteIdentifier(indexRow.name)})`
+      );
+      const columns = indexInfoRows.filter((row) => row.name != null).sort((a, b) => a.seqno - b.seqno).map((row) => row.name);
+      if (!columns.length) continue;
+      indexes2.push({
+        name: indexRow.name,
+        columns,
+        unique: indexRow.unique === 1,
+        type: indexRow.partial === 1 ? "PARTIAL" : void 0
+      });
+    }
+    return indexes2;
+  }
+  #quoteIdentifier(name) {
+    return `'${name.replace(/'/g, "''")}'`;
+  }
+};
+
+// 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
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/low-cardinality.sqlite.grounding.ts
+var LOW_CARDINALITY_LIMIT = 20;
+var SqliteLowCardinalityGrounding = class extends LowCardinalityGrounding {
+  #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 = LOW_CARDINALITY_LIMIT + 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 > LOW_CARDINALITY_LIMIT) {
+      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);
+    }
+    if (!values.length) {
+      return void 0;
+    }
+    return { kind: "LowCardinality", values };
+  }
+  #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/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  constructor(config = {}) {
+    super("views");
+    this.#filter = config.filter;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered views to the context.
+   */
+  async execute(ctx) {
+    const viewNames = await this.applyFilter();
+    const views2 = await Promise.all(
+      viewNames.map((name) => this.getView(name))
+    );
+    ctx.views.push(...views2);
+    return () => this.#describe(views2);
+  }
+  #describe(views2) {
+    if (!views2.length) {
+      return "No views available.";
+    }
+    return views2.map((view) => {
+      const columns = view.columns.map((column) => {
+        const annotations = [];
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const definition = view.definition ? `
+  Definition: ${view.definition.length > 200 ? view.definition.slice(0, 200) + "..." : view.definition}` : "";
+      return `- View: ${view.name}${definition}
+  Columns:
+${columns}`;
+    }).join("\n\n");
+  }
+  /**
+   * Apply the filter to get view names.
+   * If filter is an explicit array, skip querying all view names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllViewNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlite/view.sqlite.grounding.ts
+var SqliteViewGrounding = class extends ViewGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getAllViewNames() {
+    const rows = await this.#adapter.runQuery(`SELECT name FROM sqlite_master WHERE type='view' ORDER BY name`);
+    return rows.map((row) => row.name).filter((name) => typeof name === "string");
+  }
+  async getView(viewName) {
+    const defRows = await this.#adapter.runQuery(
+      `SELECT sql FROM sqlite_master WHERE type='view' AND name=${this.#quoteIdentifier(viewName)}`
+    );
+    const columns = await this.#adapter.runQuery(
+      `PRAGMA table_info(${this.#quoteIdentifier(viewName)})`
+    );
+    return {
+      name: viewName,
+      definition: defRows[0]?.sql ?? void 0,
+      columns: columns.map((col) => ({
+        name: col.name ?? "unknown",
+        type: col.type ?? "unknown"
+      }))
+    };
+  }
+  #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 views(config = {}) {
+  return (adapter) => {
+    return new SqliteViewGrounding(adapter, config);
+  };
+}
+function columnStats(config = {}) {
+  return (adapter) => {
+    return new SqliteColumnStatsGrounding(adapter, config);
+  };
+}
+function lowCardinality(config = {}) {
+  return (adapter) => {
+    return new SqliteLowCardinalityGrounding(adapter, config);
+  };
+}
+function indexes(config = {}) {
+  return (adapter) => {
+    return new SqliteIndexesGrounding(adapter, config);
+  };
+}
+function rowCount(config = {}) {
+  return (adapter) => {
+    return new SqliteRowCountGrounding(adapter, config);
+  };
+}
+function constraints(config = {}) {
+  return (adapter) => {
+    return new SqliteConstraintGrounding(adapter, config);
+  };
+}
+function report(config = {}) {
+  return (adapter) => new ReportGrounding(adapter, config);
+}
+var sqlite_default = {
+  tables,
+  info,
+  views,
+  columnStats,
+  lowCardinality,
+  indexes,
+  rowCount,
+  constraints,
+  report,
+  Sqlite
+};
+export {
+  Sqlite,
+  columnStats,
+  constraints,
+  sqlite_default as default,
+  formatError,
+  indexes,
+  info,
+  lowCardinality,
+  report,
+  rowCount,
+  tables,
+  views
+};
+//# sourceMappingURL=index.js.map