@deepagents/text2sql 0.2.1 → 0.2.3

package/dist/index.js

@@ -293,6 +293,23 @@ import {
   user as user2
 } from "@deepagents/agent";
 
+// 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";
+
 // packages/text2sql/src/lib/adapters/adapter.ts
 var Adapter = class {
   async resolveTables(filter) {
@@ -370,1485 +387,1498 @@ function getTablesWithRelated(allTables, relationships, filter) {
   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;
+// packages/text2sql/src/lib/agents/brief.agent.ts
+var TmpCache = class {
+  path;
+  constructor(watermark, extension = ".txt") {
+    const hash = createHash("md5").update(watermark).digest("hex");
+    this.path = path.join(tmpdir(), `text2sql-${hash}${extension}`);
   }
-  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;
+  async get() {
+    if (existsSync(this.path)) {
+      return readFile(this.path, "utf-8");
     }
-    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);
+    return null;
   }
-  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));
-    }
+  set(content) {
+    return writeFile(this.path, content, "utf-8");
   }
-  async info() {
-    if (this.#info) {
-      return this.#info;
-    }
-    this.#info = await this.#resolveInfo();
-    return this.#info;
+};
+var JsonCache = class extends TmpCache {
+  constructor(watermark) {
+    super(watermark, ".json");
   }
-  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)}`);
+  async read() {
+    const content = await this.get();
+    if (content) {
+      return JSON.parse(content);
     }
-    return lines.join("\n");
+    return null;
   }
-  async getTables() {
-    const allTables = await this.#loadTables();
-    const allRelationships = await this.#loadRelationships(
-      allTables.map((t) => t.name)
-    );
-    return this.#applyTablesFilter(allTables, allRelationships).tables;
+  write(data) {
+    return this.set(JSON.stringify(data));
   }
-  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;
+};
+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 getRelationships() {
-    const allTables = await this.#loadTables();
-    const allRelationships = await this.#loadRelationships(
-      allTables.map((t) => t.name)
-    );
-    return this.#applyTablesFilter(allTables, allRelationships).relationships;
+});
+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);
   }
-  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)]
+  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 {
-            existing.from.push(String(row.from));
-            existing.to.push(String(row.to));
+            writer.write({
+              type: "data-brief-agent",
+              data: {
+                cache: "hit",
+                brief
+              }
+            });
           }
         }
-        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;
       }
-    }
+    });
+  };
+}
+
+// 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>
+    `;
   }
-  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;
-        }
-      }
-    }
+});
+
+// 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>
+    `;
   }
-  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;
-      }
-    }
+});
+
+// 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 "";
   }
-  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;
-      }
-    }
+  return `<${tag}>
+${indentBlock(content, 2)}
+</${tag}>`;
+}
+function list(tag, values, childTag) {
+  if (!values.length) {
+    return "";
   }
-  #quoteIdentifier(name) {
-    return `'${name.replace(/'/g, "''")}'`;
+  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}>`;
   }
-  #quoteSqlIdentifier(identifier) {
-    return `"${identifier.replace(/"/g, '""')}"`;
+  return `<${tag}>${safe}</${tag}>`;
+}
+function indentBlock(text, spaces) {
+  if (!text.trim()) {
+    return "";
   }
-  #applyTablesFilter(tables, relationships) {
-    return applyTablesFilter(tables, relationships, this.#options.tables);
+  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 "";
   }
-  #formatTableIdentifier(table) {
-    const name = table.rawName ?? table.name;
-    if (table.schema) {
-      return `${this.#quoteSqlIdentifier(table.schema)}.${this.#quoteSqlIdentifier(name)}`;
-    }
-    return this.#quoteSqlIdentifier(name);
+  const grouped = /* @__PURE__ */ new Map();
+  for (const teachable of teachables) {
+    const existing = grouped.get(teachable.type) ?? [];
+    existing.push(teachable);
+    grouped.set(teachable.type, existing);
   }
-  #toNumber(value) {
-    if (typeof value === "number" && Number.isFinite(value)) {
-      return value;
-    }
-    if (typeof value === "bigint") {
-      return Number(value);
+  const sections = SECTION_ORDER.map(({ type, tag }) => {
+    const items = grouped.get(type);
+    if (!items?.length) {
+      return "";
     }
-    if (typeof value === "string" && value.trim() !== "") {
-      const parsed = Number(value);
-      return Number.isFinite(parsed) ? parsed : null;
+    const renderedItems = items.map((item) => item.format().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
+    if (!renderedItems.length) {
+      return "";
     }
-    return null;
+    return `<${tag}>
+${renderedItems}
+</${tag}>`;
+  }).filter((section) => Boolean(section));
+  if (!sections.length) {
+    return "";
   }
-  #classifyRowCount(count) {
-    if (count < 100) {
-      return "tiny";
-    }
-    if (count < 1e3) {
-      return "small";
-    }
-    if (count < 1e4) {
-      return "medium";
+  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
+        });
     }
-    if (count < 1e5) {
-      return "large";
+  });
+}
+function userProfile(input) {
+  return {
+    type: "user_profile",
+    format: () => {
+      return "";
     }
-    return "huge";
+  };
+}
+
+// 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`);
   }
-  #shouldCollectStats(type) {
-    if (!type) {
-      return false;
+  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);
+      }
     }
-    const normalized = type.toLowerCase();
-    return /int|real|numeric|double|float|decimal|date|time|bool/.test(
-      normalized
-    );
+    return {
+      items: [],
+      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+    };
   }
-  #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;
+  /**
+   * 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");
   }
-  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."
+  /**
+   * 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
     );
-  }
-  async #resolveInfo() {
-    const { info } = this.#options;
-    if (!info) {
-      return { dialect: "sqlite" };
-    }
-    if (typeof info === "function") {
-      return info();
+    if (!exists) {
+      data.items.push({ type, text });
+      await this.save(data);
     }
-    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`);
+  /**
+   * 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 });
   }
-  async get() {
-    if (existsSync(this.path)) {
-      return readFile(this.path, "utf-8");
-    }
-    return null;
+  /**
+   * Clear the entire profile.
+   */
+  async clear() {
+    await this.save({ items: [], lastUpdated: (/* @__PURE__ */ new Date()).toISOString() });
   }
-  set(brief) {
-    return writeFile(this.path, brief, "utf-8");
+  /**
+   * Get the formatted XML string for the system prompt.
+   */
+  async toXml() {
+    const data = await this.get();
+    return toUserProfileXml(data.items);
   }
 };
-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);
-      }
-    })
+function toUserProfileXml(items) {
+  if (items.length === 0) {
+    return "";
   }
-});
-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);
+  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));
   }
-  return brief;
+  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 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
-              }
-            });
-          }
-        }
-      }
-    });
-  };
+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/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/sql.ts
+var Text2Sql = class {
+  #config;
+  #introspectionCache;
+  constructor(config) {
+    this.#config = {
+      ...config,
+      instructions: config.instructions ?? [],
+      tools: config.tools ?? {}
+    };
+    this.#introspectionCache = new JsonCache(
+      "introspection" + config.version
+    );
   }
-});
-
-// 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>
-    `;
+  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");
   }
-});
-
-// 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 "";
+  async explain(sql) {
+    const { experimental_output } = await generate2(
+      explainerAgent,
+      [user2("Explain this SQL.")],
+      { sql }
+    );
+    return experimental_output.explanation;
   }
-  return `<${tag}>
-${indentBlock(content, 2)}
-</${tag}>`;
-}
-function list(tag, values, childTag) {
-  if (!values.length) {
-    return "";
+  async toSql(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.index(),
+      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;
+      }
+    };
   }
-  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}>`;
+  async inspect() {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.index(),
+      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)
+    });
   }
-  return `<${tag}>${safe}</${tag}>`;
-}
-function indentBlock(text, spaces) {
-  if (!text.trim()) {
-    return "";
+  instruct(...dataset) {
+    this.#config.instructions.push(...dataset);
   }
-  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;");
-}
+  async index(options) {
+    const cached = await this.#introspectionCache.read();
+    if (cached) {
+      return cached;
+    }
+    const introspection = await this.#config.adapter.introspect(options);
+    await this.#introspectionCache.write(introspection);
+    return introspection;
+  }
+  async teach(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.index(),
+      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.index(),
+      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.
 
-// 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 "";
+        <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;
+      }
+    };
   }
-  const grouped = /* @__PURE__ */ new Map();
-  for (const teachable of teachables) {
-    const existing = grouped.get(teachable.type) ?? [];
-    existing.push(teachable);
-    grouped.set(teachable.type, existing);
+  async suggest() {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.index(),
+      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;
   }
-  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 "";
+  async single(input) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.index(),
+      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 || {}
+      }
+    );
   }
-  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
+  async chat(messages, params, model) {
+    const [introspection, adapterInfo] = await Promise.all([
+      this.index({ onProgress: console.log }),
+      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({
+        model,
+        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
         });
-    }
-  });
-}
-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");
+if (import.meta.main) {
 }
 
-// packages/text2sql/src/lib/sql.ts
-var Text2Sql = class {
-  #config;
-  constructor(config) {
-    this.#config = {
-      ...config,
-      instructions: config.instructions ?? [],
-      tools: config.tools ?? {}
+// 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
     };
   }
-  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;
+  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.");
     }
-    throw new Error("No SQL generated");
+    this.#options = options;
   }
-  async explain(sql) {
-    const { experimental_output } = await generate2(
-      explainerAgent,
-      [user2("Explain this SQL.")],
-      { sql }
+  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)
     );
-    return experimental_output.explanation;
+    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 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 execute(sql) {
+    return this.#options.execute(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)
+  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));
+    }
   }
-  instruct(...dataset) {
-    this.#config.instructions.push(...dataset);
+  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 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
-      }
+  async getTables() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships(
+      allTables.map((t) => t.name)
     );
-    const teachables = toTeachables(experimental_output.teachables);
-    this.#config.instructions.push(...teachables);
-    return {
-      teachables,
-      teachings: toInstructions(...this.#config.instructions)
-    };
+    return this.#applyTablesFilter(allTables, allRelationships).tables;
   }
-  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
+  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)})`
         );
-        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
+        return {
+          name: tableName,
+          rawName: tableName,
+          columns: columns.map((col) => ({
+            name: col.name ?? "unknown",
+            type: col.type ?? "unknown",
+            isPrimaryKey: (col.pk ?? 0) > 0
+          }))
+        };
+      })
     );
-    const stream2 = pipeline();
-    return {
-      generate: async () => {
-        const sql = await this.#getSql(stream2);
-        return sql;
-      },
-      stream: () => {
-        return stream2;
-      }
-    };
+    return tables;
   }
-  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
-      }
+  async getRelationships() {
+    const allTables = await this.#loadTables();
+    const allRelationships = await this.#loadRelationships(
+      allTables.map((t) => t.name)
     );
-    return output.suggestions;
+    return this.#applyTablesFilter(allTables, allRelationships).relationships;
   }
-  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
+  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));
+          }
         }
-      }),
-      [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 || {}
-      }
+        return Array.from(groups.values());
+      })
     );
+    return relationshipGroups.flat();
   }
-  async chat(messages, params, model) {
-    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({
-        model,
-        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}`;
+  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;
               }
-              await userProfileStore.add(type, text);
-              return `Added ${type}: ${text}`;
             }
+            return {
+              name: indexName,
+              columns,
+              unique: index.unique === 1,
+              primary: index.origin === "pk",
+              type: index.origin ?? void 0
+            };
           })
-        }
-      }),
-      [...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
+        );
+      } catch {
+        indexes = [];
       }
-    );
-    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.";
+      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;
         }
-      },
-      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");
+        if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT) {
+          continue;
         }
-        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
-        });
+        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;
   }
 };
-if (import.meta.main) {
-}
 
 // packages/text2sql/src/lib/adapters/postgres.ts
 var POSTGRES_ERROR_MAP = {
@@ -3070,14 +3100,15 @@ var InMemoryHistory = class extends SqliteHistory {
 };
 export {
   Adapter,
-  BriefCache,
   History,
   InMemoryHistory,
+  JsonCache,
   Postgres,
   SqlServer,
   Sqlite,
   SqliteHistory,
   Text2Sql,
+  TmpCache,
   analogy,
   applyTablesFilter,
   clarification,