@deepagents/text2sql 0.19.0 → 0.22.0

package/dist/lib/synthesis/index.js

@@ -714,6 +714,32 @@ var LastQueryExtractor = class extends BaseContextualExtractor {
 // packages/text2sql/src/lib/synthesis/synthesizers/schema-synthesizer.ts
 import pLimit from "p-limit";
 
+// packages/text2sql/src/lib/agents/exceptions.ts
+var sqlValidationMarker = Symbol("SQLValidationError");
+var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [sqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[sqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
+  }
+};
+
 // packages/text2sql/src/lib/agents/question.agent.ts
 import { groq as groq4 } from "@ai-sdk/groq";
 import dedent4 from "dedent";
@@ -838,42 +864,231 @@ import {
   defaultSettingsMiddleware,
   wrapLanguageModel
 } from "ai";
+import dedent5 from "dedent";
 import pRetry from "p-retry";
 import z5 from "zod";
 import "@deepagents/agent";
 import {
   ContextEngine as ContextEngine5,
   InMemoryContextStore as InMemoryContextStore5,
+  example,
+  fragment as fragment5,
+  guardrail as guardrail2,
+  hint,
   persona as persona5,
+  policy,
   structuredOutput as structuredOutput5,
-  user as user5
+  user as user5,
+  workflow
 } from "@deepagents/context";
-var RETRY_TEMPERATURES = [0, 0.2, 0.3];
+var RETRY_TEMPERATURES = [0, 0.4, 0.8];
+var SQL_AGENT_ROLE = "Expert SQL query generator.";
+var SQL_AGENT_OBJECTIVE = "Generate precise SQL grounded in provided schema.";
+var SQL_AGENT_POLICIES = [
+  fragment5(
+    "schema_mapping",
+    policy({
+      rule: "Translate natural language into precise SQL grounded in available schema entities."
+    }),
+    hint("Preserve schema spelling exactly, including typos in column names.")
+  ),
+  fragment5(
+    "projection_minimality",
+    policy({
+      rule: "Return only columns requested by the question; do not add helper columns unless explicitly requested."
+    }),
+    policy({
+      rule: 'For requests of the form "X sorted/ordered by Y", project X only unless Y is explicitly requested as an output field.'
+    }),
+    policy({
+      rule: "Prefer selecting schema columns directly without derived expressions when direct selection answers the request."
+    }),
+    hint(
+      "Do not include ORDER BY, GROUP BY, or JOIN helper columns in SELECT output unless the question explicitly asks for them."
+    ),
+    policy({
+      rule: "Use DISTINCT only when uniqueness is explicitly requested (for example distinct/unique/different/no duplicates)."
+    }),
+    hint(
+      'Do not infer DISTINCT from generic wording such as "some", plural nouns, or entity-set phrasing; for transactional/attendance-style tables, default to raw rows unless uniqueness is explicitly requested.'
+    )
+  ),
+  fragment5(
+    "date_transform_safety",
+    policy({
+      rule: "Do not assume VARCHAR/TEXT values are parseable dates. Avoid date extraction functions on text columns by default."
+    }),
+    policy({
+      rule: "Use date-part extraction only when both conditions hold: the question explicitly asks for transformation and schema values require transformation to produce that unit."
+    }),
+    hint(
+      "Do not apply SUBSTR, STRFTIME, DATE_PART, YEAR, or similar extraction functions unless the question explicitly asks for transformation and schema values require it."
+    ),
+    hint(
+      "If a column already represents the requested concept (for example a stored year-like value), use the column as-is."
+    )
+  ),
+  fragment5(
+    "sql_minimality",
+    guardrail2({
+      rule: "Never hallucinate tables or columns.",
+      reason: "Schema fidelity is required.",
+      action: "Use only available schema entities."
+    }),
+    guardrail2({
+      rule: "Avoid unnecessary transformations and derived projections.",
+      reason: "Extra transformations frequently change semantics and reduce correctness.",
+      action: "Do not add date parsing, substring extraction, or derived columns unless explicitly required by the question or schema."
+    })
+  ),
+  fragment5(
+    "preflight_checklist",
+    workflow({
+      task: "Final SQL preflight before returning output",
+      steps: [
+        "Verify selected columns match the question and remove unrequested helper projections.",
+        "If aggregate values are used only for ranking/filtering, keep them out of SELECT unless explicitly requested.",
+        "Prefer raw schema columns over derived expressions when raw columns already satisfy the request.",
+        "If a candidate query uses STRFTIME, SUBSTR, DATE_PART, YEAR, or similar extraction on text-like columns, remove that transformation unless explicitly required by the question.",
+        "Return only schema-grounded SQL using existing tables and columns."
+      ]
+    })
+  ),
+  fragment5(
+    "set_semantics",
+    policy({
+      rule: "For questions asking where both condition A and condition B hold over an attribute, compute the intersection of qualifying sets for that attribute."
+    }),
+    policy({
+      rule: "Do not force the same entity instance to satisfy both conditions unless the question explicitly requests the same person/row/entity."
+    }),
+    hint(
+      "Prefer INTERSECT (or logically equivalent set-based shape) over requiring the same physical row/entity to satisfy both conditions unless explicitly requested."
+    ),
+    hint(
+      "When two conditions describe different row groups whose shared attribute is requested, build each group separately and intersect the attribute values."
+    ),
+    hint(
+      "Do not collapse cross-group conditions into a single-row AND predicate when the intent is shared values across groups."
+    ),
+    policy({
+      rule: "If two predicates on the same field cannot both be true for one row, do not combine them with AND; use set operations across separate filtered subsets when shared values are requested."
+    })
+  ),
+  fragment5(
+    "predicate_column_alignment",
+    policy({
+      rule: "Match literal values to semantically compatible columns. Do not compare descriptive names to identifier columns."
+    }),
+    hint(
+      "When a filter value is a descriptive label (for example a department name), join through the lookup table and filter on its name/title column, not on *_id columns."
+    ),
+    hint(
+      "When relation roles are explicit in wording (for example host/home/source/destination), prefer foreign keys with matching role qualifiers over generic similarly named columns."
+    ),
+    policy({
+      rule: "When multiple foreign-key candidates exist, select the column whose qualifier best matches the relationship described in the question."
+    }),
+    policy({
+      rule: "For hosting/held semantics, prefer host_* relationship columns when available over generic *_id alternatives."
+    }),
+    hint(
+      'Interpret wording like "held/hosted a competition or event" as a hosting relationship and map to host_* foreign keys when present.'
+    ),
+    policy({
+      rule: "Do not compare descriptive labels or names to *_id columns; join to the table containing the descriptive field and filter there."
+    }),
+    policy({
+      rule: "Keep numeric identifiers unquoted when used as numeric equality filters unless schema indicates text identifiers."
+    }),
+    policy({
+      rule: "When filtering by a descriptive label value and a related table exposes a corresponding *_name or title column, join to that table and filter on the descriptive column."
+    })
+  ),
+  fragment5(
+    "ordering_semantics",
+    policy({
+      rule: "Respect explicit sort direction terms. If direction is not specified, use ascending order unless a superlative intent (most/least/highest/lowest) implies direction."
+    }),
+    policy({
+      rule: "When ranking categories by frequency, use COUNT for ordering but keep output focused on requested category fields unless counts are explicitly requested."
+    }),
+    policy({
+      rule: "Do not use DESC unless descending direction is explicit or a superlative intent requires descending ranking."
+    }),
+    policy({
+      rule: 'For "most common/frequent <attribute>" requests, return the attribute value(s) only; use counts only for ordering/filtering unless the question explicitly asks to return counts.'
+    }),
+    hint(
+      'Use DESC with LIMIT 1 for "most/highest/largest"; use ASC with LIMIT 1 for "least/lowest/smallest".'
+    )
+  ),
+  fragment5(
+    "negative_membership_queries",
+    policy({
+      rule: "For requests asking entities that did not participate/host/appear in related records, prefer NOT IN or NOT EXISTS against the related foreign-key set."
+    }),
+    hint(
+      "Map role-bearing relationship columns carefully (for example host_* foreign keys for hosting relationships) instead of generic IDs when role wording is explicit."
+    ),
+    hint(
+      'For "never had/never exceeded" conditions over history tables, exclude entities via NOT IN/NOT EXISTS against the disqualifying entity-id set (often built with GROUP BY/HAVING MAX(...)).'
+    )
+  ),
+  fragment5(
+    "join_completeness",
+    policy({
+      rule: "Preserve entity-restricting joins implied by the question. Do not widen results by querying only a broader attribute table when a subset entity table is available."
+    }),
+    policy({
+      rule: "If an entity term in the question maps to a table, keep that table in query scope and join to attribute tables rather than dropping the entity table."
+    }),
+    hint(
+      "If the question targets a specific entity group, include that entity table and its join conditions even when selected columns come from a related table."
+    ),
+    hint(
+      "When the question names an entity type and a relation table links to that entity via *_id, include the entity table in scope instead of counting only relation rows."
+    ),
+    hint(
+      "Prefer INNER JOIN by default; use LEFT JOIN only when the question explicitly requests including unmatched rows or zero-related entities."
+    )
+  ),
+  fragment5(
+    "aggregation_exactness",
+    policy({
+      rule: "Preserve requested aggregation semantics exactly: use COUNT(*) by default for total rows, use COUNT(DISTINCT ...) only when uniqueness is explicitly requested, and group by stable entity keys when computing per-entity aggregates."
+    }),
+    policy({
+      rule: "For questions asking which entity has lowest/highest average of a metric, compute AVG(metric) per entity (GROUP BY entity) and rank those aggregates."
+    }),
+    hint(
+      'For "how many <entities>" questions over relation records, default to COUNT(*) on qualifying rows unless explicit uniqueness language is present.'
+    )
+  ),
+  fragment5(
+    "query_shape_examples",
+    example({
+      question: "List categories ordered by how many records belong to each category.",
+      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*)"
+    }),
+    example({
+      question: "Show labels shared by rows with metric > 100 and rows with metric < 10.",
+      answer: "SELECT label FROM records WHERE metric > 100 INTERSECT SELECT label FROM records WHERE metric < 10"
+    }),
+    example({
+      question: "List locations that have not hosted any event.",
+      answer: "SELECT location_name FROM locations WHERE location_id NOT IN (SELECT host_location_id FROM events)"
+    }),
+    example({
+      question: "List the most common category across records.",
+      answer: "SELECT category FROM records GROUP BY category ORDER BY COUNT(*) DESC LIMIT 1"
+    })
+  )
+];
 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(
@@ -886,20 +1101,38 @@ async function toSql(options) {
       context.set(
         persona5({
           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.",
-          objective: "Translate natural language questions into precise, efficient SQL queries"
+          role: SQL_AGENT_ROLE,
+          objective: SQL_AGENT_OBJECTIVE
+          // role: `You are a data science expert that provides well-reasoned and detailed responses.`,
+          // objective: `Your task is to understand the schema and generate a valid SQL query to answer the question. You first think about the reasoning process as an internal monologue and then provide the user with the answer.`,
         }),
+        ...SQL_AGENT_POLICIES,
         ...options.fragments
       );
       if (errors.length) {
+        const lastError = errors.at(-1);
         context.set(
-          user5(options.input),
-          user5(
-            `<validation_error>Your previous SQL query had the following error: ${errors.at(-1)?.message}. Please fix the query.</validation_error>`
+          user5(dedent5`
+            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
+Given the question, the evidence and the database schema, return the SQL script that addresses the question.
+
+Question: ${options.input}
+`),
+          UnanswerableSQLError.isInstance(lastError) ? user5(
+            `<retry_instruction>Your previous response marked the task as unanswerable. Re-evaluate using best-effort schema mapping. If the core intent is answerable with existing tables/columns, return SQL. Return error only when required core intent cannot be mapped without inventing schema elements.</retry_instruction>`
+          ) : user5(
+            `<validation_error>Your previous SQL query had the following error: ${lastError?.message}. Please fix the query.</validation_error>`
           )
         );
       } else {
-        context.set(user5(options.input));
+        context.set(
+          user5(dedent5`
+            Answer the following question with the SQL code. Use the piece of evidence and base your answer on the database schema.
+Given the question, the evidence and the database schema, return the SQL script that addresses the question.
+
+Question: ${options.input}
+`)
+        );
       }
       const temperature = RETRY_TEMPERATURES[attemptNumber - 1] ?? RETRY_TEMPERATURES[RETRY_TEMPERATURES.length - 1];
       const baseModel = options.model ?? groq5("openai/gpt-oss-20b");
@@ -925,19 +1158,45 @@ async function toSql(options) {
         })
       });
       const { result: output } = await sqlOutput.generate();
+      const finalizeSql = async (rawSql) => {
+        const sql = options.adapter.format(extractSql(rawSql));
+        const validationError = await options.adapter.validate(sql);
+        if (validationError) {
+          throw new SQLValidationError(validationError);
+        }
+        return {
+          attempts,
+          sql,
+          errors: errors.length ? errors.map(formatErrorMessage) : void 0
+        };
+      };
       if ("error" in output) {
-        throw new UnanswerableSQLError(output.error);
-      }
-      const sql = options.adapter.format(extractSql(output.sql));
-      const validationError = await options.adapter.validate(sql);
-      if (validationError) {
-        throw new SQLValidationError(validationError);
+        context.set(
+          user5(
+            "<best_effort_fallback>Do not return unanswerable. Produce the best valid SQL query that answers the core intent using only available schema entities.</best_effort_fallback>"
+          )
+        );
+        const forcedSqlOutput = structuredOutput5({
+          model,
+          context,
+          schema: z5.object({
+            sql: z5.string().describe(
+              "Best-effort SQL query that answers the core intent using only available schema entities."
+            ),
+            reasoning: z5.string().describe("Reasoning steps for best-effort schema mapping.")
+          })
+        });
+        try {
+          const forced = await forcedSqlOutput.generate();
+          return await finalizeSql(forced.sql);
+        } catch (error) {
+          if (SQLValidationError.isInstance(error) || APICallError.isInstance(error) || JSONParseError.isInstance(error) || TypeValidationError.isInstance(error) || NoObjectGeneratedError.isInstance(error) || NoOutputGeneratedError.isInstance(error) || NoContentGeneratedError.isInstance(error)) {
+            throw error;
+          }
+          throw new UnanswerableSQLError(output.error);
+        }
       }
-      return {
-        attempts,
-        sql,
-        errors: errors.length ? errors.map(formatErrorMessage) : void 0
-      };
+      return await finalizeSql(output.sql);
     },
     { retries: maxRetries - 1 }
   );
@@ -1000,9 +1259,6 @@ async function withRetry(computation, options = { retries: 3 }) {
         return APICallError.isInstance(context.error) || JSONParseError.isInstance(context.error) || TypeValidationError.isInstance(context.error) || NoObjectGeneratedError.isInstance(context.error) || NoOutputGeneratedError.isInstance(context.error) || NoContentGeneratedError.isInstance(context.error);
       },
       onFailedAttempt(context) {
-        console.log(
-          `Attempt ${context.attemptNumber} failed. There are ${context.retriesLeft} retries left.`
-        );
         errors.push(context.error);
       }
     }
@@ -1104,15 +1360,15 @@ Generate ${this.options.count} questions at ${complexity} complexity.` : void 0;
 
 // packages/text2sql/src/lib/synthesis/synthesizers/breadth-evolver.ts
 import { groq as groq6 } from "@ai-sdk/groq";
-import dedent5 from "dedent";
+import dedent6 from "dedent";
 import pLimit2 from "p-limit";
 import z6 from "zod";
 import "@deepagents/agent";
 import {
   ContextEngine as ContextEngine6,
   InMemoryContextStore as InMemoryContextStore6,
-  fragment as fragment5,
-  guardrail as guardrail2,
+  fragment as fragment6,
+  guardrail as guardrail3,
   persona as personaFragment,
   structuredOutput as structuredOutput6,
   user as user6
@@ -1163,7 +1419,7 @@ async function paraphraseQuestion(params) {
     chatId: `paraphraser-${crypto.randomUUID()}`,
     userId: "system"
   });
-  const personaInstruction = params.persona ? dedent5`
+  const personaInstruction = params.persona ? dedent6`
         <persona role="${params.persona.role}">
           ${params.persona.perspective}
 
@@ -1171,7 +1427,7 @@ async function paraphraseQuestion(params) {
           Use their vocabulary, priorities, and framing style.
         </persona>
       ` : "";
-  const styleInstruction = params.persona?.styles && params.persona.styles.length > 0 ? dedent5`
+  const styleInstruction = params.persona?.styles && params.persona.styles.length > 0 ? dedent6`
         <communication_styles>
           Generate paraphrases using these communication styles: ${params.persona.styles.join(", ")}
 
@@ -1187,17 +1443,17 @@ async function paraphraseQuestion(params) {
       role: "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.",
       objective: "Generate paraphrased versions of questions that preserve exact semantic meaning and produce identical SQL"
     }),
-    fragment5("original_question", params.question),
-    fragment5(
+    fragment6("original_question", params.question),
+    fragment6(
       "reference_sql",
       params.sql,
       "This SQL shows what the question is really asking - all paraphrases must ask for exactly this"
     ),
-    ...personaInstruction ? [fragment5("persona", personaInstruction)] : [],
-    ...styleInstruction ? [fragment5("communication_styles", styleInstruction)] : [],
-    fragment5(
+    ...personaInstruction ? [fragment6("persona", personaInstruction)] : [],
+    ...styleInstruction ? [fragment6("communication_styles", styleInstruction)] : [],
+    fragment6(
       "task",
-      dedent5`
+      dedent6`
         Generate exactly ${params.count} paraphrased versions of the original question.
 
         Requirements:
@@ -1209,14 +1465,14 @@ async function paraphraseQuestion(params) {
         ${params.persona?.styles?.length ? "6. Apply the specified communication styles to create diverse phrasings" : ""}
       `
     ),
-    guardrail2({ rule: "NEVER change what data is being requested" }),
-    guardrail2({
+    guardrail3({ rule: "NEVER change what data is being requested" }),
+    guardrail3({
       rule: "NEVER add filters, aggregations, or conditions not in the original"
     }),
-    guardrail2({
+    guardrail3({
       rule: "NEVER remove any specificity from the original question"
     }),
-    guardrail2({
+    guardrail3({
       rule: "All paraphrases must be answerable by the exact same SQL query"
     }),
     user6(
@@ -1274,7 +1530,7 @@ var BreadthEvolver = class extends PairProducer {
 // packages/text2sql/src/lib/synthesis/synthesizers/depth-evolver.ts
 import { groq as groq7 } from "@ai-sdk/groq";
 import { NoObjectGeneratedError as NoObjectGeneratedError2, NoOutputGeneratedError as NoOutputGeneratedError2 } from "ai";
-import dedent6 from "dedent";
+import dedent7 from "dedent";
 import pLimit3 from "p-limit";
 import pRetry2 from "p-retry";
 import z7 from "zod";
@@ -1282,14 +1538,14 @@ import "@deepagents/agent";
 import {
   ContextEngine as ContextEngine7,
   InMemoryContextStore as InMemoryContextStore7,
-  fragment as fragment6,
-  guardrail as guardrail3,
+  fragment as fragment7,
+  guardrail as guardrail4,
   persona as persona6,
   structuredOutput as structuredOutput7,
   user as user7
 } from "@deepagents/context";
 var techniqueInstructions = {
-  "add-aggregation": dedent6`
+  "add-aggregation": dedent7`
     Add aggregation requirements to the question.
     Transform it to require GROUP BY, COUNT, SUM, AVG, MIN, MAX, or similar operations.
     Examples:
@@ -1297,7 +1553,7 @@ var techniqueInstructions = {
     - "List products" → "What is the average price per category?"
     - "Get employees" → "How many employees are in each department?"
   `,
-  "add-filter": dedent6`
+  "add-filter": dedent7`
     Add filtering conditions to the question.
     Transform it to require WHERE clauses with specific conditions.
     Examples:
@@ -1305,7 +1561,7 @@ var techniqueInstructions = {
     - "List customers" → "List customers who have made more than 5 purchases"
     - "Get products" → "Get products with price above $100"
   `,
-  "add-join": dedent6`
+  "add-join": dedent7`
     Add requirements that need data from related tables.
     Transform it to require JOIN operations between multiple tables.
     Examples:
@@ -1313,7 +1569,7 @@ var techniqueInstructions = {
     - "List products" → "List products with their supplier information"
     - "Get employees" → "Get employees with their department and manager names"
   `,
-  "add-reasoning": dedent6`
+  "add-reasoning": dedent7`
     Add multi-step reasoning requirements.
     Transform it to require logical deduction, comparisons, or derived calculations.
     Examples:
@@ -1321,7 +1577,7 @@ var techniqueInstructions = {
     - "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`
+  hypothetical: dedent7`
     Add a hypothetical or speculative scenario.
     Transform it to require applying calculations or projections.
     Examples:
@@ -1345,21 +1601,21 @@ async function evolveQuestion(params) {
       role: "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.",
       objective: "Transform simple questions into complex versions requiring advanced SQL techniques"
     }),
-    fragment6("original_question", params.question),
-    fragment6(
+    fragment7("original_question", params.question),
+    fragment7(
       "original_sql",
       params.sql,
       "(This shows what the original question required)"
     ),
-    fragment6("database_schema", params.schema),
-    fragment6(
+    fragment7("database_schema", params.schema),
+    fragment7(
       "technique",
       { name: params.technique },
       params.techniqueInstruction
     ),
-    fragment6(
+    fragment7(
       "task",
-      dedent6`
+      dedent7`
         Evolve the original question using the "${params.technique}" technique.
 
         Requirements:
@@ -1371,16 +1627,16 @@ async function evolveQuestion(params) {
         6. The evolved question should build upon the original topic/domain
       `
     ),
-    guardrail3({
+    guardrail4({
       rule: "The evolved question MUST require more complex SQL than the original"
     }),
-    guardrail3({
+    guardrail4({
       rule: "Do not ask for data that does not exist in the schema"
     }),
-    guardrail3({
+    guardrail4({
       rule: "Keep the question grounded in the same domain as the original"
     }),
-    guardrail3({ rule: "Make sure the question is clear and unambiguous" }),
+    guardrail4({ rule: "Make sure the question is clear and unambiguous" }),
     user7(
       `Evolve this question using "${params.technique}": "${params.question}"`
     )
@@ -1502,15 +1758,15 @@ async function withRetry2(computation) {
 
 // packages/text2sql/src/lib/synthesis/synthesizers/persona-generator.ts
 import { groq as groq8 } from "@ai-sdk/groq";
-import dedent7 from "dedent";
+import dedent8 from "dedent";
 import z8 from "zod";
 import "@deepagents/agent";
 import {
   ContextEngine as ContextEngine8,
   InMemoryContextStore as InMemoryContextStore8,
   XmlRenderer,
-  fragment as fragment7,
-  guardrail as guardrail4,
+  fragment as fragment8,
+  guardrail as guardrail5,
   persona as personaFragment2,
   structuredOutput as structuredOutput8,
   user as user8
@@ -1542,10 +1798,10 @@ async function generatePersonas(schemaFragments, options) {
       role: "You are an expert at understanding database schemas and inferring who would use them.",
       objective: "Generate realistic personas representing users who would query this database"
     }),
-    fragment7("database_schema", schema),
-    fragment7(
+    fragment8("database_schema", schema),
+    fragment8(
       "task",
-      dedent7`
+      dedent8`
         Analyze the database schema and generate realistic personas representing
         the different types of users who would query this database.
 
@@ -1576,9 +1832,9 @@ async function generatePersonas(schemaFragments, options) {
         - Styles should match how this persona would naturally communicate
       `
     ),
-    fragment7(
+    fragment8(
       "example",
-      dedent7`
+      dedent8`
         For an e-commerce schema with orders, customers, products tables:
 
         {
@@ -1594,13 +1850,13 @@ async function generatePersonas(schemaFragments, options) {
         }
       `
     ),
-    guardrail4({
+    guardrail5({
       rule: "Only generate personas relevant to the actual schema provided"
     }),
-    guardrail4({
+    guardrail5({
       rule: "Do not invent tables or data that do not exist in the schema"
     }),
-    guardrail4({
+    guardrail5({
       rule: "Ensure perspectives are specific to the domain, not generic"
     }),
     user8(
@@ -1621,7 +1877,7 @@ import { XmlRenderer as XmlRenderer2 } from "@deepagents/context";
 
 // packages/text2sql/src/lib/agents/teachables.agent.ts
 import { groq as groq9 } from "@ai-sdk/groq";
-import dedent8 from "dedent";
+import dedent9 from "dedent";
 import z9 from "zod";
 import "@deepagents/agent";
 import {
@@ -1629,18 +1885,18 @@ import {
   InMemoryContextStore as InMemoryContextStore9,
   analogy,
   clarification,
-  example,
+  example as example2,
   explain,
-  fragment as fragment8,
-  guardrail as guardrail5,
-  hint,
+  fragment as fragment9,
+  guardrail as guardrail6,
+  hint as hint2,
   persona as persona7,
   quirk,
   structuredOutput as structuredOutput9,
   styleGuide,
   term,
   user as user9,
-  workflow
+  workflow as workflow2
 } from "@deepagents/context";
 var outputSchema4 = z9.object({
   terms: z9.array(z9.object({ name: z9.string(), definition: z9.string() })).optional().describe("Domain terminology definitions"),
@@ -1705,11 +1961,11 @@ async function toTeachings(input, options) {
       role: 'You design "fragments" for a Text2SQL system. Fragments become structured XML instructions.',
       objective: "Choose only high-impact items that improve accuracy, safety, or clarity for this database"
     }),
-    fragment8("database_schema", input.schema),
-    ...input.context ? [fragment8("additional_context", input.context)] : [],
-    fragment8(
+    fragment9("database_schema", input.schema),
+    ...input.context ? [fragment9("additional_context", input.context)] : [],
+    fragment9(
       "output_structure",
-      dedent8`
+      dedent9`
         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
@@ -1723,9 +1979,9 @@ async function toTeachings(input, options) {
         - analogies: [{ concepts: string[], relationship: string, insight?: string, therefore?: string, pitfall?: string }]
       `
     ),
-    fragment8(
+    fragment9(
       "task",
-      dedent8`
+      dedent9`
         1. Analyze the schema to infer domain, relationships, and sensitive columns.
         2. Generate 3-10 fragments total across all categories, prioritizing:
            - guardrails for PII columns (email, ssn, phone, etc)
@@ -1747,10 +2003,10 @@ async function toTeachings(input, options) {
   const result = await teachablesOutput.generate();
   const fragments = [];
   result.terms?.forEach((t) => fragments.push(term(t.name, t.definition)));
-  result.hints?.forEach((h) => fragments.push(hint(h.text)));
+  result.hints?.forEach((h) => fragments.push(hint2(h.text)));
   result.guardrails?.forEach(
     (g) => fragments.push(
-      guardrail5({ rule: g.rule, reason: g.reason, action: g.action })
+      guardrail6({ rule: g.rule, reason: g.reason, action: g.action })
     )
   );
   result.explains?.forEach(
@@ -1764,7 +2020,7 @@ async function toTeachings(input, options) {
   );
   result.examples?.forEach(
     (e) => fragments.push(
-      example({ question: e.question, answer: e.answer, note: e.note })
+      example2({ question: e.question, answer: e.answer, note: e.note })
     )
   );
   result.clarifications?.forEach(
@@ -1774,7 +2030,7 @@ async function toTeachings(input, options) {
   );
   result.workflows?.forEach(
     (w) => fragments.push(
-      workflow({
+      workflow2({
         task: w.task,
         steps: w.steps,
         triggers: w.triggers,