@deepagents/text2sql 0.2.0

package/dist/index.js

@@ -0,0 +1,3102 @@
+// packages/text2sql/src/lib/agents/text2sql.agent.ts
+import { groq } from "@ai-sdk/groq";
+import { tool } from "ai";
+import z from "zod";
+import {
+  agent,
+  stepBackPrompt,
+  toState
+} from "@deepagents/agent";
+import { scratchpad_tool } from "@deepagents/toolbox";
+
+// packages/text2sql/src/lib/prompt.ts
+import pluralize from "pluralize";
+var describeTables = (introspection) => {
+  if (!introspection.tables.length) {
+    return "Schema unavailable.";
+  }
+  return introspection.tables.map((table) => {
+    const rowCountInfo = table.rowCount != null ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ""}]` : "";
+    const columns = table.columns.map((column) => {
+      const annotations = [];
+      if (column.isPrimaryKey) {
+        annotations.push("PK");
+      }
+      if (column.isIndexed && !column.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 indexes = table.indexes?.length ? `
+  Indexes:
+${table.indexes.map((index) => {
+      const props = [];
+      if (index.primary) {
+        props.push("PRIMARY");
+      } else 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}${indexes}`;
+  }).join("\n\n");
+};
+var formatTableLabel = (tableName) => {
+  const base = tableName.split(".").pop() ?? tableName;
+  return base.replace(/_/g, " ");
+};
+var describeRelationships = (introspection) => {
+  if (!introspection.relationships.length) {
+    return "None detected";
+  }
+  const tableMap = new Map(introspection.tables.map((table) => [table.name, table]));
+  return introspection.relationships.map((relationship) => {
+    const sourceLabel = formatTableLabel(relationship.table);
+    const targetLabel = formatTableLabel(relationship.referenced_table);
+    const singularSource = pluralize.singular(sourceLabel);
+    const pluralSource = pluralize(sourceLabel);
+    const singularTarget = pluralize.singular(targetLabel);
+    const pluralTarget = pluralize(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");
+};
+function databaseSchemaPrompt(options) {
+  const tablesSummary = describeTables(options.introspection);
+  const relationshipsSummary = describeRelationships(options.introspection);
+  const contextInfo = options.context || "";
+  const adapterInfo = options.adapterInfo;
+  const lines = [
+    adapterInfo ? `<dialect_info>${adapterInfo}</dialect_info>` : "",
+    contextInfo ? `<context>${contextInfo}</context>` : "",
+    `<tables>
+${tablesSummary}
+</tables>`,
+    `<relationships>
+${relationshipsSummary}
+</relationships>`
+  ];
+  return `<schema_context>${lines.filter(Boolean).join("\n\n")}</schema_context>`;
+}
+
+// packages/text2sql/src/lib/agents/text2sql.agent.ts
+var tools = {
+  validate_query: tool({
+    description: `Validate SQL query syntax before execution. Use this to check if your SQL is valid before running db_query. This helps catch errors early and allows you to correct the query if needed.`,
+    inputSchema: z.object({
+      sql: z.string().describe("The SQL query to validate.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState(options);
+      const result = await state.adapter.validate(sql);
+      if (typeof result === "string") {
+        return `Validation Error: ${result}`;
+      }
+      return "Query is valid.";
+    }
+  }),
+  get_sample_rows: tool({
+    description: `Get a few sample rows from a table to understand data formatting and values. Use this when you are unsure about the content of a column (e.g. date formats, status codes, string variations).`,
+    inputSchema: z.object({
+      tableName: z.string().describe("The name of the table to sample.")
+    }),
+    execute: ({ tableName }, options) => {
+      tableName = tableName.replace(/[^a-zA-Z0-9_.]/g, "");
+      const state = toState(options);
+      return state.adapter.execute(`SELECT * FROM ${tableName} LIMIT 3`);
+    }
+  }),
+  db_query: tool({
+    description: `Internal tool to fetch data from the store's database. Write a SQL query to retrieve the information needed to answer the user's question. The results will be returned as data that you can then present to the user in natural language.`,
+    inputSchema: z.object({
+      reasoning: z.string().describe(
+        "Your reasoning for why this SQL query is relevant to the user request."
+      ),
+      sql: z.string().min(1, { message: "SQL query cannot be empty." }).refine(
+        (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
+        {
+          message: "Only read-only SELECT or WITH queries are allowed."
+        }
+      ).describe("The SQL query to execute against the database.")
+    }),
+    execute: ({ sql }, options) => {
+      const state = toState(options);
+      return state.adapter.execute(sql);
+    }
+  }),
+  scratchpad: scratchpad_tool
+};
+var getRenderingGuidance = (renderingTools) => {
+  const renderingToolNames = Object.keys(renderingTools ?? {}).filter(
+    (toolName) => toolName.startsWith("render_")
+  );
+  if (!renderingToolNames.length) {
+    return { constraint: void 0, section: "" };
+  }
+  return {
+    constraint: "**Rendering**: Use a render_* visualization tool for trend/over time/monthly requests or explicit chart asks; otherwise provide the insight in text.",
+    section: `
+    <rendering_tools>
+      Rendering tools available: ${renderingToolNames.join(", ")}.
+      Use the matching render_* tool when the user requests a chart or mentions trends/over time/monthly performance. Prefer a line chart for those time-based requests. Always include a concise text insight alongside any visualization; if no suitable render_* tool fits, deliver the insight in text only.
+    </rendering_tools>
+    `
+  };
+};
+var SQL_STEP_BACK_EXAMPLES = [
+  {
+    originalQuestion: "Who are our top 5 customers by spending?",
+    stepBackQuestion: "What are the SQL principles for ranking and aggregation queries?",
+    stepBackAnswer: "Ranking queries require: 1) Aggregation functions (SUM, COUNT, AVG) grouped by the entity to rank, 2) JOINs to connect related data across tables (e.g., Customer to Invoice), 3) ORDER BY to sort by the aggregated metric, 4) LIMIT to restrict to top N results. For customer spending, join Customer and Invoice tables, sum invoice totals, group by customer identifier, order by total descending.",
+    finalAnswer: "SELECT c.FirstName, c.LastName, SUM(i.Total) as total_spent FROM Customer c JOIN Invoice i ON c.CustomerId = i.CustomerId GROUP BY c.CustomerId ORDER BY total_spent DESC LIMIT 5"
+  },
+  {
+    originalQuestion: "Show me sales by month for 2013",
+    stepBackQuestion: "What are the principles of time-based grouping and aggregation in SQL?",
+    stepBackAnswer: "Time-based queries require: 1) Date extraction functions (e.g., DATE_TRUNC, strftime, YEAR/FORMAT) to bucket timestamps, 2) WHERE clauses to filter the date range, 3) GROUP BY the derived period, 4) Aggregations such as SUM for revenue and COUNT for transactions, 5) ORDER BY the period chronologically.",
+    finalAnswer: "SELECT date_trunc('month', InvoiceDate) as month, COUNT(*) as sales_count, SUM(Total) as revenue FROM Invoice WHERE EXTRACT(year FROM InvoiceDate) = 2013 GROUP BY month ORDER BY month -- replace date_trunc/EXTRACT with your dialect's month/year helpers"
+  },
+  {
+    originalQuestion: "What are the best-selling tracks by genre?",
+    stepBackQuestion: "What are the SQL principles for multi-dimensional aggregation with categories?",
+    stepBackAnswer: "Multi-dimensional queries require: 1) Multiple JOINs to connect entities through foreign key relationships (Genre \u2192 Track \u2192 InvoiceLine), 2) GROUP BY all categorical dimensions you want to analyze (GenreId, TrackId), 3) Aggregation at the intersection of these dimensions (COUNT of sales per track per genre), 4) Proper table aliasing for query readability, 5) Understanding the data model relationships (which tables link to which).",
+    finalAnswer: "SELECT g.Name as genre, t.Name as track, COUNT(*) as times_sold FROM Genre g JOIN Track t ON g.GenreId = t.GenreId JOIN InvoiceLine il ON t.TrackId = il.TrackId GROUP BY g.GenreId, t.TrackId ORDER BY times_sold DESC LIMIT 10"
+  }
+];
+var text2sqlAgent = agent({
+  name: "text2sql",
+  model: groq("openai/gpt-oss-20b"),
+  prompt: (state) => {
+    const renderingGuidance = getRenderingGuidance(state?.renderingTools);
+    const constraints = [
+      "**Max Output Rows**: Never output more than 100 rows of raw data. Use aggregation or pagination otherwise.",
+      "**Validation**: You must validate your query before final execution. Follow the pattern: Draft Query \u2192 `validate_query` \u2192 Fix (if needed) \u2192 `db_query`.",
+      "**Data Inspection**: If you are unsure about column values (e.g. status codes, date formats), use `get_sample_rows` to inspect the data before writing the query.",
+      "**Tool Usage**: If you have not produced a SQL snippet, do not call `db_query`. First produce the query string, then validate.",
+      renderingGuidance.constraint,
+      "**Scratchpad**: Use the `scratchpad` tool for strategic reflection during SQL query generation."
+    ].filter(Boolean);
+    const constraintsSection = constraints.map((constraint, index) => `      ${index + 1}. ${constraint}`).join("\n");
+    return `
+    <identity>
+      You are an expert SQL query generator, answering business questions with accurate queries.
+      Your tone should be concise and business-friendly.
+    </identity>
+
+    ${state?.userProfile || ""}
+
+    ${databaseSchemaPrompt(state)}
+
+    ${state?.teachings || ""}
+
+    <query_reasoning_strategy>
+      ${stepBackPrompt("general", {
+      examples: SQL_STEP_BACK_EXAMPLES,
+      stepBackQuestionTemplate: "What are the SQL patterns, database principles, and schema relationships needed to answer this question?"
+    })}
+
+      Skip Step-Back only if the question is a direct \u201CSELECT * FROM \u2026\u201D or a simple aggregation with a clear target.
+    </query_reasoning_strategy>
+
+    <constraints>
+${constraintsSection}
+    </constraints>
+${renderingGuidance.section}
+  `;
+  }
+});
+var text2sqlOnly = text2sqlAgent.clone({
+  tools: {},
+  output: z.object({
+    sql: z.string().describe("The SQL query generated to answer the user question.")
+  }),
+  prompt: (state) => {
+    return `
+    <identity>
+      You are an expert SQL query generator, answering business questions with accurate queries.
+      Your tone should be concise and business-friendly.
+    </identity>
+
+    ${databaseSchemaPrompt(state)}
+
+    <constraints>
+      1. **Output**: Provide ONLY the SQL query. Do not include markdown formatting like \`\`\`sql ... \`\`\`.
+      2. **Dialect**: Use standard SQL compatible with SQLite unless specified otherwise.
+    </constraints>
+  `;
+  }
+});
+var text2sqlMonolith = text2sqlAgent.clone({
+  model: groq("openai/gpt-oss-20b"),
+  // model: openai('gpt-5.1-codex'),
+  tools
+});
+
+// packages/text2sql/src/lib/sql.ts
+import {
+  InvalidToolInputError,
+  NoSuchToolError,
+  ToolCallRepairError,
+  tool as tool3
+} from "ai";
+import dedent6 from "dedent";
+import { v7 } from "uuid";
+import z6 from "zod";
+import { generate as generate2, pipe, stream, user as user2 } from "@deepagents/agent";
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  async resolveTables(filter) {
+    const allTables = await this.getTables();
+    const relationships = await this.getRelationships();
+    return getTablesWithRelated(allTables, relationships, filter);
+  }
+};
+function filterTablesByName(tables, filter) {
+  if (!filter) return tables;
+  return tables.filter((table) => matchesFilter(table.name, filter));
+}
+function filterRelationshipsByTables(relationships, tableNames) {
+  if (tableNames === void 0) {
+    return relationships;
+  }
+  if (tableNames.size === 0) {
+    return [];
+  }
+  return relationships.filter(
+    (it) => tableNames.has(it.table) || tableNames.has(it.referenced_table)
+  );
+}
+function applyTablesFilter(tables, relationships, filter) {
+  if (!filter) {
+    return { tables, relationships };
+  }
+  const allowedNames = new Set(
+    getTablesWithRelated(tables, relationships, filter)
+  );
+  return {
+    tables: tables.filter((table) => allowedNames.has(table.name)),
+    relationships: filterRelationshipsByTables(relationships, allowedNames)
+  };
+}
+function matchesFilter(tableName, filter) {
+  if (Array.isArray(filter)) {
+    return filter.includes(tableName);
+  }
+  return filter.test(tableName);
+}
+function getTablesWithRelated(allTables, relationships, filter) {
+  const matchedTables = filterTablesByName(allTables, filter).map(
+    (it) => it.name
+  );
+  if (matchedTables.length === 0) {
+    return [];
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const rel of relationships) {
+    if (!adjacency.has(rel.table)) {
+      adjacency.set(rel.table, /* @__PURE__ */ new Set());
+    }
+    if (!adjacency.has(rel.referenced_table)) {
+      adjacency.set(rel.referenced_table, /* @__PURE__ */ new Set());
+    }
+    adjacency.get(rel.table).add(rel.referenced_table);
+    adjacency.get(rel.referenced_table).add(rel.table);
+  }
+  const result = new Set(matchedTables);
+  const queue = [...matchedTables];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const neighbors = adjacency.get(current);
+    if (!neighbors) {
+      continue;
+    }
+    for (const neighbor of neighbors) {
+      if (!result.has(neighbor)) {
+        result.add(neighbor);
+        queue.push(neighbor);
+      }
+    }
+  }
+  return Array.from(result);
+}
+
+// packages/text2sql/src/lib/adapters/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."
+  }
+];
+var LOW_CARDINALITY_LIMIT = 20;
+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;
+  #introspection = null;
+  #info = null;
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("Sqlite adapter requires an execute function.");
+    }
+    this.#options = options;
+  }
+  async introspect(options) {
+    const onProgress = options?.onProgress;
+    if (this.#introspection) {
+      return this.#introspection;
+    }
+    if (this.#options.introspect) {
+      this.#introspection = await this.#options.introspect();
+      return this.#introspection;
+    }
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships(
+      allTables.map((t) => t.name)
+    );
+    const { tables, relationships } = this.#applyTablesFilter(
+      allTables,
+      allRelationships
+    );
+    onProgress?.({
+      phase: "tables",
+      message: `Loaded ${tables.length} tables`,
+      total: tables.length
+    });
+    onProgress?.({ phase: "row_counts", message: "Counting table rows..." });
+    await this.#annotateRowCounts(tables, onProgress);
+    onProgress?.({
+      phase: "column_stats",
+      message: "Collecting column statistics..."
+    });
+    await this.#annotateColumnStats(tables, onProgress);
+    onProgress?.({ phase: "indexes", message: "Loading index information..." });
+    await this.#annotateIndexes(tables, onProgress);
+    onProgress?.({
+      phase: "low_cardinality",
+      message: "Identifying low cardinality columns..."
+    });
+    await this.#annotateLowCardinalityColumns(tables, onProgress);
+    onProgress?.({
+      phase: "relationships",
+      message: "Loading foreign key relationships..."
+    });
+    this.#introspection = { tables, relationships };
+    return this.#introspection;
+  }
+  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));
+    }
+  }
+  async info() {
+    if (this.#info) {
+      return this.#info;
+    }
+    this.#info = await this.#resolveInfo();
+    return this.#info;
+  }
+  formatInfo(info) {
+    const lines = [`Dialect: ${info.dialect ?? "unknown"}`];
+    if (info.version) {
+      lines.push(`Version: ${info.version}`);
+    }
+    if (info.database) {
+      lines.push(`Database: ${info.database}`);
+    }
+    if (info.host) {
+      lines.push(`Host: ${info.host}`);
+    }
+    if (info.details && Object.keys(info.details).length) {
+      lines.push(`Details: ${JSON.stringify(info.details)}`);
+    }
+    return lines.join("\n");
+  }
+  async getTables() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships(
+      allTables.map((t) => t.name)
+    );
+    return this.#applyTablesFilter(allTables, allRelationships).tables;
+  }
+  async #loadTables() {
+    const rows = await this.#runQuery(
+      `SELECT name FROM sqlite_master WHERE type='table' ORDER BY name`
+    );
+    const tableNames = rows.map((row) => row.name).filter(
+      (name) => typeof name === "string" && !name.startsWith("sqlite_")
+    );
+    const tables = await Promise.all(
+      tableNames.map(async (tableName) => {
+        const columns = await this.#runQuery(
+          `PRAGMA table_info(${this.#quoteIdentifier(tableName)})`
+        );
+        return {
+          name: tableName,
+          rawName: tableName,
+          columns: columns.map((col) => ({
+            name: col.name ?? "unknown",
+            type: col.type ?? "unknown",
+            isPrimaryKey: (col.pk ?? 0) > 0
+          }))
+        };
+      })
+    );
+    return tables;
+  }
+  async getRelationships() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships(
+      allTables.map((t) => t.name)
+    );
+    return this.#applyTablesFilter(allTables, allRelationships).relationships;
+  }
+  async #loadRelationships(tableNames) {
+    const names = tableNames ?? (await this.#loadTables()).map((table) => table.name);
+    const relationshipGroups = await Promise.all(
+      names.map(async (tableName) => {
+        const rows = await this.#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());
+      })
+    );
+    return relationshipGroups.flat();
+  }
+  async #annotateRowCounts(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatTableIdentifier(table);
+      onProgress?.({
+        phase: "row_counts",
+        message: `Counting rows in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      try {
+        const rows = await this.#runQuery(
+          `SELECT COUNT(*) as count FROM ${tableIdentifier}`
+        );
+        const rowCount = this.#toNumber(rows[0]?.count);
+        if (rowCount != null) {
+          table.rowCount = rowCount;
+          table.sizeHint = this.#classifyRowCount(rowCount);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  async #annotateColumnStats(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatTableIdentifier(table);
+      onProgress?.({
+        phase: "column_stats",
+        message: `Collecting stats for ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        if (!this.#shouldCollectStats(column.type)) {
+          continue;
+        }
+        const columnIdentifier = this.#quoteSqlIdentifier(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}
+        `;
+        try {
+          const rows = await this.#runQuery(sql);
+          if (!rows.length) {
+            continue;
+          }
+          const min = this.#normalizeValue(rows[0]?.min_value);
+          const max = this.#normalizeValue(rows[0]?.max_value);
+          const nullFraction = this.#toNumber(rows[0]?.null_fraction);
+          if (min != null || max != null || nullFraction != null) {
+            column.stats = {
+              min: min ?? void 0,
+              max: max ?? void 0,
+              nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
+            };
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+  async #annotateIndexes(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#quoteIdentifier(
+        table.rawName ?? table.name
+      );
+      onProgress?.({
+        phase: "indexes",
+        message: `Loading indexes for ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      let indexes = [];
+      try {
+        const indexList = await this.#runQuery(
+          `PRAGMA index_list(${tableIdentifier})`
+        );
+        indexes = await Promise.all(
+          indexList.filter((index) => index.name).map(async (index) => {
+            const indexName = String(index.name);
+            const indexInfo = await this.#runQuery(
+              `PRAGMA index_info('${indexName.replace(/'/g, "''")}')`
+            );
+            const columns = indexInfo.map((col) => col.name).filter((name) => Boolean(name));
+            for (const columnName of columns) {
+              const column = table.columns.find(
+                (col) => col.name === columnName
+              );
+              if (column) {
+                column.isIndexed = true;
+              }
+            }
+            return {
+              name: indexName,
+              columns,
+              unique: index.unique === 1,
+              primary: index.origin === "pk",
+              type: index.origin ?? void 0
+            };
+          })
+        );
+      } catch {
+        indexes = [];
+      }
+      if (indexes.length) {
+        table.indexes = indexes;
+      }
+    }
+  }
+  async #annotateLowCardinalityColumns(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatTableIdentifier(table);
+      onProgress?.({
+        phase: "low_cardinality",
+        message: `Analyzing cardinality in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        const columnIdentifier = this.#quoteSqlIdentifier(column.name);
+        const limit = LOW_CARDINALITY_LIMIT + 1;
+        const sql = `
+          SELECT DISTINCT ${columnIdentifier} AS value
+          FROM ${tableIdentifier}
+          WHERE ${columnIdentifier} IS NOT NULL
+          LIMIT ${limit}
+        `;
+        let rows = [];
+        try {
+          rows = await this.#runQuery(sql);
+        } catch {
+          continue;
+        }
+        if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT) {
+          continue;
+        }
+        const values = [];
+        let shouldSkip = false;
+        for (const row of rows) {
+          const formatted = this.#normalizeValue(row.value);
+          if (formatted == null) {
+            shouldSkip = true;
+            break;
+          }
+          values.push(formatted);
+        }
+        if (shouldSkip || !values.length) {
+          continue;
+        }
+        column.kind = "LowCardinality";
+        column.values = values;
+      }
+    }
+  }
+  #quoteIdentifier(name) {
+    return `'${name.replace(/'/g, "''")}'`;
+  }
+  #quoteSqlIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+  }
+  #applyTablesFilter(tables, relationships) {
+    return applyTablesFilter(tables, relationships, this.#options.tables);
+  }
+  #formatTableIdentifier(table) {
+    const name = table.rawName ?? table.name;
+    if (table.schema) {
+      return `${this.#quoteSqlIdentifier(table.schema)}.${this.#quoteSqlIdentifier(name)}`;
+    }
+    return this.#quoteSqlIdentifier(name);
+  }
+  #toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+  }
+  #classifyRowCount(count) {
+    if (count < 100) {
+      return "tiny";
+    }
+    if (count < 1e3) {
+      return "small";
+    }
+    if (count < 1e4) {
+      return "medium";
+    }
+    if (count < 1e5) {
+      return "large";
+    }
+    return "huge";
+  }
+  #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;
+  }
+  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."
+    );
+  }
+  async #resolveInfo() {
+    const { info } = this.#options;
+    if (!info) {
+      return { dialect: "sqlite" };
+    }
+    if (typeof info === "function") {
+      return info();
+    }
+    return info;
+  }
+};
+
+// packages/text2sql/src/lib/agents/brief.agent.ts
+import { groq as groq2 } from "@ai-sdk/groq";
+import { createUIMessageStream, tool as tool2 } from "ai";
+import dedent from "dedent";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import z2 from "zod";
+import {
+  agent as agent2,
+  generate,
+  toState as toState2,
+  user
+} from "@deepagents/agent";
+var BriefCache = class {
+  path;
+  constructor(watermark) {
+    const hash = createHash("md5").update(watermark).digest("hex");
+    this.path = path.join(tmpdir(), `db-brief-${hash}.txt`);
+  }
+  async get() {
+    if (existsSync(this.path)) {
+      return readFile(this.path, "utf-8");
+    }
+    return null;
+  }
+  set(brief) {
+    return writeFile(this.path, brief, "utf-8");
+  }
+};
+var briefAgent = agent2({
+  name: "db-brief-agent",
+  model: groq2("openai/gpt-oss-20b"),
+  prompt: (state) => 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>
+
+    ${databaseSchemaPrompt(state)}
+
+    <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\u00eds Gon\u00e7alves'", etc.
+
+      Keep it 400-600 words, conversational style.
+    </instructions>
+  `,
+  tools: {
+    query_database: tool2({
+      description: "Execute a SELECT query to explore the database and gather insights.",
+      inputSchema: z2.object({
+        sql: z2.string().describe("The SELECT query to execute"),
+        purpose: z2.string().describe("What insight you are trying to gather with this query")
+      }),
+      execute: ({ sql }, options) => {
+        const state = toState2(options);
+        return state.execute(sql);
+      }
+    })
+  }
+});
+async function runAndCache(introspection, cache) {
+  const { text } = await generate(
+    briefAgent,
+    [
+      user(
+        "Please analyze the database and write a contextual report about what this database represents."
+      )
+    ],
+    { introspection }
+  );
+  await cache.set(text);
+  return text;
+}
+async function generateBrief(introspection, cache) {
+  const brief = await cache.get();
+  if (!brief) {
+    return runAndCache(introspection, cache);
+  }
+  return brief;
+}
+function toBrief(forceRefresh = false) {
+  return (state, setState) => {
+    return createUIMessageStream({
+      execute: async ({ writer }) => {
+        if (forceRefresh) {
+          const brief = await runAndCache(state.introspection, state.cache);
+          writer.write({
+            type: "data-brief-agent",
+            data: {
+              cache: "forced",
+              brief
+            }
+          });
+          setState({ context: brief });
+        } else {
+          let brief = await state.cache.get();
+          if (!brief) {
+            writer.write({
+              type: "data-brief-agent",
+              data: {
+                cache: "miss"
+              }
+            });
+            brief = await runAndCache(state.introspection, state.cache);
+            writer.write({
+              type: "data-brief-agent",
+              data: {
+                cache: "new",
+                brief
+              }
+            });
+          } else {
+            writer.write({
+              type: "data-brief-agent",
+              data: {
+                cache: "hit",
+                brief
+              }
+            });
+          }
+        }
+      }
+    });
+  };
+}
+
+// packages/text2sql/src/lib/agents/explainer.agent.ts
+import { groq as groq3 } from "@ai-sdk/groq";
+import dedent2 from "dedent";
+import z3 from "zod";
+import { agent as agent3 } from "@deepagents/agent";
+var explainerAgent = agent3({
+  name: "explainer",
+  model: groq3("openai/gpt-oss-20b"),
+  prompt: (state) => dedent2`
+    You are an expert SQL tutor.
+    Explain the following SQL query in plain English to a non-technical user.
+    Focus on the intent and logic, not the syntax.
+
+    <sql>
+    ${state?.sql}
+    </sql>
+  `,
+  output: z3.object({
+    explanation: z3.string().describe("The explanation of the SQL query.")
+  })
+});
+
+// packages/text2sql/src/lib/agents/suggestions.agents.ts
+import { groq as groq4 } from "@ai-sdk/groq";
+import dedent3 from "dedent";
+import z4 from "zod";
+import { agent as agent4, thirdPersonPrompt } from "@deepagents/agent";
+var suggestionsAgent = agent4({
+  name: "text2sql-suggestions",
+  model: groq4("openai/gpt-oss-20b"),
+  output: z4.object({
+    suggestions: z4.array(
+      z4.object({
+        question: z4.string().describe("A complex, high-impact business question."),
+        sql: z4.string().describe("The SQL statement needed to answer the question."),
+        businessValue: z4.string().describe("Why the question matters to stakeholders.")
+      })
+    ).min(1).max(5).describe("A set of up to two advanced question + SQL pairs.")
+  }),
+  prompt: (state) => {
+    return dedent3`
+      ${thirdPersonPrompt()}
+
+      <identity>
+        You are a senior analytics strategist who proposes ambitious business questions
+        and drafts the SQL needed to answer them. You specialize in identifying ideas
+        that combine multiple tables, apply segmentation or time analysis, and surface
+        metrics that drive executive decisions.
+      </identity>
+
+      ${databaseSchemaPrompt(state)}
+
+      <instructions>
+        - Recommend one or two UNIQUE questions that go beyond simple counts or listings.
+        - Favor questions that require joins, aggregates, time comparisons, cohort analysis,
+          or window functions.
+        - For each question, explain the business reason stakeholders care about it.
+        - Provide the complete SQL query that could answer the question in the given schema.
+        - Keep result sets scoped with LIMIT clauses (max 50 rows) when returning raw rows.
+        - Ensure table/column names match the provided schema exactly.
+        - Use columns marked [LowCardinality: ...] to identify meaningful categorical filters or segmentations.
+        - Leverage table [rows / size] hints to determine whether to aggregate (large tables) or inspect detailed data (tiny tables).
+        - Reference PK/Indexed annotations and the Indexes list to recommend queries that use efficient join/filter paths.
+        - Column annotations may expose ranges/null percentages—use them to suggest realistic thresholds or quality checks.
+        - Consult <relationship_examples> to anchor your recommendations in the actual join paths between tables.
+        - Output only information grounded in the schema/context provided.
+      </instructions>
+
+      <response-format>
+        Return valid JSON that satisfies the defined output schema.
+      </response-format>
+    `;
+  }
+});
+
+// packages/text2sql/src/lib/agents/synthesizer.agent.ts
+import { groq as groq5 } from "@ai-sdk/groq";
+import dedent4 from "dedent";
+import { agent as agent5 } from "@deepagents/agent";
+var synthesizerAgent = agent5({
+  name: "synthesizer_agent",
+  model: groq5("openai/gpt-oss-20b"),
+  handoffDescription: "Use this tool to synthesizes the final user-facing response. This agent understands how the user interface works and can tailor the response accordingly.",
+  prompt: (state) => {
+    const contextInfo = state?.context ?? "No additional context provided.";
+    return dedent4`
+      <identity>
+        You are a data insights companion helping users understand information using clear, everyday language.
+        You communicate in a friendly, conversational manner.
+        You only see the user's question and the results from internal systems. You do not know how those results were produced, so never reference technical systems or implementation details.
+      </identity>
+
+      <context>
+        ${contextInfo}
+      </context>
+
+      <response-strategy>
+        1. Re-read the user's question, then inspect the <data> provided to understand what it represents.
+        2. Translate technical field names into friendly descriptions based on the domain context.
+        3. Explain the core insight in 2-4 sentences focused on what the data reveals.
+        4. When multiple records are present, highlight only the most relevant ones (max 5) with comparisons or rankings.
+        5. If data is empty or contains an error, state that plainly and suggest what to clarify or try next.
+        6. Close with an optional follow-up recommendation or next step based on the insights.
+      </response-strategy>
+
+      <guardrails>
+        - Never mention technical implementation details, data structures, or internal systems.
+        - Keep tone casual, confident, and insight-driven; do not narrate your process.
+        - Base every statement strictly on the <data> provided plus the context - no speculation.
+      </guardrails>
+    `;
+  }
+});
+
+// packages/text2sql/src/lib/agents/teachables.agent.ts
+import { groq as groq6 } from "@ai-sdk/groq";
+import dedent5 from "dedent";
+import z5 from "zod";
+import { agent as agent6, thirdPersonPrompt as thirdPersonPrompt2 } from "@deepagents/agent";
+
+// packages/text2sql/src/lib/teach/xml.ts
+function wrapBlock(tag, children) {
+  const content = children.filter((child) => Boolean(child)).join("\n");
+  if (!content) {
+    return "";
+  }
+  return `<${tag}>
+${indentBlock(content, 2)}
+</${tag}>`;
+}
+function list(tag, values, childTag) {
+  if (!values.length) {
+    return "";
+  }
+  const children = values.map((value) => leaf(childTag, value)).join("\n");
+  return `<${tag}>
+${indentBlock(children, 2)}
+</${tag}>`;
+}
+function leaf(tag, value) {
+  const safe = escapeXml(value);
+  if (safe.includes("\n")) {
+    return `<${tag}>
+${indentBlock(safe, 2)}
+</${tag}>`;
+  }
+  return `<${tag}>${safe}</${tag}>`;
+}
+function indentBlock(text, spaces) {
+  if (!text.trim()) {
+    return "";
+  }
+  const padding = " ".repeat(spaces);
+  return text.split("\n").map((line) => line.length ? padding + line : padding).join("\n");
+}
+function escapeXml(value) {
+  return value.replaceAll(/&/g, "&amp;").replaceAll(/</g, "&lt;").replaceAll(/>/g, "&gt;").replaceAll(/"/g, "&quot;").replaceAll(/'/g, "&apos;");
+}
+
+// packages/text2sql/src/lib/teach/teachables.ts
+function term(name, definition) {
+  return {
+    type: "term",
+    format: () => wrapBlock("term", [leaf("name", name), leaf("definition", definition)])
+  };
+}
+function hint(text) {
+  return {
+    type: "hint",
+    format: () => leaf("hint", text)
+  };
+}
+function guardrail(input) {
+  const { rule, reason, action } = input;
+  return {
+    type: "guardrail",
+    format: () => wrapBlock("guardrail", [
+      leaf("rule", rule),
+      reason ? leaf("reason", reason) : "",
+      action ? leaf("action", action) : ""
+    ])
+  };
+}
+function explain(input) {
+  const { concept, explanation, therefore } = input;
+  return {
+    type: "explain",
+    format: () => wrapBlock("explanation", [
+      leaf("concept", concept),
+      leaf("details", explanation),
+      therefore ? leaf("therefore", therefore) : ""
+    ])
+  };
+}
+function example(input) {
+  const { question, sql, note } = input;
+  return {
+    type: "example",
+    format: () => wrapBlock("example", [
+      leaf("question", question),
+      leaf("sql", sql),
+      note ? leaf("note", note) : ""
+    ])
+  };
+}
+function clarification(input) {
+  const { when, ask, reason } = input;
+  return {
+    type: "clarification",
+    format: () => wrapBlock("clarification", [
+      leaf("when", when),
+      leaf("ask", ask),
+      leaf("reason", reason)
+    ])
+  };
+}
+function workflow(input) {
+  const { task, steps, triggers, notes } = input;
+  return {
+    type: "workflow",
+    format: () => wrapBlock("workflow", [
+      leaf("task", task),
+      triggers?.length ? list("triggers", triggers, "trigger") : "",
+      list("steps", steps, "step"),
+      notes ? leaf("notes", notes) : ""
+    ])
+  };
+}
+function quirk(input) {
+  const { issue, workaround } = input;
+  return {
+    type: "quirk",
+    format: () => wrapBlock("quirk", [
+      leaf("issue", issue),
+      leaf("workaround", workaround)
+    ])
+  };
+}
+function styleGuide(input) {
+  const { prefer, never, always } = input;
+  return {
+    type: "styleGuide",
+    format: () => wrapBlock("style_guide", [
+      leaf("prefer", prefer),
+      always ? leaf("always", always) : "",
+      never ? leaf("never", never) : ""
+    ])
+  };
+}
+function analogy(input) {
+  const { concept, relationship, insight, therefore, pitfall } = input;
+  return {
+    type: "analogy",
+    format: () => wrapBlock("analogy", [
+      list("concepts", concept, "concept"),
+      leaf("relationship", relationship),
+      insight ? leaf("insight", insight) : "",
+      therefore ? leaf("therefore", therefore) : "",
+      pitfall ? leaf("pitfall", pitfall) : ""
+    ])
+  };
+}
+function toInstructions(...teachables) {
+  if (!teachables.length) {
+    return "";
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const teachable of teachables) {
+    const existing = grouped.get(teachable.type) ?? [];
+    existing.push(teachable);
+    grouped.set(teachable.type, existing);
+  }
+  const sections = SECTION_ORDER.map(({ type, tag }) => {
+    const items = grouped.get(type);
+    if (!items?.length) {
+      return "";
+    }
+    const renderedItems = items.map((item) => item.format().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
+    if (!renderedItems.length) {
+      return "";
+    }
+    return `<${tag}>
+${renderedItems}
+</${tag}>`;
+  }).filter((section) => Boolean(section));
+  if (!sections.length) {
+    return "";
+  }
+  const content = indentBlock(sections.join("\n"), 2);
+  return `<teachings>
+${content}
+</teachings>`;
+}
+var SECTION_ORDER = [
+  { type: "guardrail", tag: "guardrails" },
+  { type: "styleGuide", tag: "style_guides" },
+  { type: "hint", tag: "hints" },
+  { type: "clarification", tag: "clarifications" },
+  { type: "workflow", tag: "workflows" },
+  { type: "quirk", tag: "quirks" },
+  { type: "term", tag: "terminology" },
+  { type: "explain", tag: "explanations" },
+  { type: "analogy", tag: "analogies" },
+  { type: "example", tag: "examples" }
+];
+function toTeachables(generated) {
+  return generated.map((item) => {
+    switch (item.type) {
+      case "term":
+        return term(item.name, item.definition);
+      case "hint":
+        return hint(item.text);
+      case "guardrail":
+        return guardrail({
+          rule: item.rule,
+          reason: item.reason,
+          action: item.action
+        });
+      case "explain":
+        return explain({
+          concept: item.concept,
+          explanation: item.explanation,
+          therefore: item.therefore
+        });
+      case "example":
+        return example({
+          question: item.question,
+          sql: item.sql,
+          note: item.note
+        });
+      case "clarification":
+        return clarification({
+          when: item.when,
+          ask: item.ask,
+          reason: item.reason
+        });
+      case "workflow":
+        return workflow({
+          task: item.task,
+          steps: item.steps,
+          triggers: item.triggers,
+          notes: item.notes
+        });
+      case "quirk":
+        return quirk({
+          issue: item.issue,
+          workaround: item.workaround
+        });
+      case "styleGuide":
+        return styleGuide({
+          prefer: item.prefer,
+          never: item.never,
+          always: item.always
+        });
+      case "analogy":
+        return analogy({
+          concept: item.concept,
+          relationship: item.relationship,
+          insight: item.insight,
+          therefore: item.therefore,
+          pitfall: item.pitfall
+        });
+    }
+  });
+}
+function userProfile(input) {
+  return {
+    type: "user_profile",
+    format: () => {
+      return "";
+    }
+  };
+}
+
+// packages/text2sql/src/lib/agents/teachables.agent.ts
+var teachableSchema = z5.discriminatedUnion("type", [
+  z5.object({
+    type: z5.literal("term"),
+    name: z5.string(),
+    definition: z5.string()
+  }),
+  z5.object({
+    type: z5.literal("hint"),
+    text: z5.string()
+  }),
+  z5.object({
+    type: z5.literal("guardrail"),
+    rule: z5.string(),
+    reason: z5.string().optional(),
+    action: z5.string().optional()
+  }),
+  z5.object({
+    type: z5.literal("explain"),
+    concept: z5.string(),
+    explanation: z5.string(),
+    therefore: z5.string().optional()
+  }),
+  z5.object({
+    type: z5.literal("example"),
+    question: z5.string(),
+    sql: z5.string(),
+    note: z5.string().optional()
+  }),
+  z5.object({
+    type: z5.literal("clarification"),
+    when: z5.string(),
+    ask: z5.string(),
+    reason: z5.string()
+  }),
+  z5.object({
+    type: z5.literal("workflow"),
+    task: z5.string(),
+    steps: z5.array(z5.string()).min(2),
+    triggers: z5.array(z5.string()).optional(),
+    notes: z5.string().optional()
+  }),
+  z5.object({
+    type: z5.literal("quirk"),
+    issue: z5.string(),
+    workaround: z5.string()
+  }),
+  z5.object({
+    type: z5.literal("styleGuide"),
+    prefer: z5.string(),
+    never: z5.string().optional(),
+    always: z5.string().optional()
+  }),
+  z5.object({
+    type: z5.literal("analogy"),
+    concept: z5.array(z5.string()).min(2),
+    relationship: z5.string(),
+    insight: z5.string().optional(),
+    therefore: z5.string().optional(),
+    pitfall: z5.string().optional()
+  })
+]);
+var teachablesAuthorAgent = agent6({
+  name: "teachables-author",
+  model: groq6("openai/gpt-oss-20b"),
+  output: z5.object({
+    teachables: z5.array(teachableSchema).min(3).max(10).describe(
+      "A concise, high-value set of teachables grounded in the provided schema."
+    )
+  }),
+  prompt: (state) => dedent5`
+    ${thirdPersonPrompt2()}
+
+    <identity>
+      You design "teachables" for a Text2SQL system. Teachables become structured XML instructions.
+      Choose only high-impact items that improve accuracy, safety, or clarity for this database.
+    </identity>
+
+    ${databaseSchemaPrompt(state)}
+
+    <teachables_catalog>
+      term: name + definition for domain vocabulary.
+      hint: behavioral rule/constraint to apply by default.
+      guardrail: hard safety/performance boundary with action and optional reason.
+      explain: deeper concept metaphor/explanation (+ optional therefore).
+      example: question + SQL (+ optional note).
+      clarification: when/ask/reason to prompt the user before querying.
+      workflow: task + ordered steps (+ optional triggers/notes).
+      quirk: data edge case with workaround.
+      styleGuide: prefer/never/always guidance for SQL output.
+      analogy: comparison of two concepts with relationship (+ optional insight/therefore/pitfall).
+    </teachables_catalog>
+
+    <instructions>
+      - Ground everything in the provided schema/context; do not invent tables/columns.
+      - Prefer guardrails + clarifications for performance, safety, and ambiguity.
+      - Use examples only when a clear, schema-valid pattern is evident.
+      - Keep the set lean (3-10 items) and non-duplicative; combine overlapping ideas.
+      - Return JSON that satisfies the output schema; do not wrap in prose.
+    </instructions>
+  `
+});
+
+// packages/text2sql/src/lib/history/history.ts
+var History = class {
+};
+
+// packages/text2sql/src/lib/memory/user-profile.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { tmpdir as tmpdir2 } from "node:os";
+import path2 from "node:path";
+var UserProfileStore = class {
+  constructor(userId) {
+    this.userId = userId;
+    const safeUserId = userId.replace(/[^a-z0-9]/gi, "_").toLowerCase();
+    this.path = path2.join(tmpdir2(), `user-profile-${safeUserId}.json`);
+  }
+  path;
+  /**
+   * Retrieve the full user profile data.
+   */
+  async get() {
+    if (existsSync2(this.path)) {
+      try {
+        const content = await readFile2(this.path, "utf-8");
+        return JSON.parse(content);
+      } catch (error) {
+        console.error("Failed to read user profile:", error);
+      }
+    }
+    return {
+      items: [],
+      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  /**
+   * Save the user profile data.
+   */
+  async save(data) {
+    data.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
+    await writeFile2(this.path, JSON.stringify(data, null, 2), "utf-8");
+  }
+  /**
+   * Add an item to the profile.
+   */
+  async add(type, text) {
+    const data = await this.get();
+    const exists = data.items.some(
+      (item) => item.type === type && item.text === text
+    );
+    if (!exists) {
+      data.items.push({ type, text });
+      await this.save(data);
+    }
+  }
+  /**
+   * Remove a specific item from the profile.
+   */
+  async remove(type, text) {
+    const data = await this.get();
+    const filtered = data.items.filter((item) => {
+      return !(item.type === type && item.text === text);
+    });
+    await this.save({ ...data, items: filtered });
+  }
+  /**
+   * Clear the entire profile.
+   */
+  async clear() {
+    await this.save({ items: [], lastUpdated: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  /**
+   * Get the formatted XML string for the system prompt.
+   */
+  async toXml() {
+    const data = await this.get();
+    return toUserProfileXml(data.items);
+  }
+};
+function toUserProfileXml(items) {
+  if (items.length === 0) {
+    return "";
+  }
+  const facts = items.filter((i) => i.type === "fact");
+  const preferences = items.filter((i) => i.type === "preference");
+  const present = items.filter((i) => i.type === "present");
+  const sections = [];
+  if (facts.length > 0) {
+    const lines = facts.map((f) => `- ${f.text}`);
+    sections.push(wrapBlock2("identity", lines));
+  }
+  if (preferences.length > 0) {
+    const lines = preferences.map((p) => `- ${p.text}`);
+    sections.push(wrapBlock2("preferences", lines));
+  }
+  if (present.length > 0) {
+    const lines = present.map((c) => `- ${c.text}`);
+    sections.push(wrapBlock2("working_context", lines));
+  }
+  if (sections.length === 0) return "";
+  return `<user_profile>
+${indentBlock2(sections.join("\n"), 2)}
+</user_profile>`;
+}
+function wrapBlock2(tag, lines) {
+  if (lines.length === 0) return "";
+  return `<${tag}>
+${indentBlock2(lines.join("\n"), 2)}
+</${tag}>`;
+}
+function indentBlock2(text, spaces) {
+  const padding = " ".repeat(spaces);
+  return text.split("\n").map((line) => line.length ? padding + line : padding).join("\n");
+}
+
+// packages/text2sql/src/lib/sql.ts
+var Text2Sql = class {
+  #config;
+  constructor(config) {
+    this.#config = {
+      ...config,
+      instructions: config.instructions ?? [],
+      tools: config.tools ?? {}
+    };
+  }
+  async #getSql(stream2) {
+    const chunks = await Array.fromAsync(
+      stream2
+    );
+    const sql = chunks.at(-1);
+    if (sql && sql.type === "data-text-delta") {
+      return sql.data.text;
+    }
+    throw new Error("No SQL generated");
+  }
+  async explain(sql) {
+    const { experimental_output } = await generate2(
+      explainerAgent,
+      [user2("Explain this SQL.")],
+      { sql }
+    );
+    return experimental_output.explanation;
+  }
+  async toSql(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    const context = await generateBrief(introspection, this.#config.cache);
+    return {
+      generate: async () => {
+        const { experimental_output: output } = await generate2(
+          text2sqlOnly,
+          [user2(input)],
+          {
+            adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+            context,
+            introspection,
+            teachings: toInstructions(...this.#config.instructions)
+          }
+        );
+        return output.sql;
+      }
+    };
+  }
+  async inspect() {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    const context = await generateBrief(introspection, this.#config.cache);
+    return text2sqlOnly.instructions({
+      adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+      context,
+      introspection,
+      teachings: toInstructions(...this.#config.instructions)
+    });
+  }
+  instruct(...dataset) {
+    this.#config.instructions.push(...dataset);
+  }
+  async teach(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    const context = await generateBrief(introspection, this.#config.cache);
+    const { experimental_output } = await generate2(
+      teachablesAuthorAgent,
+      [user2(input)],
+      {
+        introspection,
+        adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+        context
+      }
+    );
+    const teachables = toTeachables(experimental_output.teachables);
+    this.#config.instructions.push(...teachables);
+    return {
+      teachables,
+      teachings: toInstructions(...this.#config.instructions)
+    };
+  }
+  async tag(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    const pipeline = pipe(
+      {
+        input,
+        adapter: this.#config.adapter,
+        cache: this.#config.cache,
+        introspection,
+        adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+        messages: [user2(input)],
+        renderingTools: this.#config.tools || {},
+        teachings: toInstructions(...this.#config.instructions)
+      },
+      toBrief(),
+      async (state, update) => {
+        const { experimental_output: output } = await generate2(
+          text2sqlOnly,
+          state.messages,
+          state
+        );
+        update({
+          messages: [
+            user2(
+              dedent6`
+        Based on the data provided, please explain in clear, conversational language what insights this reveals.
+
+        <user_question>${state.input}</user_question>
+        <data>${JSON.stringify(this.#config.adapter.execute(output.sql))}</data>
+        `
+            )
+          ]
+        });
+        return output.sql;
+      },
+      synthesizerAgent
+    );
+    const stream2 = pipeline();
+    return {
+      generate: async () => {
+        const sql = await this.#getSql(stream2);
+        return sql;
+      },
+      stream: () => {
+        return stream2;
+      }
+    };
+  }
+  async suggest() {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    const context = await generateBrief(introspection, this.#config.cache);
+    const { experimental_output: output } = await generate2(
+      suggestionsAgent,
+      [
+        user2(
+          "Suggest high-impact business questions and matching SQL queries for this database."
+        )
+      ],
+      {
+        introspection,
+        adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+        context
+      }
+    );
+    return output.suggestions;
+  }
+  async single(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    return stream(
+      text2sqlMonolith.clone({
+        tools: {
+          ...text2sqlMonolith.handoff.tools,
+          ...this.#config.tools
+        }
+      }),
+      [user2(input)],
+      {
+        teachings: toInstructions(...this.#config.instructions),
+        adapter: this.#config.adapter,
+        introspection,
+        adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+        context: await generateBrief(introspection, this.#config.cache),
+        renderingTools: this.#config.tools || {}
+      }
+    );
+  }
+  async chat(messages, params) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.#config.adapter.introspect(),
+      this.#config.adapter.info()
+    ]);
+    const chat = await this.#config.history.upsertChat({
+      id: params.chatId,
+      userId: params.userId,
+      title: "Chat " + params.chatId
+    });
+    const userProfileStore = new UserProfileStore(params.userId);
+    const userProfileXml = await userProfileStore.toXml();
+    const result = stream(
+      text2sqlMonolith.clone({
+        tools: {
+          ...text2sqlMonolith.handoff.tools,
+          ...this.#config.tools,
+          update_user_profile: tool3({
+            description: `Update the user's profile with new facts, preferences, or present context.
+            Use this when the user explicitly states a preference (e.g., "I like dark mode", "Call me Ezz")
+            or when their working context changes (e.g., "I'm working on a hackathon").`,
+            inputSchema: z6.object({
+              type: z6.enum(["fact", "preference", "present"]).describe("The type of information to update."),
+              text: z6.string().describe(
+                "The content of the fact, preference, or present context."
+              ),
+              action: z6.enum(["add", "remove"]).default("add").describe("Whether to add or remove the item.")
+            }),
+            execute: async ({ type, text, action }) => {
+              if (action === "remove") {
+                await userProfileStore.remove(type, text);
+                return `Removed ${type}: ${text}`;
+              }
+              await userProfileStore.add(type, text);
+              return `Added ${type}: ${text}`;
+            }
+          })
+        }
+      }),
+      [...chat.messages.map((it) => it.content), ...messages],
+      {
+        teachings: toInstructions(...this.#config.instructions),
+        adapter: this.#config.adapter,
+        renderingTools: this.#config.tools || {},
+        introspection,
+        adapterInfo: this.#config.adapter.formatInfo(adapterInfo),
+        context: await generateBrief(introspection, this.#config.cache),
+        userProfile: userProfileXml
+      }
+    );
+    return result.toUIMessageStream({
+      onError: (error) => {
+        if (NoSuchToolError.isInstance(error)) {
+          return "The model tried to call a unknown tool.";
+        } else if (InvalidToolInputError.isInstance(error)) {
+          return "The model called a tool with invalid arguments.";
+        } else if (ToolCallRepairError.isInstance(error)) {
+          return "The model tried to call a tool with invalid arguments, but it was repaired.";
+        } else {
+          return "An unknown error occurred.";
+        }
+      },
+      sendStart: true,
+      sendFinish: true,
+      sendReasoning: true,
+      sendSources: true,
+      originalMessages: messages,
+      onFinish: async ({ messages: messages2 }) => {
+        const userMessage = messages2.at(-2);
+        const botMessage = messages2.at(-1);
+        if (!userMessage || !botMessage) {
+          throw new Error("Not implemented yet");
+        }
+        await this.#config.history.addMessage({
+          id: v7(),
+          chatId: params.chatId,
+          role: userMessage.role,
+          content: userMessage
+        });
+        await this.#config.history.addMessage({
+          id: v7(),
+          chatId: params.chatId,
+          role: botMessage.role,
+          content: botMessage
+        });
+      }
+    });
+  }
+};
+if (import.meta.main) {
+}
+
+// packages/text2sql/src/lib/adapters/postgres.ts
+var POSTGRES_ERROR_MAP = {
+  "42P01": {
+    type: "MISSING_TABLE",
+    hint: "Check the database schema for the correct table name. Include the schema prefix if necessary."
+  },
+  "42703": {
+    type: "INVALID_COLUMN",
+    hint: "Verify the column exists on the referenced table and use table aliases to disambiguate."
+  },
+  "42601": {
+    type: "SYNTAX_ERROR",
+    hint: "There is a SQL syntax error. Review keywords, punctuation, and the overall query shape."
+  },
+  "42P10": {
+    type: "INVALID_COLUMN",
+    hint: "Columns referenced in GROUP BY/SELECT must exist. Double-check the column names and aliases."
+  },
+  "42883": {
+    type: "INVALID_FUNCTION",
+    hint: "The function or operator you used is not recognized. Confirm its name and argument types."
+  }
+};
+var LOW_CARDINALITY_LIMIT2 = 20;
+function isPostgresError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string";
+}
+function formatPostgresError(sql, error) {
+  const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error occurred";
+  if (isPostgresError(error)) {
+    const metadata = POSTGRES_ERROR_MAP[error.code ?? ""];
+    if (metadata) {
+      return {
+        error: errorMessage,
+        error_type: metadata.type,
+        suggestion: metadata.hint,
+        sql_attempted: sql
+      };
+    }
+  }
+  return {
+    error: errorMessage,
+    error_type: "UNKNOWN_ERROR",
+    suggestion: "Review the query and try again",
+    sql_attempted: sql
+  };
+}
+var Postgres = class extends Adapter {
+  #options;
+  #introspection = null;
+  #info = null;
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("Postgres adapter requires an execute function.");
+    }
+    this.#options = {
+      ...options,
+      schemas: options.schemas?.length ? options.schemas : void 0
+    };
+  }
+  async introspect(options) {
+    const onProgress = options?.onProgress;
+    if (this.#introspection) {
+      return this.#introspection;
+    }
+    if (this.#options.introspect) {
+      this.#introspection = await this.#options.introspect();
+      return this.#introspection;
+    }
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships();
+    const { tables, relationships } = this.#applyTablesFilter(
+      allTables,
+      allRelationships
+    );
+    onProgress?.({
+      phase: "tables",
+      message: `Loaded ${tables.length} tables`,
+      total: tables.length
+    });
+    onProgress?.({ phase: "row_counts", message: "Counting table rows..." });
+    await this.#annotateRowCounts(tables, onProgress);
+    onProgress?.({ phase: "primary_keys", message: "Detecting primary keys..." });
+    await this.#annotatePrimaryKeys(tables);
+    onProgress?.({ phase: "primary_keys", message: "Primary keys annotated" });
+    onProgress?.({ phase: "indexes", message: "Loading index information..." });
+    await this.#annotateIndexes(tables);
+    onProgress?.({ phase: "indexes", message: "Indexes annotated" });
+    onProgress?.({ phase: "column_stats", message: "Collecting column statistics..." });
+    await this.#annotateColumnStats(tables, onProgress);
+    onProgress?.({ phase: "low_cardinality", message: "Identifying low cardinality columns..." });
+    await this.#annotateLowCardinalityColumns(tables, onProgress);
+    onProgress?.({
+      phase: "relationships",
+      message: `Loaded ${relationships.length} relationships`
+    });
+    this.#introspection = { tables, relationships };
+    return this.#introspection;
+  }
+  async execute(sql) {
+    return this.#options.execute(sql);
+  }
+  async validate(sql) {
+    const validator = this.#options.validate ?? (async (text) => {
+      await this.#options.execute(`EXPLAIN ${text}`);
+    });
+    try {
+      return await validator(sql);
+    } catch (error) {
+      return JSON.stringify(formatPostgresError(sql, error));
+    }
+  }
+  async info() {
+    if (this.#info) {
+      return this.#info;
+    }
+    this.#info = await this.#resolveInfo();
+    return this.#info;
+  }
+  formatInfo(info) {
+    const lines = [`Dialect: ${info.dialect ?? "unknown"}`];
+    if (info.version) {
+      lines.push(`Version: ${info.version}`);
+    }
+    if (info.database) {
+      lines.push(`Database: ${info.database}`);
+    }
+    if (info.host) {
+      lines.push(`Host: ${info.host}`);
+    }
+    if (info.details && Object.keys(info.details).length) {
+      lines.push(`Details: ${JSON.stringify(info.details)}`);
+    }
+    return lines.join("\n");
+  }
+  async getTables() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships();
+    return this.#applyTablesFilter(allTables, allRelationships).tables;
+  }
+  async #loadTables() {
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        c.table_schema,
+        c.table_name,
+        c.column_name,
+        c.data_type
+      FROM information_schema.columns AS c
+      JOIN information_schema.tables AS t
+        ON c.table_schema = t.table_schema
+        AND c.table_name = t.table_name
+      WHERE t.table_type = 'BASE TABLE'
+        ${this.#buildSchemaFilter("c.table_schema")}
+      ORDER BY c.table_schema, c.table_name, c.ordinal_position
+    `);
+    const tables = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const tableName = row.table_name;
+      const qualifiedName = `${schema}.${tableName}`;
+      const table = tables.get(qualifiedName) ?? {
+        name: qualifiedName,
+        schema,
+        rawName: tableName,
+        columns: []
+      };
+      table.columns.push({
+        name: row.column_name ?? "unknown",
+        type: row.data_type ?? "unknown"
+      });
+      tables.set(qualifiedName, table);
+    }
+    return Array.from(tables.values());
+  }
+  async getRelationships() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships();
+    return this.#applyTablesFilter(allTables, allRelationships).relationships;
+  }
+  async #loadRelationships() {
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        tc.constraint_name,
+        tc.table_schema,
+        tc.table_name,
+        kcu.column_name,
+        ccu.table_schema AS foreign_table_schema,
+        ccu.table_name AS foreign_table_name,
+        ccu.column_name AS foreign_column_name
+      FROM information_schema.table_constraints AS tc
+      JOIN information_schema.key_column_usage AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      JOIN information_schema.constraint_column_usage AS ccu
+        ON ccu.constraint_name = tc.constraint_name
+        AND ccu.table_schema = tc.table_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        ${this.#buildSchemaFilter("tc.table_schema")}
+      ORDER BY tc.table_schema, tc.table_name, tc.constraint_name, kcu.ordinal_position
+    `);
+    const relationships = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name || !row.foreign_table_name || !row.constraint_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const referencedSchema = row.foreign_table_schema ?? "public";
+      const key = `${schema}.${row.table_name}:${row.constraint_name}`;
+      const relationship = relationships.get(key) ?? {
+        table: `${schema}.${row.table_name}`,
+        from: [],
+        referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
+        to: []
+      };
+      relationship.from.push(row.column_name ?? "unknown");
+      relationship.to.push(row.foreign_column_name ?? "unknown");
+      relationships.set(key, relationship);
+    }
+    return Array.from(relationships.values());
+  }
+  async #annotateRowCounts(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "row_counts",
+        message: `Counting rows in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      try {
+        const rows = await this.#runIntrospectionQuery(`SELECT COUNT(*) as count FROM ${tableIdentifier}`);
+        const rowCount = this.#toNumber(rows[0]?.count);
+        if (rowCount != null) {
+          table.rowCount = rowCount;
+          table.sizeHint = this.#classifyRowCount(rowCount);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  async #annotatePrimaryKeys(tables) {
+    if (!tables.length) {
+      return;
+    }
+    const tableMap = new Map(tables.map((table) => [table.name, table]));
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        tc.table_schema,
+        tc.table_name,
+        kcu.column_name
+      FROM information_schema.table_constraints AS tc
+      JOIN information_schema.key_column_usage AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.table_schema = kcu.table_schema
+      WHERE tc.constraint_type = 'PRIMARY KEY'
+        ${this.#buildSchemaFilter("tc.table_schema")}
+    `);
+    for (const row of rows) {
+      if (!row.table_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const qualifiedName = `${schema}.${row.table_name}`;
+      const table = tableMap.get(qualifiedName);
+      if (!table) {
+        continue;
+      }
+      const column = table.columns.find((col) => col.name === row.column_name);
+      if (column) {
+        column.isPrimaryKey = true;
+      }
+    }
+  }
+  async #annotateIndexes(tables) {
+    if (!tables.length) {
+      return;
+    }
+    const tableMap = new Map(tables.map((table) => [table.name, table]));
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        n.nspname AS table_schema,
+        t.relname AS table_name,
+        i.relname AS index_name,
+        a.attname AS column_name,
+        ix.indisunique,
+        ix.indisprimary,
+        ix.indisclustered,
+        am.amname AS method
+      FROM pg_index ix
+      JOIN pg_class t ON t.oid = ix.indrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      JOIN pg_class i ON i.oid = ix.indexrelid
+      JOIN pg_am am ON am.oid = i.relam
+      LEFT JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS key(attnum, ordinality) ON TRUE
+      LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = key.attnum
+      WHERE t.relkind = 'r'
+        ${this.#buildSchemaFilter("n.nspname")}
+      ORDER BY n.nspname, t.relname, i.relname, key.ordinality
+    `);
+    const indexMap = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name || !row.index_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "public";
+      const tableKey = `${schema}.${row.table_name}`;
+      const table = tableMap.get(tableKey);
+      if (!table) {
+        continue;
+      }
+      const indexKey = `${tableKey}:${row.index_name}`;
+      let index = indexMap.get(indexKey);
+      if (!index) {
+        index = {
+          name: row.index_name,
+          columns: [],
+          unique: Boolean(row.indisunique ?? false),
+          primary: Boolean(row.indisprimary ?? false),
+          type: row.indisclustered ? "clustered" : row.method ?? void 0
+        };
+        indexMap.set(indexKey, index);
+        if (!table.indexes) {
+          table.indexes = [];
+        }
+        table.indexes.push(index);
+      }
+      if (row.column_name) {
+        index.columns.push(row.column_name);
+        const column = table.columns.find(
+          (col) => col.name === row.column_name
+        );
+        if (column) {
+          column.isIndexed = true;
+        }
+      }
+    }
+  }
+  async #annotateColumnStats(tables, onProgress) {
+    if (!tables.length) {
+      return;
+    }
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "column_stats",
+        message: `Collecting stats for ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        if (!this.#shouldCollectStats(column.type)) {
+          continue;
+        }
+        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const sql = `
+          SELECT
+            MIN(${columnIdentifier})::text AS min_value,
+            MAX(${columnIdentifier})::text AS max_value,
+            AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END)::float AS null_fraction
+          FROM ${tableIdentifier}
+        `;
+        try {
+          const rows = await this.#runIntrospectionQuery(sql);
+          if (!rows.length) {
+            continue;
+          }
+          const min = rows[0]?.min_value ?? void 0;
+          const max = rows[0]?.max_value ?? void 0;
+          const nullFraction = this.#toNumber(rows[0]?.null_fraction);
+          if (min != null || max != null || nullFraction != null) {
+            column.stats = {
+              min,
+              max,
+              nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
+            };
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+  async #annotateLowCardinalityColumns(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "low_cardinality",
+        message: `Analyzing cardinality in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const limit = LOW_CARDINALITY_LIMIT2 + 1;
+        const sql = `
+          SELECT DISTINCT ${columnIdentifier} AS value
+          FROM ${tableIdentifier}
+          WHERE ${columnIdentifier} IS NOT NULL
+          LIMIT ${limit}
+        `;
+        let rows = [];
+        try {
+          rows = await this.#runIntrospectionQuery(sql);
+        } catch {
+          continue;
+        }
+        if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT2) {
+          continue;
+        }
+        const values = [];
+        let shouldSkip = false;
+        for (const row of rows) {
+          const formatted = this.#normalizeValue(row.value);
+          if (formatted == null) {
+            shouldSkip = true;
+            break;
+          }
+          values.push(formatted);
+        }
+        if (shouldSkip || !values.length) {
+          continue;
+        }
+        column.kind = "LowCardinality";
+        column.values = values;
+      }
+    }
+  }
+  #buildSchemaFilter(columnName) {
+    if (this.#options.schemas && this.#options.schemas.length > 0) {
+      const values = this.#options.schemas.map((schema) => `'${schema.replace(/'/g, "''")}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    return `AND ${columnName} NOT IN ('pg_catalog', 'information_schema')`;
+  }
+  async #runIntrospectionQuery(sql) {
+    const result = await this.#options.execute(sql);
+    if (Array.isArray(result)) {
+      return result;
+    }
+    if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
+      return result.rows;
+    }
+    throw new Error(
+      "Postgres adapter execute() must return an array of rows or an object with a rows array when introspecting."
+    );
+  }
+  #quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+  }
+  #applyTablesFilter(tables, relationships) {
+    return applyTablesFilter(tables, relationships, this.#options.tables);
+  }
+  #formatQualifiedTableName(table) {
+    if (table.schema && table.rawName) {
+      return `${this.#quoteIdentifier(table.schema)}.${this.#quoteIdentifier(table.rawName)}`;
+    }
+    if (table.name.includes(".")) {
+      const [schemaPart, ...rest] = table.name.split(".");
+      const tablePart = rest.join(".") || schemaPart;
+      if (rest.length === 0) {
+        return this.#quoteIdentifier(schemaPart);
+      }
+      return `${this.#quoteIdentifier(schemaPart)}.${this.#quoteIdentifier(tablePart)}`;
+    }
+    return this.#quoteIdentifier(table.name);
+  }
+  #toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+  }
+  #shouldCollectStats(type) {
+    if (!type) {
+      return false;
+    }
+    const normalized = type.toLowerCase();
+    return /int|numeric|decimal|double|real|money|date|time|timestamp|bool/.test(
+      normalized
+    );
+  }
+  #classifyRowCount(count) {
+    if (count < 100) {
+      return "tiny";
+    }
+    if (count < 1e3) {
+      return "small";
+    }
+    if (count < 1e4) {
+      return "medium";
+    }
+    if (count < 1e5) {
+      return "large";
+    }
+    return "huge";
+  }
+  #normalizeValue(value) {
+    if (value === null || value === void 0) {
+      return null;
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+      return String(value);
+    }
+    if (typeof value === "boolean") {
+      return value ? "true" : "false";
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) {
+      return value.toString("utf-8");
+    }
+    return null;
+  }
+  async #resolveInfo() {
+    const { info } = this.#options;
+    if (!info) {
+      return { dialect: "postgresql" };
+    }
+    if (typeof info === "function") {
+      return info();
+    }
+    return info;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/sqlserver.ts
+var SQL_SERVER_ERROR_MAP = {
+  "208": {
+    type: "MISSING_TABLE",
+    hint: "Check that the table exists and include the schema prefix (e.g., dbo.TableName)."
+  },
+  "207": {
+    type: "INVALID_COLUMN",
+    hint: "Verify the column exists on the table and that any aliases are referenced correctly."
+  },
+  "156": {
+    type: "SYNTAX_ERROR",
+    hint: "There is a SQL syntax error. Review keywords, punctuation, and clauses such as GROUP BY."
+  },
+  "4104": {
+    type: "INVALID_COLUMN",
+    hint: "Columns must be qualified with table aliases when ambiguous. Double-check join aliases."
+  },
+  "1934": {
+    type: "CONSTRAINT_ERROR",
+    hint: "The query violates a constraint. Re-check join logic and filtering."
+  }
+};
+var LOW_CARDINALITY_LIMIT3 = 20;
+function getErrorCode(error) {
+  if (typeof error === "object" && error !== null && "number" in error && typeof error.number === "number") {
+    return String(error.number);
+  }
+  if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return null;
+}
+function formatSqlServerError(sql, error) {
+  const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error occurred";
+  const code = getErrorCode(error);
+  const metadata = code ? SQL_SERVER_ERROR_MAP[code] : void 0;
+  if (metadata) {
+    return {
+      error: errorMessage,
+      error_type: metadata.type,
+      suggestion: metadata.hint,
+      sql_attempted: sql
+    };
+  }
+  return {
+    error: errorMessage,
+    error_type: "UNKNOWN_ERROR",
+    suggestion: "Review the query and try again",
+    sql_attempted: sql
+  };
+}
+var SqlServer = class extends Adapter {
+  #options;
+  #introspection = null;
+  #info = null;
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("SqlServer adapter requires an execute function.");
+    }
+    this.#options = {
+      ...options,
+      schemas: options.schemas?.length ? options.schemas : void 0
+    };
+  }
+  async introspect(options) {
+    const onProgress = options?.onProgress;
+    if (this.#introspection) {
+      return this.#introspection;
+    }
+    if (this.#options.introspect) {
+      this.#introspection = await this.#options.introspect();
+      return this.#introspection;
+    }
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships();
+    const { tables, relationships } = this.#applyTablesFilter(
+      allTables,
+      allRelationships
+    );
+    onProgress?.({
+      phase: "tables",
+      message: `Loaded ${tables.length} tables`,
+      total: tables.length
+    });
+    onProgress?.({ phase: "row_counts", message: "Counting table rows..." });
+    await this.#annotateRowCounts(tables, onProgress);
+    onProgress?.({ phase: "primary_keys", message: "Detecting primary keys..." });
+    await this.#annotatePrimaryKeys(tables);
+    onProgress?.({ phase: "primary_keys", message: "Primary keys annotated" });
+    onProgress?.({ phase: "indexes", message: "Loading index information..." });
+    await this.#annotateIndexes(tables);
+    onProgress?.({ phase: "indexes", message: "Indexes annotated" });
+    onProgress?.({ phase: "column_stats", message: "Collecting column statistics..." });
+    await this.#annotateColumnStats(tables, onProgress);
+    onProgress?.({ phase: "low_cardinality", message: "Identifying low cardinality columns..." });
+    await this.#annotateLowCardinalityColumns(tables, onProgress);
+    onProgress?.({
+      phase: "relationships",
+      message: `Loaded ${relationships.length} relationships`
+    });
+    this.#introspection = { tables, relationships };
+    return this.#introspection;
+  }
+  async execute(sql) {
+    return this.#options.execute(sql);
+  }
+  async validate(sql) {
+    const validator = this.#options.validate ?? (async (text) => {
+      await this.#options.execute(
+        `SET PARSEONLY ON; ${text}; SET PARSEONLY OFF;`
+      );
+    });
+    try {
+      return await validator(sql);
+    } catch (error) {
+      return JSON.stringify(formatSqlServerError(sql, error));
+    }
+  }
+  async info() {
+    if (this.#info) {
+      return this.#info;
+    }
+    this.#info = await this.#resolveInfo();
+    return this.#info;
+  }
+  formatInfo(info) {
+    const lines = [`Dialect: ${info.dialect ?? "unknown"}`];
+    if (info.version) {
+      lines.push(`Version: ${info.version}`);
+    }
+    if (info.database) {
+      lines.push(`Database: ${info.database}`);
+    }
+    if (info.host) {
+      lines.push(`Host: ${info.host}`);
+    }
+    if (info.details && Object.keys(info.details).length) {
+      lines.push(`Details: ${JSON.stringify(info.details)}`);
+    }
+    return lines.join("\n");
+  }
+  async getTables() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships();
+    return this.#applyTablesFilter(allTables, allRelationships).tables;
+  }
+  async #loadTables() {
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        c.TABLE_SCHEMA AS table_schema,
+        c.TABLE_NAME AS table_name,
+        c.COLUMN_NAME AS column_name,
+        c.DATA_TYPE AS data_type
+      FROM INFORMATION_SCHEMA.COLUMNS AS c
+      JOIN INFORMATION_SCHEMA.TABLES AS t
+        ON c.TABLE_SCHEMA = t.TABLE_SCHEMA
+        AND c.TABLE_NAME = t.TABLE_NAME
+      WHERE t.TABLE_TYPE = 'BASE TABLE'
+        ${this.#buildSchemaFilter("c.TABLE_SCHEMA")}
+      ORDER BY c.TABLE_SCHEMA, c.TABLE_NAME, c.ORDINAL_POSITION
+    `);
+    const tables = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "dbo";
+      const tableName = row.table_name;
+      const qualifiedName = `${schema}.${tableName}`;
+      const table = tables.get(qualifiedName) ?? {
+        name: qualifiedName,
+        schema,
+        rawName: tableName,
+        columns: []
+      };
+      table.columns.push({
+        name: row.column_name ?? "unknown",
+        type: row.data_type ?? "unknown"
+      });
+      tables.set(qualifiedName, table);
+    }
+    return Array.from(tables.values());
+  }
+  async getRelationships() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships();
+    return this.#applyTablesFilter(allTables, allRelationships).relationships;
+  }
+  async #loadRelationships() {
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        fk.CONSTRAINT_NAME AS constraint_name,
+        fk.TABLE_SCHEMA AS table_schema,
+        fk.TABLE_NAME AS table_name,
+        fk.COLUMN_NAME AS column_name,
+        pk.TABLE_SCHEMA AS referenced_table_schema,
+        pk.TABLE_NAME AS referenced_table_name,
+        pk.COLUMN_NAME AS referenced_column_name
+      FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS AS rc
+      JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE AS fk
+        ON fk.CONSTRAINT_NAME = rc.CONSTRAINT_NAME
+      JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE AS pk
+        ON pk.CONSTRAINT_NAME = rc.UNIQUE_CONSTRAINT_NAME
+        AND pk.ORDINAL_POSITION = fk.ORDINAL_POSITION
+      WHERE 1 = 1
+        ${this.#buildSchemaFilter("fk.TABLE_SCHEMA")}
+      ORDER BY fk.TABLE_SCHEMA, fk.TABLE_NAME, fk.CONSTRAINT_NAME, fk.ORDINAL_POSITION
+    `);
+    const relationships = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.constraint_name || !row.table_name || !row.referenced_table_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "dbo";
+      const referencedSchema = row.referenced_table_schema ?? "dbo";
+      const key = `${schema}.${row.table_name}:${row.constraint_name}`;
+      const relationship = 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);
+    }
+    return Array.from(relationships.values());
+  }
+  async #annotateRowCounts(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "row_counts",
+        message: `Counting rows in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      try {
+        const rows = await this.#runIntrospectionQuery(`SELECT COUNT(*) as count FROM ${tableIdentifier}`);
+        const rowCount = this.#toNumber(rows[0]?.count);
+        if (rowCount != null) {
+          table.rowCount = rowCount;
+          table.sizeHint = this.#classifyRowCount(rowCount);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  async #annotatePrimaryKeys(tables) {
+    if (!tables.length) {
+      return;
+    }
+    const tableMap = new Map(tables.map((table) => [table.name, table]));
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        kc.TABLE_SCHEMA AS table_schema,
+        kc.TABLE_NAME AS table_name,
+        kc.COLUMN_NAME AS column_name
+      FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS AS tc
+      JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE AS kc
+        ON tc.CONSTRAINT_NAME = kc.CONSTRAINT_NAME
+        AND tc.TABLE_SCHEMA = kc.TABLE_SCHEMA
+      WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY'
+        ${this.#buildSchemaFilter("kc.TABLE_SCHEMA")}
+    `);
+    for (const row of rows) {
+      if (!row.table_name || !row.column_name) {
+        continue;
+      }
+      const schema = row.table_schema ?? "dbo";
+      const tableKey = `${schema}.${row.table_name}`;
+      const table = tableMap.get(tableKey);
+      if (!table) {
+        continue;
+      }
+      const column = table.columns.find((col) => col.name === row.column_name);
+      if (column) {
+        column.isPrimaryKey = true;
+      }
+    }
+  }
+  async #annotateIndexes(tables) {
+    if (!tables.length) {
+      return;
+    }
+    const tableMap = new Map(tables.map((table) => [table.name, table]));
+    const rows = await this.#runIntrospectionQuery(`
+      SELECT
+        sch.name AS schema_name,
+        t.name AS table_name,
+        ind.name AS index_name,
+        col.name AS column_name,
+        ind.is_unique,
+        ind.is_primary_key,
+        ind.type_desc,
+        ic.is_included_column
+      FROM sys.indexes AS ind
+      JOIN sys.tables AS t ON ind.object_id = t.object_id
+      JOIN sys.schemas AS sch ON t.schema_id = sch.schema_id
+      JOIN sys.index_columns AS ic
+        ON ind.object_id = ic.object_id
+        AND ind.index_id = ic.index_id
+      JOIN sys.columns AS col
+        ON ic.object_id = col.object_id
+        AND ic.column_id = col.column_id
+      WHERE ind.is_hypothetical = 0
+        AND ind.name IS NOT NULL
+        ${this.#buildSchemaFilter("sch.name")}
+      ORDER BY sch.name, t.name, ind.name, ic.key_ordinal
+    `);
+    const indexMap = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.table_name || !row.index_name) {
+        continue;
+      }
+      const schema = row.schema_name ?? "dbo";
+      const tableKey = `${schema}.${row.table_name}`;
+      const table = tableMap.get(tableKey);
+      if (!table) {
+        continue;
+      }
+      const indexKey = `${tableKey}:${row.index_name}`;
+      let index = indexMap.get(indexKey);
+      if (!index) {
+        index = {
+          name: row.index_name,
+          columns: [],
+          unique: Boolean(row.is_unique),
+          primary: Boolean(row.is_primary_key),
+          type: row.type_desc ?? void 0
+        };
+        indexMap.set(indexKey, index);
+        if (!table.indexes) {
+          table.indexes = [];
+        }
+        table.indexes.push(index);
+      }
+      if (row.is_included_column) {
+        continue;
+      }
+      if (row.column_name) {
+        index.columns.push(row.column_name);
+        const column = table.columns.find(
+          (col) => col.name === row.column_name
+        );
+        if (column) {
+          column.isIndexed = true;
+        }
+      }
+    }
+  }
+  async #annotateColumnStats(tables, onProgress) {
+    if (!tables.length) {
+      return;
+    }
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "column_stats",
+        message: `Collecting stats for ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        if (!this.#shouldCollectStats(column.type)) {
+          continue;
+        }
+        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const sql = `
+          SELECT
+            CONVERT(NVARCHAR(4000), MIN(${columnIdentifier})) AS min_value,
+            CONVERT(NVARCHAR(4000), MAX(${columnIdentifier})) AS max_value,
+            AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END) AS null_fraction
+          FROM ${tableIdentifier}
+        `;
+        try {
+          const rows = await this.#runIntrospectionQuery(sql);
+          if (!rows.length) {
+            continue;
+          }
+          const nullFraction = this.#toNumber(rows[0]?.null_fraction);
+          if (rows[0]?.min_value != null || rows[0]?.max_value != null || nullFraction != null) {
+            column.stats = {
+              min: rows[0]?.min_value ?? void 0,
+              max: rows[0]?.max_value ?? void 0,
+              nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
+            };
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+  async #annotateLowCardinalityColumns(tables, onProgress) {
+    const total = tables.length;
+    for (let i = 0; i < tables.length; i++) {
+      const table = tables[i];
+      const tableIdentifier = this.#formatQualifiedTableName(table);
+      onProgress?.({
+        phase: "low_cardinality",
+        message: `Analyzing cardinality in ${table.name}...`,
+        current: i + 1,
+        total
+      });
+      for (const column of table.columns) {
+        const columnIdentifier = this.#quoteIdentifier(column.name);
+        const limit = LOW_CARDINALITY_LIMIT3 + 1;
+        const sql = `
+          SELECT DISTINCT TOP (${limit}) ${columnIdentifier} AS value
+          FROM ${tableIdentifier}
+          WHERE ${columnIdentifier} IS NOT NULL
+        `;
+        let rows = [];
+        try {
+          rows = await this.#runIntrospectionQuery(sql);
+        } catch {
+          continue;
+        }
+        if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT3) {
+          continue;
+        }
+        const values = [];
+        let shouldSkip = false;
+        for (const row of rows) {
+          const formatted = this.#normalizeValue(row.value);
+          if (formatted == null) {
+            shouldSkip = true;
+            break;
+          }
+          values.push(formatted);
+        }
+        if (shouldSkip || !values.length) {
+          continue;
+        }
+        column.kind = "LowCardinality";
+        column.values = values;
+      }
+    }
+  }
+  #buildSchemaFilter(columnName) {
+    if (this.#options.schemas && this.#options.schemas.length > 0) {
+      const values = this.#options.schemas.map((schema) => `'${schema.replace(/'/g, "''")}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    return `AND ${columnName} NOT IN ('INFORMATION_SCHEMA', 'sys')`;
+  }
+  async #runIntrospectionQuery(sql) {
+    const result = await this.#options.execute(sql);
+    if (Array.isArray(result)) {
+      return result;
+    }
+    if (result && typeof result === "object") {
+      if ("rows" in result && Array.isArray(result.rows)) {
+        return result.rows;
+      }
+      if ("recordset" in result && Array.isArray(result.recordset)) {
+        return result.recordset;
+      }
+      if ("recordsets" in result && Array.isArray(result.recordsets) && Array.isArray(result.recordsets[0])) {
+        return result.recordsets[0];
+      }
+    }
+    throw new Error(
+      "SqlServer adapter execute() must return an array of rows or an object with rows/recordset properties when introspecting."
+    );
+  }
+  #quoteIdentifier(name) {
+    return `[${name.replace(/]/g, "]]")}]`;
+  }
+  #applyTablesFilter(tables, relationships) {
+    return applyTablesFilter(tables, relationships, this.#options.tables);
+  }
+  #formatQualifiedTableName(table) {
+    if (table.schema && table.rawName) {
+      return `${this.#quoteIdentifier(table.schema)}.${this.#quoteIdentifier(table.rawName)}`;
+    }
+    if (table.name.includes(".")) {
+      const [schemaPart, ...rest] = table.name.split(".");
+      const tablePart = rest.join(".") || schemaPart;
+      if (rest.length === 0) {
+        return this.#quoteIdentifier(schemaPart);
+      }
+      return `${this.#quoteIdentifier(schemaPart)}.${this.#quoteIdentifier(tablePart)}`;
+    }
+    return this.#quoteIdentifier(table.name);
+  }
+  #toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+  }
+  #classifyRowCount(count) {
+    if (count < 100) {
+      return "tiny";
+    }
+    if (count < 1e3) {
+      return "small";
+    }
+    if (count < 1e4) {
+      return "medium";
+    }
+    if (count < 1e5) {
+      return "large";
+    }
+    return "huge";
+  }
+  #shouldCollectStats(type) {
+    if (!type) {
+      return false;
+    }
+    const normalized = type.toLowerCase();
+    return /int|numeric|decimal|float|real|money|date|time|timestamp|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;
+  }
+  async #resolveInfo() {
+    const { info } = this.#options;
+    if (!info) {
+      return { dialect: "sqlserver" };
+    }
+    if (typeof info === "function") {
+      return info();
+    }
+    return info;
+  }
+};
+
+// packages/text2sql/src/lib/history/sqlite.history.ts
+import { DatabaseSync } from "node:sqlite";
+
+// packages/text2sql/src/lib/history/history.sqlite.sql
+var history_sqlite_default = 'CREATE TABLE IF NOT EXISTS "chats" (\n	"id" VARCHAR PRIMARY KEY,\n	"title" VARCHAR,\n	"userId" VARCHAR\n);\n\nCREATE TABLE IF NOT EXISTS "messages" (\n	"id" VARCHAR PRIMARY KEY,\n	"chatId" VARCHAR NOT NULL REFERENCES "chats" ("id") ON DELETE CASCADE,\n	"createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\n	"role" VARCHAR NOT NULL,\n	"content" TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS "messages_chat_id_idx" ON "messages" ("chatId");\n\nCREATE INDEX IF NOT EXISTS "messages_chat_id_created_at_idx" ON "messages" ("chatId", "createdAt");\n';
+
+// packages/text2sql/src/lib/history/sqlite.history.ts
+var SqliteHistory = class extends History {
+  #db;
+  constructor(path3) {
+    super();
+    this.#db = new DatabaseSync(path3);
+    this.#db.exec(history_sqlite_default);
+  }
+  async listChats(userId) {
+    return this.#db.prepare(`SELECT * FROM chats WHERE "userId" = ?`).all(userId);
+  }
+  async getChat(chatId) {
+    const rows = this.#db.prepare(
+      `SELECT
+          c.id as chatId, c."userId", c.title,
+          m.id as messageId, m.role, m."createdAt", m.content
+        FROM chats c
+        LEFT JOIN messages m ON m."chatId" = c.id
+        WHERE c.id = ?
+        ORDER BY m."createdAt" ASC`
+    ).all(chatId);
+    if (!rows.length) return null;
+    const firstRow = rows[0];
+    const chat = {
+      id: firstRow.chatId,
+      userId: firstRow.userId,
+      title: firstRow.title,
+      messages: []
+    };
+    for (const row of rows) {
+      if (row.messageId) {
+        chat.messages.push({
+          id: row.messageId,
+          chatId: firstRow.chatId,
+          role: row.role,
+          createdAt: row.createdAt,
+          content: JSON.parse(row.content)
+        });
+      }
+    }
+    return chat;
+  }
+  async createChat(chat) {
+    this.#db.prepare(`INSERT INTO chats (id, "userId", title) VALUES (?, ?, ?)`).run(chat.id, chat.userId, chat.title || null);
+    return chat;
+  }
+  async upsertChat(chat) {
+    this.#db.prepare(
+      `INSERT INTO chats (id, "userId", title) VALUES (?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET title = excluded.title, "userId" = excluded."userId"`
+    ).run(chat.id, chat.userId, chat.title || null);
+    return this.getChat(chat.id);
+  }
+  async deleteChat(chatId) {
+    this.#db.prepare(`DELETE FROM chats WHERE id = ?`).run(chatId);
+  }
+  async updateChat(chatId, updates) {
+    if (updates.title !== void 0) {
+      this.#db.prepare(`UPDATE chats SET title = ? WHERE id = ?`).run(updates.title, chatId);
+    }
+  }
+  async addMessage(message) {
+    const createdAt = message.createdAt ? message.createdAt.toISOString() : (/* @__PURE__ */ new Date()).toISOString();
+    this.#db.prepare(
+      `INSERT INTO messages (id, "chatId", role, "createdAt", content) VALUES (?, ?, ?, ?, ?)`
+    ).run(
+      message.id,
+      message.chatId,
+      message.role,
+      createdAt,
+      JSON.stringify(message.content)
+    );
+  }
+  async upsertMessage(message) {
+    const createdAt = message.createdAt ? message.createdAt.toISOString() : (/* @__PURE__ */ new Date()).toISOString();
+    this.#db.prepare(
+      `INSERT INTO messages (id, "chatId", role, "createdAt", content) VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET "chatId" = excluded."chatId", role = excluded.role, "createdAt" = excluded."createdAt", content = excluded.content`
+    ).run(
+      message.id,
+      message.chatId,
+      message.role,
+      createdAt,
+      JSON.stringify(message.content)
+    );
+    return {
+      ...message,
+      createdAt
+    };
+  }
+  async deleteMessage(messageId) {
+    this.#db.prepare(`DELETE FROM messages WHERE id = ?`).run(messageId);
+  }
+};
+
+// packages/text2sql/src/lib/history/memory.history.ts
+var InMemoryHistory = class extends SqliteHistory {
+  constructor() {
+    super(":memory:");
+  }
+};
+export {
+  Adapter,
+  BriefCache,
+  History,
+  InMemoryHistory,
+  Postgres,
+  SqlServer,
+  Sqlite,
+  SqliteHistory,
+  Text2Sql,
+  analogy,
+  applyTablesFilter,
+  clarification,
+  example,
+  explain,
+  filterRelationshipsByTables,
+  filterTablesByName,
+  formatError,
+  formatPostgresError,
+  formatSqlServerError,
+  generateBrief,
+  getTablesWithRelated,
+  guardrail,
+  hint,
+  matchesFilter,
+  quirk,
+  styleGuide,
+  suggestionsAgent,
+  term,
+  text2sqlMonolith,
+  text2sqlOnly,
+  toBrief,
+  toInstructions,
+  toTeachables,
+  userProfile,
+  workflow
+};
+//# sourceMappingURL=index.js.map