@deepagents/text2sql 0.6.0 → 0.8.0

package/dist/index.js

@@ -149,64 +149,58 @@ function getTablesWithRelated(allTables, relationships, filter) {
   return Array.from(result);
 }
 
-// packages/text2sql/src/lib/agents/suggestions.agents.ts
+// 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 } from "@deepagents/agent";
-import { scratchpad_tool } from "@deepagents/toolbox";
+import {
+  agent as agent2,
+  generate,
+  toOutput,
+  user
+} from "@deepagents/agent";
 
 // packages/text2sql/src/lib/teach/xml.ts
 function wrapBlock(tag, children) {
@@ -581,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",
@@ -710,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}`;
@@ -725,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,
@@ -749,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."
@@ -763,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",
@@ -776,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);
@@ -845,30 +1217,117 @@ 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 t_a_g = agent2({
-  model: groq2("openai/gpt-oss-20b"),
-  tools,
+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",
   prompt: (state) => {
     const hasMemory = !!state?.memory;
     return `
-
     ${state?.teachings || ""}
     ${state?.introspection || ""}
 
+    ${chainOfThoughtPrompt}
+
+    ${fewShotExamples}
+
     ${hasMemory ? memory_prompt_default : ""}
   `;
   }
@@ -939,9 +1398,7 @@ var Checkpoint = class _Checkpoint {
    * @param step - Unique identifier for this checkpoint point
    */
   point(step) {
-    if (!this.points[step]) {
-      this.points[step] = { committed: false, entries: [] };
-    }
+    this.points[step] ??= { committed: false, entries: [] };
     return new Point(this.points[step], () => this.save());
   }
   /**
@@ -1279,156 +1736,338 @@ import {
 } from "ai";
 import { v7 as v72 } from "uuid";
 import {
-  generate as generate4,
+  generate as generate5,
   stream,
   user as user4
 } from "@deepagents/agent";
 
-// packages/text2sql/src/lib/agents/chat1.agent.ts
-import { groq as groq4 } from "@ai-sdk/groq";
-import { tool as tool2 } from "ai";
-import z4 from "zod";
-import { agent as agent4, toState as toState2 } from "@deepagents/agent";
-import { scratchpad_tool as scratchpad_tool2 } from "@deepagents/toolbox";
+// packages/text2sql/src/lib/agents/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.
 
-// packages/text2sql/src/lib/agents/sql.agent.ts
-import { groq as groq3 } from "@ai-sdk/groq";
-import { defaultSettingsMiddleware, wrapLanguageModel } from "ai";
-import z3 from "zod";
-import { agent as agent3, generate, user } from "@deepagents/agent";
-var RETRY_TEMPERATURES = [0, 0.2, 0.3];
-var sqlQueryAgent = agent3({
-  name: "text2sql",
-  model: groq3("openai/gpt-oss-20b"),
-  logging: process.env.AGENT_LOGGING === "true",
-  output: z3.union([
-    z3.object({
-      sql: z3.string().describe("The SQL query that answers the question"),
-      reasoning: z3.string().optional().describe("The reasoning steps taken to generate the SQL")
+      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.")
     }),
-    z3.object({
-      error: z3.string().describe(
-        "Error message explaining why the question cannot be answered with the given schema"
-      )
-    })
-  ]),
-  prompt: (state) => {
-    return `
-    ${state?.teachings || ""}
-    ${state?.introspection || ""}
-  `;
-  }
-});
-function extractSql(output) {
-  const match = output.match(/```sql\n?([\s\S]*?)```/);
-  return match ? match[1].trim() : output.trim();
-}
-async function generateSql(params) {
-  const {
-    input,
-    model,
-    temperature,
-    introspection,
-    instructions,
-    previousError
-  } = params;
-  const agentInstance = sqlQueryAgent.clone({
-    model: wrapLanguageModel({
-      model,
-      middleware: defaultSettingsMiddleware({
-        settings: { temperature, topP: 1 }
-      })
-    })
-  });
-  const messages = previousError ? [
-    user(input),
-    user(
-      `<validation_error>Your previous SQL query had the following error: ${previousError}. Please fix the query.</validation_error>`
-    )
-  ] : [user(input)];
-  try {
-    const { experimental_output: output } = await generate(
-      agentInstance,
-      messages,
-      {
-        teachings: toInstructions(
-          "instructions",
-          persona({
-            name: "Freya",
-            role: "You are an expert SQL query generator. You translate natural language questions into precise, efficient SQL queries based on the provided database schema."
-          }),
-          ...instructions
-        ),
-        introspection
+    execute: async ({ sql }, options) => {
+      const state = toState3(options);
+      const result = await state.adapter.validate(sql);
+      if (typeof result === "string") {
+        return { valid: false, error: result };
       }
-    );
-    if ("error" in output) {
-      return { success: false, error: output.error, isUnanswerable: true };
-    }
-    return { success: true, sql: extractSql(output.sql) };
-  } catch (error) {
-    if (error instanceof Error && (error.message.includes("Failed to validate JSON") || error.message.includes("response did not match schema"))) {
-      return {
-        success: false,
-        error: `Schema validation failed: ${error.message}`
-      };
+      return { valid: true };
     }
-    throw error;
-  }
-}
-var sqlGenerators = {
-  generateSql
+  }),
+  /**
+   * Record insights and reasoning during schema analysis and dashboard design.
+   */
+  scratchpad: scratchpad_tool3
 };
-async function generateAndValidate(options, temperature, previousError) {
-  const result = await sqlGenerators.generateSql({
-    input: options.input,
-    model: options.model ?? sqlQueryAgent.model,
-    temperature,
-    introspection: options.introspection,
-    instructions: options.instructions,
-    previousError
-  });
-  if (!result.success) {
-    return {
-      ok: false,
-      error: result.error,
-      isUnanswerable: result.isUnanswerable
-    };
-  }
-  const validationError = await options.adapter.validate(result.sql);
-  if (validationError) {
-    return { ok: false, error: validationError };
-  }
-  return { ok: true, sql: result.sql };
-}
-async function toSql(options) {
-  const { maxRetries = 3 } = options;
-  const errors = [];
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    const temperature = RETRY_TEMPERATURES[attempt - 1] ?? 0.3;
-    const result = await generateAndValidate(
-      options,
-      temperature,
-      errors.at(-1)
-    );
-    if (result.ok) {
-      return {
-        sql: result.sql,
-        attempts: attempt,
-        errors: errors.length ? errors : void 0
-      };
-    }
-    if (result.isUnanswerable) {
-      return { sql: "", attempts: attempt, errors: [result.error] };
-    }
-    errors.push(result.error);
+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 || ""}
+    `;
   }
-  return { sql: "", attempts: maxRetries, errors };
-}
+});
 
 // packages/text2sql/src/lib/agents/chat1.agent.ts
-var tools2 = {
-  query_database: tool2({
+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
@@ -1436,16 +2075,16 @@ var tools2 = {
 4. Return the results
 
 Use this tool when you need to retrieve data to answer the user's question.`,
-    inputSchema: z4.object({
-      question: z4.string().min(1).describe(
+    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: z4.string().optional().describe(
+      reasoning: z7.string().optional().describe(
         "Your reasoning for why this query is needed to answer the user."
       )
     }),
     execute: async ({ question }, options) => {
-      const state = toState2(options);
+      const state = toState4(options);
       try {
         const sqlResult = await toSql({
           input: question,
@@ -1456,16 +2095,14 @@ Use this tool when you need to retrieve data to answer the user's question.`,
         if (!sqlResult.sql) {
           return {
             success: false,
-            error: sqlResult.errors?.join("; ") || "Failed to generate SQL",
-            attempts: sqlResult.attempts
+            error: sqlResult.errors?.join("; ") || "Failed to generate SQL"
           };
         }
         const data = await state.adapter.execute(sqlResult.sql);
         return {
           success: true,
           sql: sqlResult.sql,
-          data,
-          attempts: sqlResult.attempts
+          data
         };
       } catch (error) {
         return {
@@ -1475,12 +2112,12 @@ Use this tool when you need to retrieve data to answer the user's question.`,
       }
     }
   }),
-  scratchpad: scratchpad_tool2
+  scratchpad: scratchpad_tool4
 };
-var chat1Agent = agent4({
+var chat1Agent = agent7({
   name: "chat1-combined",
-  model: groq4("openai/gpt-oss-20b"),
-  tools: tools2,
+  model: groq7("openai/gpt-oss-20b"),
+  tools: tools4,
   prompt: (state) => {
     return `
 ${state?.teachings || ""}
@@ -1490,13 +2127,13 @@ ${state?.introspection || ""}
 });
 
 // packages/text2sql/src/lib/agents/chat2.agent.ts
-import { groq as groq5 } from "@ai-sdk/groq";
-import { tool as tool3 } from "ai";
-import z5 from "zod";
-import { agent as agent5, toState as toState3 } from "@deepagents/agent";
-import { scratchpad_tool as scratchpad_tool3 } from "@deepagents/toolbox";
-var tools3 = {
-  generate_sql: tool3({
+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
@@ -1507,14 +2144,14 @@ Use this BEFORE execute_sql to see what query will be run. You can then:
 - Explain the approach to the user
 - Decide if the SQL looks correct
 - Refine your question and regenerate if needed`,
-    inputSchema: z5.object({
-      question: z5.string().min(1).describe(
+    inputSchema: z8.object({
+      question: z8.string().min(1).describe(
         "The question to translate into SQL. Be specific about what data you need."
       ),
-      reasoning: z5.string().optional().describe("Your reasoning for why this data is needed.")
+      reasoning: z8.string().optional().describe("Your reasoning for why this data is needed.")
     }),
     execute: async ({ question }, options) => {
-      const state = toState3(options);
+      const state = toState5(options);
       try {
         const sqlResult = await toSql({
           input: question,
@@ -1526,14 +2163,12 @@ Use this BEFORE execute_sql to see what query will be run. You can then:
           return {
             success: false,
             error: sqlResult.errors?.join("; ") || "Failed to generate SQL",
-            attempts: sqlResult.attempts,
             validationErrors: sqlResult.errors
           };
         }
         return {
           success: true,
           sql: sqlResult.sql,
-          attempts: sqlResult.attempts,
           validationErrors: sqlResult.errors
         };
       } catch (error) {
@@ -1544,21 +2179,21 @@ Use this BEFORE execute_sql to see what query will be run. You can then:
       }
     }
   }),
-  execute_sql: tool3({
+  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: z5.object({
-      sql: z5.string().min(1).refine(
+    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: z5.string().optional().describe("Brief explanation of what this query retrieves.")
+      reasoning: z8.string().optional().describe("Brief explanation of what this query retrieves.")
     }),
     execute: async ({ sql }, options) => {
-      const state = toState3(options);
+      const state = toState5(options);
       try {
         const data = await state.adapter.execute(sql);
         return {
@@ -1574,12 +2209,12 @@ Only SELECT and WITH (CTE) queries are allowed - no data modification.`,
       }
     }
   }),
-  scratchpad: scratchpad_tool3
+  scratchpad: scratchpad_tool5
 };
-var chat2Agent = agent5({
+var chat2Agent = agent8({
   name: "chat2-with-peek",
-  model: groq5("openai/gpt-oss-20b"),
-  tools: tools3,
+  model: groq8("openai/gpt-oss-20b"),
+  tools: tools5,
   prompt: (state) => {
     return `
 ${state?.teachings || ""}
@@ -1597,34 +2232,34 @@ If the generated SQL doesn't look right, you can refine your question and regene
 });
 
 // packages/text2sql/src/lib/agents/chat3.agent.ts
-import { groq as groq6 } from "@ai-sdk/groq";
-import { defaultSettingsMiddleware as defaultSettingsMiddleware2, tool as tool4, wrapLanguageModel as wrapLanguageModel2 } from "ai";
-import z6 from "zod";
-import { agent as agent6, generate as generate2, toState as toState4, user as user2 } from "@deepagents/agent";
-import { scratchpad_tool as scratchpad_tool4 } from "@deepagents/toolbox";
-var collaborativeSqlOutputSchema = z6.discriminatedUnion("status", [
-  z6.object({
-    status: z6.literal("success"),
-    sql: z6.string().describe("The generated SQL query"),
-    confidence: z6.enum(["high", "medium", "low"]).describe("Confidence level in this SQL being correct"),
-    assumptions: z6.array(z6.string()).optional().describe("Assumptions made during SQL generation"),
-    reasoning: z6.string().optional().describe("Brief explanation of the query approach")
+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")
   }),
-  z6.object({
-    status: z6.literal("clarification_needed"),
-    question: z6.string().describe("Question to clarify the request"),
-    context: z6.string().optional().describe("Why this clarification is needed"),
-    options: z6.array(z6.string()).optional().describe("Possible options if applicable")
+  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")
   }),
-  z6.object({
-    status: z6.literal("unanswerable"),
-    reason: z6.string().describe("Why this question cannot be answered"),
-    suggestions: z6.array(z6.string()).optional().describe("Alternative questions that could be answered")
+  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 = agent6({
+var collaborativeSqlAgent = agent9({
   name: "collaborative-sql",
-  model: groq6("openai/gpt-oss-20b"),
+  model: groq9("openai/gpt-oss-20b"),
   output: collaborativeSqlOutputSchema,
   prompt: (state) => {
     return `
@@ -1658,8 +2293,8 @@ Prefer asking for clarification over making low-confidence guesses.
 `;
   }
 });
-var tools4 = {
-  consult_sql_agent: tool4({
+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
@@ -1669,15 +2304,15 @@ Based on the response:
 - If clarification is needed, you can provide context or ask the user
 - If assumptions were made, verify them with the user for important queries
 - If unanswerable, relay the suggestions to the user`,
-    inputSchema: z6.object({
-      question: z6.string().min(1).describe("The question to translate into SQL."),
-      context: z6.string().optional().describe("Additional context from the conversation that might help."),
-      previousClarification: z6.string().optional().describe(
+    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 = toState4(options);
+      const state = toState6(options);
       try {
         let fullQuestion = question;
         if (context2) {
@@ -1698,7 +2333,7 @@ Clarification provided: ${previousClarification}`;
             })
           })
         });
-        const { experimental_output: output } = await generate2(
+        const { experimental_output: output } = await generate3(
           agentInstance,
           [user2(fullQuestion)],
           state
@@ -1747,11 +2382,11 @@ Clarification provided: ${previousClarification}`;
       }
     }
   }),
-  execute_sql: tool4({
+  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: z6.object({
-      sql: z6.string().min(1).refine(
+    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."
@@ -1759,7 +2394,7 @@ Clarification provided: ${previousClarification}`;
       ).describe("The SQL query to execute.")
     }),
     execute: async ({ sql }, options) => {
-      const state = toState4(options);
+      const state = toState6(options);
       try {
         const validationError = await state.adapter.validate(sql);
         if (validationError) {
@@ -1782,12 +2417,12 @@ Clarification provided: ${previousClarification}`;
       }
     }
   }),
-  scratchpad: scratchpad_tool4
+  scratchpad: scratchpad_tool6
 };
-var chat3Agent = agent6({
+var chat3Agent = agent9({
   name: "chat3-collaborative",
-  model: groq6("openai/gpt-oss-20b"),
-  tools: tools4,
+  model: groq9("openai/gpt-oss-20b"),
+  tools: tools6,
   prompt: (state) => {
     return `
 ${state?.teachings || ""}
@@ -1807,39 +2442,39 @@ For clarification requests, try to answer from conversation context first before
 });
 
 // packages/text2sql/src/lib/agents/chat4.agent.ts
-import { groq as groq7 } from "@ai-sdk/groq";
-import { defaultSettingsMiddleware as defaultSettingsMiddleware3, tool as tool5, wrapLanguageModel as wrapLanguageModel3 } from "ai";
-import z7 from "zod";
-import { agent as agent7, generate as generate3, toState as toState5, user as user3 } from "@deepagents/agent";
-import { scratchpad_tool as scratchpad_tool5 } from "@deepagents/toolbox";
-var questionDecompositionSchema = z7.object({
-  originalQuestion: z7.string().describe("The original question being decomposed"),
-  breakdown: z7.array(z7.string()).min(1).describe(
+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: z7.array(z7.string()).optional().describe(
+  entities: z10.array(z10.string()).optional().describe(
     "Key entities/concepts mentioned (e.g., customers, orders, products)"
   ),
-  filters: z7.array(z7.string()).optional().describe(
+  filters: z10.array(z10.string()).optional().describe(
     'Filtering criteria mentioned (e.g., "last quarter", "above $100")'
   ),
-  aggregation: z7.string().optional().describe(
+  aggregation: z10.string().optional().describe(
     'Type of aggregation if any (e.g., "count", "sum", "average", "top N")'
   ),
-  ambiguities: z7.array(z7.string()).optional().describe("Any ambiguous parts that might need clarification")
+  ambiguities: z10.array(z10.string()).optional().describe("Any ambiguous parts that might need clarification")
 });
-var decompositionSqlOutputSchema = z7.union([
-  z7.object({
-    sql: z7.string().describe("The SQL query that answers the decomposed question"),
-    reasoning: z7.string().optional().describe("How each breakdown component was addressed")
+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")
   }),
-  z7.object({
-    error: z7.string().describe("Error message if the question cannot be answered")
+  z10.object({
+    error: z10.string().describe("Error message if the question cannot be answered")
   })
 ]);
-var decompositionSqlAgent = agent7({
+var decompositionSqlAgent = agent10({
   name: "decomposition-sql",
-  model: groq7("openai/gpt-oss-20b"),
+  model: groq10("openai/gpt-oss-20b"),
   output: decompositionSqlOutputSchema,
   prompt: (state) => {
     return `
@@ -1866,8 +2501,8 @@ If there are ambiguities, make reasonable assumptions and note them in your reas
   }
 });
 var RETRY_TEMPERATURES2 = [0, 0.2, 0.3];
-var tools5 = {
-  query_with_decomposition: tool5({
+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
@@ -1875,22 +2510,22 @@ var tools5 = {
 4. Executes and returns results
 
 This approach helps ensure all aspects of the question are addressed in the query.`,
-    inputSchema: z7.object({
-      question: z7.string().min(1).describe("The question to answer."),
-      breakdown: z7.array(z7.string()).min(1).describe(
+    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: z7.array(z7.string()).optional().describe(
+      entities: z10.array(z10.string()).optional().describe(
         'Key entities mentioned (e.g., ["customers", "orders", "products"])'
       ),
-      filters: z7.array(z7.string()).optional().describe('Filter criteria (e.g., ["last month", "status = active"])'),
-      aggregation: z7.string().optional().describe(
+      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: z7.array(z7.string()).optional().describe("Note any ambiguous parts you identified")
+      ambiguities: z10.array(z10.string()).optional().describe("Note any ambiguous parts you identified")
     }),
     execute: async ({ question, breakdown, entities, filters, aggregation, ambiguities }, options) => {
-      const state = toState5(options);
+      const state = toState7(options);
       const decomposition = {
         originalQuestion: question,
         breakdown,
@@ -1915,7 +2550,7 @@ This approach helps ensure all aspects of the question are addressed in the quer
           const prompt = lastError ? `${decomposedPrompt}
 
 Previous attempt failed with: ${lastError}. Please fix the query.` : decomposedPrompt;
-          const { experimental_output: output } = await generate3(
+          const { experimental_output: output } = await generate4(
             agentInstance,
             [user3(prompt)],
             state
@@ -1962,10 +2597,10 @@ Previous attempt failed with: ${lastError}. Please fix the query.` : decomposedP
       }
     }
   }),
-  execute_sql: tool5({
+  execute_sql: tool7({
     description: `Execute a SQL query directly. Use for follow-up queries or when you already have SQL.`,
-    inputSchema: z7.object({
-      sql: z7.string().min(1).refine(
+    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."
@@ -1973,7 +2608,7 @@ Previous attempt failed with: ${lastError}. Please fix the query.` : decomposedP
       ).describe("The SQL query to execute.")
     }),
     execute: async ({ sql }, options) => {
-      const state = toState5(options);
+      const state = toState7(options);
       try {
         const validationError = await state.adapter.validate(sql);
         if (validationError) {
@@ -1996,7 +2631,7 @@ Previous attempt failed with: ${lastError}. Please fix the query.` : decomposedP
       }
     }
   }),
-  scratchpad: scratchpad_tool5
+  scratchpad: scratchpad_tool7
 };
 function formatDecomposition(decomposition) {
   const parts = [
@@ -2027,10 +2662,10 @@ function formatDecomposition(decomposition) {
   );
   return parts.join("\n");
 }
-var chat4Agent = agent7({
+var chat4Agent = agent10({
   name: "chat4-decomposition",
-  model: groq7("openai/gpt-oss-20b"),
-  tools: tools5,
+  model: groq10("openai/gpt-oss-20b"),
+  tools: tools7,
   prompt: (state) => {
     return `
 ${state?.teachings || ""}
@@ -2056,28 +2691,6 @@ Break the question into its semantic aspects, and let the SQL specialist figure
   }
 });
 
-// packages/text2sql/src/lib/agents/explainer.agent.ts
-import { groq as groq8 } from "@ai-sdk/groq";
-import dedent2 from "dedent";
-import z8 from "zod";
-import { agent as agent8 } from "@deepagents/agent";
-var explainerAgent = agent8({
-  name: "explainer",
-  model: groq8("openai/gpt-oss-20b"),
-  prompt: (state) => dedent2`
-    You are an expert SQL tutor.
-    Explain the following SQL query in plain English to a non-technical user.
-    Focus on the intent and logic, not the syntax.
-
-    <sql>
-    ${state?.sql}
-    </sql>
-  `,
-  output: z8.object({
-    explanation: z8.string().describe("The explanation of the SQL query.")
-  })
-});
-
 // packages/text2sql/src/lib/synthesis/types.ts
 async function toPairs(producer) {
   const pairs = [];
@@ -2139,7 +2752,8 @@ function guidelines(options = {}) {
     ),
     // Style and readability
     styleGuide({
-      prefer: "Use meaningful aliases for tables and columns to improve readability."
+      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."
@@ -2151,7 +2765,7 @@ function guidelines(options = {}) {
       action: "Validate syntax and schema references before returning."
     }),
     guardrail({
-      rule: "Only generate SELECT statements (read-only queries).",
+      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."
     }),
@@ -2239,7 +2853,7 @@ var Text2Sql = class {
     };
   }
   async explain(sql) {
-    const { experimental_output } = await generate4(
+    const { experimental_output } = await generate5(
       explainerAgent,
       [user4("Explain this SQL.")],
       { sql }
@@ -2260,7 +2874,7 @@ var Text2Sql = class {
   instruct(...dataset) {
     this.#config.instructions.push(...dataset);
   }
-  async inspect(agent9) {
+  async inspect(agent11) {
     const [grounding] = await Promise.all([this.index()]);
     const renderToolNames = Object.keys(this.#config.tools ?? {}).filter(
       (name) => name.startsWith("render_")
@@ -2280,14 +2894,14 @@ var Text2Sql = class {
         })
       ] : []
     ];
-    const tools6 = Object.keys({
-      ...agent9.handoff.tools,
+    const tools8 = Object.keys({
+      ...agent11.handoff.tools,
       ...this.#config.memory ? memoryTools : {},
       ...this.#config.tools
     });
     return {
-      tools: tools6,
-      prompt: agent9.instructions({
+      tools: tools8,
+      prompt: agent11.instructions({
         introspection: grounding,
         teachings: toInstructions("instructions", ...allInstructions)
       })
@@ -2401,46 +3015,12 @@ var Text2Sql = class {
         userId: params.userId
       }
     );
-    return result.toUIMessageStream({
-      onError: (error) => {
-        if (NoSuchToolError.isInstance(error)) {
-          return "The model tried to call a unknown tool.";
-        } else if (InvalidToolInputError.isInstance(error)) {
-          return "The model called a tool with invalid arguments.";
-        } else if (ToolCallRepairError.isInstance(error)) {
-          return "The model tried to call a tool with invalid arguments, but it was repaired.";
-        } else {
-          return "An unknown error occurred.";
-        }
-      },
-      sendStart: true,
-      sendFinish: true,
-      sendReasoning: true,
-      sendSources: true,
-      originalMessages: originalMessage,
-      generateMessageId: generateId,
-      onFinish: async ({ responseMessage, isContinuation }) => {
-        const userMessage = messages.at(-1);
-        if (!isContinuation && userMessage) {
-          console.log(
-            "Saving user message to history:",
-            JSON.stringify(userMessage)
-          );
-          await this.#config.history.addMessage({
-            id: v72(),
-            chatId: params.chatId,
-            role: userMessage.role,
-            content: userMessage
-          });
-        }
-        await this.#config.history.addMessage({
-          id: v72(),
-          chatId: params.chatId,
-          role: responseMessage.role,
-          content: responseMessage
-        });
-      }
-    });
+    return this.#createUIMessageStream(
+      result,
+      messages,
+      params,
+      originalMessage
+    );
   }
   /**
    * Chat1 - Combined tool, no peek.
@@ -2484,7 +3064,7 @@ var Text2Sql = class {
       chat1Agent.clone({
         model: this.#config.model,
         tools: {
-          ...tools2,
+          ...tools4,
           ...this.#config.memory ? memoryTools : {},
           ...this.#config.tools
         }
@@ -2493,11 +3073,6 @@ var Text2Sql = class {
       {
         teachings: toInstructions(
           "instructions",
-          persona({
-            name: "Freya",
-            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
-            tone: "Your tone should be concise and business-friendly."
-          }),
           ...instructions,
           teachable("user_profile", ...userTeachables)
         ),
@@ -2555,7 +3130,7 @@ var Text2Sql = class {
       chat2Agent.clone({
         model: this.#config.model,
         tools: {
-          ...tools3,
+          ...tools5,
           ...this.#config.memory ? memoryTools : {},
           ...this.#config.tools
         }
@@ -2564,11 +3139,6 @@ var Text2Sql = class {
       {
         teachings: toInstructions(
           "instructions",
-          persona({
-            name: "Freya",
-            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
-            tone: "Your tone should be concise and business-friendly."
-          }),
           ...instructions,
           teachable("user_profile", ...userTeachables)
         ),
@@ -2625,7 +3195,7 @@ var Text2Sql = class {
       chat3Agent.clone({
         model: this.#config.model,
         tools: {
-          ...tools4,
+          ...tools6,
           ...this.#config.memory ? memoryTools : {},
           ...this.#config.tools
         }
@@ -2634,11 +3204,6 @@ var Text2Sql = class {
       {
         teachings: toInstructions(
           "instructions",
-          persona({
-            name: "Freya",
-            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
-            tone: "Your tone should be concise and business-friendly."
-          }),
           ...instructions,
           teachable("user_profile", ...userTeachables)
         ),
@@ -2698,7 +3263,7 @@ var Text2Sql = class {
       chat4Agent.clone({
         model: this.#config.model,
         tools: {
-          ...tools5,
+          ...tools7,
           ...this.#config.memory ? memoryTools : {},
           ...this.#config.tools
         }
@@ -2707,11 +3272,6 @@ var Text2Sql = class {
       {
         teachings: toInstructions(
           "instructions",
-          persona({
-            name: "Freya",
-            role: "You are an expert SQL query generator, answering business questions with accurate queries.",
-            tone: "Your tone should be concise and business-friendly."
-          }),
           ...instructions,
           teachable("user_profile", ...userTeachables)
         ),
@@ -2729,10 +3289,117 @@ var Text2Sql = class {
       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, originalMessage) {
+  #createUIMessageStream(result, messages, params, originalMessages) {
     return result.toUIMessageStream({
       onError: (error) => {
         if (NoSuchToolError.isInstance(error)) {
@@ -2749,7 +3416,7 @@ var Text2Sql = class {
       sendFinish: true,
       sendReasoning: true,
       sendSources: true,
-      originalMessages: originalMessage,
+      originalMessages,
       generateMessageId: generateId,
       onFinish: async ({ responseMessage, isContinuation }) => {
         const userMessage = messages.at(-1);
@@ -2789,6 +3456,7 @@ export {
   TeachablesStore,
   Text2Sql,
   applyTablesFilter,
+  developerAgent,
   filterRelationshipsByTables,
   filterTablesByName,
   getTablesWithRelated,