@deepagents/text2sql 0.3.0 → 0.6.0

package/dist/index.js

@@ -1,3 +1,154 @@
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+function createGroundingContext() {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  async introspect(ctx = createGroundingContext()) {
+    const lines = [];
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      lines.push({
+        tag: grounding.tag,
+        fn: await grounding.execute(ctx)
+      });
+    }
+    return lines.map(({ fn, tag }) => {
+      const description = fn();
+      if (description === null) {
+        return "";
+      }
+      return `<${tag}>
+${description}
+</${tag}>`;
+    }).join("\n");
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+function filterTablesByName(tables, filter) {
+  if (!filter) return tables;
+  return tables.filter((table) => matchesFilter(table.name, filter));
+}
+function filterRelationshipsByTables(relationships, tableNames) {
+  if (tableNames === void 0) {
+    return relationships;
+  }
+  if (tableNames.size === 0) {
+    return [];
+  }
+  return relationships.filter(
+    (it) => tableNames.has(it.table) || tableNames.has(it.referenced_table)
+  );
+}
+function applyTablesFilter(tables, relationships, filter) {
+  if (!filter) {
+    return { tables, relationships };
+  }
+  const allowedNames = new Set(
+    getTablesWithRelated(tables, relationships, filter)
+  );
+  return {
+    tables: tables.filter((table) => allowedNames.has(table.name)),
+    relationships: filterRelationshipsByTables(relationships, allowedNames)
+  };
+}
+function matchesFilter(tableName, filter) {
+  if (Array.isArray(filter)) {
+    return filter.includes(tableName);
+  }
+  return filter.test(tableName);
+}
+function getTablesWithRelated(allTables, relationships, filter) {
+  const matchedTables = filterTablesByName(allTables, filter).map(
+    (it) => it.name
+  );
+  if (matchedTables.length === 0) {
+    return [];
+  }
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const rel of relationships) {
+    if (!adjacency.has(rel.table)) {
+      adjacency.set(rel.table, /* @__PURE__ */ new Set());
+    }
+    if (!adjacency.has(rel.referenced_table)) {
+      adjacency.set(rel.referenced_table, /* @__PURE__ */ new Set());
+    }
+    adjacency.get(rel.table).add(rel.referenced_table);
+    adjacency.get(rel.referenced_table).add(rel.table);
+  }
+  const result = new Set(matchedTables);
+  const queue = [...matchedTables];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const neighbors = adjacency.get(current);
+    if (!neighbors) {
+      continue;
+    }
+    for (const neighbor of neighbors) {
+      if (!result.has(neighbor)) {
+        result.add(neighbor);
+        queue.push(neighbor);
+      }
+    }
+  }
+  return Array.from(result);
+}
+
 // packages/text2sql/src/lib/agents/suggestions.agents.ts
 import { groq } from "@ai-sdk/groq";
 import dedent from "dedent";
@@ -54,10 +205,7 @@ var suggestionsAgent = agent({
 import { groq as groq2 } from "@ai-sdk/groq";
 import { tool } from "ai";
 import z2 from "zod";
-import {
-  agent as agent2,
-  toState
-} from "@deepagents/agent";
+import { agent as agent2, toState } from "@deepagents/agent";
 import { scratchpad_tool } from "@deepagents/toolbox";
 
 // packages/text2sql/src/lib/teach/xml.ts
@@ -106,20 +254,23 @@ function escapeXml(value) {
 function term(name, definition) {
   return {
     type: "term",
-    format: () => wrapBlock("term", [leaf("name", name), leaf("definition", definition)])
+    encode: () => ({ type: "term", name, definition }),
+    decode: () => wrapBlock("term", [leaf("name", name), leaf("definition", definition)])
   };
 }
 function hint(text) {
   return {
     type: "hint",
-    format: () => leaf("hint", text)
+    encode: () => ({ type: "hint", text }),
+    decode: () => leaf("hint", text)
   };
 }
 function guardrail(input) {
   const { rule, reason, action } = input;
   return {
     type: "guardrail",
-    format: () => wrapBlock("guardrail", [
+    encode: () => ({ type: "guardrail", rule, reason, action }),
+    decode: () => wrapBlock("guardrail", [
       leaf("rule", rule),
       reason ? leaf("reason", reason) : "",
       action ? leaf("action", action) : ""
@@ -130,7 +281,8 @@ function explain(input) {
   const { concept, explanation, therefore } = input;
   return {
     type: "explain",
-    format: () => wrapBlock("explanation", [
+    encode: () => ({ type: "explain", concept, explanation, therefore }),
+    decode: () => wrapBlock("explanation", [
       leaf("concept", concept),
       leaf("details", explanation),
       therefore ? leaf("therefore", therefore) : ""
@@ -141,7 +293,8 @@ function example(input) {
   const { question, answer, note } = input;
   return {
     type: "example",
-    format: () => wrapBlock("example", [
+    encode: () => ({ type: "example", question, answer, note }),
+    decode: () => wrapBlock("example", [
       leaf("question", question),
       leaf("answer", answer),
       note ? leaf("note", note) : ""
@@ -152,7 +305,8 @@ function clarification(input) {
   const { when, ask, reason } = input;
   return {
     type: "clarification",
-    format: () => wrapBlock("clarification", [
+    encode: () => ({ type: "clarification", when, ask, reason }),
+    decode: () => wrapBlock("clarification", [
       leaf("when", when),
       leaf("ask", ask),
       leaf("reason", reason)
@@ -163,7 +317,8 @@ function workflow(input) {
   const { task, steps, triggers, notes } = input;
   return {
     type: "workflow",
-    format: () => wrapBlock("workflow", [
+    encode: () => ({ type: "workflow", task, steps, triggers, notes }),
+    decode: () => wrapBlock("workflow", [
       leaf("task", task),
       triggers?.length ? list("triggers", triggers, "trigger") : "",
       list("steps", steps, "step"),
@@ -175,7 +330,8 @@ function quirk(input) {
   const { issue, workaround } = input;
   return {
     type: "quirk",
-    format: () => wrapBlock("quirk", [
+    encode: () => ({ type: "quirk", issue, workaround }),
+    decode: () => wrapBlock("quirk", [
       leaf("issue", issue),
       leaf("workaround", workaround)
     ])
@@ -185,7 +341,8 @@ function styleGuide(input) {
   const { prefer, never, always } = input;
   return {
     type: "styleGuide",
-    format: () => wrapBlock("style_guide", [
+    encode: () => ({ type: "styleGuide", prefer, never, always }),
+    decode: () => wrapBlock("style_guide", [
       leaf("prefer", prefer),
       always ? leaf("always", always) : "",
       never ? leaf("never", never) : ""
@@ -196,7 +353,15 @@ function analogy(input) {
   const { concept, relationship, insight, therefore, pitfall } = input;
   return {
     type: "analogy",
-    format: () => wrapBlock("analogy", [
+    encode: () => ({
+      type: "analogy",
+      concept,
+      relationship,
+      insight,
+      therefore,
+      pitfall
+    }),
+    decode: () => wrapBlock("analogy", [
       list("concepts", concept, "concept"),
       leaf("relationship", relationship),
       insight ? leaf("insight", insight) : "",
@@ -208,7 +373,8 @@ function analogy(input) {
 function glossary(entries) {
   return {
     type: "glossary",
-    format: () => wrapBlock(
+    encode: () => ({ type: "glossary", entries }),
+    decode: () => wrapBlock(
       "glossary",
       Object.entries(entries).map(
         ([term2, sql]) => wrapBlock("entry", [leaf("term", term2), leaf("sql", sql)])
@@ -220,7 +386,8 @@ function identity(input) {
   const { name, role } = input;
   return {
     type: "identity",
-    format: () => wrapBlock("identity", [
+    encode: () => ({ type: "identity", name, role }),
+    decode: () => wrapBlock("identity", [
       name ? leaf("name", name) : "",
       role ? leaf("role", role) : ""
     ])
@@ -230,35 +397,40 @@ function persona(input) {
   const { name, role, tone } = input;
   return {
     type: "persona",
-    format: () => wrapBlock("persona", [
+    encode: () => ({ type: "persona", name, role, tone: tone ?? "" }),
+    decode: () => wrapBlock("persona", [
       leaf("name", name),
       leaf("role", role),
-      leaf("tone", tone)
+      tone ? leaf("tone", tone) : ""
     ])
   };
 }
 function alias(termName, meaning) {
   return {
     type: "alias",
-    format: () => wrapBlock("alias", [leaf("term", termName), leaf("meaning", meaning)])
+    encode: () => ({ type: "alias", term: termName, meaning }),
+    decode: () => wrapBlock("alias", [leaf("term", termName), leaf("meaning", meaning)])
   };
 }
 function preference(aspect, value) {
   return {
     type: "preference",
-    format: () => wrapBlock("preference", [leaf("aspect", aspect), leaf("value", value)])
+    encode: () => ({ type: "preference", aspect, value }),
+    decode: () => wrapBlock("preference", [leaf("aspect", aspect), leaf("value", value)])
   };
 }
 function context(description) {
   return {
     type: "context",
-    format: () => leaf("context", description)
+    encode: () => ({ type: "context", description }),
+    decode: () => leaf("context", description)
   };
 }
 function correction(subject, clarification2) {
   return {
     type: "correction",
-    format: () => wrapBlock("correction", [
+    encode: () => ({ type: "correction", subject, clarification: clarification2 }),
+    decode: () => wrapBlock("correction", [
       leaf("subject", subject),
       leaf("clarification", clarification2)
     ])
@@ -267,7 +439,8 @@ function correction(subject, clarification2) {
 function teachable(tag, ...teachables) {
   return {
     type: "user_profile",
-    format: () => toInstructions(tag, ...teachables)
+    encode: () => teachables[0]?.encode() ?? { type: "context", description: "" },
+    decode: () => toInstructions(tag, ...teachables)
   };
 }
 function toInstructions(tag, ...teachables) {
@@ -286,7 +459,7 @@ function toInstructions(tag, ...teachables) {
     if (!items?.length) {
       return "";
     }
-    const renderedItems = items.map((item) => item.format().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
+    const renderedItems = items.map((item) => item.decode().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
     if (!renderedItems.length) {
       return "";
     }
@@ -298,7 +471,7 @@ ${renderedItems}
     if (definedTypes.has(type)) {
       continue;
     }
-    const renderedItems = items.map((item) => item.format().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
+    const renderedItems = items.map((item) => item.decode().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
     if (renderedItems.length) {
       sections.push(renderedItems);
     }
@@ -566,14 +739,14 @@ var tools = {
       limit: z2.number().min(1).max(10).default(3).optional().describe("Number of rows to sample (1-10, default 3).")
     }),
     execute: ({ tableName, columns, limit = 3 }, options) => {
-      const sanitize = (name) => name.replace(/[^a-zA-Z0-9_.]/g, "");
-      const safeTable = sanitize(tableName);
-      const columnList = columns?.length ? columns.map(sanitize).join(", ") : "*";
       const safeLimit = Math.min(Math.max(1, limit), 10);
       const state = toState(options);
-      return state.adapter.execute(
-        `SELECT ${columnList} FROM ${safeTable} LIMIT ${safeLimit}`
+      const sql = state.adapter.buildSampleRowsQuery(
+        tableName,
+        columns,
+        safeLimit
       );
+      return state.adapter.execute(sql);
     }
   }),
   db_query: tool({
@@ -685,28 +858,6 @@ var memoryTools = {
     }
   })
 };
-var sqlQueryAgent = agent2({
-  name: "text2sql",
-  model: groq2("openai/gpt-oss-20b"),
-  tools,
-  // output: z.object({
-  //   sql: z
-  //     .string()
-  //     .describe('The SQL query generated to answer the user question.'),
-  // }),
-  prompt: (state) => {
-    return `
-    <agent>
-      <name>Freya</name>
-      <role>You are an expert SQL query generator, answering business questions with accurate queries.</role>
-      <tone>Your tone should be concise and business-friendly.</tone>
-    </agent>
-    ${state?.teachings || ""}
-    ${state?.introspection || ""}
-    <output>SQL query that can run directly without prose whatsoever</output>
-  `;
-  }
-});
 var t_a_g = agent2({
   model: groq2("openai/gpt-oss-20b"),
   tools,
@@ -723,20 +874,187 @@ var t_a_g = agent2({
   }
 });
 
-// packages/text2sql/src/lib/file-cache.ts
+// packages/text2sql/src/lib/checkpoint.ts
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import pLimit from "p-limit";
+var Checkpoint = class _Checkpoint {
+  constructor(path2, configHash, points) {
+    this.path = path2;
+    this.configHash = configHash;
+    this.points = points;
+  }
+  points;
+  /**
+   * Load checkpoint from file, or return empty checkpoint if none exists.
+   * Handles corrupted files and config changes gracefully.
+   */
+  static async load(options) {
+    const { path: path2, configHash } = options;
+    if (existsSync(path2)) {
+      try {
+        const content = readFileSync(path2, "utf-8");
+        const file = JSON.parse(content);
+        if (configHash && file.configHash && file.configHash !== configHash) {
+          console.log("\u26A0 Config changed, starting fresh");
+          return new _Checkpoint(path2, configHash, {});
+        }
+        const points = file.points ?? {};
+        const totalEntries = Object.values(points).reduce(
+          (sum, p) => sum + p.entries.length,
+          0
+        );
+        console.log(`\u2713 Resuming from checkpoint (${totalEntries} entries)`);
+        return new _Checkpoint(path2, configHash, points);
+      } catch {
+        console.log("\u26A0 Checkpoint corrupted, starting fresh");
+        return new _Checkpoint(path2, configHash, {});
+      }
+    }
+    console.log("Starting new checkpoint");
+    return new _Checkpoint(path2, configHash, {});
+  }
+  /**
+   * Run a single computation with checkpointing.
+   * If already completed, returns cached value.
+   *
+   * @param key - Unique identifier for this computation
+   * @param computation - Async function that produces the value
+   * @param codec - Optional codec for encoding/decoding non-primitive values
+   */
+  async run(key, computation, codec) {
+    const point = this.point(key);
+    return point.through(
+      "single",
+      async () => {
+        const result = await computation();
+        return codec ? codec.encode(result) : result;
+      },
+      codec
+    );
+  }
+  /**
+   * Create a resumable checkpoint point for iterative operations.
+   *
+   * @param step - Unique identifier for this checkpoint point
+   */
+  point(step) {
+    if (!this.points[step]) {
+      this.points[step] = { committed: false, entries: [] };
+    }
+    return new Point(this.points[step], () => this.save());
+  }
+  /**
+   * Process each input with automatic checkpointing and concurrency.
+   *
+   * @param step - Unique identifier for this checkpoint
+   * @param inputs - Items to process
+   * @param process - Function to process each input
+   * @param options - Optional settings like concurrency
+   * @returns All outputs (use `.flat()` if outputs are arrays)
+   */
+  async each(step, inputs, process2, options) {
+    const point = this.point(step);
+    const limit = pLimit(options?.concurrency ?? 1);
+    const inputArray = Array.from(inputs);
+    await Promise.all(
+      inputArray.map(
+        (input) => limit(() => point.through(input, () => process2(input)))
+      )
+    );
+    await point.commit();
+    return point.values();
+  }
+  /**
+   * Get clean output from all completed points.
+   * Single-entry points return the value directly, multi-entry return arrays.
+   */
+  getOutput() {
+    const output = {};
+    for (const [key, pointData] of Object.entries(this.points)) {
+      if (pointData.entries.length === 1) {
+        output[key] = pointData.entries[0].output;
+      } else {
+        output[key] = pointData.entries.map((e) => e.output);
+      }
+    }
+    return output;
+  }
+  /** Get the file path where checkpoint is stored */
+  getPath() {
+    return this.path;
+  }
+  async save() {
+    const file = {
+      configHash: this.configHash,
+      points: this.points
+    };
+    const content = JSON.stringify(file, null, 2);
+    const tempPath = `${this.path}.tmp`;
+    writeFileSync(tempPath, content);
+    renameSync(tempPath, this.path);
+  }
+};
+function hash(value) {
+  return createHash("md5").update(JSON.stringify(value)).digest("hex");
+}
+var Point = class {
+  constructor(data, persist) {
+    this.data = data;
+    this.persist = persist;
+    this.#cache = new Map(
+      data.entries.map((e) => [e.inputHash, e.output])
+    );
+  }
+  #cache;
+  /**
+   * Execute computation if input wasn't processed before.
+   * Returns cached output if input hash exists, otherwise executes, saves, and returns.
+   */
+  async through(input, compute, codec) {
+    const inputHash = hash(input);
+    if (this.#cache.has(inputHash)) {
+      const cached = this.#cache.get(inputHash);
+      return codec ? codec.decode(cached) : cached;
+    }
+    const output = await compute();
+    this.data.entries.push({ inputHash, output });
+    this.#cache.set(inputHash, output);
+    await this.persist();
+    return codec ? codec.decode(output) : output;
+  }
+  /** Mark this point as complete. */
+  async commit() {
+    this.data.committed = true;
+    await this.persist();
+  }
+  /** Check if this point has been committed. */
+  isCommitted() {
+    return this.data.committed;
+  }
+  /** Get all outputs from this point. */
+  values() {
+    return this.data.entries.map((e) => e.output);
+  }
+};
+function hashConfig(config) {
+  return createHash("md5").update(JSON.stringify(config)).digest("hex");
+}
+
+// packages/text2sql/src/lib/file-cache.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync2 } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 var FileCache = class {
   path;
   constructor(watermark, extension = ".txt") {
-    const hash = createHash("md5").update(watermark).digest("hex");
-    this.path = path.join(tmpdir(), `text2sql-${hash}${extension}`);
+    const hash2 = createHash2("md5").update(watermark).digest("hex");
+    this.path = path.join(tmpdir(), `text2sql-${hash2}${extension}`);
   }
   async get() {
-    if (existsSync(this.path)) {
+    if (existsSync2(this.path)) {
       return readFile(this.path, "utf-8");
     }
     return null;
@@ -961,240 +1279,1000 @@ import {
 } from "ai";
 import { v7 as v72 } from "uuid";
 import {
-  generate,
+  generate as generate4,
   stream,
-  user
+  user as user4
 } from "@deepagents/agent";
 
-// packages/text2sql/src/lib/agents/explainer.agent.ts
+// packages/text2sql/src/lib/agents/chat1.agent.ts
+import { groq as groq4 } from "@ai-sdk/groq";
+import { tool as tool2 } from "ai";
+import z4 from "zod";
+import { agent as agent4, toState as toState2 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool2 } from "@deepagents/toolbox";
+
+// packages/text2sql/src/lib/agents/sql.agent.ts
 import { groq as groq3 } from "@ai-sdk/groq";
-import dedent2 from "dedent";
+import { defaultSettingsMiddleware, wrapLanguageModel } from "ai";
 import z3 from "zod";
-import { agent as agent3 } from "@deepagents/agent";
-var explainerAgent = agent3({
-  name: "explainer",
+import { agent as agent3, generate, user } from "@deepagents/agent";
+var RETRY_TEMPERATURES = [0, 0.2, 0.3];
+var sqlQueryAgent = agent3({
+  name: "text2sql",
   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/teach/teachings.ts
-var teachings_default = [
-  hint(
-    "If the user asks to show a table or entity without specifying columns, use SELECT *."
-  ),
-  hint(
-    "When showing items associated with another entity, include the item ID and the related details requested."
-  ),
-  hint(
-    'When asked to "show" items, list them unless the user explicitly asks to count or total.'
-  ),
-  hint(
-    "Use canonical/LowCardinality values verbatim for filtering; [rows/size] hints suggest when to aggregate instead of listing."
-  ),
-  hint(
-    "Favor PK/indexed columns for joins and filters; follow relationship metadata for join direction and cardinality."
-  ),
-  guardrail({
-    rule: "Avoid unbounded scans on large/time-based tables.",
-    action: "Ask for or apply a reasonable recent date range before querying broad fact tables."
-  }),
-  guardrail({
-    rule: "Do not return oversized raw result sets.",
-    action: "Keep raw outputs to ~100 rows; aggregate or paginate unless the user explicitly confirms a larger pull."
-  }),
-  guardrail({
-    rule: "Prevent cartesian or guesswork joins.",
-    reason: "Protect correctness and performance.",
-    action: "If join keys are missing or unclear, inspect relationships and ask for the intended join path before executing."
-  }),
-  clarification({
-    when: "The request targets time-based data without a date range.",
-    ask: "Confirm the intended timeframe (e.g., last 30/90 days, YTD, specific year).",
-    reason: "Prevents large scans and irrelevant results."
-  }),
-  clarification({
-    when: 'The request uses ambiguous scoring or ranking language (e.g., "top", "best", "active") without a metric.',
-    ask: "Clarify the ranking metric or definition before writing the query.",
-    reason: "Ensures the correct aggregation/ordering is used."
-  }),
-  workflow({
-    task: "SQL generation plan",
-    steps: [
-      "Translate the question into SQL patterns (aggregation, segmentation, time range, ranking).",
-      "Choose tables/relations that satisfy those patterns; note lookup tables and filter values implied by schema hints.",
-      "Inspect samples with 'get_sample_rows' for any column you'll use in WHERE/JOIN conditions - target just those columns (e.g., get_sample_rows('orders', ['status', 'order_type'])).",
-      "Sketch join/filter/aggregation order considering table sizes, indexes, and stats.",
-      "Draft SQL, validate via 'validate_query', then execute via 'db_query' with a short reasoning note."
-    ]
-  }),
-  styleGuide({
-    prefer: "Summaries should be concise, business-friendly, highlight key comparisons, and add a short helpful follow-up when useful."
-  }),
-  // Tool usage constraints
-  guardrail({
-    rule: "Never output more than 100 rows of raw data.",
-    action: "Use aggregation or pagination otherwise."
-  }),
-  guardrail({
-    rule: "You must validate your query before final execution.",
-    action: "Follow the pattern: Draft Query \u2192 `validate_query` \u2192 Fix (if needed) \u2192 `db_query`."
-  }),
-  guardrail({
-    rule: "ALWAYS use `get_sample_rows` before writing queries that filter or compare against string columns.",
-    reason: "Prevents SQL errors from wrong value formats.",
-    action: "Target specific columns (e.g., get_sample_rows('table', ['status', 'type']))."
-  }),
-  guardrail({
-    rule: "Do not call `db_query` without first producing and validating a SQL snippet.",
-    action: "First produce the query string, then validate."
-  }),
-  hint(
-    "Use the `scratchpad` tool for strategic reflection during SQL query generation."
-  )
-];
-
-// packages/text2sql/src/lib/sql.ts
-var Text2Sql = class {
-  #config;
-  constructor(config) {
-    this.#config = {
-      adapter: config.adapter,
-      briefCache: new FileCache("brief-" + config.version),
-      history: config.history,
-      instructions: [...teachings_default, ...config.instructions ?? []],
-      tools: config.tools ?? {},
-      model: config.model,
-      memory: config.memory,
-      introspection: new FileCache("introspection-" + config.version)
-    };
-  }
-  async explain(sql) {
-    const { experimental_output } = await generate(
-      explainerAgent,
-      [user("Explain this SQL.")],
-      { sql }
-    );
-    return experimental_output.explanation;
+  logging: process.env.AGENT_LOGGING === "true",
+  output: z3.union([
+    z3.object({
+      sql: z3.string().describe("The SQL query that answers the question"),
+      reasoning: z3.string().optional().describe("The reasoning steps taken to generate the SQL")
+    }),
+    z3.object({
+      error: z3.string().describe(
+        "Error message explaining why the question cannot be answered with the given schema"
+      )
+    })
+  ]),
+  prompt: (state) => {
+    return `
+    ${state?.teachings || ""}
+    ${state?.introspection || ""}
+  `;
   }
-  async toSql(query, options) {
-    const introspection = await this.index();
-    const { text } = await generate(
-      sqlQueryAgent.clone({
-        model: this.#config.model,
-        tools: {
-          ...t_a_g.handoff.tools,
-          ...options?.tools ?? this.#config.tools
-        }
-      }),
-      [user(query)],
+});
+function extractSql(output) {
+  const match = output.match(/```sql\n?([\s\S]*?)```/);
+  return match ? match[1].trim() : output.trim();
+}
+async function generateSql(params) {
+  const {
+    input,
+    model,
+    temperature,
+    introspection,
+    instructions,
+    previousError
+  } = params;
+  const agentInstance = sqlQueryAgent.clone({
+    model: wrapLanguageModel({
+      model,
+      middleware: defaultSettingsMiddleware({
+        settings: { temperature, topP: 1 }
+      })
+    })
+  });
+  const messages = previousError ? [
+    user(input),
+    user(
+      `<validation_error>Your previous SQL query had the following error: ${previousError}. Please fix the query.</validation_error>`
+    )
+  ] : [user(input)];
+  try {
+    const { experimental_output: output } = await generate(
+      agentInstance,
+      messages,
       {
         teachings: toInstructions(
           "instructions",
           persona({
             name: "Freya",
-            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
-            tone: "Your tone should be concise and business-friendly."
+            role: "You are an expert SQL query generator. You translate natural language questions into precise, efficient SQL queries based on the provided database schema."
           }),
-          ...this.#config.instructions
+          ...instructions
         ),
-        adapter: this.#config.adapter,
         introspection
       }
     );
-    return text;
-  }
-  instruct(...dataset) {
-    this.#config.instructions.push(...dataset);
+    if ("error" in output) {
+      return { success: false, error: output.error, isUnanswerable: true };
+    }
+    return { success: true, sql: extractSql(output.sql) };
+  } catch (error) {
+    if (error instanceof Error && (error.message.includes("Failed to validate JSON") || error.message.includes("response did not match schema"))) {
+      return {
+        success: false,
+        error: `Schema validation failed: ${error.message}`
+      };
+    }
+    throw error;
   }
-  async inspect(agent4) {
-    const [grounding] = await Promise.all([this.index()]);
-    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
-      (name) => name.startsWith("render_")
-    );
-    const allInstructions = [
-      ...this.#config.instructions,
-      ...renderToolNames.length ? [
-        hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
-        styleGuide({
-          prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
-          always: "Include text insight alongside visualizations. Prefer line charts for time-based data."
-        })
-      ] : []
-    ];
-    const tools2 = Object.keys({
-      ...agent4.handoff.tools,
-      ...this.#config.memory ? memoryTools : {},
-      ...this.#config.tools
-    });
+}
+var sqlGenerators = {
+  generateSql
+};
+async function generateAndValidate(options, temperature, previousError) {
+  const result = await sqlGenerators.generateSql({
+    input: options.input,
+    model: options.model ?? sqlQueryAgent.model,
+    temperature,
+    introspection: options.introspection,
+    instructions: options.instructions,
+    previousError
+  });
+  if (!result.success) {
     return {
-      tools: tools2,
-      prompt: agent4.instructions({
-        introspection: grounding,
-        teachings: toInstructions(
-          "instructions",
-          persona({
-            name: "Freya",
-            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
-            tone: "Your tone should be concise and business-friendly."
-          }),
-          ...allInstructions
-        )
-      })
+      ok: false,
+      error: result.error,
+      isUnanswerable: result.isUnanswerable
     };
   }
-  async index(options) {
-    const cached = await this.#config.introspection.get();
-    if (cached) {
-      return cached;
-    }
-    const introspection = await this.#config.adapter.introspect();
-    await this.#config.introspection.set(introspection);
-    return introspection;
+  const validationError = await options.adapter.validate(result.sql);
+  if (validationError) {
+    return { ok: false, error: validationError };
   }
-  // public async suggest() {
-  //   const [introspection, adapterInfo] = await Promise.all([
-  //     this.index(),
-  //     this.#config.adapter.introspect(),
-  //   ]);
-  //   const { experimental_output: output } = await generate(
-  //     suggestionsAgent,
-  //     [
-  //       user(
-  //         'Suggest high-impact business questions and matching SQL queries for this database.',
-  //       ),
-  //     ],
-  //     {
-  //     },
-  //   );
-  //   return output.suggestions;
-  // }
-  async chat(messages, params) {
-    const [introspection, userTeachables] = await Promise.all([
-      this.index({ onProgress: console.log }),
-      this.#config.memory ? this.#config.memory.toTeachables(params.userId) : []
-    ]);
-    const chat = await this.#config.history.upsertChat({
-      id: params.chatId,
-      userId: params.userId,
-      title: "Chat " + params.chatId
-    });
-    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
-      (name) => name.startsWith("render_")
+  return { ok: true, sql: result.sql };
+}
+async function toSql(options) {
+  const { maxRetries = 3 } = options;
+  const errors = [];
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const temperature = RETRY_TEMPERATURES[attempt - 1] ?? 0.3;
+    const result = await generateAndValidate(
+      options,
+      temperature,
+      errors.at(-1)
     );
-    const instructions = [
-      ...this.#config.instructions,
-      ...renderToolNames.length ? [
+    if (result.ok) {
+      return {
+        sql: result.sql,
+        attempts: attempt,
+        errors: errors.length ? errors : void 0
+      };
+    }
+    if (result.isUnanswerable) {
+      return { sql: "", attempts: attempt, errors: [result.error] };
+    }
+    errors.push(result.error);
+  }
+  return { sql: "", attempts: maxRetries, errors };
+}
+
+// packages/text2sql/src/lib/agents/chat1.agent.ts
+var tools2 = {
+  query_database: tool2({
+    description: `Query the database to answer a question. Provide your question in natural language and this tool will:
+1. Generate the appropriate SQL query
+2. Validate the SQL syntax
+3. Execute the query
+4. Return the results
+
+Use this tool when you need to retrieve data to answer the user's question.`,
+    inputSchema: z4.object({
+      question: z4.string().min(1).describe(
+        "The question to answer, expressed in natural language. Be specific about what data you need."
+      ),
+      reasoning: z4.string().optional().describe(
+        "Your reasoning for why this query is needed to answer the user."
+      )
+    }),
+    execute: async ({ question }, options) => {
+      const state = toState2(options);
+      try {
+        const sqlResult = await toSql({
+          input: question,
+          adapter: state.adapter,
+          introspection: state.introspection,
+          instructions: state.instructions
+        });
+        if (!sqlResult.sql) {
+          return {
+            success: false,
+            error: sqlResult.errors?.join("; ") || "Failed to generate SQL",
+            attempts: sqlResult.attempts
+          };
+        }
+        const data = await state.adapter.execute(sqlResult.sql);
+        return {
+          success: true,
+          sql: sqlResult.sql,
+          data,
+          attempts: sqlResult.attempts
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error occurred"
+        };
+      }
+    }
+  }),
+  scratchpad: scratchpad_tool2
+};
+var chat1Agent = agent4({
+  name: "chat1-combined",
+  model: groq4("openai/gpt-oss-20b"),
+  tools: tools2,
+  prompt: (state) => {
+    return `
+${state?.teachings || ""}
+${state?.introspection || ""}
+`;
+  }
+});
+
+// packages/text2sql/src/lib/agents/chat2.agent.ts
+import { groq as groq5 } from "@ai-sdk/groq";
+import { tool as tool3 } from "ai";
+import z5 from "zod";
+import { agent as agent5, toState as toState3 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool3 } from "@deepagents/toolbox";
+var tools3 = {
+  generate_sql: tool3({
+    description: `Generate a SQL query from a natural language question. This tool will:
+1. Translate your question into SQL
+2. Validate the SQL syntax
+3. Retry with corrections if validation fails
+4. Return the validated SQL for your review
+
+Use this BEFORE execute_sql to see what query will be run. You can then:
+- Explain the approach to the user
+- Decide if the SQL looks correct
+- Refine your question and regenerate if needed`,
+    inputSchema: z5.object({
+      question: z5.string().min(1).describe(
+        "The question to translate into SQL. Be specific about what data you need."
+      ),
+      reasoning: z5.string().optional().describe("Your reasoning for why this data is needed.")
+    }),
+    execute: async ({ question }, options) => {
+      const state = toState3(options);
+      try {
+        const sqlResult = await toSql({
+          input: question,
+          adapter: state.adapter,
+          introspection: state.introspection,
+          instructions: state.instructions
+        });
+        if (!sqlResult.sql) {
+          return {
+            success: false,
+            error: sqlResult.errors?.join("; ") || "Failed to generate SQL",
+            attempts: sqlResult.attempts,
+            validationErrors: sqlResult.errors
+          };
+        }
+        return {
+          success: true,
+          sql: sqlResult.sql,
+          attempts: sqlResult.attempts,
+          validationErrors: sqlResult.errors
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error occurred"
+        };
+      }
+    }
+  }),
+  execute_sql: tool3({
+    description: `Execute a SQL query and return the results. Use this AFTER generate_sql to run the query.
+
+Only SELECT and WITH (CTE) queries are allowed - no data modification.`,
+    inputSchema: z5.object({
+      sql: z5.string().min(1).refine(
+        (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
+        {
+          message: "Only read-only SELECT or WITH queries are allowed."
+        }
+      ).describe("The SQL query to execute (must be SELECT or WITH)."),
+      reasoning: z5.string().optional().describe("Brief explanation of what this query retrieves.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState3(options);
+      try {
+        const data = await state.adapter.execute(sql);
+        return {
+          success: true,
+          data,
+          rowCount: Array.isArray(data) ? data.length : void 0
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Query execution failed"
+        };
+      }
+    }
+  }),
+  scratchpad: scratchpad_tool3
+};
+var chat2Agent = agent5({
+  name: "chat2-with-peek",
+  model: groq5("openai/gpt-oss-20b"),
+  tools: tools3,
+  prompt: (state) => {
+    return `
+${state?.teachings || ""}
+${state?.introspection || ""}
+
+When answering questions that require database queries:
+1. First use generate_sql to create the SQL query
+2. Review the generated SQL to ensure it matches the user's intent
+3. Use execute_sql to run the query
+4. Present the results to the user
+
+If the generated SQL doesn't look right, you can refine your question and regenerate.
+`;
+  }
+});
+
+// packages/text2sql/src/lib/agents/chat3.agent.ts
+import { groq as groq6 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware2, tool as tool4, wrapLanguageModel as wrapLanguageModel2 } from "ai";
+import z6 from "zod";
+import { agent as agent6, generate as generate2, toState as toState4, user as user2 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool4 } from "@deepagents/toolbox";
+var collaborativeSqlOutputSchema = z6.discriminatedUnion("status", [
+  z6.object({
+    status: z6.literal("success"),
+    sql: z6.string().describe("The generated SQL query"),
+    confidence: z6.enum(["high", "medium", "low"]).describe("Confidence level in this SQL being correct"),
+    assumptions: z6.array(z6.string()).optional().describe("Assumptions made during SQL generation"),
+    reasoning: z6.string().optional().describe("Brief explanation of the query approach")
+  }),
+  z6.object({
+    status: z6.literal("clarification_needed"),
+    question: z6.string().describe("Question to clarify the request"),
+    context: z6.string().optional().describe("Why this clarification is needed"),
+    options: z6.array(z6.string()).optional().describe("Possible options if applicable")
+  }),
+  z6.object({
+    status: z6.literal("unanswerable"),
+    reason: z6.string().describe("Why this question cannot be answered"),
+    suggestions: z6.array(z6.string()).optional().describe("Alternative questions that could be answered")
+  })
+]);
+var collaborativeSqlAgent = agent6({
+  name: "collaborative-sql",
+  model: groq6("openai/gpt-oss-20b"),
+  output: collaborativeSqlOutputSchema,
+  prompt: (state) => {
+    return `
+${toInstructions(
+      "instructions",
+      persona({
+        name: "SQLCollab",
+        role: "You are an expert SQL query generator that collaborates with the user to ensure accuracy."
+      }),
+      ...state?.instructions || []
+    )}
+${state?.introspection || ""}
+
+IMPORTANT: You have three response options:
+
+1. SUCCESS - When you can confidently generate SQL:
+   - Provide the SQL query
+   - Rate your confidence (high/medium/low)
+   - List any assumptions you made
+
+2. CLARIFICATION_NEEDED - When the question is ambiguous:
+   - Ask a specific clarifying question
+   - Explain why clarification is needed
+   - Provide options if applicable
+
+3. UNANSWERABLE - When the question cannot be answered with available data:
+   - Explain why
+   - Suggest alternative questions that could be answered
+
+Prefer asking for clarification over making low-confidence guesses.
+`;
+  }
+});
+var tools4 = {
+  consult_sql_agent: tool4({
+    description: `Consult the SQL specialist agent to generate a query. The SQL agent may:
+- Return a SQL query with confidence level and assumptions
+- Ask for clarification if the question is ambiguous
+- Indicate if the question cannot be answered with available data
+
+Based on the response:
+- If clarification is needed, you can provide context or ask the user
+- If assumptions were made, verify them with the user for important queries
+- If unanswerable, relay the suggestions to the user`,
+    inputSchema: z6.object({
+      question: z6.string().min(1).describe("The question to translate into SQL."),
+      context: z6.string().optional().describe("Additional context from the conversation that might help."),
+      previousClarification: z6.string().optional().describe(
+        "Answer to a previous clarification question from the SQL agent."
+      )
+    }),
+    execute: async ({ question, context: context2, previousClarification }, options) => {
+      const state = toState4(options);
+      try {
+        let fullQuestion = question;
+        if (context2) {
+          fullQuestion = `${question}
+
+Additional context: ${context2}`;
+        }
+        if (previousClarification) {
+          fullQuestion = `${fullQuestion}
+
+Clarification provided: ${previousClarification}`;
+        }
+        const agentInstance = collaborativeSqlAgent.clone({
+          model: wrapLanguageModel2({
+            model: collaborativeSqlAgent.model,
+            middleware: defaultSettingsMiddleware2({
+              settings: { temperature: 0.1 }
+            })
+          })
+        });
+        const { experimental_output: output } = await generate2(
+          agentInstance,
+          [user2(fullQuestion)],
+          state
+        );
+        if (output.status === "success") {
+          const validationError = await state.adapter.validate(output.sql);
+          if (validationError) {
+            return {
+              success: false,
+              error: `SQL validation failed: ${validationError}`
+            };
+          }
+          const data = await state.adapter.execute(output.sql);
+          return {
+            success: true,
+            sql: output.sql,
+            data,
+            confidence: output.confidence,
+            assumptions: output.assumptions
+          };
+        }
+        if (output.status === "clarification_needed") {
+          return {
+            success: false,
+            clarificationNeeded: output.question,
+            clarificationContext: output.context,
+            clarificationOptions: output.options
+          };
+        }
+        if (output.status === "unanswerable") {
+          return {
+            success: false,
+            unanswerableReason: output.reason,
+            suggestions: output.suggestions
+          };
+        }
+        return {
+          success: false,
+          error: "Unexpected response from SQL agent"
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error occurred"
+        };
+      }
+    }
+  }),
+  execute_sql: tool4({
+    description: `Execute a SQL query directly. Use this when you have SQL that you want to run
+(e.g., after receiving SQL from consult_sql_agent or for follow-up queries).`,
+    inputSchema: z6.object({
+      sql: z6.string().min(1).refine(
+        (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
+        {
+          message: "Only read-only SELECT or WITH queries are allowed."
+        }
+      ).describe("The SQL query to execute.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState4(options);
+      try {
+        const validationError = await state.adapter.validate(sql);
+        if (validationError) {
+          return {
+            success: false,
+            error: `Validation failed: ${validationError}`
+          };
+        }
+        const data = await state.adapter.execute(sql);
+        return {
+          success: true,
+          data,
+          rowCount: Array.isArray(data) ? data.length : void 0
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Execution failed"
+        };
+      }
+    }
+  }),
+  scratchpad: scratchpad_tool4
+};
+var chat3Agent = agent6({
+  name: "chat3-collaborative",
+  model: groq6("openai/gpt-oss-20b"),
+  tools: tools4,
+  prompt: (state) => {
+    return `
+${state?.teachings || ""}
+${state?.introspection || ""}
+
+When answering questions that require database queries, use the consult_sql_agent tool.
+
+The SQL agent may respond in three ways:
+1. SUCCESS with SQL, confidence, and assumptions - review the confidence and assumptions
+2. CLARIFICATION_NEEDED with a question - either answer from context or ask the user
+3. UNANSWERABLE with reason and suggestions - relay this to the user helpfully
+
+For medium/low confidence results, consider mentioning the assumptions to the user.
+For clarification requests, try to answer from conversation context first before asking the user.
+`;
+  }
+});
+
+// packages/text2sql/src/lib/agents/chat4.agent.ts
+import { groq as groq7 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware3, tool as tool5, wrapLanguageModel as wrapLanguageModel3 } from "ai";
+import z7 from "zod";
+import { agent as agent7, generate as generate3, toState as toState5, user as user3 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool5 } from "@deepagents/toolbox";
+var questionDecompositionSchema = z7.object({
+  originalQuestion: z7.string().describe("The original question being decomposed"),
+  breakdown: z7.array(z7.string()).min(1).describe(
+    "Semantic breakdown of the question into its component parts. Each part describes an aspect of what is being asked, NOT how to implement it."
+  ),
+  entities: z7.array(z7.string()).optional().describe(
+    "Key entities/concepts mentioned (e.g., customers, orders, products)"
+  ),
+  filters: z7.array(z7.string()).optional().describe(
+    'Filtering criteria mentioned (e.g., "last quarter", "above $100")'
+  ),
+  aggregation: z7.string().optional().describe(
+    'Type of aggregation if any (e.g., "count", "sum", "average", "top N")'
+  ),
+  ambiguities: z7.array(z7.string()).optional().describe("Any ambiguous parts that might need clarification")
+});
+var decompositionSqlOutputSchema = z7.union([
+  z7.object({
+    sql: z7.string().describe("The SQL query that answers the decomposed question"),
+    reasoning: z7.string().optional().describe("How each breakdown component was addressed")
+  }),
+  z7.object({
+    error: z7.string().describe("Error message if the question cannot be answered")
+  })
+]);
+var decompositionSqlAgent = agent7({
+  name: "decomposition-sql",
+  model: groq7("openai/gpt-oss-20b"),
+  output: decompositionSqlOutputSchema,
+  prompt: (state) => {
+    return `
+${toInstructions(
+      "instructions",
+      persona({
+        name: "SQLDecomp",
+        role: "You are an expert SQL query generator. You receive questions broken down into semantic components and generate precise SQL."
+      }),
+      ...state?.instructions || []
+    )}
+${state?.introspection || ""}
+
+You will receive questions in a decomposed format with:
+- breakdown: Semantic parts of the question
+- entities: Key concepts mentioned
+- filters: Filtering criteria
+- aggregation: Type of aggregation needed
+- ambiguities: Potentially unclear parts
+
+Address each component of the breakdown in your SQL.
+If there are ambiguities, make reasonable assumptions and note them in your reasoning.
+`;
+  }
+});
+var RETRY_TEMPERATURES2 = [0, 0.2, 0.3];
+var tools5 = {
+  query_with_decomposition: tool5({
+    description: `Query the database using question decomposition. This tool:
+1. Breaks down your question into semantic components (entities, filters, aggregations)
+2. Passes the decomposition to the SQL specialist
+3. Generates and validates SQL
+4. Executes and returns results
+
+This approach helps ensure all aspects of the question are addressed in the query.`,
+    inputSchema: z7.object({
+      question: z7.string().min(1).describe("The question to answer."),
+      breakdown: z7.array(z7.string()).min(1).describe(
+        'Break down the question into its semantic parts. Each part should describe an ASPECT of what is being asked, not instructions. Example for "top customers by revenue last month": ["customers who made purchases", "revenue from those purchases", "time period: last month", "ranking: top by total revenue"]'
+      ),
+      entities: z7.array(z7.string()).optional().describe(
+        'Key entities mentioned (e.g., ["customers", "orders", "products"])'
+      ),
+      filters: z7.array(z7.string()).optional().describe('Filter criteria (e.g., ["last month", "status = active"])'),
+      aggregation: z7.string().optional().describe(
+        'Aggregation type if any (e.g., "sum revenue", "count orders", "top 10")'
+      ),
+      ambiguities: z7.array(z7.string()).optional().describe("Note any ambiguous parts you identified")
+    }),
+    execute: async ({ question, breakdown, entities, filters, aggregation, ambiguities }, options) => {
+      const state = toState5(options);
+      const decomposition = {
+        originalQuestion: question,
+        breakdown,
+        entities,
+        filters,
+        aggregation,
+        ambiguities
+      };
+      const decomposedPrompt = formatDecomposition(decomposition);
+      try {
+        let lastError;
+        for (let attempt = 0; attempt < RETRY_TEMPERATURES2.length; attempt++) {
+          const temperature = RETRY_TEMPERATURES2[attempt];
+          const agentInstance = decompositionSqlAgent.clone({
+            model: wrapLanguageModel3({
+              model: decompositionSqlAgent.model,
+              middleware: defaultSettingsMiddleware3({
+                settings: { temperature }
+              })
+            })
+          });
+          const prompt = lastError ? `${decomposedPrompt}
+
+Previous attempt failed with: ${lastError}. Please fix the query.` : decomposedPrompt;
+          const { experimental_output: output } = await generate3(
+            agentInstance,
+            [user3(prompt)],
+            state
+          );
+          if ("error" in output) {
+            return {
+              success: false,
+              question,
+              decomposition,
+              error: output.error,
+              attempts: attempt + 1
+            };
+          }
+          const validationError = await state.adapter.validate(output.sql);
+          if (validationError) {
+            lastError = validationError;
+            continue;
+          }
+          const data = await state.adapter.execute(output.sql);
+          return {
+            success: true,
+            question,
+            decomposition,
+            sql: output.sql,
+            data,
+            reasoning: output.reasoning,
+            attempts: attempt + 1
+          };
+        }
+        return {
+          success: false,
+          question,
+          decomposition,
+          error: `Failed after ${RETRY_TEMPERATURES2.length} attempts. Last error: ${lastError}`,
+          attempts: RETRY_TEMPERATURES2.length
+        };
+      } catch (error) {
+        return {
+          success: false,
+          question,
+          decomposition,
+          error: error instanceof Error ? error.message : "Unknown error occurred"
+        };
+      }
+    }
+  }),
+  execute_sql: tool5({
+    description: `Execute a SQL query directly. Use for follow-up queries or when you already have SQL.`,
+    inputSchema: z7.object({
+      sql: z7.string().min(1).refine(
+        (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
+        {
+          message: "Only read-only SELECT or WITH queries are allowed."
+        }
+      ).describe("The SQL query to execute.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState5(options);
+      try {
+        const validationError = await state.adapter.validate(sql);
+        if (validationError) {
+          return {
+            success: false,
+            error: `Validation failed: ${validationError}`
+          };
+        }
+        const data = await state.adapter.execute(sql);
+        return {
+          success: true,
+          data,
+          rowCount: Array.isArray(data) ? data.length : void 0
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Execution failed"
+        };
+      }
+    }
+  }),
+  scratchpad: scratchpad_tool5
+};
+function formatDecomposition(decomposition) {
+  const parts = [
+    `Original Question: ${decomposition.originalQuestion}`,
+    "",
+    "Question Breakdown:",
+    ...decomposition.breakdown.map((part, i) => `  ${i + 1}. ${part}`)
+  ];
+  if (decomposition.entities?.length) {
+    parts.push("", `Entities: ${decomposition.entities.join(", ")}`);
+  }
+  if (decomposition.filters?.length) {
+    parts.push("", `Filters: ${decomposition.filters.join(", ")}`);
+  }
+  if (decomposition.aggregation) {
+    parts.push("", `Aggregation: ${decomposition.aggregation}`);
+  }
+  if (decomposition.ambiguities?.length) {
+    parts.push(
+      "",
+      "Potential Ambiguities:",
+      ...decomposition.ambiguities.map((a) => `  - ${a}`)
+    );
+  }
+  parts.push(
+    "",
+    "Generate SQL that addresses each component of the breakdown."
+  );
+  return parts.join("\n");
+}
+var chat4Agent = agent7({
+  name: "chat4-decomposition",
+  model: groq7("openai/gpt-oss-20b"),
+  tools: tools5,
+  prompt: (state) => {
+    return `
+${state?.teachings || ""}
+${state?.introspection || ""}
+
+When answering questions that require database queries, use the query_with_decomposition tool.
+
+IMPORTANT: You must break down the question into semantic parts - describe WHAT is being asked, not HOW to implement it.
+
+Good breakdown example for "Which customers bought the most expensive products last quarter?":
+- "customers who made purchases" (entity relationship)
+- "products they purchased" (what products)
+- "expensive products - need definition" (filter criteria - note ambiguity)
+- "last quarter" (time filter)
+- "most - ranking by count or value?" (aggregation - note ambiguity)
+
+Bad breakdown (too instructional):
+- "JOIN customers with orders" (this is HOW, not WHAT)
+- "Use ORDER BY and LIMIT" (this is implementation)
+
+Break the question into its semantic aspects, and let the SQL specialist figure out the implementation.
+`;
+  }
+});
+
+// packages/text2sql/src/lib/agents/explainer.agent.ts
+import { groq as groq8 } from "@ai-sdk/groq";
+import dedent2 from "dedent";
+import z8 from "zod";
+import { agent as agent8 } from "@deepagents/agent";
+var explainerAgent = agent8({
+  name: "explainer",
+  model: groq8("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: z8.object({
+    explanation: z8.string().describe("The explanation of the SQL query.")
+  })
+});
+
+// packages/text2sql/src/lib/synthesis/types.ts
+async function toPairs(producer) {
+  const pairs = [];
+  for await (const chunk of producer.produce()) {
+    pairs.push(...chunk);
+  }
+  return pairs;
+}
+
+// packages/text2sql/src/lib/teach/teachings.ts
+function guidelines(options = {}) {
+  const { date = "strict" } = options;
+  const baseTeachings = [
+    // Schema adherence
+    hint(
+      "Use only tables and columns that exist in the schema. Never reference non-existent entities."
+    ),
+    hint(
+      "If the user asks to show a table or entity without specifying columns, use SELECT *."
+    ),
+    hint(
+      "When showing items associated with another entity, include the item ID and the related details requested."
+    ),
+    hint(
+      'When asked to "show" items, list them unless the user explicitly asks to count or total.'
+    ),
+    hint(
+      "Use canonical/LowCardinality values verbatim for filtering; [rows/size] hints suggest when to aggregate instead of listing."
+    ),
+    // Joins and relationships
+    hint(
+      "Use appropriate JOINs based on the relationships defined in the schema."
+    ),
+    hint(
+      "Favor PK/indexed columns for joins and filters; follow relationship metadata for join direction and cardinality."
+    ),
+    // Aggregations and calculations
+    hint(
+      "Apply proper aggregations (COUNT, SUM, AVG, etc.) when the question implies summarization."
+    ),
+    hint(
+      'When asked "how many X are there" about types/categories/statuses (e.g., "how many statuses are there?"), use COUNT(DISTINCT column). This asks about variety, not row count.'
+    ),
+    hint(
+      "Use window functions when the question requires ranking, running totals, or comparisons across rows."
+    ),
+    // Query semantics
+    hint(
+      'Words like "reach", "reached", "hit" with a value (e.g., "temperature reach 80") mean >= (greater than or equal), not = (exact match).'
+    ),
+    hint(
+      'For "shared by" two groups or mutually exclusive conditions (e.g., population > 1500 AND < 500), use INTERSECT between separate queries. A single WHERE with contradictory AND returns nothing.'
+    ),
+    hint(
+      'When filtering by a specific value from a joined table (e.g., "students who registered course statistics"), always include that WHERE condition. Do not omit mentioned filters.'
+    ),
+    hint(
+      "Handle NULL values appropriately using IS NULL, IS NOT NULL, or COALESCE."
+    ),
+    // Style and readability
+    styleGuide({
+      prefer: "Use meaningful aliases for tables and columns to improve readability."
+    }),
+    styleGuide({
+      prefer: "Summaries should be concise, business-friendly, highlight key comparisons, and add a short helpful follow-up when useful."
+    }),
+    // Guardrails - Query safety
+    guardrail({
+      rule: "Generate ONLY valid, executable SQL.",
+      reason: "Invalid SQL wastes resources and confuses users.",
+      action: "Validate syntax and schema references before returning."
+    }),
+    guardrail({
+      rule: "Only generate SELECT statements (read-only queries).",
+      reason: "Prevents accidental data modification.",
+      action: "Never generate INSERT, UPDATE, DELETE, DROP, or other DDL/DML statements."
+    }),
+    guardrail({
+      rule: "Avoid unbounded scans on large tables.",
+      reason: "Protects performance and prevents runaway queries.",
+      action: "Ensure filters are applied on indexed columns before querying broad fact tables."
+    }),
+    guardrail({
+      rule: "Do not add LIMIT unless explicitly requested.",
+      action: 'Only add LIMIT when user explicitly asks for "top N", "first N", or similar. Do NOT add LIMIT for "list all", "show all", or simple "list" queries.',
+      reason: "Adding arbitrary limits changes query semantics."
+    }),
+    guardrail({
+      rule: "Add ORDER BY where appropriate for deterministic results.",
+      reason: "Ensures consistent query output.",
+      action: "Include ORDER BY when results have a natural ordering or when combined with LIMIT."
+    }),
+    guardrail({
+      rule: "Prevent cartesian or guesswork joins.",
+      reason: "Protect correctness and performance.",
+      action: "If join keys are missing or unclear, inspect relationships and ask for the intended join path before executing."
+    }),
+    guardrail({
+      rule: "Ensure the query is optimized for the schema.",
+      reason: "Better performance and resource usage.",
+      action: "Use indexed columns for filtering, avoid SELECT * on large joins, prefer specific column selection when appropriate."
+    }),
+    guardrail({
+      rule: "When facing genuine ambiguity with multiple valid interpretations, seek clarification.",
+      reason: "Prevents incorrect assumptions in edge cases.",
+      action: "Ask a focused clarifying question before proceeding with a guess."
+    }),
+    // Clarifications
+    clarification({
+      when: 'The request uses ambiguous scoring or ranking language (e.g., "top", "best", "active") without a metric.',
+      ask: "Clarify the ranking metric or definition before writing the query.",
+      reason: "Ensures the correct aggregation/ordering is used."
+    }),
+    // Workflow
+    workflow({
+      task: "SQL generation plan",
+      steps: [
+        'Scan column names for terms matching the question. If a phrase like "total X" or "number of Y" matches a column name (e.g., Total_X, Num_Y), select that column directly instead of aggregating.',
+        "Translate the question into SQL patterns (aggregation, segmentation, time range, ranking) only if no column name match.",
+        "Choose tables/relations that satisfy those patterns; note lookup tables and filter values implied by schema hints.",
+        "Sketch join/filter/aggregation order considering table sizes, indexes, and stats.",
+        "Generate precise, validated SQL that answers the question."
+      ]
+    })
+  ];
+  if (date === "strict") {
+    baseTeachings.push(
+      clarification({
+        when: "The request targets time-based data without a date range.",
+        ask: "Confirm the intended timeframe (e.g., last 30/90 days, YTD, specific year).",
+        reason: "Prevents large scans and irrelevant results."
+      })
+    );
+  } else {
+    baseTeachings.push(
+      hint(
+        'When a month, day, or time period is mentioned without a year (e.g., "in August", "on Monday"), assume ALL occurrences of that period in the data. Do not ask for year clarification.'
+      )
+    );
+  }
+  return baseTeachings;
+}
+
+// packages/text2sql/src/lib/sql.ts
+var Text2Sql = class {
+  #config;
+  constructor(config) {
+    this.#config = {
+      adapter: config.adapter,
+      history: config.history,
+      instructions: [
+        ...guidelines(config.teachingsOptions),
+        ...config.instructions ?? []
+      ],
+      tools: config.tools ?? {},
+      model: config.model,
+      memory: config.memory,
+      introspection: new FileCache("introspection-" + config.version)
+    };
+  }
+  async explain(sql) {
+    const { experimental_output } = await generate4(
+      explainerAgent,
+      [user4("Explain this SQL.")],
+      { sql }
+    );
+    return experimental_output.explanation;
+  }
+  async toSql(input) {
+    const introspection = await this.index();
+    const result = await toSql({
+      input,
+      adapter: this.#config.adapter,
+      introspection,
+      instructions: this.#config.instructions,
+      model: this.#config.model
+    });
+    return result.sql;
+  }
+  instruct(...dataset) {
+    this.#config.instructions.push(...dataset);
+  }
+  async inspect(agent9) {
+    const [grounding] = await Promise.all([this.index()]);
+    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
+      (name) => name.startsWith("render_")
+    );
+    const allInstructions = [
+      ...this.#config.instructions,
+      guardrail({
+        rule: "ALWAYS use `get_sample_rows` before writing queries that filter or compare against string columns.",
+        reason: "Prevents SQL errors from wrong value formats.",
+        action: "Target specific columns (e.g., get_sample_rows('table', ['status', 'type']))."
+      }),
+      ...renderToolNames.length ? [
         hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
         styleGuide({
           prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
@@ -1202,6 +2280,100 @@ var Text2Sql = class {
         })
       ] : []
     ];
+    const tools6 = Object.keys({
+      ...agent9.handoff.tools,
+      ...this.#config.memory ? memoryTools : {},
+      ...this.#config.tools
+    });
+    return {
+      tools: tools6,
+      prompt: agent9.instructions({
+        introspection: grounding,
+        teachings: toInstructions("instructions", ...allInstructions)
+      })
+    };
+  }
+  async index(options) {
+    const cached = await this.#config.introspection.get();
+    if (cached) {
+      return cached;
+    }
+    const introspection = await this.#config.adapter.introspect();
+    await this.#config.introspection.set(introspection);
+    return introspection;
+  }
+  /**
+   * Generate training data pairs using a producer factory.
+   * The factory receives the configured adapter, so users don't need to pass it manually.
+   *
+   * @example
+   * // Generate questions for existing SQL
+   * const pairs = await text2sql.toPairs(
+   *   (adapter) => new SqlExtractor(sqls, adapter, { validateSql: true })
+   * );
+   *
+   * @example
+   * // Extract from chat history with validation
+   * const pairs = await text2sql.toPairs(
+   *   (adapter) => new ValidatedProducer(
+   *     new MessageExtractor(messages),
+   *     adapter
+   *   )
+   * );
+   */
+  async toPairs(factory) {
+    const producer = factory(this.#config.adapter);
+    return toPairs(producer);
+  }
+  // public async suggest() {
+  //   const [introspection, adapterInfo] = await Promise.all([
+  //     this.index(),
+  //     this.#config.adapter.introspect(),
+  //   ]);
+  //   const { experimental_output: output } = await generate(
+  //     suggestionsAgent,
+  //     [
+  //       user(
+  //         'Suggest high-impact business questions and matching SQL queries for this database.',
+  //       ),
+  //     ],
+  //     {
+  //     },
+  //   );
+  //   return output.suggestions;
+  // }
+  async chat(messages, params) {
+    const [introspection, userTeachables] = await Promise.all([
+      this.index({ onProgress: console.log }),
+      this.#config.memory ? this.#config.memory.toTeachables(params.userId) : []
+    ]);
+    const chat = await this.#config.history.upsertChat({
+      id: params.chatId,
+      userId: params.userId,
+      title: "Chat " + params.chatId
+    });
+    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
+      (name) => name.startsWith("render_")
+    );
+    const instructions = [
+      ...this.#config.instructions,
+      guardrail({
+        rule: "ALWAYS use `get_sample_rows` before writing queries that filter or compare against string columns.",
+        reason: "Prevents SQL errors from wrong value formats.",
+        action: "Target specific columns (e.g., get_sample_rows('table', ['status', 'type']))."
+      }),
+      ...renderToolNames.length ? [
+        hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
+        styleGuide({
+          prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
+          always: "Include text insight alongside visualizations. Prefer line charts for time-based data."
+        })
+      ] : []
+    ];
+    const originalMessage = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
     const result = stream(
       t_a_g.clone({
         model: this.#config.model,
@@ -1211,7 +2383,7 @@ var Text2Sql = class {
           ...this.#config.tools
         }
       }),
-      [...chat.messages.map((it) => it.content), ...messages],
+      originalMessage,
       {
         teachings: toInstructions(
           "instructions",
@@ -1245,46 +2417,385 @@ var Text2Sql = class {
       sendFinish: true,
       sendReasoning: true,
       sendSources: true,
-      originalMessages: messages,
+      originalMessages: originalMessage,
       generateMessageId: generateId,
-      onFinish: async ({ messages: messages2 }) => {
-        const userMessage = messages2.at(-2);
-        const botMessage = messages2.at(-1);
-        if (!userMessage || !botMessage) {
-          throw new Error("Not implemented yet");
+      onFinish: async ({ responseMessage, isContinuation }) => {
+        const userMessage = messages.at(-1);
+        if (!isContinuation && userMessage) {
+          console.log(
+            "Saving user message to history:",
+            JSON.stringify(userMessage)
+          );
+          await this.#config.history.addMessage({
+            id: v72(),
+            chatId: params.chatId,
+            role: userMessage.role,
+            content: userMessage
+          });
         }
         await this.#config.history.addMessage({
           id: v72(),
           chatId: params.chatId,
-          role: userMessage.role,
-          content: userMessage
+          role: responseMessage.role,
+          content: responseMessage
         });
+      }
+    });
+  }
+  /**
+   * Chat1 - Combined tool, no peek.
+   *
+   * Uses a single `query_database` tool that:
+   * 1. Takes a natural language question
+   * 2. Internally calls toSql() to generate validated SQL
+   * 3. Executes the SQL
+   * 4. Returns both SQL and results
+   *
+   * The agent does NOT see the SQL before execution.
+   */
+  async chat1(messages, params) {
+    const [introspection, userTeachables] = await Promise.all([
+      this.index({ onProgress: console.log }),
+      this.#config.memory ? this.#config.memory.toTeachables(params.userId) : []
+    ]);
+    const chat = await this.#config.history.upsertChat({
+      id: params.chatId,
+      userId: params.userId,
+      title: "Chat " + params.chatId
+    });
+    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
+      (name) => name.startsWith("render_")
+    );
+    const instructions = [
+      ...this.#config.instructions,
+      ...renderToolNames.length ? [
+        hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
+        styleGuide({
+          prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
+          always: "Include text insight alongside visualizations. Prefer line charts for time-based data."
+        })
+      ] : []
+    ];
+    const originalMessage = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
+    const result = stream(
+      chat1Agent.clone({
+        model: this.#config.model,
+        tools: {
+          ...tools2,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          persona({
+            name: "Freya",
+            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
+            tone: "Your tone should be concise and business-friendly."
+          }),
+          ...instructions,
+          teachable("user_profile", ...userTeachables)
+        ),
+        adapter: this.#config.adapter,
+        introspection,
+        instructions: this.#config.instructions,
+        memory: this.#config.memory,
+        userId: params.userId
+      }
+    );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessage
+    );
+  }
+  /**
+   * Chat2 - Separate generate + execute tools (with peek).
+   *
+   * Uses two separate tools:
+   * 1. `generate_sql` - Takes a question, returns validated SQL
+   * 2. `execute_sql` - Takes SQL, executes it
+   *
+   * The agent sees the SQL before execution and can review/refine.
+   */
+  async chat2(messages, params) {
+    const [introspection, userTeachables] = await Promise.all([
+      this.index({ onProgress: console.log }),
+      this.#config.memory ? this.#config.memory.toTeachables(params.userId) : []
+    ]);
+    const chat = await this.#config.history.upsertChat({
+      id: params.chatId,
+      userId: params.userId,
+      title: "Chat " + params.chatId
+    });
+    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
+      (name) => name.startsWith("render_")
+    );
+    const instructions = [
+      ...this.#config.instructions,
+      ...renderToolNames.length ? [
+        hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
+        styleGuide({
+          prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
+          always: "Include text insight alongside visualizations. Prefer line charts for time-based data."
+        })
+      ] : []
+    ];
+    const originalMessage = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
+    const result = stream(
+      chat2Agent.clone({
+        model: this.#config.model,
+        tools: {
+          ...tools3,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          persona({
+            name: "Freya",
+            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
+            tone: "Your tone should be concise and business-friendly."
+          }),
+          ...instructions,
+          teachable("user_profile", ...userTeachables)
+        ),
+        adapter: this.#config.adapter,
+        introspection,
+        instructions: this.#config.instructions,
+        memory: this.#config.memory,
+        userId: params.userId
+      }
+    );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessage
+    );
+  }
+  /**
+   * Chat3 - Agent conversation/collaboration.
+   *
+   * Enables richer interaction where the SQL agent can:
+   * - Surface confidence levels
+   * - State assumptions
+   * - Request clarification when uncertain
+   */
+  async chat3(messages, params) {
+    const [introspection, userTeachables] = await Promise.all([
+      this.index({ onProgress: console.log }),
+      this.#config.memory ? this.#config.memory.toTeachables(params.userId) : []
+    ]);
+    const chat = await this.#config.history.upsertChat({
+      id: params.chatId,
+      userId: params.userId,
+      title: "Chat " + params.chatId
+    });
+    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
+      (name) => name.startsWith("render_")
+    );
+    const instructions = [
+      ...this.#config.instructions,
+      ...renderToolNames.length ? [
+        hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
+        styleGuide({
+          prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
+          always: "Include text insight alongside visualizations. Prefer line charts for time-based data."
+        })
+      ] : []
+    ];
+    const originalMessage = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
+    const result = stream(
+      chat3Agent.clone({
+        model: this.#config.model,
+        tools: {
+          ...tools4,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          persona({
+            name: "Freya",
+            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
+            tone: "Your tone should be concise and business-friendly."
+          }),
+          ...instructions,
+          teachable("user_profile", ...userTeachables)
+        ),
+        adapter: this.#config.adapter,
+        introspection,
+        instructions: this.#config.instructions,
+        memory: this.#config.memory,
+        userId: params.userId
+      }
+    );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessage
+    );
+  }
+  /**
+   * Chat4 - Question decomposition approach.
+   *
+   * Breaks down questions into semantic components before SQL generation:
+   * - entities: Key concepts mentioned
+   * - filters: Filtering criteria
+   * - aggregation: Type of aggregation
+   * - breakdown: Semantic parts of the question
+   *
+   * This helps ensure all aspects of the question are addressed.
+   */
+  async chat4(messages, params) {
+    const [introspection, userTeachables] = await Promise.all([
+      this.index({ onProgress: console.log }),
+      this.#config.memory ? this.#config.memory.toTeachables(params.userId) : []
+    ]);
+    const chat = await this.#config.history.upsertChat({
+      id: params.chatId,
+      userId: params.userId,
+      title: "Chat " + params.chatId
+    });
+    const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
+      (name) => name.startsWith("render_")
+    );
+    const instructions = [
+      ...this.#config.instructions,
+      ...renderToolNames.length ? [
+        hint(`Rendering tools available: ${renderToolNames.join(", ")}.`),
+        styleGuide({
+          prefer: "Use render_* tools for trend/over time/monthly requests or chart asks",
+          always: "Include text insight alongside visualizations. Prefer line charts for time-based data."
+        })
+      ] : []
+    ];
+    const originalMessage = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
+    const result = stream(
+      chat4Agent.clone({
+        model: this.#config.model,
+        tools: {
+          ...tools5,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          persona({
+            name: "Freya",
+            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
+            tone: "Your tone should be concise and business-friendly."
+          }),
+          ...instructions,
+          teachable("user_profile", ...userTeachables)
+        ),
+        adapter: this.#config.adapter,
+        introspection,
+        instructions: this.#config.instructions,
+        memory: this.#config.memory,
+        userId: params.userId
+      }
+    );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessage
+    );
+  }
+  /**
+   * Helper to create UI message stream with common error handling and persistence.
+   */
+  #createUIMessageStream(result, messages, params, originalMessage) {
+    return result.toUIMessageStream({
+      onError: (error) => {
+        if (NoSuchToolError.isInstance(error)) {
+          return "The model tried to call an 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: originalMessage,
+      generateMessageId: generateId,
+      onFinish: async ({ responseMessage, isContinuation }) => {
+        const userMessage = messages.at(-1);
+        if (!isContinuation && userMessage) {
+          console.log(
+            "Saving user message to history:",
+            JSON.stringify(userMessage)
+          );
+          await this.#config.history.addMessage({
+            id: v72(),
+            chatId: params.chatId,
+            role: userMessage.role,
+            content: userMessage
+          });
+        }
         await this.#config.history.addMessage({
           id: v72(),
           chatId: params.chatId,
-          role: botMessage.role,
-          content: botMessage
+          role: responseMessage.role,
+          content: responseMessage
         });
       }
     });
   }
 };
-
-// packages/text2sql/src/index.ts
-if (import.meta.main) {
-}
 export {
+  Adapter,
+  Checkpoint,
   FileCache,
   History,
   InMemoryHistory,
   InMemoryTeachablesStore,
   JsonCache,
+  Point,
   SqliteHistory,
   SqliteTeachablesStore,
   TeachablesStore,
   Text2Sql,
+  applyTablesFilter,
+  filterRelationshipsByTables,
+  filterTablesByName,
+  getTablesWithRelated,
+  guidelines,
+  hashConfig,
+  matchesFilter,
   memoryTools,
-  sqlQueryAgent,
   suggestionsAgent,
   t_a_g
 };