@deepagents/text2sql 0.3.1 → 0.7.0

package/dist/index.js

@@ -1,64 +1,206 @@
-// packages/text2sql/src/lib/agents/suggestions.agents.ts
+// 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/developer.agent.ts
+import { groq as groq3 } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent2 from "dedent";
+import z3 from "zod";
+import { agent as agent3, generate as generate2, toState } from "@deepagents/agent";
+import { scratchpad_tool } from "@deepagents/toolbox";
+
+// packages/text2sql/src/lib/agents/explainer.agent.ts
 import { groq } from "@ai-sdk/groq";
 import dedent from "dedent";
 import z from "zod";
-import { agent, thirdPersonPrompt } from "@deepagents/agent";
-var suggestionsAgent = agent({
-  name: "text2sql-suggestions",
+import { agent } from "@deepagents/agent";
+var explainerAgent = agent({
+  name: "explainer",
   model: groq("openai/gpt-oss-20b"),
-  output: z.object({
-    suggestions: z.array(
-      z.object({
-        question: z.string().describe("A complex, high-impact business question."),
-        sql: z.string().describe("The SQL statement needed to answer the question."),
-        businessValue: z.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 dedent`
-      ${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>
-
-
-      <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>
+  prompt: (state) => dedent`
+    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.
 
-      <response-format>
-        Return valid JSON that satisfies the defined output schema.
-      </response-format>
-    `;
-  }
+    <sql>
+    ${state?.sql}
+    </sql>
+  `,
+  output: z.object({
+    explanation: z.string().describe("The explanation of the SQL query.")
+  })
 });
 
-// packages/text2sql/src/lib/agents/text2sql.agent.ts
+// packages/text2sql/src/lib/agents/sql.agent.ts
 import { groq as groq2 } from "@ai-sdk/groq";
-import { tool } from "ai";
+import {
+  APICallError,
+  JSONParseError,
+  NoContentGeneratedError,
+  NoObjectGeneratedError,
+  NoOutputGeneratedError,
+  TypeValidationError,
+  defaultSettingsMiddleware,
+  wrapLanguageModel
+} from "ai";
+import { Console } from "node:console";
+import { createWriteStream } from "node:fs";
+import pRetry from "p-retry";
 import z2 from "zod";
 import {
   agent as agent2,
-  toState
+  generate,
+  toOutput,
+  user
 } from "@deepagents/agent";
-import { scratchpad_tool } from "@deepagents/toolbox";
 
 // packages/text2sql/src/lib/teach/xml.ts
 function wrapBlock(tag, children) {
@@ -106,20 +248,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 +275,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 +287,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 +299,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 +311,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 +324,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 +335,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 +347,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 +367,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 +380,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 +391,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 +433,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 +453,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 +465,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);
     }
@@ -408,6 +575,384 @@ function toTeachables(generated) {
   });
 }
 
+// packages/text2sql/src/lib/agents/sql.agent.ts
+var logger = new Console({
+  stdout: createWriteStream("./sql-agent.log", { flags: "a" }),
+  stderr: createWriteStream("./sql-agent-error.log", { flags: "a" }),
+  inspectOptions: { depth: null }
+});
+var RETRY_TEMPERATURES = [0, 0.2, 0.3];
+var sqlQueryAgent = agent2({
+  name: "text2sql",
+  model: groq2("openai/gpt-oss-20b"),
+  logging: process.env.AGENT_LOGGING === "true",
+  output: z2.union([
+    z2.object({
+      sql: z2.string().describe("The SQL query that answers the question"),
+      reasoning: z2.string().optional().describe("The reasoning steps taken to generate the SQL")
+    }),
+    z2.object({
+      error: z2.string().describe(
+        "Error message explaining why the question cannot be answered with the given schema"
+      )
+    })
+  ]),
+  prompt: (state) => {
+    return `
+    ${state?.teachings || ""}
+    ${state?.introspection || ""}
+  `;
+  }
+});
+function extractSql(output) {
+  const match = output.match(/```sql\n?([\s\S]*?)```/);
+  return match ? match[1].trim() : output.trim();
+}
+var marker = Symbol("SQLValidationError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [marker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[marker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[marker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError;
+  }
+};
+async function toSql(options) {
+  const { maxRetries = 3 } = options;
+  return withRetry(
+    async (attemptNumber, errors, attempts) => {
+      const agentInstance = sqlQueryAgent.clone({
+        model: wrapLanguageModel({
+          model: options.model ?? sqlQueryAgent.model,
+          middleware: defaultSettingsMiddleware({
+            settings: {
+              temperature: RETRY_TEMPERATURES[attemptNumber - 1] ?? 0.3,
+              topP: 1
+            }
+          })
+        })
+      });
+      const messages = errors.length ? [
+        user(options.input),
+        user(
+          `<validation_error>Your previous SQL query had the following error: ${errors.at(-1)?.message}. Please fix the query.</validation_error>`
+        )
+      ] : [user(options.input)];
+      const output = await toOutput(
+        generate(agentInstance, messages, {
+          introspection: options.introspection,
+          teachings: toInstructions(
+            "instructions",
+            persona({
+              name: "Freya",
+              role: "You are an expert SQL query generator. You translate natural language questions into precise, efficient SQL queries based on the provided database schema."
+            }),
+            ...options.instructions
+          )
+        })
+      );
+      if ("error" in output) {
+        throw new UnanswerableSQLError(output.error);
+      }
+      const sql = extractSql(output.sql);
+      const validationError = await options.adapter.validate(sql);
+      if (validationError) {
+        throw new SQLValidationError(validationError);
+      }
+      return {
+        attempts,
+        sql,
+        errors: errors.length ? errors.map(formatErrorMessage) : void 0
+      };
+    },
+    { retries: maxRetries - 1 }
+  );
+}
+function formatErrorMessage(error) {
+  if (APICallError.isInstance(error)) {
+    if (error.message.startsWith("Failed to validate JSON")) {
+      return `Schema validation failed: ${error.message}`;
+    }
+    return error.message;
+  }
+  if (SQLValidationError.isInstance(error)) {
+    return `SQL Validation Error: ${error.message}`;
+  }
+  return error.message;
+}
+async function withRetry(computation, options = { retries: 3 }) {
+  const errors = [];
+  let attempts = 0;
+  return pRetry(
+    (attemptNumber) => {
+      return computation(attemptNumber, errors, ++attempts);
+    },
+    {
+      retries: options.retries,
+      shouldRetry: (context2) => {
+        if (UnanswerableSQLError.isInstance(context2.error)) {
+          return false;
+        }
+        if (SQLValidationError.isInstance(context2.error)) {
+          return true;
+        }
+        console.log({
+          NoObjectGeneratedError: NoObjectGeneratedError.isInstance(
+            context2.error
+          ),
+          NoOutputGeneratedError: NoOutputGeneratedError.isInstance(
+            context2.error
+          ),
+          APICallError: APICallError.isInstance(context2.error),
+          JSONParseError: JSONParseError.isInstance(context2.error),
+          TypeValidationError: TypeValidationError.isInstance(context2.error),
+          NoContentGeneratedError: NoContentGeneratedError.isInstance(
+            context2.error
+          )
+        });
+        return APICallError.isInstance(context2.error) || JSONParseError.isInstance(context2.error) || TypeValidationError.isInstance(context2.error) || NoObjectGeneratedError.isInstance(context2.error) || NoOutputGeneratedError.isInstance(context2.error) || NoContentGeneratedError.isInstance(context2.error);
+      },
+      onFailedAttempt(context2) {
+        logger.error(`toSQL`, context2.error);
+        console.log(
+          `Attempt ${context2.attemptNumber} failed. There are ${context2.retriesLeft} retries left.`
+        );
+        errors.push(context2.error);
+      }
+    }
+  );
+}
+
+// packages/text2sql/src/lib/agents/developer.agent.ts
+var tools = {
+  /**
+   * Generate SQL from natural language question.
+   * Uses the toSql function with retry logic and validation.
+   */
+  generate_sql: tool({
+    description: dedent2`
+      Generate a validated SQL query from a natural language question.
+      The query is automatically validated against the database schema.
+      Use this when the user asks a question that requires data retrieval.
+
+      Returns the SQL query along with generation metadata (attempts, any errors encountered).
+    `,
+    inputSchema: z3.object({
+      question: z3.string().min(1).describe("The natural language question to convert to SQL")
+    }),
+    execute: async ({ question }, options) => {
+      const state = toState(options);
+      try {
+        const result = await toSql({
+          input: question,
+          adapter: state.adapter,
+          introspection: state.introspection,
+          instructions: state.instructions
+        });
+        return {
+          success: true,
+          sql: result.sql,
+          attempts: result.attempts,
+          errors: result.errors
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+      }
+    }
+  }),
+  /**
+   * Get plain-English explanation of a SQL query.
+   */
+  explain_sql: tool({
+    description: dedent2`
+      Get a plain-English explanation of a SQL query.
+      Use this to help the user understand what a query does.
+
+      The explanation focuses on intent and logic, not syntax.
+    `,
+    inputSchema: z3.object({
+      sql: z3.string().min(1).describe("The SQL query to explain")
+    }),
+    execute: async ({ sql }) => {
+      const { experimental_output } = await generate2(explainerAgent, [], {
+        sql
+      });
+      return { explanation: experimental_output.explanation };
+    }
+  }),
+  /**
+   * Show database schema introspection.
+   */
+  show_schema: tool({
+    description: dedent2`
+      Display the database schema introspection.
+      Use this when the user wants to see available tables, columns, or relationships.
+
+      Optionally filter by table name to reduce output.
+    `,
+    inputSchema: z3.object({
+      table: z3.string().optional().describe(
+        "Optional: filter to show only a specific table. If omitted, shows full schema."
+      )
+    }),
+    execute: async ({ table }, options) => {
+      const state = toState(options);
+      if (!table) {
+        return { schema: state.introspection };
+      }
+      const lines = state.introspection.split("\n");
+      const tableLines = [];
+      let inTable = false;
+      let depth = 0;
+      for (const line of lines) {
+        const lowerLine = line.toLowerCase();
+        if (lowerLine.includes(`name="${table.toLowerCase()}"`) || lowerLine.includes(`table="${table.toLowerCase()}"`)) {
+          inTable = true;
+          depth = 1;
+          tableLines.push(line);
+          continue;
+        }
+        if (inTable) {
+          tableLines.push(line);
+          if (line.includes("</")) {
+            depth--;
+          }
+          if (line.includes("<") && !line.includes("</") && !line.includes("/>")) {
+            depth++;
+          }
+          if (depth <= 0) {
+            break;
+          }
+        }
+      }
+      if (tableLines.length === 0) {
+        return {
+          schema: `Table "${table}" not found in schema. Use show_schema without a table filter to see all available tables.`
+        };
+      }
+      return { schema: tableLines.join("\n") };
+    }
+  }),
+  /**
+   * Developer scratchpad for notes and reasoning.
+   */
+  scratchpad: scratchpad_tool
+};
+var developerAgent = agent3({
+  model: groq3("gpt-oss-20b"),
+  tools,
+  name: "developer_agent",
+  prompt: (state) => {
+    return dedent2`
+      You are an expert SQL developer assistant helping power users build and refine queries.
+
+      ## Your Capabilities
+
+      You have access to the following tools:
+
+      1. **generate_sql**: Convert natural language questions to validated SQL queries
+         - Automatically validates against the database schema
+         - Returns generation metadata (attempts, errors if any)
+
+      2. **explain_sql**: Get a plain-English explanation of any SQL query
+         - Helps users understand complex queries
+         - Focuses on intent and logic, not syntax
+
+      3. **show_schema**: Display database schema information
+         - Can show full schema or filter by table name
+         - Use to explore available tables and columns
+
+      4. **scratchpad**: Record your reasoning and notes
+
+      ## Guidelines
+
+      - Be transparent: show the SQL you generate before explaining it
+      - Be precise: provide exact column names and table references
+      - Be helpful: suggest refinements and alternatives when appropriate
+      - Support both natural language questions AND raw SQL input
+      - When validating user SQL, explain any errors clearly
+      - Use show_schema proactively when you need to verify table/column names
+
+      ${state?.teachings || ""}
+      ${state?.introspection || ""}
+    `;
+  }
+});
+
+// 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>
+
+
+      <instructions>
+        - Recommend one or two UNIQUE questions that go beyond simple counts or listings.
+        - Favor questions that require joins, aggregates, time comparisons, cohort analysis,
+          or window functions.
+        - For each question, explain the business reason stakeholders care about it.
+        - Provide the complete SQL query that could answer the question in the given schema.
+        - Keep result sets scoped with LIMIT clauses (max 50 rows) when returning raw rows.
+        - Ensure table/column names match the provided schema exactly.
+        - Use columns marked [LowCardinality: ...] to identify meaningful categorical filters or segmentations.
+        - Leverage table [rows / size] hints to determine whether to aggregate (large tables) or inspect detailed data (tiny tables).
+        - Reference PK/Indexed annotations and the Indexes list to recommend queries that use efficient join/filter paths.
+        - Column annotations may expose ranges/null percentages—use them to suggest realistic thresholds or quality checks.
+        - Consult <relationship_examples> to anchor your recommendations in the actual join paths between tables.
+        - Output only information grounded in the schema/context provided.
+      </instructions>
+
+      <response-format>
+        Return valid JSON that satisfies the defined output schema.
+      </response-format>
+    `;
+  }
+});
+
+// packages/text2sql/src/lib/agents/text2sql.agent.ts
+import { groq as groq5 } from "@ai-sdk/groq";
+import { tool as tool2 } from "ai";
+import z5 from "zod";
+import { agent as agent5, toState as toState2 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool2 } from "@deepagents/toolbox";
+
 // packages/text2sql/src/lib/memory/memory.prompt.ts
 var memory_prompt_default = toInstructions(
   "memory_guidelines",
@@ -537,14 +1082,14 @@ var memory_prompt_default = toInstructions(
 );
 
 // packages/text2sql/src/lib/agents/text2sql.agent.ts
-var tools = {
-  validate_query: tool({
+var tools2 = {
+  validate_query: tool2({
     description: `Validate SQL query syntax before execution. Use this to check if your SQL is valid before running db_query. This helps catch errors early and allows you to correct the query if needed.`,
-    inputSchema: z2.object({
-      sql: z2.string().describe("The SQL query to validate.")
+    inputSchema: z5.object({
+      sql: z5.string().describe("The SQL query to validate.")
     }),
     execute: async ({ sql }, options) => {
-      const state = toState(options);
+      const state = toState2(options);
       const result = await state.adapter.validate(sql);
       if (typeof result === "string") {
         return `Validation Error: ${result}`;
@@ -552,22 +1097,22 @@ var tools = {
       return "Query is valid.";
     }
   }),
-  get_sample_rows: tool({
+  get_sample_rows: tool2({
     description: `Sample rows from a table to understand data formatting, codes, and value patterns. Use BEFORE writing queries when:
 - Column types in schema don't reveal format (e.g., "status" could be 'active'/'inactive' or 1/0)
 - Date/time formats are unclear (ISO, Unix timestamp, locale-specific)
 - You need to understand lookup table codes or enum values
 - Column names are ambiguous (e.g., "type", "category", "code")`,
-    inputSchema: z2.object({
-      tableName: z2.string().describe("The name of the table to sample."),
-      columns: z2.array(z2.string()).optional().describe(
+    inputSchema: z5.object({
+      tableName: z5.string().describe("The name of the table to sample."),
+      columns: z5.array(z5.string()).optional().describe(
         "Specific columns to sample. If omitted, samples all columns."
       ),
-      limit: z2.number().min(1).max(10).default(3).optional().describe("Number of rows to sample (1-10, default 3).")
+      limit: z5.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 safeLimit = Math.min(Math.max(1, limit), 10);
-      const state = toState(options);
+      const state = toState2(options);
       const sql = state.adapter.buildSampleRowsQuery(
         tableName,
         columns,
@@ -576,13 +1121,13 @@ var tools = {
       return state.adapter.execute(sql);
     }
   }),
-  db_query: tool({
+  db_query: tool2({
     description: `Internal tool to fetch data from the store's database. Write a SQL query to retrieve the information needed to answer the user's question. The results will be returned as data that you can then present to the user in natural language.`,
-    inputSchema: z2.object({
-      reasoning: z2.string().describe(
+    inputSchema: z5.object({
+      reasoning: z5.string().describe(
         "Your reasoning for why this SQL query is relevant to the user request."
       ),
-      sql: z2.string().min(1, { message: "SQL query cannot be empty." }).refine(
+      sql: z5.string().min(1, { message: "SQL query cannot be empty." }).refine(
         (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
         {
           message: "Only read-only SELECT or WITH queries are allowed."
@@ -590,11 +1135,11 @@ var tools = {
       ).describe("The SQL query to execute against the database.")
     }),
     execute: ({ sql }, options) => {
-      const state = toState(options);
+      const state = toState2(options);
       return state.adapter.execute(sql);
     }
   }),
-  scratchpad: scratchpad_tool
+  scratchpad: scratchpad_tool2
 };
 var userMemoryTypes = [
   "identity",
@@ -603,61 +1148,61 @@ var userMemoryTypes = [
   "context",
   "correction"
 ];
-var userMemorySchema = z2.discriminatedUnion("type", [
-  z2.object({
-    type: z2.literal("identity"),
-    description: z2.string().describe("The user's identity: role or/and name")
+var userMemorySchema = z5.discriminatedUnion("type", [
+  z5.object({
+    type: z5.literal("identity"),
+    description: z5.string().describe("The user's identity: role or/and name")
   }),
-  z2.object({
-    type: z2.literal("alias"),
-    term: z2.string().describe("The term the user uses"),
-    meaning: z2.string().describe("What the user means by this term")
+  z5.object({
+    type: z5.literal("alias"),
+    term: z5.string().describe("The term the user uses"),
+    meaning: z5.string().describe("What the user means by this term")
   }),
-  z2.object({
-    type: z2.literal("preference"),
-    aspect: z2.string().describe("What aspect of output this preference applies to"),
-    value: z2.string().describe("The user's preference")
+  z5.object({
+    type: z5.literal("preference"),
+    aspect: z5.string().describe("What aspect of output this preference applies to"),
+    value: z5.string().describe("The user's preference")
   }),
-  z2.object({
-    type: z2.literal("context"),
-    description: z2.string().describe("What the user is currently working on")
+  z5.object({
+    type: z5.literal("context"),
+    description: z5.string().describe("What the user is currently working on")
   }),
-  z2.object({
-    type: z2.literal("correction"),
-    subject: z2.string().describe("What was misunderstood"),
-    clarification: z2.string().describe("The correct understanding")
+  z5.object({
+    type: z5.literal("correction"),
+    subject: z5.string().describe("What was misunderstood"),
+    clarification: z5.string().describe("The correct understanding")
   })
 ]);
 var memoryTools = {
-  remember_memory: tool({
+  remember_memory: tool2({
     description: "Store something about the user for future conversations. Use silently when user shares facts, preferences, vocabulary, corrections, or context.",
-    inputSchema: z2.object({ memory: userMemorySchema }),
+    inputSchema: z5.object({ memory: userMemorySchema }),
     execute: async ({ memory }, options) => {
-      const state = toState(
+      const state = toState2(
         options
       );
       await state.memory.remember(state.userId, memory);
       return "Remembered.";
     }
   }),
-  forget_memory: tool({
+  forget_memory: tool2({
     description: "Forget a specific memory. Use when user asks to remove something.",
-    inputSchema: z2.object({
-      id: z2.string().describe("The ID of the teachable to forget")
+    inputSchema: z5.object({
+      id: z5.string().describe("The ID of the teachable to forget")
     }),
     execute: async ({ id }, options) => {
-      const state = toState(options);
+      const state = toState2(options);
       await state.memory.forget(id);
       return "Forgotten.";
     }
   }),
-  recall_memory: tool({
+  recall_memory: tool2({
     description: "List stored memories for the current user. Use when user asks what you remember about them or wants to see their stored preferences.",
-    inputSchema: z2.object({
-      type: z2.enum(userMemoryTypes).optional().catch(void 0).describe("Optional: filter by memory type")
+    inputSchema: z5.object({
+      type: z5.enum(userMemoryTypes).optional().catch(void 0).describe("Optional: filter by memory type")
     }),
     execute: async ({ type }, options) => {
-      const state = toState(
+      const state = toState2(
         options
       );
       const memories = await state.memory.recall(state.userId, type);
@@ -672,71 +1217,301 @@ var memoryTools = {
       }));
     }
   }),
-  update_memory: tool({
+  update_memory: tool2({
     description: "Update an existing memory. Use when user wants to modify something you previously stored.",
-    inputSchema: z2.object({
+    inputSchema: z5.object({
       memory: userMemorySchema,
-      id: z2.string().describe("The ID of the memory to update")
+      id: z5.string().describe("The ID of the memory to update")
     }),
     execute: async ({ id, memory }, options) => {
-      const state = toState(options);
+      const state = toState2(options);
       await state.memory.update(id, memory);
       return "Updated.";
     }
   })
 };
-var sqlQueryAgent = agent2({
+var chainOfThoughtPrompt = `
+## Query Reasoning Process
+
+Let's think step by step before writing SQL:
+
+1. **Schema Link**: Which tables and columns are relevant? Verify they exist in the schema.
+2. **Join Path**: If multiple tables, what relationships connect them?
+3. **Filters**: What WHERE conditions are needed?
+4. **Aggregation**: Is COUNT, SUM, AVG, GROUP BY, or HAVING required?
+5. **Output**: What columns to SELECT and any ORDER BY or LIMIT?
+6. **Verify**: Do all referenced tables and columns exist in the schema above?
+
+For simple queries, steps 2-4 may not apply\u2014skip them.
+
+For complex queries requiring multiple data points, decompose into sub-questions:
+- Break the question into simpler parts (Q1, Q2, ...)
+- Determine if each part needs a subquery or CTE
+- Combine the parts into the final query
+
+Keep reasoning brief. Verbose explanations cause errors.
+`;
+var fewShotExamples = `
+## Examples
+
+### Example 1: Simple Filter
+Question: "How many records in table_a have column_x equal to 'value'?"
+Reasoning:
+- Schema Link: table_a, column_x
+- Filters: column_x = 'value'
+- Aggregation: COUNT(*)
+SQL: SELECT COUNT(*) FROM table_a WHERE column_x = 'value'
+
+### Example 2: JOIN Query
+Question: "Show column_y from table_b for each record in table_a where column_x is 'value'"
+Reasoning:
+- Schema Link: table_a (column_x, id), table_b (column_y, fk_a)
+- Join Path: table_a.id \u2192 table_b.fk_a
+- Filters: column_x = 'value'
+- Output: column_y from table_b
+SQL: SELECT b.column_y FROM table_a a JOIN table_b b ON b.fk_a = a.id WHERE a.column_x = 'value'
+
+### Example 3: Aggregation with GROUP BY
+Question: "What is the total of column_y grouped by column_x?"
+Reasoning:
+- Schema Link: table_a (column_x, column_y)
+- Aggregation: SUM(column_y), GROUP BY column_x
+- Output: column_x, sum
+SQL: SELECT column_x, SUM(column_y) as total FROM table_a GROUP BY column_x
+
+### Example 4: Complex Aggregation
+Question: "Which values of column_x have more than 10 records, sorted by count descending?"
+Reasoning:
+- Schema Link: table_a (column_x)
+- Aggregation: COUNT(*), GROUP BY column_x, HAVING > 10
+- Output: column_x, count, ORDER BY count DESC
+SQL: SELECT column_x, COUNT(*) as cnt FROM table_a GROUP BY column_x HAVING COUNT(*) > 10 ORDER BY cnt DESC
+
+### Example 5: Subquery (Decomposition)
+Question: "Show records from table_a where column_y is above average"
+Reasoning:
+- Decompose:
+  - Q1: What is the average of column_y?
+  - Q2: Which records have column_y above that value?
+- Schema Link: table_a (column_y)
+- Filters: column_y > (result of Q1)
+- Output: all columns from matching records
+- Verify: table_a and column_y exist \u2713
+SQL: SELECT * FROM table_a WHERE column_y > (SELECT AVG(column_y) FROM table_a)
+
+### Example 6: Complex Multi-Join (Decomposition)
+Question: "Find the top 3 categories by total sales amount for orders placed last month"
+Reasoning:
+- Decompose:
+  - Q1: Which orders were placed last month?
+  - Q2: What is the total sales per category for those orders?
+  - Q3: Which 3 categories have the highest totals?
+- Schema Link: orders (order_date, id), order_items (order_id, amount, product_id), products (id, category_id), categories (id, name)
+- Join Path: orders \u2192 order_items \u2192 products \u2192 categories
+- Filters: order_date within last month
+- Aggregation: SUM(amount), GROUP BY category
+- Output: category name, total, ORDER BY total DESC, LIMIT 3
+- Verify: all tables and columns exist \u2713
+SQL: SELECT c.name, SUM(oi.amount) as total FROM orders o JOIN order_items oi ON oi.order_id = o.id JOIN products p ON p.id = oi.product_id JOIN categories c ON c.id = p.category_id WHERE o.order_date >= DATE('now', '-1 month') GROUP BY c.id, c.name ORDER BY total DESC LIMIT 3
+`;
+var t_a_g = agent5({
+  model: groq5("openai/gpt-oss-20b"),
+  tools: tools2,
   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) => {
+    const hasMemory = !!state?.memory;
     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>
+
+    ${chainOfThoughtPrompt}
+
+    ${fewShotExamples}
+
+    ${hasMemory ? memory_prompt_default : ""}
   `;
   }
 });
-var t_a_g = agent2({
-  model: groq2("openai/gpt-oss-20b"),
-  tools,
-  name: "text2sql",
-  prompt: (state) => {
-    const hasMemory = !!state?.memory;
-    return `
 
-    ${state?.teachings || ""}
-    ${state?.introspection || ""}
-
-    ${hasMemory ? memory_prompt_default : ""}
-  `;
+// packages/text2sql/src/lib/checkpoint.ts
+import { createHash } from "node:crypto";
+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) {
+    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 } from "node:crypto";
-import { existsSync } from "node:fs";
+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,166 +1736,1156 @@ import {
 } from "ai";
 import { v7 as v72 } from "uuid";
 import {
-  generate,
+  generate as generate5,
   stream,
-  user
+  user as user4
 } from "@deepagents/agent";
 
-// 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.
+// packages/text2sql/src/lib/agents/bi.agent.ts
+import { groq as groq6 } from "@ai-sdk/groq";
+import { tool as tool3 } from "ai";
+import dedent4 from "dedent";
+import z6 from "zod";
+import { agent as agent6, toState as toState3 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool3 } from "@deepagents/toolbox";
+var tools3 = {
+  /**
+   * Validate SQL query syntax without executing.
+   * Use this to verify queries are correct before embedding in dashboard components.
+   */
+  validate_query: tool3({
+    description: dedent4`
+      Validate SQL query syntax before embedding in dashboard components.
+      Use this to verify your queries are syntactically correct and reference valid tables/columns.
 
-    <sql>
-    ${state?.sql}
-    </sql>
-  `,
-  output: z3.object({
-    explanation: z3.string().describe("The explanation of the SQL query.")
-  })
+      This tool does NOT execute the query or return data.
+      Only SELECT or WITH statements are allowed.
+    `,
+    inputSchema: z6.object({
+      reasoning: z6.string().describe(
+        "Why this query helps understand the data for dashboard design."
+      ),
+      sql: z6.string().min(1, { message: "SQL query cannot be empty." }).refine(
+        (sql) => sql.trim().toUpperCase().startsWith("SELECT") || sql.trim().toUpperCase().startsWith("WITH"),
+        {
+          message: "Only read-only SELECT or WITH queries are allowed."
+        }
+      ).describe("The SQL query to validate.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState3(options);
+      const result = await state.adapter.validate(sql);
+      if (typeof result === "string") {
+        return { valid: false, error: result };
+      }
+      return { valid: true };
+    }
+  }),
+  /**
+   * Record insights and reasoning during schema analysis and dashboard design.
+   */
+  scratchpad: scratchpad_tool3
+};
+var COMPONENTS_DOC = dedent4`
+  ## Available Components
+
+  You output markdown with embedded HTML custom elements. Use kebab-case tags with closing tags.
+
+  ### Chart Components
+
+  #### Area Charts
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<area-chart>\` | \`title\`, \`sql\` | \`x-key\`, \`y-key\`, \`variant\` | Cumulative values, trends with volume |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Basic area with smooth curves
+  - \`linear\` - Sharp-edged lines showing precise changes
+  - \`step\` - Step-based segments for discrete data
+  - \`stacked\` - Multiple series stacked on top of each other
+  - \`stacked-expand\` - Normalized to 100% showing percentage contribution
+  - \`gradient\` - Filled with gradient for visual depth
+
+  #### Bar Charts
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<bar-chart>\` | \`title\`, \`sql\` | \`x-key\`, \`y-key\`, \`variant\`, \`orientation\` | Categorical comparisons, grouped data |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Basic vertical bars
+  - \`multiple\` - Multiple series side by side
+  - \`stacked\` - Multiple series stacked
+  - \`labeled\` - With value labels on bars
+  - \`negative\` - Supports positive/negative values with conditional coloring
+  - \`mixed\` - Different colors per category
+
+  **Orientation** (use \`orientation\` prop):
+  - \`vertical\` (default) - Vertical bars
+  - \`horizontal\` - Horizontal bars (good for long category names)
+
+  #### Line Charts
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<line-chart>\` | \`title\`, \`sql\` | \`x-key\`, \`y-key\`, \`variant\` | Trends over time, continuous data |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Smooth curved lines
+  - \`linear\` - Straight lines between points
+  - \`step\` - Step-based transitions
+  - \`dots\` - Lines with visible data point markers
+  - \`multiple\` - Multiple series for comparisons (A/B testing, etc.)
+  - \`interactive\` - With metric switching capability
+  - \`labeled\` - With value labels at each point
+
+  #### Pie & Donut Charts
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<pie-chart>\` | \`title\`, \`sql\` | \`label-key\`, \`value-key\`, \`variant\` | Part-to-whole relationships, distributions |
+  | \`<donut-chart>\` | \`title\`, \`sql\` | \`label-key\`, \`value-key\`, \`variant\` | Same as pie but with center space for text/KPI |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Basic pie/donut
+  - \`labeled\` - With labels on segments
+  - \`legend\` - With external legend
+  - \`interactive\` - With hover highlighting and selection
+  - \`stacked\` - Multiple concentric rings for comparison
+
+  #### Radar Charts
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<radar-chart>\` | \`title\`, \`sql\` | \`label-key\`, \`value-key\`, \`variant\` | Multi-dimensional comparisons, skill assessments |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Basic radar with polygon grid
+  - \`dots\` - With visible data point markers
+  - \`filled\` - With filled area
+  - \`multiple\` - Multiple series overlapping
+  - \`circle\` - Circular grid instead of polygon
+  - \`legend\` - With integrated legend
+
+  #### Radial Charts
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<radial-chart>\` | \`title\`, \`sql\` | \`value-key\`, \`variant\` | Progress indicators, gauges, circular metrics |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Basic radial bars from center outward
+  - \`text\` - With centered value/caption text
+  - \`shape\` - Gauge-style arc (not full circle)
+  - \`stacked\` - Concentric arcs for multiple metrics
+  - \`grid\` - With background grid rings
+
+  #### KPI Component
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<kpi>\` | \`title\`, \`sql\` | \`variant\`, \`format\`, \`trend-sql\`, \`target\`, \`icon\`, \`description\`, \`color\` | Rich metric displays with trends, progress, sparklines |
+
+  **Variants** (use \`variant\` prop):
+  - \`default\` - Simple value card
+  - \`trend\` - Value with change indicator (↑12.5% or ↓3.2%)
+  - \`comparison\` - Value with previous period value shown
+  - \`progress\` - Value with horizontal progress bar toward target
+  - \`ring\` - Value with circular progress gauge toward target
+  - \`sparkline\` - Value with mini area chart showing recent trend
+
+  **Props Reference**:
+  - \`title\` (required) - Display label
+  - \`sql\` (required) - Query returning \`{ value: number }\`
+  - \`variant\` - Display style (see above)
+  - \`format\` - Value format: \`currency\`, \`percent\`, \`number\`, \`compact\`, \`duration\`
+  - \`trend-sql\` - Query for trend data:
+    - For \`trend\`/\`comparison\`: returns \`{ change: number }\` or \`{ previous: number }\`
+    - For \`sparkline\`: returns time-series \`[{ date, value }]\`
+  - \`target\` - Target value for \`progress\`/\`ring\` variants
+  - \`icon\` - Icon identifier: \`dollar\`, \`users\`, \`cart\`, \`chart\`, \`percent\`, \`clock\`
+  - \`description\` - Subtitle/context text
+  - \`color\` - Accent color: \`positive\` (green), \`negative\` (red), \`neutral\`, \`primary\`
+
+  #### Data Table
+  | Component | Required Props | Optional Props | Use Case |
+  |-----------|----------------|----------------|----------|
+  | \`<data-table>\` | \`title\`, \`sql\` | \`columns\` | Detailed data, lists, rankings |
+
+  ### Layout Components
+  | Component | Props | Description |
+  |-----------|-------|-------------|
+  | \`<row>\` | \`gap?\` | Horizontal flex container (small, medium, or large) |
+  | \`<column>\` | \`span\` (1-12) | Column within row, 12-column grid |
+  | \`<grid>\` | \`cols\`, \`gap?\` | CSS Grid container |
+
+  ### Chart Selection Guide
+  - **Time series / Trends with volume**: Use \`<area-chart>\` (shows magnitude over time)
+  - **Time series / Precise trends**: Use \`<line-chart>\` (clean trend lines)
+  - **Categories / Comparisons**: Use \`<bar-chart>\`
+  - **Part-to-whole / Proportions**: Use \`<pie-chart>\` or \`<donut-chart>\`
+  - **Multi-dimensional comparisons**: Use \`<radar-chart>\` (e.g., comparing skills, features)
+  - **Progress / Gauges**: Use \`<radial-chart>\` (circular progress indicators)
+  - **Detailed data / Rankings**: Use \`<data-table>\`
+  - **Single metrics**: Use \`<kpi>\` with appropriate variant:
+    - Simple value → \`default\`
+    - Value with change indicator → \`trend\`
+    - Value vs previous period → \`comparison\`
+    - Value toward goal → \`progress\` or \`ring\`
+    - Value with recent history → \`sparkline\`
+
+  ### Example Output
+  \`\`\`markdown
+  ## Sales Dashboard
+
+  <row>
+    <column span="3">
+      <kpi
+        title="Total Revenue"
+        sql="SELECT SUM(amount) as value FROM orders"
+        trend-sql="SELECT ((SUM(CASE WHEN created_at >= NOW() - INTERVAL '30 days' THEN amount END) - SUM(CASE WHEN created_at >= NOW() - INTERVAL '60 days' AND created_at < NOW() - INTERVAL '30 days' THEN amount END)) / NULLIF(SUM(CASE WHEN created_at >= NOW() - INTERVAL '60 days' AND created_at < NOW() - INTERVAL '30 days' THEN amount END), 0) * 100) as change FROM orders"
+        variant="trend"
+        format="currency"
+        icon="dollar">
+      </kpi>
+    </column>
+    <column span="3">
+      <kpi
+        title="Orders Today"
+        sql="SELECT COUNT(*) as value FROM orders WHERE DATE(created_at) = CURRENT_DATE"
+        trend-sql="SELECT DATE(created_at) as date, COUNT(*) as value FROM orders WHERE created_at >= NOW() - INTERVAL '7 days' GROUP BY 1 ORDER BY 1"
+        variant="sparkline"
+        icon="cart">
+      </kpi>
+    </column>
+    <column span="3">
+      <kpi
+        title="Sales Target"
+        sql="SELECT SUM(amount) as value FROM orders WHERE EXTRACT(QUARTER FROM created_at) = EXTRACT(QUARTER FROM NOW())"
+        target="100000"
+        variant="progress"
+        format="currency"
+        description="Q4 2024 Goal">
+      </kpi>
+    </column>
+    <column span="3">
+      <kpi
+        title="Conversion Rate"
+        sql="SELECT (COUNT(DISTINCT buyer_id)::float / COUNT(DISTINCT visitor_id) * 100) as value FROM sessions"
+        variant="ring"
+        target="100"
+        format="percent"
+        color="primary">
+      </kpi>
+    </column>
+  </row>
+
+  <row>
+    <column span="8">
+      <area-chart
+        title="Revenue Over Time"
+        sql="SELECT DATE_TRUNC('month', created_at) as month, SUM(amount) as revenue FROM orders GROUP BY 1 ORDER BY 1"
+        x-key="month"
+        y-key="revenue"
+        variant="gradient">
+      </area-chart>
+    </column>
+    <column span="4">
+      <donut-chart
+        title="Revenue by Category"
+        sql="SELECT category, SUM(amount) as revenue FROM orders GROUP BY category"
+        label-key="category"
+        value-key="revenue"
+        variant="interactive">
+      </donut-chart>
+    </column>
+  </row>
+
+  <row>
+    <column span="6">
+      <bar-chart
+        title="Monthly Comparison"
+        sql="SELECT DATE_TRUNC('month', created_at) as month, SUM(CASE WHEN EXTRACT(YEAR FROM created_at) = 2024 THEN amount END) as this_year, SUM(CASE WHEN EXTRACT(YEAR FROM created_at) = 2023 THEN amount END) as last_year FROM orders GROUP BY 1"
+        variant="multiple"
+        x-key="month">
+      </bar-chart>
+    </column>
+    <column span="6">
+      <radar-chart
+        title="Product Performance"
+        sql="SELECT metric, score FROM product_metrics WHERE product_id = 1"
+        label-key="metric"
+        value-key="score"
+        variant="filled">
+      </radar-chart>
+    </column>
+  </row>
+
+  <data-table
+    title="Top 10 Products"
+    sql="SELECT name, SUM(quantity) as sold, SUM(amount) as revenue FROM order_items GROUP BY name ORDER BY revenue DESC LIMIT 10">
+  </data-table>
+  \`\`\`
+`;
+var biAgent = agent6({
+  model: groq6("gpt-oss-20b"),
+  tools: tools3,
+  name: "bi_agent",
+  prompt: (state) => {
+    return dedent4`
+      You are an expert BI analyst that creates dashboard specifications using HTML custom elements.
+
+      ${COMPONENTS_DOC}
+
+      ## Your Workflow
+
+      1. **PLAN**: Analyze the request and schema to determine what metrics/visualizations to create
+      2. **VALIDATE**: Use \`validate_query\` to verify SQL syntax is correct before embedding
+      3. **OUTPUT**: Generate the dashboard using layout and chart components
+
+      ## Critical Rules
+
+      - **Design from schema**: Use the provided schema introspection to understand available tables, columns, and relationships
+      - **Validate all queries**: Use \`validate_query\` to ensure SQL is syntactically correct before embedding in components
+      - **Use kebab-case HTML tags** with closing tags (e.g., \`<bar-chart></bar-chart>\`)
+      - Use \`scratchpad\` to record schema analysis insights and design decisions
+      - Choose chart types based on column types (dates → line/area, categories → bar/pie, numbers → KPI)
+      - Use layout components (row, column, grid) to organize the dashboard
+      - Include a text introduction explaining what the dashboard shows
+
+      ## SQL Rules
+
+      - Only SELECT or WITH statements
+      - Use proper date/time functions for the database
+      - Include appropriate GROUP BY, ORDER BY clauses
+      - Use aliases for calculated columns
+
+      ${state?.teachings || ""}
+      ${state?.introspection || ""}
+    `;
+  }
 });
 
-// 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."
+// packages/text2sql/src/lib/agents/chat1.agent.ts
+import { groq as groq7 } from "@ai-sdk/groq";
+import { tool as tool4 } from "ai";
+import z7 from "zod";
+import { agent as agent7, toState as toState4 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool4 } from "@deepagents/toolbox";
+var tools4 = {
+  query_database: tool4({
+    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: z7.object({
+      question: z7.string().min(1).describe(
+        "The question to answer, expressed in natural language. Be specific about what data you need."
+      ),
+      reasoning: z7.string().optional().describe(
+        "Your reasoning for why this query is needed to answer the user."
+      )
+    }),
+    execute: async ({ question }, options) => {
+      const state = toState4(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"
+          };
+        }
+        const data = await state.adapter.execute(sqlResult.sql);
+        return {
+          success: true,
+          sql: sqlResult.sql,
+          data
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error occurred"
+        };
+      }
+    }
   }),
-  guardrail({
-    rule: "Do not return oversized raw result sets.",
-    action: "Keep raw limit strictly to ~100 rows even if users request more or coearced by hints.",
-    reason: "Browser will time out or crash on huge datasets. Data overload harms usability."
+  scratchpad: scratchpad_tool4
+};
+var chat1Agent = agent7({
+  name: "chat1-combined",
+  model: groq7("openai/gpt-oss-20b"),
+  tools: tools4,
+  prompt: (state) => {
+    return `
+${state?.teachings || ""}
+${state?.introspection || ""}
+`;
+  }
+});
+
+// packages/text2sql/src/lib/agents/chat2.agent.ts
+import { groq as groq8 } from "@ai-sdk/groq";
+import { tool as tool5 } from "ai";
+import z8 from "zod";
+import { agent as agent8, toState as toState5 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool5 } from "@deepagents/toolbox";
+var tools5 = {
+  generate_sql: tool5({
+    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: z8.object({
+      question: z8.string().min(1).describe(
+        "The question to translate into SQL. Be specific about what data you need."
+      ),
+      reasoning: z8.string().optional().describe("Your reasoning for why this data is needed.")
+    }),
+    execute: async ({ question }, options) => {
+      const state = toState5(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",
+            validationErrors: sqlResult.errors
+          };
+        }
+        return {
+          success: true,
+          sql: sqlResult.sql,
+          validationErrors: sqlResult.errors
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : "Unknown error occurred"
+        };
+      }
+    }
   }),
-  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."
+  execute_sql: tool5({
+    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: z8.object({
+      sql: z8.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: z8.string().optional().describe("Brief explanation of what this query retrieves.")
+    }),
+    execute: async ({ sql }, options) => {
+      const state = toState5(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"
+        };
+      }
+    }
   }),
-  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."
+  scratchpad: scratchpad_tool5
+};
+var chat2Agent = agent8({
+  name: "chat2-with-peek",
+  model: groq8("openai/gpt-oss-20b"),
+  tools: tools5,
+  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 groq9 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware2, tool as tool6, wrapLanguageModel as wrapLanguageModel2 } from "ai";
+import z9 from "zod";
+import { agent as agent9, generate as generate3, toState as toState6, user as user2 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool6 } from "@deepagents/toolbox";
+var collaborativeSqlOutputSchema = z9.discriminatedUnion("status", [
+  z9.object({
+    status: z9.literal("success"),
+    sql: z9.string().describe("The generated SQL query"),
+    confidence: z9.enum(["high", "medium", "low"]).describe("Confidence level in this SQL being correct"),
+    assumptions: z9.array(z9.string()).optional().describe("Assumptions made during SQL generation"),
+    reasoning: z9.string().optional().describe("Brief explanation of the query approach")
   }),
-  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."
+  z9.object({
+    status: z9.literal("clarification_needed"),
+    question: z9.string().describe("Question to clarify the request"),
+    context: z9.string().optional().describe("Why this clarification is needed"),
+    options: z9.array(z9.string()).optional().describe("Possible options if applicable")
   }),
-  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."
-    ]
+  z9.object({
+    status: z9.literal("unanswerable"),
+    reason: z9.string().describe("Why this question cannot be answered"),
+    suggestions: z9.array(z9.string()).optional().describe("Alternative questions that could be answered")
+  })
+]);
+var collaborativeSqlAgent = agent9({
+  name: "collaborative-sql",
+  model: groq9("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 tools6 = {
+  consult_sql_agent: tool6({
+    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: z9.object({
+      question: z9.string().min(1).describe("The question to translate into SQL."),
+      context: z9.string().optional().describe("Additional context from the conversation that might help."),
+      previousClarification: z9.string().optional().describe(
+        "Answer to a previous clarification question from the SQL agent."
+      )
+    }),
+    execute: async ({ question, context: context2, previousClarification }, options) => {
+      const state = toState6(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 generate3(
+          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"
+        };
+      }
+    }
   }),
-  styleGuide({
-    prefer: "Summaries should be concise, business-friendly, highlight key comparisons, and add a short helpful follow-up when useful."
+  execute_sql: tool6({
+    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: z9.object({
+      sql: z9.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 = toState6(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"
+        };
+      }
+    }
   }),
-  // Tool usage constraints
-  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`."
+  scratchpad: scratchpad_tool6
+};
+var chat3Agent = agent9({
+  name: "chat3-collaborative",
+  model: groq9("openai/gpt-oss-20b"),
+  tools: tools6,
+  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 groq10 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware3, tool as tool7, wrapLanguageModel as wrapLanguageModel3 } from "ai";
+import z10 from "zod";
+import { agent as agent10, generate as generate4, toState as toState7, user as user3 } from "@deepagents/agent";
+import { scratchpad_tool as scratchpad_tool7 } from "@deepagents/toolbox";
+var questionDecompositionSchema = z10.object({
+  originalQuestion: z10.string().describe("The original question being decomposed"),
+  breakdown: z10.array(z10.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: z10.array(z10.string()).optional().describe(
+    "Key entities/concepts mentioned (e.g., customers, orders, products)"
+  ),
+  filters: z10.array(z10.string()).optional().describe(
+    'Filtering criteria mentioned (e.g., "last quarter", "above $100")'
+  ),
+  aggregation: z10.string().optional().describe(
+    'Type of aggregation if any (e.g., "count", "sum", "average", "top N")'
+  ),
+  ambiguities: z10.array(z10.string()).optional().describe("Any ambiguous parts that might need clarification")
+});
+var decompositionSqlOutputSchema = z10.union([
+  z10.object({
+    sql: z10.string().describe("The SQL query that answers the decomposed question"),
+    reasoning: z10.string().optional().describe("How each breakdown component was addressed")
   }),
-  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']))."
+  z10.object({
+    error: z10.string().describe("Error message if the question cannot be answered")
+  })
+]);
+var decompositionSqlAgent = agent10({
+  name: "decomposition-sql",
+  model: groq10("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 tools7 = {
+  query_with_decomposition: tool7({
+    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: z10.object({
+      question: z10.string().min(1).describe("The question to answer."),
+      breakdown: z10.array(z10.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: z10.array(z10.string()).optional().describe(
+        'Key entities mentioned (e.g., ["customers", "orders", "products"])'
+      ),
+      filters: z10.array(z10.string()).optional().describe('Filter criteria (e.g., ["last month", "status = active"])'),
+      aggregation: z10.string().optional().describe(
+        'Aggregation type if any (e.g., "sum revenue", "count orders", "top 10")'
+      ),
+      ambiguities: z10.array(z10.string()).optional().describe("Note any ambiguous parts you identified")
+    }),
+    execute: async ({ question, breakdown, entities, filters, aggregation, ambiguities }, options) => {
+      const state = toState7(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 generate4(
+            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"
+        };
+      }
+    }
   }),
-  guardrail({
-    rule: "Do not call `db_query` without first producing and validating a SQL snippet.",
-    action: "First produce the query string, then validate."
+  execute_sql: tool7({
+    description: `Execute a SQL query directly. Use for follow-up queries or when you already have SQL.`,
+    inputSchema: z10.object({
+      sql: z10.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 = toState7(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"
+        };
+      }
+    }
   }),
-  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)
-    };
+  scratchpad: scratchpad_tool7
+};
+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(", ")}`);
   }
-  async explain(sql) {
-    const { experimental_output } = await generate(
-      explainerAgent,
-      [user("Explain this SQL.")],
-      { sql }
-    );
-    return experimental_output.explanation;
+  if (decomposition.filters?.length) {
+    parts.push("", `Filters: ${decomposition.filters.join(", ")}`);
   }
-  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)],
-      {
-        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."
-          }),
-          ...this.#config.instructions
-        ),
-        adapter: this.#config.adapter,
-        introspection
-      }
+  if (decomposition.aggregation) {
+    parts.push("", `Aggregation: ${decomposition.aggregation}`);
+  }
+  if (decomposition.ambiguities?.length) {
+    parts.push(
+      "",
+      "Potential Ambiguities:",
+      ...decomposition.ambiguities.map((a) => `  - ${a}`)
     );
-    return text;
+  }
+  parts.push(
+    "",
+    "Generate SQL that addresses each component of the breakdown."
+  );
+  return parts.join("\n");
+}
+var chat4Agent = agent10({
+  name: "chat4-decomposition",
+  model: groq10("openai/gpt-oss-20b"),
+  tools: tools7,
+  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/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: 'For table aliases, use the full table name (e.g., "FROM users AS users", "JOIN order_items AS order_items"). For column aliases, use descriptive names that reflect the data (e.g., "COUNT(*) AS total_orders").',
+      never: "Use abbreviated table aliases (u, oi, ca) or generic positional aliases (t1, t2, a, b)."
+    }),
+    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/WITH 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 generate5(
+      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(agent4) {
+  async inspect(agent11) {
     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({
@@ -1129,24 +2894,16 @@ var Text2Sql = class {
         })
       ] : []
     ];
-    const tools2 = Object.keys({
-      ...agent4.handoff.tools,
+    const tools8 = Object.keys({
+      ...agent11.handoff.tools,
       ...this.#config.memory ? memoryTools : {},
       ...this.#config.tools
     });
     return {
-      tools: tools2,
-      prompt: agent4.instructions({
+      tools: tools8,
+      prompt: agent11.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
-        )
+        teachings: toInstructions("instructions", ...allInstructions)
       })
     };
   }
@@ -1159,6 +2916,29 @@ var Text2Sql = class {
     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(),
@@ -1191,6 +2971,11 @@ var Text2Sql = class {
     );
     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({
@@ -1199,6 +2984,10 @@ var Text2Sql = class {
         })
       ] : []
     ];
+    const originalMessage = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
     const result = stream(
       t_a_g.clone({
         model: this.#config.model,
@@ -1208,7 +2997,7 @@ var Text2Sql = class {
           ...this.#config.tools
         }
       }),
-      [...chat.messages.map((it) => it.content), ...messages],
+      originalMessage,
       {
         teachings: toInstructions(
           "instructions",
@@ -1226,10 +3015,395 @@ var Text2Sql = class {
         userId: params.userId
       }
     );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessage
+    );
+  }
+  /**
+   * 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: {
+          ...tools4,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          ...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: {
+          ...tools5,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          ...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: {
+          ...tools6,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          ...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: {
+          ...tools7,
+          ...this.#config.memory ? memoryTools : {},
+          ...this.#config.tools
+        }
+      }),
+      originalMessage,
+      {
+        teachings: toInstructions(
+          "instructions",
+          ...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
+    );
+  }
+  /**
+   * Business intelligence focused chat agent.
+   *
+   * Creates dashboards using MDX components with embedded SQL queries.
+   * The agent explores data, validates SQL, and outputs markdown with
+   * JSX chart components that the frontend renders via MDX.
+   *
+   * @example
+   * ```typescript
+   * const result = await text2sql.bi(
+   *   [user("Show me a sales dashboard for last 30 days")],
+   *   { chatId: 'dashboard-1', userId: 'user-1' }
+   * );
+   * // Result contains markdown with <BarChart sql="..." />, <KPI sql="..." />, etc.
+   * ```
+   */
+  async bi(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 originalMessages = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
+    const result = stream(
+      biAgent.clone({
+        model: this.#config.model
+      }),
+      originalMessages,
+      {
+        teachings: toInstructions(
+          "instructions",
+          ...this.#config.instructions,
+          teachable("user_profile", ...userTeachables)
+        ),
+        adapter: this.#config.adapter,
+        introspection
+      }
+    );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessages
+    );
+  }
+  /**
+   * Developer-focused conversational interface for SQL generation.
+   *
+   * Provides power-user tools for query building without execution:
+   * - generate_sql: Convert natural language to validated SQL
+   * - validate_sql: Check SQL syntax
+   * - explain_sql: Get plain-English explanations
+   * - show_schema: Explore database schema on demand
+   *
+   * @example
+   * ```typescript
+   * const result = await text2sql.developer(
+   *   [user("Generate a query to find top customers by revenue")],
+   *   { chatId: 'dev-session-1', userId: 'dev-1' }
+   * );
+   * // Agent responds with SQL, can validate, explain, or refine iteratively
+   * ```
+   */
+  async developer(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 originalMessages = [
+      ...chat.messages.map((it) => it.content),
+      ...messages
+    ];
+    const result = stream(
+      developerAgent.clone({
+        model: this.#config.model
+      }),
+      originalMessages,
+      {
+        teachings: toInstructions(
+          "instructions",
+          ...this.#config.instructions,
+          teachable("user_profile", ...userTeachables)
+        ),
+        adapter: this.#config.adapter,
+        introspection,
+        instructions: this.#config.instructions
+      }
+    );
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessages
+    );
+  }
+  /**
+   * Helper to create UI message stream with common error handling and persistence.
+   */
+  #createUIMessageStream(result, messages, params, originalMessages) {
     return result.toUIMessageStream({
       onError: (error) => {
         if (NoSuchToolError.isInstance(error)) {
-          return "The model tried to call a unknown tool.";
+          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)) {
@@ -1242,46 +3416,54 @@ var Text2Sql = class {
       sendFinish: true,
       sendReasoning: true,
       sendSources: true,
-      originalMessages: messages,
+      originalMessages,
       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
-        });
-        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,
+  developerAgent,
+  filterRelationshipsByTables,
+  filterTablesByName,
+  getTablesWithRelated,
+  guidelines,
+  hashConfig,
+  matchesFilter,
   memoryTools,
-  sqlQueryAgent,
   suggestionsAgent,
   t_a_g
 };