@deepagents/text2sql 0.3.1 → 0.6.0

package/dist/lib/synthesis/index.js

@@ -0,0 +1,2069 @@
+// packages/text2sql/src/lib/synthesis/types.ts
+var PairProducer = class {
+  from(producer) {
+    return Array.isArray(producer) ? (async function* (pairs) {
+      yield pairs;
+    })(producer) : producer.produce();
+  }
+  toPairs() {
+    return toPairs(this);
+  }
+};
+async function toPairs(producer) {
+  const pairs = [];
+  for await (const chunk of producer.produce()) {
+    pairs.push(...chunk);
+  }
+  return pairs;
+}
+
+// packages/text2sql/src/lib/synthesis/decorators/filtered-producer.ts
+var FilteredProducer = class extends PairProducer {
+  /**
+   * @param producer - Source producer to filter
+   * @param options - Filter configuration
+   */
+  constructor(producer, options = {}) {
+    super();
+    this.producer = producer;
+    this.options = options;
+  }
+  /**
+   * Produces pairs filtered by success status, table usage, and custom predicates.
+   * @returns Pairs matching all configured filter criteria
+   */
+  async *produce() {
+    for await (const chunk of this.producer.produce()) {
+      const filtered = chunk.filter((pair) => {
+        if (this.options.successOnly !== false && !pair.success) {
+          return false;
+        }
+        if (this.options.tables?.length) {
+          const sqlLower = pair.sql.toLowerCase();
+          const hasTable = this.options.tables.some(
+            (t) => sqlLower.includes(t.toLowerCase())
+          );
+          if (!hasTable) return false;
+        }
+        if (this.options.filter && !this.options.filter(pair)) {
+          return false;
+        }
+        return true;
+      });
+      if (filtered.length) {
+        yield filtered;
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/decorators/deduplicated-producer.ts
+var DeduplicatedProducer = class extends PairProducer {
+  /**
+   * @param producer - Source producer to deduplicate
+   * @param options - Deduplication configuration
+   */
+  constructor(producer, options = {}) {
+    super();
+    this.producer = producer;
+    this.options = options;
+  }
+  /**
+   * Produces pairs with duplicates removed based on the configured strategy.
+   * @returns Unique pairs after deduplication
+   */
+  async *produce() {
+    const { strategy = "exact" } = this.options;
+    const seen = /* @__PURE__ */ new Set();
+    for await (const chunk of this.producer.produce()) {
+      const unique = [];
+      for (const pair of chunk) {
+        let key;
+        switch (strategy) {
+          case "sql-only":
+            key = this.normalizeSQL(pair.sql);
+            break;
+          case "question-only":
+            key = pair.question.toLowerCase().trim();
+            break;
+          case "exact":
+          default:
+            key = `${pair.question.toLowerCase().trim()}|||${this.normalizeSQL(pair.sql)}`;
+        }
+        if (!seen.has(key)) {
+          seen.add(key);
+          unique.push(pair);
+        }
+      }
+      if (unique.length) {
+        yield unique;
+      }
+    }
+  }
+  normalizeSQL(sql) {
+    return sql.toLowerCase().replace(/\s+/g, " ").trim();
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/decorators/validated-producer.ts
+var ValidatedProducer = class extends PairProducer {
+  /**
+   * @param producer - Source producer to validate
+   * @param adapter - Database adapter for SQL validation
+   * @param options - Validation configuration
+   */
+  constructor(producer, adapter, options = {}) {
+    super();
+    this.producer = producer;
+    this.adapter = adapter;
+    this.options = options;
+  }
+  /**
+   * Produces pairs with SQL validation applied, optionally executing queries.
+   * @returns Validated pairs with error/rowCount metadata attached
+   */
+  async *produce() {
+    for await (const chunk of this.producer.produce()) {
+      const validated = [];
+      for (const pair of chunk) {
+        const error = await this.adapter.validate(pair.sql);
+        if (error) {
+          if (!this.options.removeInvalid) {
+            validated.push({
+              ...pair,
+              success: false,
+              error
+            });
+          }
+          continue;
+        }
+        let rowCount;
+        if (this.options.execute) {
+          try {
+            const result = await this.adapter.execute(pair.sql);
+            rowCount = Array.isArray(result) ? result.length : void 0;
+          } catch {
+          }
+        }
+        validated.push({
+          ...pair,
+          success: true,
+          rowCount
+        });
+      }
+      if (validated.length) {
+        yield validated;
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/message-extractor.ts
+import {
+  getToolOrDynamicToolName as getToolOrDynamicToolName2,
+  isToolOrDynamicToolUIPart as isToolOrDynamicToolUIPart2
+} from "ai";
+
+// packages/text2sql/src/lib/synthesis/extractors/base-contextual-extractor.ts
+import { groq } from "@ai-sdk/groq";
+import {
+  getToolOrDynamicToolName,
+  isTextUIPart,
+  isToolOrDynamicToolUIPart
+} from "ai";
+import dedent from "dedent";
+import z from "zod";
+import { agent, generate, user } from "@deepagents/agent";
+var contextResolverAgent = agent({
+  name: "context_resolver",
+  model: groq("openai/gpt-oss-20b"),
+  output: z.object({
+    question: z.string().describe(
+      "A standalone natural language question that the SQL query answers"
+    )
+  }),
+  prompt: (state) => dedent`
+    <identity>
+      You are an expert at understanding conversational context and generating clear,
+      standalone questions from multi-turn conversations.
+    </identity>
+
+    ${state?.introspection ? `<schema>
+${state.introspection}
+</schema>` : ""}
+
+    <conversation>
+    ${state?.conversation}
+    </conversation>
+
+    <sql>
+    ${state?.sql}
+    </sql>
+
+    <task>
+      Given the conversation above and the SQL query that was executed,
+      generate a single, standalone natural language question that:
+      1. Fully captures the user's intent without needing prior context
+      2. Uses natural business language (not SQL terminology)
+      3. Could be asked by someone who hasn't seen the conversation
+      4. Accurately represents what the SQL query answers
+    </task>
+
+    <examples>
+      Conversation: "Show me customers" → "Filter to NY" → "Sort by revenue"
+      SQL: SELECT * FROM customers WHERE region = 'NY' ORDER BY revenue DESC
+      Question: "Show me customers in the NY region sorted by revenue"
+
+      Conversation: "What were sales last month?" → "Break it down by category"
+      SQL: SELECT category, SUM(amount) FROM sales WHERE date >= '2024-11-01' GROUP BY category
+      Question: "What were sales by category for last month?"
+    </examples>
+  `
+});
+function getMessageText(message) {
+  const textParts = message.parts.filter(isTextUIPart).map((part) => part.text);
+  return textParts.join(" ").trim();
+}
+function formatConversation(messages) {
+  return messages.map((msg, i) => `[${i + 1}] ${msg}`).join("\n");
+}
+var BaseContextualExtractor = class extends PairProducer {
+  constructor(messages, adapter, options = {}) {
+    super();
+    this.messages = messages;
+    this.adapter = adapter;
+    this.options = options;
+  }
+  context = [];
+  results = [];
+  /**
+   * Template method - defines the extraction algorithm skeleton.
+   * Subclasses customize behavior via hooks, not by overriding this method.
+   */
+  async *produce() {
+    this.context = [];
+    this.results = [];
+    const { includeFailures = false, toolName = "db_query" } = this.options;
+    await this.extractSqlsWithContext(toolName, includeFailures);
+    if (this.results.length === 0) {
+      return;
+    }
+    const introspection = await this.adapter.introspect();
+    yield* this.resolveQuestions(introspection);
+  }
+  /**
+   * Core extraction loop - iterates through messages and calls hooks.
+   */
+  async extractSqlsWithContext(toolName, includeFailures) {
+    for (const message of this.messages) {
+      if (message.role === "user") {
+        const text = getMessageText(message);
+        if (text) {
+          await this.onUserMessage(text);
+        }
+        continue;
+      }
+      if (message.role === "assistant") {
+        await this.extractFromAssistant(message, toolName, includeFailures);
+      }
+    }
+  }
+  /**
+   * Extract SQL from assistant message parts.
+   */
+  async extractFromAssistant(message, toolName, includeFailures) {
+    for (const part of message.parts) {
+      if (!isToolOrDynamicToolUIPart(part)) {
+        continue;
+      }
+      if (getToolOrDynamicToolName(part) !== toolName) {
+        continue;
+      }
+      const toolInput = "input" in part ? part.input : void 0;
+      if (!toolInput?.sql) {
+        continue;
+      }
+      const success = part.state === "output-available";
+      const failed = part.state === "output-error";
+      if (failed && !includeFailures) {
+        continue;
+      }
+      if (!success && !failed) {
+        continue;
+      }
+      const snapshot = this.getContextSnapshot();
+      if (snapshot.length === 0) {
+        continue;
+      }
+      this.results.push({
+        sql: toolInput.sql,
+        success,
+        conversationContext: snapshot
+      });
+    }
+    const assistantText = getMessageText(message);
+    if (assistantText) {
+      this.context.push(`Assistant: ${assistantText}`);
+    }
+  }
+  /**
+   * Resolve extracted SQL contexts into standalone questions using LLM.
+   */
+  async *resolveQuestions(introspection) {
+    for (const item of this.results) {
+      const { experimental_output } = await generate(
+        contextResolverAgent,
+        [user("Generate a standalone question for this SQL query.")],
+        {
+          conversation: formatConversation(item.conversationContext),
+          sql: item.sql,
+          introspection
+        }
+      );
+      yield [
+        {
+          question: experimental_output.question,
+          sql: item.sql,
+          context: item.conversationContext,
+          success: item.success
+        }
+      ];
+    }
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/message-extractor.ts
+var MessageExtractor = class extends PairProducer {
+  /**
+   * @param messages - Chat history to extract pairs from
+   * @param options - Extraction configuration
+   */
+  constructor(messages, options = {}) {
+    super();
+    this.messages = messages;
+    this.options = options;
+  }
+  /**
+   * Extracts question-SQL pairs by parsing tool calls and pairing with user messages.
+   * @returns Pairs extracted from db_query tool invocations
+   */
+  async *produce() {
+    const { includeFailures = false, toolName = "db_query" } = this.options;
+    let lastUserMessage = null;
+    for (const message of this.messages) {
+      if (message.role === "user") {
+        lastUserMessage = message;
+        continue;
+      }
+      if (message.role === "assistant" && lastUserMessage) {
+        for (const part of message.parts) {
+          if (!isToolOrDynamicToolUIPart2(part)) {
+            continue;
+          }
+          if (getToolOrDynamicToolName2(part) !== toolName) {
+            continue;
+          }
+          const toolInput = "input" in part ? part.input : void 0;
+          if (!toolInput?.sql) {
+            continue;
+          }
+          const success = part.state === "output-available";
+          const failed = part.state === "output-error";
+          if (failed && !includeFailures) {
+            continue;
+          }
+          if (!success && !failed) {
+            continue;
+          }
+          const question = getMessageText(lastUserMessage);
+          if (!question) {
+            continue;
+          }
+          yield [
+            {
+              question,
+              sql: toolInput.sql,
+              success
+            }
+          ];
+        }
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/sql-extractor.ts
+import { groq as groq2 } from "@ai-sdk/groq";
+import dedent2 from "dedent";
+import z2 from "zod";
+import { agent as agent2, generate as generate2, user as user2 } from "@deepagents/agent";
+var sqlToQuestionAgent = agent2({
+  name: "sql_to_question",
+  model: groq2("llama-3.3-70b-versatile"),
+  output: z2.object({
+    question: z2.string().describe("A natural language question that the SQL query answers")
+  }),
+  prompt: (state) => dedent2`
+    <identity>
+      You are an expert at understanding SQL queries and generating clear,
+      natural language questions that describe what the query retrieves.
+    </identity>
+
+    <schema>
+    ${state?.introspection}
+    </schema>
+
+    <sql>
+    ${state?.sql}
+    </sql>
+
+    <task>
+      Given the database schema and the SQL query above, generate a single
+      natural language question that:
+      1. Accurately describes what information the query retrieves
+      2. Uses natural business language (not SQL terminology)
+      3. Could be asked by a non-technical user
+      4. Is concise but complete
+    </task>
+
+    <examples>
+      SQL: SELECT COUNT(*) FROM customers WHERE region = 'NY'
+      Question: "How many customers do we have in New York?"
+
+      SQL: SELECT product_name, SUM(quantity) as total FROM orders GROUP BY product_name ORDER BY total DESC LIMIT 10
+      Question: "What are our top 10 products by quantity sold?"
+
+      SQL: SELECT c.name, COUNT(o.id) FROM customers c LEFT JOIN orders o ON c.id = o.customer_id GROUP BY c.id HAVING COUNT(o.id) = 0
+      Question: "Which customers have never placed an order?"
+    </examples>
+  `
+});
+var SqlExtractor = class extends PairProducer {
+  #sqls;
+  #adapter;
+  #options;
+  /**
+   * @param sql - SQL query or queries to generate questions for
+   * @param adapter - Database adapter for validation and schema introspection
+   * @param options - Extraction configuration
+   */
+  constructor(sql, adapter, options = {}) {
+    super();
+    this.#sqls = Array.isArray(sql) ? sql : [sql];
+    this.#adapter = adapter;
+    this.#options = options;
+  }
+  /**
+   * Generates natural language questions for each SQL query using an LLM.
+   * @returns Pairs with generated questions and original SQL
+   */
+  async *produce() {
+    const { validateSql = true, skipInvalid = false } = this.#options;
+    const introspection = await this.#adapter.introspect();
+    for (const sql of this.#sqls) {
+      let isValid = true;
+      if (validateSql) {
+        const error = await this.#adapter.validate(sql);
+        isValid = error === void 0 || error === null;
+        if (!isValid && skipInvalid) {
+          continue;
+        }
+      }
+      const { experimental_output } = await generate2(
+        sqlToQuestionAgent,
+        [user2("Generate a natural language question for this SQL query.")],
+        {
+          sql,
+          introspection
+        }
+      );
+      yield [
+        {
+          question: experimental_output.question,
+          sql,
+          success: isValid
+        }
+      ];
+    }
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/full-context-extractor.ts
+var FullContextExtractor = class extends BaseContextualExtractor {
+  constructor(messages, adapter, options = {}) {
+    super(messages, adapter, options);
+  }
+  /**
+   * Add user message to context (keeps all messages).
+   */
+  async onUserMessage(text) {
+    this.context.push(`User: ${text}`);
+  }
+  /**
+   * Return all context accumulated so far.
+   */
+  getContextSnapshot() {
+    return [...this.context];
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/windowed-context-extractor.ts
+var WindowedContextExtractor = class extends BaseContextualExtractor {
+  windowSize;
+  constructor(messages, adapter, options) {
+    super(messages, adapter, options);
+    this.windowSize = options.windowSize;
+  }
+  /**
+   * Add user message to context (keeps all, windowing happens on snapshot).
+   */
+  async onUserMessage(text) {
+    this.context.push(`User: ${text}`);
+  }
+  /**
+   * Return only the last N messages based on window size.
+   */
+  getContextSnapshot() {
+    if (this.context.length <= this.windowSize) {
+      return [...this.context];
+    }
+    return this.context.slice(-this.windowSize);
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/segmented-context-extractor.ts
+import { groq as groq3 } from "@ai-sdk/groq";
+import dedent3 from "dedent";
+import z3 from "zod";
+import { agent as agent3, generate as generate3, user as user3 } from "@deepagents/agent";
+var topicChangeAgent = agent3({
+  name: "topic_change_detector",
+  model: groq3("openai/gpt-oss-20b"),
+  output: z3.object({
+    isTopicChange: z3.boolean().describe("Whether the new message represents a topic change"),
+    reason: z3.string().describe("Brief explanation for the decision")
+  }),
+  prompt: (state) => dedent3`
+    <identity>
+      You are an expert at understanding conversational flow and detecting topic changes.
+    </identity>
+
+    <conversation_context>
+    ${state?.context || "(no prior context)"}
+    </conversation_context>
+
+    <new_message>
+    ${state?.newMessage}
+    </new_message>
+
+    <task>
+      Determine if the new message represents a significant topic change from the
+      prior conversation context. A topic change occurs when:
+      1. The user asks about a completely different entity/table/domain
+      2. The user starts a new analytical question unrelated to prior discussion
+      3. There's a clear shift in what data or metrics are being discussed
+
+      NOT a topic change:
+      - Follow-up questions refining the same query ("filter by...", "sort by...")
+      - Questions about the same entities with different conditions
+      - Requests for more details on the same topic
+    </task>
+
+    <examples>
+      Context: "Show me customers in NY" → "Sort by revenue"
+      New: "Filter to those with orders over $1000"
+      Decision: NOT a topic change (still refining customer query)
+
+      Context: "Show me customers in NY" → "Sort by revenue"
+      New: "What were our total sales last quarter?"
+      Decision: Topic change (shifted from customers to sales metrics)
+
+      Context: "List all products"
+      New: "How many orders did we have last month?"
+      Decision: Topic change (products → orders/sales)
+    </examples>
+  `
+});
+var SegmentedContextExtractor = class extends BaseContextualExtractor {
+  constructor(messages, adapter, options = {}) {
+    super(messages, adapter, options);
+  }
+  /**
+   * Handle user message with topic change detection.
+   * If topic changes, resolve the message to standalone form before resetting.
+   *
+   * Note: We capture context snapshot before async LLM calls to prevent race conditions
+   * where context might be modified during the async operation.
+   */
+  async onUserMessage(text) {
+    if (this.context.length >= 2) {
+      const contextSnapshot = [...this.context];
+      const isTopicChange = await this.detectTopicChange(text, contextSnapshot);
+      if (isTopicChange) {
+        const resolved = await this.resolveToStandalone(text, contextSnapshot);
+        this.context = [`User: ${resolved}`];
+        return;
+      }
+    }
+    this.context.push(`User: ${text}`);
+  }
+  /**
+   * Return all context in current topic segment.
+   */
+  getContextSnapshot() {
+    return [...this.context];
+  }
+  /**
+   * Detect if a new message represents a topic change using LLM.
+   * @param newMessage - The new user message to check
+   * @param contextSnapshot - Snapshot of context captured before this async call
+   */
+  async detectTopicChange(newMessage, contextSnapshot) {
+    const { experimental_output } = await generate3(
+      topicChangeAgent,
+      [user3("Determine if this is a topic change.")],
+      {
+        context: formatConversation(contextSnapshot),
+        newMessage
+      }
+    );
+    return experimental_output.isTopicChange;
+  }
+  /**
+   * Resolve a context-dependent message into a standalone question.
+   * Called when topic change is detected to preserve the meaning of
+   * the triggering message before context is reset.
+   * @param text - The user message to resolve
+   * @param contextSnapshot - Snapshot of context captured before this async call
+   */
+  async resolveToStandalone(text, contextSnapshot) {
+    const { experimental_output } = await generate3(
+      contextResolverAgent,
+      [user3("Generate a standalone question for this message.")],
+      {
+        conversation: formatConversation([...contextSnapshot, `User: ${text}`]),
+        sql: ""
+        // No SQL yet, just resolving the question
+      }
+    );
+    return experimental_output.question;
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/extractors/last-query-extractor.ts
+import { generate as generate4, user as user4 } from "@deepagents/agent";
+var LastQueryExtractor = class extends BaseContextualExtractor {
+  constructor(messages, adapter, options = {}) {
+    super(messages, adapter, options);
+  }
+  /**
+   * Add user message to context (keeps all messages).
+   */
+  async onUserMessage(text) {
+    this.context.push(`User: ${text}`);
+  }
+  /**
+   * Return all context accumulated so far.
+   */
+  getContextSnapshot() {
+    return [...this.context];
+  }
+  /**
+   * Override to only resolve the LAST query instead of all queries.
+   */
+  async *resolveQuestions(introspection) {
+    if (this.results.length === 0) {
+      return;
+    }
+    const last = this.results.at(-1);
+    const { experimental_output } = await generate4(
+      contextResolverAgent,
+      [user4("Generate a standalone question for this SQL query.")],
+      {
+        conversation: formatConversation(last.conversationContext),
+        sql: last.sql,
+        introspection
+      }
+    );
+    yield [
+      {
+        question: experimental_output.question,
+        sql: last.sql,
+        context: last.conversationContext,
+        success: last.success
+      }
+    ];
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/synthesizers/schema-synthesizer.ts
+import pLimit from "p-limit";
+
+// packages/text2sql/src/lib/agents/question.agent.ts
+import { groq as groq4 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware, wrapLanguageModel } from "ai";
+import dedent4 from "dedent";
+import z4 from "zod";
+import { agent as agent4, generate as generate5, user as user5 } from "@deepagents/agent";
+var complexityInstructions = {
+  low: dedent4`
+    Generate simple questions that require:
+    - Basic SELECT with single table
+    - Simple WHERE clauses with one condition
+    - COUNT(*) or basic aggregations
+    - No joins required
+    Examples: "How many customers do we have?", "List all products", "What is the total revenue?"
+  `,
+  medium: dedent4`
+    Generate moderate questions that require:
+    - JOINs between 2-3 tables
+    - Multiple WHERE conditions (AND/OR)
+    - GROUP BY with HAVING clauses
+    - ORDER BY with LIMIT
+    - Basic subqueries
+    Examples: "What are the top 5 customers by total orders?", "Which products have never been ordered?"
+  `,
+  hard: dedent4`
+    Generate complex questions that require:
+    - Multiple JOINs (3+ tables)
+    - Nested subqueries or CTEs
+    - Complex aggregations with multiple GROUP BY columns
+    - CASE expressions
+    - Date/time calculations
+    Examples: "What is the month-over-month growth rate?", "Which customers have increased spending compared to last year?"
+  `,
+  window: dedent4`
+    Generate advanced questions that require window functions:
+    - ROW_NUMBER, RANK, DENSE_RANK
+    - LAG, LEAD for comparisons
+    - Running totals (SUM OVER)
+    - Moving averages
+    - PARTITION BY clauses
+    Examples: "What is the running total of sales per month?", "Rank customers by their purchase frequency within each region"
+  `
+};
+var questionGeneratorAgent = agent4({
+  name: "question_generator",
+  model: wrapLanguageModel({
+    model: groq4("openai/gpt-oss-20b"),
+    middleware: defaultSettingsMiddleware({
+      settings: { temperature: 0.8, topP: 0.95 }
+    })
+  }),
+  handoffDescription: "Generates natural language questions that users might ask about the database schema.",
+  output: z4.object({
+    questions: z4.array(z4.string().describe("A natural language question about the data")).min(1).describe("List of natural language questions a user might ask")
+  }),
+  prompt: (state) => {
+    const count = state?.count;
+    const complexity = state?.complexity ?? "medium";
+    return dedent4`
+      <identity>
+        You are a synthetic data generator specializing in creating realistic natural language questions
+        that users might ask about a database. You understand database schemas and can generate diverse,
+        practical questions that would require SQL queries to answer.
+      </identity>
+
+      ${state?.introspection || ""}
+
+      <complexity level="${complexity}">
+        ${complexityInstructions[complexity]}
+      </complexity>
+
+      <task>
+        Generate exactly ${count} natural language questions at the "${complexity}" complexity level.
+        The questions should:
+        1. Match the complexity requirements above
+        2. Use natural business language, not technical SQL terms
+        3. Be realistic questions a non-technical user would actually ask
+        4. Cover different tables and relationships when possible
+      </task>
+
+      <guardrails>
+        - Questions MUST ONLY reference tables and columns that exist in the schema above
+        - Before generating each question, verify that ALL entities (tables, columns, relationships) you reference are explicitly listed in the schema
+        - DO NOT invent or assume tables/columns that aren't explicitly shown in the schema
+        - Use natural language without SQL keywords like SELECT, WHERE, etc.
+        - All questions must match the specified complexity level
+      </guardrails>
+    `;
+  }
+});
+async function generateQuestions(params) {
+  const { introspection, complexity, count, prompt, model } = params;
+  const agentInstance = model ? questionGeneratorAgent.clone({ model }) : questionGeneratorAgent;
+  const userPrompt = prompt ?? `Generate ${count} questions at ${complexity} complexity given db schema.`;
+  const { experimental_output } = await generate5(agentInstance, [user5(userPrompt)], {
+    introspection,
+    complexity,
+    count
+  });
+  return { questions: experimental_output.questions };
+}
+
+// packages/text2sql/src/lib/agents/sql.agent.ts
+import { groq as groq5 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware2, wrapLanguageModel as wrapLanguageModel2 } from "ai";
+import z5 from "zod";
+import { agent as agent5, generate as generate6, user as user6 } from "@deepagents/agent";
+
+// packages/text2sql/src/lib/teach/xml.ts
+function wrapBlock(tag, children) {
+  const content = children.filter((child) => Boolean(child)).join("\n");
+  if (!content) {
+    return "";
+  }
+  return `<${tag}>
+${indentBlock(content, 2)}
+</${tag}>`;
+}
+function list(tag, values, childTag) {
+  if (!values.length) {
+    return "";
+  }
+  const children = values.map((value) => leaf(childTag, value)).join("\n");
+  return `<${tag}>
+${indentBlock(children, 2)}
+</${tag}>`;
+}
+function leaf(tag, value) {
+  const safe = escapeXml(value);
+  if (safe.includes("\n")) {
+    return `<${tag}>
+${indentBlock(safe, 2)}
+</${tag}>`;
+  }
+  return `<${tag}>${safe}</${tag}>`;
+}
+function indentBlock(text, spaces) {
+  if (!text.trim()) {
+    return "";
+  }
+  const padding = " ".repeat(spaces);
+  return text.split("\n").map((line) => line.length ? padding + line : padding).join("\n");
+}
+function escapeXml(value) {
+  if (value == null) {
+    return "";
+  }
+  return value.replaceAll(/&/g, "&amp;").replaceAll(/</g, "&lt;").replaceAll(/>/g, "&gt;").replaceAll(/"/g, "&quot;").replaceAll(/'/g, "&apos;");
+}
+
+// packages/text2sql/src/lib/teach/teachables.ts
+function term(name, definition) {
+  return {
+    type: "term",
+    encode: () => ({ type: "term", name, definition }),
+    decode: () => wrapBlock("term", [leaf("name", name), leaf("definition", definition)])
+  };
+}
+function hint(text) {
+  return {
+    type: "hint",
+    encode: () => ({ type: "hint", text }),
+    decode: () => leaf("hint", text)
+  };
+}
+function guardrail(input) {
+  const { rule, reason, action } = input;
+  return {
+    type: "guardrail",
+    encode: () => ({ type: "guardrail", rule, reason, action }),
+    decode: () => wrapBlock("guardrail", [
+      leaf("rule", rule),
+      reason ? leaf("reason", reason) : "",
+      action ? leaf("action", action) : ""
+    ])
+  };
+}
+function explain(input) {
+  const { concept, explanation, therefore } = input;
+  return {
+    type: "explain",
+    encode: () => ({ type: "explain", concept, explanation, therefore }),
+    decode: () => wrapBlock("explanation", [
+      leaf("concept", concept),
+      leaf("details", explanation),
+      therefore ? leaf("therefore", therefore) : ""
+    ])
+  };
+}
+function example(input) {
+  const { question, answer, note } = input;
+  return {
+    type: "example",
+    encode: () => ({ type: "example", question, answer, note }),
+    decode: () => wrapBlock("example", [
+      leaf("question", question),
+      leaf("answer", answer),
+      note ? leaf("note", note) : ""
+    ])
+  };
+}
+function clarification(input) {
+  const { when, ask, reason } = input;
+  return {
+    type: "clarification",
+    encode: () => ({ type: "clarification", when, ask, reason }),
+    decode: () => wrapBlock("clarification", [
+      leaf("when", when),
+      leaf("ask", ask),
+      leaf("reason", reason)
+    ])
+  };
+}
+function workflow(input) {
+  const { task, steps, triggers, notes } = input;
+  return {
+    type: "workflow",
+    encode: () => ({ type: "workflow", task, steps, triggers, notes }),
+    decode: () => wrapBlock("workflow", [
+      leaf("task", task),
+      triggers?.length ? list("triggers", triggers, "trigger") : "",
+      list("steps", steps, "step"),
+      notes ? leaf("notes", notes) : ""
+    ])
+  };
+}
+function quirk(input) {
+  const { issue, workaround } = input;
+  return {
+    type: "quirk",
+    encode: () => ({ type: "quirk", issue, workaround }),
+    decode: () => wrapBlock("quirk", [
+      leaf("issue", issue),
+      leaf("workaround", workaround)
+    ])
+  };
+}
+function styleGuide(input) {
+  const { prefer, never, always } = input;
+  return {
+    type: "styleGuide",
+    encode: () => ({ type: "styleGuide", prefer, never, always }),
+    decode: () => wrapBlock("style_guide", [
+      leaf("prefer", prefer),
+      always ? leaf("always", always) : "",
+      never ? leaf("never", never) : ""
+    ])
+  };
+}
+function analogy(input) {
+  const { concept, relationship, insight, therefore, pitfall } = input;
+  return {
+    type: "analogy",
+    encode: () => ({
+      type: "analogy",
+      concept,
+      relationship,
+      insight,
+      therefore,
+      pitfall
+    }),
+    decode: () => wrapBlock("analogy", [
+      list("concepts", concept, "concept"),
+      leaf("relationship", relationship),
+      insight ? leaf("insight", insight) : "",
+      therefore ? leaf("therefore", therefore) : "",
+      pitfall ? leaf("pitfall", pitfall) : ""
+    ])
+  };
+}
+function glossary(entries) {
+  return {
+    type: "glossary",
+    encode: () => ({ type: "glossary", entries }),
+    decode: () => wrapBlock(
+      "glossary",
+      Object.entries(entries).map(
+        ([term2, sql]) => wrapBlock("entry", [leaf("term", term2), leaf("sql", sql)])
+      )
+    )
+  };
+}
+function identity(input) {
+  const { name, role } = input;
+  return {
+    type: "identity",
+    encode: () => ({ type: "identity", name, role }),
+    decode: () => wrapBlock("identity", [
+      name ? leaf("name", name) : "",
+      role ? leaf("role", role) : ""
+    ])
+  };
+}
+function persona(input) {
+  const { name, role, tone } = input;
+  return {
+    type: "persona",
+    encode: () => ({ type: "persona", name, role, tone: tone ?? "" }),
+    decode: () => wrapBlock("persona", [
+      leaf("name", name),
+      leaf("role", role),
+      tone ? leaf("tone", tone) : ""
+    ])
+  };
+}
+function alias(termName, meaning) {
+  return {
+    type: "alias",
+    encode: () => ({ type: "alias", term: termName, meaning }),
+    decode: () => wrapBlock("alias", [leaf("term", termName), leaf("meaning", meaning)])
+  };
+}
+function preference(aspect, value) {
+  return {
+    type: "preference",
+    encode: () => ({ type: "preference", aspect, value }),
+    decode: () => wrapBlock("preference", [leaf("aspect", aspect), leaf("value", value)])
+  };
+}
+function context(description) {
+  return {
+    type: "context",
+    encode: () => ({ type: "context", description }),
+    decode: () => leaf("context", description)
+  };
+}
+function correction(subject, clarification2) {
+  return {
+    type: "correction",
+    encode: () => ({ type: "correction", subject, clarification: clarification2 }),
+    decode: () => wrapBlock("correction", [
+      leaf("subject", subject),
+      leaf("clarification", clarification2)
+    ])
+  };
+}
+function toInstructions(tag, ...teachables) {
+  if (!teachables.length) {
+    return "";
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const teachable of teachables) {
+    const existing = grouped.get(teachable.type) ?? [];
+    existing.push(teachable);
+    grouped.set(teachable.type, existing);
+  }
+  const definedTypes = new Set(SECTION_ORDER.map((s) => s.type));
+  const sections = SECTION_ORDER.map(({ type, tag: tag2 }) => {
+    const items = grouped.get(type);
+    if (!items?.length) {
+      return "";
+    }
+    const renderedItems = items.map((item) => item.decode().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
+    if (!renderedItems.length) {
+      return "";
+    }
+    return `<${tag2}>
+${renderedItems}
+</${tag2}>`;
+  }).filter((section) => Boolean(section));
+  for (const [type, items] of grouped) {
+    if (definedTypes.has(type)) {
+      continue;
+    }
+    const renderedItems = items.map((item) => item.decode().trim()).filter(Boolean).map((item) => indentBlock(item, 2)).join("\n");
+    if (renderedItems.length) {
+      sections.push(renderedItems);
+    }
+  }
+  if (!sections.length) {
+    return "";
+  }
+  const content = indentBlock(sections.join("\n"), 2);
+  return `<${tag}>
+${content}
+</${tag}>`;
+}
+var SECTION_ORDER = [
+  // User context (render first - most important for personalization)
+  { type: "identity", tag: "identity" },
+  { type: "persona", tag: "persona" },
+  { type: "context", tag: "user_context" },
+  { type: "preference", tag: "user_preferences" },
+  { type: "alias", tag: "user_vocabulary" },
+  { type: "correction", tag: "user_corrections" },
+  // Domain knowledge
+  { type: "guardrail", tag: "guardrails" },
+  { type: "styleGuide", tag: "style_guides" },
+  { type: "hint", tag: "hints" },
+  { type: "clarification", tag: "clarifications" },
+  { type: "workflow", tag: "workflows" },
+  { type: "quirk", tag: "quirks" },
+  { type: "term", tag: "terminology" },
+  { type: "explain", tag: "explanations" },
+  { type: "analogy", tag: "analogies" },
+  { type: "glossary", tag: "glossary" },
+  { type: "example", tag: "examples" }
+];
+function toTeachables(generated) {
+  return generated.map((item) => {
+    switch (item.type) {
+      case "persona":
+        return persona({ name: item.name, role: item.role, tone: item.tone });
+      case "term":
+        return term(item.name, item.definition);
+      case "hint":
+        return hint(item.text);
+      case "guardrail":
+        return guardrail({
+          rule: item.rule,
+          reason: item.reason,
+          action: item.action
+        });
+      case "explain":
+        return explain({
+          concept: item.concept,
+          explanation: item.explanation,
+          therefore: item.therefore
+        });
+      case "example":
+        return example({
+          question: item.question,
+          answer: item.answer,
+          note: item.note
+        });
+      case "clarification":
+        return clarification({
+          when: item.when,
+          ask: item.ask,
+          reason: item.reason
+        });
+      case "workflow":
+        return workflow({
+          task: item.task,
+          steps: item.steps,
+          triggers: item.triggers,
+          notes: item.notes
+        });
+      case "quirk":
+        return quirk({
+          issue: item.issue,
+          workaround: item.workaround
+        });
+      case "styleGuide":
+        return styleGuide({
+          prefer: item.prefer,
+          never: item.never,
+          always: item.always
+        });
+      case "analogy":
+        return analogy({
+          concept: item.concept,
+          relationship: item.relationship,
+          insight: item.insight,
+          therefore: item.therefore,
+          pitfall: item.pitfall
+        });
+      case "glossary":
+        return glossary(item.entries);
+      // User-specific teachable types
+      case "identity":
+        return identity({ name: item.name, role: item.role });
+      case "alias":
+        return alias(item.term, item.meaning);
+      case "preference":
+        return preference(item.aspect, item.value);
+      case "context":
+        return context(item.description);
+      case "correction":
+        return correction(item.subject, item.clarification);
+    }
+  });
+}
+
+// packages/text2sql/src/lib/agents/sql.agent.ts
+var RETRY_TEMPERATURES = [0, 0.2, 0.3];
+var sqlQueryAgent = agent5({
+  name: "text2sql",
+  model: groq5("openai/gpt-oss-20b"),
+  logging: process.env.AGENT_LOGGING === "true",
+  output: z5.union([
+    z5.object({
+      sql: z5.string().describe("The SQL query that answers the question"),
+      reasoning: z5.string().optional().describe("The reasoning steps taken to generate the SQL")
+    }),
+    z5.object({
+      error: z5.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: wrapLanguageModel2({
+      model,
+      middleware: defaultSettingsMiddleware2({
+        settings: { temperature, topP: 1 }
+      })
+    })
+  });
+  const messages = previousError ? [
+    user6(input),
+    user6(
+      `<validation_error>Your previous SQL query had the following error: ${previousError}. Please fix the query.</validation_error>`
+    )
+  ] : [user6(input)];
+  try {
+    const { experimental_output: output } = await generate6(
+      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
+      }
+    );
+    if ("error" in output) {
+      return { success: false, error: output.error, isUnanswerable: true };
+    }
+    return { success: true, sql: extractSql(output.sql) };
+  } catch (error) {
+    if (error instanceof Error && (error.message.includes("Failed to validate JSON") || error.message.includes("response did not match schema"))) {
+      return {
+        success: false,
+        error: `Schema validation failed: ${error.message}`
+      };
+    }
+    throw error;
+  }
+}
+var sqlGenerators = {
+  generateSql
+};
+async function generateAndValidate(options, temperature, previousError) {
+  const result = await sqlGenerators.generateSql({
+    input: options.input,
+    model: options.model ?? sqlQueryAgent.model,
+    temperature,
+    introspection: options.introspection,
+    instructions: options.instructions,
+    previousError
+  });
+  if (!result.success) {
+    return {
+      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);
+  }
+  return { sql: "", attempts: maxRetries, errors };
+}
+
+// packages/text2sql/src/lib/synthesis/synthesizers/schema-synthesizer.ts
+var SchemaSynthesizer = class extends PairProducer {
+  /**
+   * @param adapter - Database adapter for schema introspection and SQL validation
+   * @param options - Synthesis configuration including count, complexity, and concurrency
+   */
+  constructor(adapter, options) {
+    super();
+    this.adapter = adapter;
+    this.options = options;
+    this.#complexities = Array.isArray(this.options.complexity) ? this.options.complexity : [this.options.complexity ?? "medium"];
+    this.#personas = this.options.personas ?? [void 0];
+    this.#limit = pLimit(this.options.concurrency ?? 5);
+  }
+  #complexities = [];
+  #personas = [];
+  #limit;
+  /**
+   * Generates question-SQL pairs by iterating through all persona × complexity combinations.
+   * Uses parallel processing bounded by the configured concurrency limit.
+   * Yields results as each combination completes (streaming pattern).
+   * @returns Generated pairs from all combinations
+   */
+  async *produce() {
+    const introspection = await this.adapter.introspect();
+    const combinations = this.#personas.flatMap(
+      (persona2) => this.#complexities.map((complexity) => ({ persona: persona2, complexity }))
+    );
+    for (const { persona: persona2, complexity } of combinations) {
+      const pairs = await this.#processCombination(
+        introspection,
+        persona2,
+        complexity
+      );
+      if (pairs.length) {
+        yield pairs;
+      }
+    }
+  }
+  /**
+   * Processes a single persona × complexity combination by generating questions
+   * and converting each to SQL in parallel.
+   */
+  async #processCombination(introspection, persona2, complexity) {
+    const personaContext = persona2 ? `As ${persona2.role}, ${persona2.perspective}
+
+Generate questions this persona would ask.` : void 0;
+    const prompt = personaContext ? `${personaContext}
+
+Generate ${this.options.count} questions at ${complexity} complexity.` : void 0;
+    const { questions } = await this.#limit(
+      () => generateQuestions({
+        introspection,
+        complexity,
+        count: this.options.count,
+        prompt,
+        model: this.options.model
+      })
+    );
+    const pairs = await Promise.all(
+      questions.map(async (question) => {
+        const result = await this.#limit(
+          () => toSql({
+            input: question,
+            adapter: this.adapter,
+            introspection,
+            instructions: this.options.teachings ?? [],
+            model: this.options.model
+          })
+        );
+        return {
+          question,
+          sql: result.sql,
+          success: !result.errors || result.errors.length === 0
+        };
+      })
+    );
+    return pairs;
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/synthesizers/breadth-evolver.ts
+import { groq as groq6 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware3, wrapLanguageModel as wrapLanguageModel3 } from "ai";
+import dedent5 from "dedent";
+import pLimit2 from "p-limit";
+import z6 from "zod";
+import { agent as agent6, generate as generate7, user as user7 } from "@deepagents/agent";
+
+// packages/text2sql/src/lib/synthesis/synthesizers/styles.ts
+var styleInstructions = {
+  formal: "Use professional business language, complete sentences, no slang",
+  colloquial: "Use casual everyday speech, contractions, informal tone",
+  imperative: 'Phrase as commands: "Show me...", "Get...", "List..."',
+  interrogative: 'Phrase as questions: "What is...", "How many...", "Which..."',
+  descriptive: "Use detailed, verbose phrasing with extra context",
+  concise: "Use minimal words, telegram-style brevity",
+  vague: "Be intentionally ambiguous, use hedging language",
+  metaphorical: "Use figurative language, analogies, creative phrasing",
+  conversational: "Chat-like tone, as if talking to a colleague"
+};
+var ALL_STYLES = [
+  "formal",
+  "colloquial",
+  "imperative",
+  "interrogative",
+  "descriptive",
+  "concise",
+  "vague",
+  "metaphorical",
+  "conversational"
+];
+
+// packages/text2sql/src/lib/synthesis/synthesizers/breadth-evolver.ts
+var paraphraserAgent = agent6({
+  name: "question_paraphraser",
+  model: wrapLanguageModel3({
+    model: groq6("openai/gpt-oss-20b"),
+    middleware: defaultSettingsMiddleware3({
+      settings: { temperature: 0.9, topP: 0.95, frequencyPenalty: 0.2 }
+    })
+  }),
+  logging: process.env.AGENT_LOGGING === "true",
+  output: z6.object({
+    paraphrases: z6.array(
+      z6.string().describe("A paraphrased version of the original question")
+    ).min(1).describe(
+      "List of paraphrased questions that would produce the same SQL"
+    )
+  }),
+  prompt: (state) => {
+    const personaInstruction = state?.persona ? dedent5`
+        <persona role="${state.persona.role}">
+          ${state.persona.perspective}
+
+          Paraphrase the question as this persona would naturally ask it.
+          Use their vocabulary, priorities, and framing style.
+        </persona>
+      ` : "";
+    const styleInstruction = state?.persona?.styles && state.persona.styles.length > 0 ? dedent5`
+        <communication_styles>
+          Generate paraphrases using these communication styles: ${state.persona.styles.join(", ")}
+
+          Style definitions:
+          ${state.persona.styles.map((s) => `- ${s}: ${styleInstructions[s]}`).join("\n")}
+
+          Distribute paraphrases across these styles for variety.
+        </communication_styles>
+      ` : "";
+    return dedent5`
+      <identity>
+        You are a linguistic expert specializing in paraphrasing database questions.
+        Your task is to generate alternative phrasings of questions that preserve
+        the exact same semantic meaning - they must all produce the identical SQL query.
+      </identity>
+
+      <original_question>
+        ${state?.question}
+      </original_question>
+
+      <reference_sql>
+        ${state?.sql}
+        (This SQL shows what the question is really asking - all paraphrases must ask for exactly this)
+      </reference_sql>
+
+      ${personaInstruction}
+
+      ${styleInstruction}
+
+      <task>
+        Generate exactly ${state?.count} paraphrased versions of the original question.
+
+        Requirements:
+        1. Each paraphrase must be semantically equivalent - it should produce the EXACT same SQL
+        2. Vary the sentence structure, word choice, and phrasing style
+        3. Use natural language without SQL keywords (SELECT, WHERE, JOIN, etc.)
+        4. Keep paraphrases realistic - how actual users would ask
+        5. Do not add or remove any conditions, filters, or requirements from the original
+        ${state?.persona?.styles?.length ? "6. Apply the specified communication styles to create diverse phrasings" : ""}
+      </task>
+
+      <guardrails>
+        - NEVER change what data is being requested
+        - NEVER add filters, aggregations, or conditions not in the original
+        - NEVER remove any specificity from the original question
+        - All paraphrases must be answerable by the exact same SQL query
+      </guardrails>
+    `;
+  }
+});
+var BreadthEvolver = class extends PairProducer {
+  /**
+   * @param source - Source pairs or producer to evolve
+   * @param options - Evolution options including count, persona, and concurrency
+   */
+  constructor(source, options) {
+    super();
+    this.source = source;
+    this.options = options;
+    this.#limit = pLimit2(this.options.concurrency ?? 4);
+  }
+  #limit;
+  /**
+   * Batch pairs within each chunk for concurrent processing.
+   * Uses pLimit for concurrency control, yields results per pair after chunk completes.
+   */
+  async *produce() {
+    for await (const chunk of this.from(this.source)) {
+      const tasks = chunk.map(
+        (pair) => this.#limit(async () => {
+          const { experimental_output } = await generate7(
+            paraphraserAgent.clone({ model: this.options.model }),
+            [
+              user7(
+                `Paraphrase this question ${this.options.count} times: "${pair.question}"`
+              )
+            ],
+            {
+              question: pair.question,
+              sql: pair.sql,
+              count: this.options.count,
+              persona: this.options.persona
+            }
+          );
+          return experimental_output.paraphrases.map((paraphrase) => ({
+            question: paraphrase,
+            sql: pair.sql,
+            context: pair.context,
+            success: pair.success
+          }));
+        })
+      );
+      const results = await Promise.all(tasks);
+      yield results.flat();
+    }
+  }
+};
+
+// packages/text2sql/src/lib/synthesis/synthesizers/depth-evolver.ts
+import { groq as groq7 } from "@ai-sdk/groq";
+import {
+  NoObjectGeneratedError,
+  NoOutputGeneratedError,
+  defaultSettingsMiddleware as defaultSettingsMiddleware4,
+  wrapLanguageModel as wrapLanguageModel4
+} from "ai";
+import dedent6 from "dedent";
+import pLimit3 from "p-limit";
+import pRetry from "p-retry";
+import z7 from "zod";
+import { agent as agent7, generate as generate8, user as user8 } from "@deepagents/agent";
+var techniqueInstructions = {
+  "add-aggregation": dedent6`
+    Add aggregation requirements to the question.
+    Transform it to require GROUP BY, COUNT, SUM, AVG, MIN, MAX, or similar operations.
+    Examples:
+    - "Show orders" → "Show total order count by customer"
+    - "List products" → "What is the average price per category?"
+    - "Get employees" → "How many employees are in each department?"
+  `,
+  "add-filter": dedent6`
+    Add filtering conditions to the question.
+    Transform it to require WHERE clauses with specific conditions.
+    Examples:
+    - "Show orders" → "Show orders from the last 30 days"
+    - "List customers" → "List customers who have made more than 5 purchases"
+    - "Get products" → "Get products with price above $100"
+  `,
+  "add-join": dedent6`
+    Add requirements that need data from related tables.
+    Transform it to require JOIN operations between multiple tables.
+    Examples:
+    - "Show orders" → "Show orders with customer names and addresses"
+    - "List products" → "List products with their supplier information"
+    - "Get employees" → "Get employees with their department and manager names"
+  `,
+  "add-reasoning": dedent6`
+    Add multi-step reasoning requirements.
+    Transform it to require logical deduction, comparisons, or derived calculations.
+    Examples:
+    - "Show orders" → "Which customers have orders above the average order value?"
+    - "List products" → "Which products are underperforming compared to their category average?"
+    - "Get revenue" → "Which month had the highest growth compared to the previous month?"
+  `,
+  hypothetical: dedent6`
+    Add a hypothetical or speculative scenario.
+    Transform it to require applying calculations or projections.
+    Examples:
+    - "Show revenue" → "What would revenue be if we increased all prices by 15%?"
+    - "List inventory" → "How many days of stock remain at current sales rate?"
+    - "Get costs" → "What would be the impact of a 10% discount on profit margins?"
+  `
+};
+var questionEvolverAgent = agent7({
+  name: "question_evolver",
+  model: wrapLanguageModel4({
+    model: groq7("openai/gpt-oss-20b"),
+    middleware: defaultSettingsMiddleware4({
+      settings: { temperature: 0.7, topP: 0.95 }
+    })
+  }),
+  output: z7.object({
+    evolvedQuestion: z7.string().describe("The evolved, more complex version of the original question")
+  }),
+  prompt: (state) => {
+    return dedent6`
+      <identity>
+        You are an expert at evolving simple database questions into more complex ones.
+        Your task is to take a basic question and transform it into a more sophisticated
+        version that requires advanced SQL techniques to answer.
+      </identity>
+
+      <original_question>
+        ${state?.question}
+      </original_question>
+
+      <original_sql>
+        ${state?.sql}
+        (This shows what the original question required)
+      </original_sql>
+
+      <database_schema>
+        ${state?.schema}
+      </database_schema>
+
+      <technique name="${state?.technique}">
+        ${state?.techniqueInstruction}
+      </technique>
+
+      <task>
+        Evolve the original question using the "${state?.technique}" technique.
+
+        Requirements:
+        1. The evolved question must be MORE COMPLEX than the original
+        2. Apply the specific technique described above
+        3. The evolved question must be answerable using the provided schema
+        4. Use natural language - no SQL keywords
+        5. Keep the question realistic and practical
+        6. The evolved question should build upon the original topic/domain
+      </task>
+
+      <guardrails>
+        - The evolved question MUST require more complex SQL than the original
+        - Do not ask for data that doesn't exist in the schema
+        - Keep the question grounded in the same domain as the original
+        - Make sure the question is clear and unambiguous
+      </guardrails>
+    `;
+  }
+});
+var ALL_TECHNIQUES = [
+  "add-aggregation",
+  "add-filter",
+  "add-join",
+  "add-reasoning",
+  "hypothetical"
+];
+var DepthEvolver = class extends PairProducer {
+  /**
+   * @param source - Source pairs or producer to evolve
+   * @param adapter - Database adapter for SQL generation
+   * @param options - Evolution options including techniques, count, and concurrency
+   */
+  constructor(source, adapter, options) {
+    super();
+    this.source = source;
+    this.adapter = adapter;
+    this.options = options;
+    this.#limit = pLimit3(this.options?.concurrency ?? 4);
+  }
+  #limit;
+  /**
+   * Yields evolved pairs as each completes (streaming pattern).
+   * Removes batch barrier - no longer waits for all evolutions before yielding.
+   */
+  async *produce() {
+    const introspection = await this.adapter.introspect();
+    const count = this.options?.count ?? 1;
+    const techniques = this.options?.techniques ?? ALL_TECHNIQUES;
+    let pairIndex = 0;
+    for await (const chunk of this.from(this.source)) {
+      for (const pair of chunk) {
+        const tasks = Array.from({ length: count }, (_, i) => {
+          const technique = this.options?.techniques ? techniques[i % techniques.length] : techniques[(pairIndex * count + i) % techniques.length];
+          return this.#limit(
+            () => this.#processTask(pair, technique, introspection)
+          );
+        });
+        const results = await Promise.all(tasks);
+        yield results;
+        pairIndex++;
+      }
+    }
+  }
+  async #processTask(pair, technique, introspection) {
+    const { experimental_output } = await withRetry(
+      () => generate8(
+        questionEvolverAgent.clone({
+          model: this.options?.model
+        }),
+        [user8(`Evolve this question using "${technique}": "${pair.question}"`)],
+        {
+          question: pair.question,
+          sql: pair.sql,
+          schema: introspection,
+          technique,
+          techniqueInstruction: techniqueInstructions[technique]
+        }
+      )
+    );
+    const evolvedQuestion = experimental_output.evolvedQuestion;
+    const sqlResult = await toSql({
+      input: evolvedQuestion,
+      adapter: this.adapter,
+      introspection,
+      instructions: [],
+      model: this.options?.model
+    });
+    return {
+      question: evolvedQuestion,
+      sql: sqlResult.sql,
+      context: pair.context,
+      success: !sqlResult.errors || sqlResult.errors.length === 0
+    };
+  }
+};
+async function withRetry(computation) {
+  return pRetry(computation, {
+    retries: 3,
+    shouldRetry: (context2) => {
+      return NoObjectGeneratedError.isInstance(context2.error) || NoOutputGeneratedError.isInstance(context2.error);
+    },
+    onFailedAttempt(context2) {
+      console.log(
+        `Attempt ${context2.attemptNumber} failed. There are ${context2.retriesLeft} retries left.`
+      );
+      console.error(context2.error);
+    }
+  });
+}
+
+// packages/text2sql/src/lib/synthesis/synthesizers/persona-generator.ts
+import { groq as groq8 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware5, wrapLanguageModel as wrapLanguageModel5 } from "ai";
+import dedent7 from "dedent";
+import z8 from "zod";
+import { agent as agent8, generate as generate9, user as user9 } from "@deepagents/agent";
+var personaGeneratorAgent = agent8({
+  name: "persona_generator",
+  model: wrapLanguageModel5({
+    model: groq8("openai/gpt-oss-20b"),
+    middleware: defaultSettingsMiddleware5({
+      settings: { temperature: 0.8, topP: 0.95, presencePenalty: 0.2 }
+    })
+  }),
+  logging: process.env.AGENT_LOGGING === "true",
+  output: z8.object({
+    personas: z8.array(
+      z8.object({
+        role: z8.string().describe("The job title or role of this persona"),
+        perspective: z8.string().describe(
+          "Rich description of what this persona cares about when querying the database"
+        ),
+        styles: z8.array(z8.enum(ALL_STYLES)).min(1).max(3).describe(
+          "Typical communication styles for this persona (1-3 styles)"
+        )
+      })
+    ).min(1).describe("List of personas who would query this database")
+  }),
+  prompt: (state) => {
+    return dedent7`
+      <identity>
+        You are an expert at understanding database schemas and inferring who would use them.
+        Your task is to analyze a database schema and generate realistic personas representing
+        the different types of users who would query this database.
+      </identity>
+
+      <database_schema>
+        ${state?.schema}
+      </database_schema>
+
+      <task>
+        Generate exactly ${state?.count} distinct personas who would query this database.
+
+        For each persona, provide:
+        1. **role**: Their job title or role (e.g., "Financial Analyst", "Customer Support Rep")
+        2. **perspective**: A rich description of what they care about, including:
+           - What questions they typically ask
+           - What metrics/data points matter to them
+           - How they prefer data formatted or presented
+           - Their priorities (speed vs accuracy, detail vs summary)
+           - Domain-specific concerns relevant to their role
+        3. **styles**: 1-3 communication styles typical for this persona. Choose from:
+           - formal: Professional business language, complete sentences
+           - colloquial: Casual everyday speech, contractions
+           - imperative: Commands like "Show me...", "Get...", "List..."
+           - interrogative: Questions like "What is...", "How many..."
+           - descriptive: Verbose, detailed phrasing
+           - concise: Brief, minimal words
+           - vague: Ambiguous, hedging language
+           - metaphorical: Figurative language, analogies
+           - conversational: Chat-like, casual tone
+
+        Requirements:
+        - Personas should be realistic for the given schema
+        - Each persona should have distinct concerns and priorities
+        - Perspectives should be detailed enough to guide question paraphrasing
+        - Cover different levels of technical expertise (some technical, some business-focused)
+        - Styles should match how this persona would naturally communicate
+      </task>
+
+      <example>
+        For an e-commerce schema with orders, customers, products tables:
+
+        {
+          "role": "Customer Support Rep",
+          "perspective": "As customer support, I care about:\\n- Quick lookups by order ID or customer email\\n- Order status and shipping tracking\\n- Return and refund history\\n- Customer contact details and order history\\n- I need fast answers, not complex analysis",
+          "styles": ["imperative", "concise"]
+        }
+
+        {
+          "role": "Inventory Manager",
+          "perspective": "As inventory manager, I care about:\\n- Current stock levels and reorder points\\n- Product availability across warehouses\\n- Slow-moving inventory identification\\n- Supplier lead times and pending orders\\n- I need accurate counts, often aggregated by location",
+          "styles": ["formal", "interrogative"]
+        }
+      </example>
+
+      <guardrails>
+        - Only generate personas relevant to the actual schema provided
+        - Do not invent tables or data that don't exist in the schema
+        - Ensure perspectives are specific to the domain, not generic
+      </guardrails>
+    `;
+  }
+});
+var PersonaGenerator = class {
+  /**
+   * @param adapter - Database adapter for schema introspection
+   * @param options - Generation options including count and model
+   */
+  constructor(adapter, options) {
+    this.adapter = adapter;
+    this.options = options;
+  }
+  /**
+   * Generates personas by analyzing the database schema to infer user types.
+   * @returns Array of personas with roles and perspectives
+   */
+  async generate() {
+    const schema = await this.adapter.introspect();
+    const count = this.options?.count ?? 5;
+    const { experimental_output } = await generate9(
+      personaGeneratorAgent.clone({
+        model: this.options?.model
+      }),
+      [user9(`Generate ${count} personas for this database schema.`)],
+      {
+        schema,
+        count
+      }
+    );
+    return experimental_output.personas;
+  }
+};
+
+// packages/text2sql/src/lib/agents/teachables.agent.ts
+import { groq as groq9 } from "@ai-sdk/groq";
+import { defaultSettingsMiddleware as defaultSettingsMiddleware6, wrapLanguageModel as wrapLanguageModel6 } from "ai";
+import dedent8 from "dedent";
+import z9 from "zod";
+import { agent as agent9, generate as generate10, user as user10 } from "@deepagents/agent";
+var outputSchema = z9.object({
+  terms: z9.array(z9.object({ name: z9.string(), definition: z9.string() })).optional().describe("Domain terminology definitions"),
+  hints: z9.array(z9.object({ text: z9.string() })).optional().describe("Helpful hints for SQL generation"),
+  guardrails: z9.array(
+    z9.object({
+      rule: z9.string(),
+      reason: z9.string().optional(),
+      action: z9.string().optional()
+    })
+  ).optional().describe("Safety rules and constraints"),
+  explains: z9.array(
+    z9.object({
+      concept: z9.string(),
+      explanation: z9.string(),
+      therefore: z9.string().optional()
+    })
+  ).optional().describe("Concept explanations"),
+  examples: z9.array(
+    z9.object({
+      question: z9.string(),
+      answer: z9.string(),
+      note: z9.string().optional()
+    })
+  ).optional().describe("Example question-answer pairs"),
+  clarifications: z9.array(z9.object({ when: z9.string(), ask: z9.string(), reason: z9.string() })).optional().describe("When to ask for clarification"),
+  workflows: z9.array(
+    z9.object({
+      task: z9.string(),
+      steps: z9.array(z9.string()).min(1),
+      triggers: z9.array(z9.string()).optional(),
+      notes: z9.string().optional()
+    })
+  ).optional().describe("Multi-step workflows"),
+  quirks: z9.array(z9.object({ issue: z9.string(), workaround: z9.string() })).optional().describe("Known issues and workarounds"),
+  styleGuides: z9.array(
+    z9.object({
+      prefer: z9.string(),
+      never: z9.string().optional(),
+      always: z9.string().optional()
+    })
+  ).optional().describe("SQL style preferences"),
+  analogies: z9.array(
+    z9.object({
+      concept: z9.array(z9.string()).min(2),
+      relationship: z9.string(),
+      insight: z9.string().optional(),
+      therefore: z9.string().optional(),
+      pitfall: z9.string().optional()
+    })
+  ).optional().describe("Concept analogies")
+});
+var teachablesAuthorAgent = agent9({
+  name: "teachables-author",
+  model: wrapLanguageModel6({
+    model: groq9("openai/gpt-oss-20b"),
+    middleware: defaultSettingsMiddleware6({
+      settings: { temperature: 0.4, topP: 0.95 }
+    })
+  }),
+  output: outputSchema,
+  prompt: (state) => dedent8`
+    <identity>
+      You design "teachables" for a Text2SQL system. Teachables become structured XML instructions.
+      Choose only high-impact items that improve accuracy, safety, or clarity for this database.
+    </identity>
+
+    <database_schema>
+    ${state?.schema}
+    </database_schema>
+
+    ${state?.context ? `<additional_context>${state.context}</additional_context>` : ""}
+
+    <output_structure>
+      Output a JSON object with these optional arrays (include only relevant ones):
+      - terms: [{ name: string, definition: string }] - Domain terminology
+      - hints: [{ text: string }] - Helpful SQL generation hints
+      - guardrails: [{ rule: string, reason?: string, action?: string }] - Safety constraints
+      - explains: [{ concept: string, explanation: string, therefore?: string }] - Concept explanations
+      - examples: [{ question: string, answer: string, note?: string }] - Q&A examples
+      - clarifications: [{ when: string, ask: string, reason: string }] - Clarification triggers
+      - workflows: [{ task: string, steps: string[], triggers?: string[], notes?: string }] - Multi-step tasks
+      - quirks: [{ issue: string, workaround: string }] - Known issues
+      - styleGuides: [{ prefer: string, never?: string, always?: string }] - SQL style rules
+      - analogies: [{ concept: string[], relationship: string, insight?: string, therefore?: string, pitfall?: string }]
+    </output_structure>
+
+    <instructions>
+      1. Analyze the schema to infer domain, relationships, and sensitive columns.
+      2. Generate 3-10 teachables total across all categories, prioritizing:
+         - guardrails for PII columns (email, ssn, phone, etc)
+         - hints for status/enum columns
+         - clarifications for ambiguous terms
+      3. Ground everything in the schema - do not invent tables/columns.
+      4. Only include categories that are relevant to this schema.
+    </instructions>
+  `
+});
+async function toTeachings(input, options) {
+  const { experimental_output: result } = await generate10(
+    teachablesAuthorAgent.clone({ model: options?.model }),
+    [
+      user10(
+        `Analyze this database schema and generate teachings that will help an AI generate accurate SQL queries.`
+      )
+    ],
+    input
+  );
+  const generated = [
+    ...result.terms?.map((t) => ({ type: "term", ...t })) ?? [],
+    ...result.hints?.map((h) => ({ type: "hint", ...h })) ?? [],
+    ...result.guardrails?.map((g) => ({ type: "guardrail", ...g })) ?? [],
+    ...result.explains?.map((e) => ({ type: "explain", ...e })) ?? [],
+    ...result.examples?.map((e) => ({ type: "example", ...e })) ?? [],
+    ...result.clarifications?.map((c) => ({
+      type: "clarification",
+      ...c
+    })) ?? [],
+    ...result.workflows?.map((w) => ({ type: "workflow", ...w })) ?? [],
+    ...result.quirks?.map((q) => ({ type: "quirk", ...q })) ?? [],
+    ...result.styleGuides?.map((s) => ({
+      type: "styleGuide",
+      ...s
+    })) ?? [],
+    ...result.analogies?.map((a) => ({ type: "analogy", ...a })) ?? []
+  ];
+  return toTeachables(generated);
+}
+
+// packages/text2sql/src/lib/synthesis/synthesizers/teachings-generator.ts
+var TeachingsGenerator = class {
+  /**
+   * @param adapter - Database adapter for schema introspection
+   * @param options - Generation options including context and model
+   */
+  constructor(adapter, options) {
+    this.adapter = adapter;
+    this.options = options;
+  }
+  /**
+   * Generates domain-specific teachings by analyzing the database schema.
+   * Retries on transient generation errors up to maxRetries attempts.
+   * @param maxRetries - Maximum retry attempts for transient failures
+   * @returns Array of teachings including vocabulary, patterns, and guardrails
+   */
+  async generate(maxRetries = 3) {
+    const schema = await this.adapter.introspect();
+    let lastError;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        return await toTeachings(
+          {
+            schema,
+            context: this.options?.context
+          },
+          { model: this.options?.model }
+        );
+      } catch (error) {
+        lastError = error;
+        const isRetryable = lastError.message.includes("parse") || lastError.message.includes("schema") || lastError.message.includes("No object generated") || lastError.name.includes("AI_");
+        if (!isRetryable) {
+          throw lastError;
+        }
+      }
+    }
+    throw lastError;
+  }
+};
+export {
+  ALL_STYLES,
+  BaseContextualExtractor,
+  BreadthEvolver,
+  DeduplicatedProducer,
+  DepthEvolver,
+  FilteredProducer,
+  FullContextExtractor,
+  LastQueryExtractor,
+  MessageExtractor,
+  PairProducer,
+  PersonaGenerator,
+  SchemaSynthesizer,
+  SegmentedContextExtractor,
+  SqlExtractor,
+  TeachingsGenerator,
+  ValidatedProducer,
+  WindowedContextExtractor,
+  contextResolverAgent,
+  formatConversation,
+  getMessageText,
+  styleInstructions,
+  toPairs
+};
+//# sourceMappingURL=index.js.map