@deepagents/text2sql 0.20.0 → 0.22.0

package/dist/lib/agents/result-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result-tools.d.ts","sourceRoot":"","sources":["../../../src/lib/agents/result-tools.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,WAAW,EAOjB,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AA+kBD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,6BAA6B;IAC7B,UAAU,EAAE,WAAW,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB;;kCA4C/B,MAAM;;;;;;;;;;;;;;;;;;;;;GAoDzC"}
+{"version":3,"file":"result-tools.d.ts","sourceRoot":"","sources":["../../../src/lib/agents/result-tools.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,WAAW,EAOjB,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAikCD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,6BAA6B;IAC7B,UAAU,EAAE,WAAW,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB;;kCA4C/B,MAAM;;;;;;;;;;;;;;;;;;;;;GAoDzC"}

package/dist/lib/agents/sql.agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.agent.d.ts","sourceRoot":"","sources":["../../../src/lib/agents/sql.agent.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAEL,KAAK,eAAe,EAOrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA4GD,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAoJvE"}
+{"version":3,"file":"sql.agent.d.ts","sourceRoot":"","sources":["../../../src/lib/agents/sql.agent.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAEL,KAAK,eAAe,EAWrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA+ND,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAmJvE"}

package/dist/lib/synthesis/index.js

@@ -871,13 +871,17 @@ 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 = [
@@ -885,94 +889,201 @@ var SQL_AGENT_POLICIES = [
     "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"
     })
-    // policy({
-    //   rule: 'Before returning an error, perform a schema-grounded self-check: identify core intent, draft best-effort SQL, then verify it uses only existing tables/columns.',
-    // }),
-    // policy({
-    //   rule: 'Return unanswerable only if that self-check confirms no valid SQL can express the required intent without inventing schema elements.',
-    // }),
-    // policy({
-    //   rule: 'Prefer a best-effort valid SQL query when entities can be reasonably inferred from table or column names.',
-    // }),
-    // policy({
-    //   rule: 'Use lexical normalization (singular/plural, paraphrases, role synonyms, and minor wording differences) to align question terms with schema names.',
-    // }),
-    // policy({
-    //   rule: 'Decompose noun phrases into core entity and qualifiers, and map the core entity first.',
-    // }),
-    // policy({
-    //   rule: 'Do not require every descriptive word to map to a separate schema field when the core entity match is unambiguous.',
-    // }),
-    // policy({
-    //   rule: 'For phrases like "X of Y", treat Y as contextual (non-blocking) when Y has no mapped schema field and the question does not ask to filter/group/select by Y explicitly.',
-    // }),
-    // policy({
-    //   rule: 'Treat unmatched qualifiers as blockers only when they are restrictive constraints (specific values, comparisons, or conditions that change row eligibility).',
-    // }),
-    // hint('Preserve schema spelling exactly, including typos in column names.'),
   )
-  // fragment(
-  //   'unanswerable_gate',
-  //   workflow({
-  //     task: 'Unanswerable decision',
-  //     steps: [
-  //       'Identify the core intent (metric/projection and required filters).',
-  //       'Attempt schema-grounded mapping for the core intent before considering error.',
-  //       'If a valid SELECT can answer the core intent without inventing schema entities, return SQL.',
-  //       'Return unanswerable only when required information cannot be mapped to any available table or column.',
-  //     ],
-  //   }),
-  //   policy({
-  //     rule: 'Do not reject a question as unanswerable when requested information can be derived by filtering, joining, grouping, counting, set operations, or sorting on available columns.',
-  //   }),
-  // ),
-  // fragment(
-  //   'query_shape_preferences',
-  //   hint(
-  //     'Prefer explicit INNER JOINs over LEFT JOINs unless the question requires unmatched rows.',
-  //   ),
-  //   hint(
-  //     'Prefer direct joins over dropping join constraints or using weaker alternatives.',
-  //   ),
-  //   hint('Use DISTINCT only when uniqueness is explicitly requested.'),
-  //   hint(
-  //     'For superlatives over grouped entities (most/least/highest/lowest by group), prefer GROUP BY with ORDER BY aggregate and LIMIT 1.',
-  //   ),
-  //   hint(
-  //     'For average/count conditions per entity, prefer GROUP BY with HAVING aggregate predicates over row-level WHERE predicates.',
-  //   ),
-  //   hint(
-  //     'For "both" conditions across two criteria, prefer INTERSECT when selecting shared values.',
-  //   ),
-  //   hint(
-  //     'For "A or B" retrieval across criteria, prefer UNION when combining two qualifying sets.',
-  //   ),
-  //   hint(
-  //     'For "never" constraints against related records, prefer NOT IN or EXCEPT against the disqualifying set.',
-  //   ),
-  //   hint(
-  //     'Use equality predicates for exact values unless the question asks for pattern matching.',
-  //   ),
-  //   hint(
-  //     'Keep numeric literals unquoted when they are purely numeric tokens in the question.',
-  //   ),
-  // ),
-  // fragment(
-  //   'sql_minimality',
-  //   guardrail({
-  //     rule: 'Never hallucinate tables or columns.',
-  //     reason: 'Schema fidelity is required.',
-  //     action: 'Use only available schema entities.',
-  //   }),
-  //   guardrail({
-  //     rule: 'Prefer the minimal query over transformed expressions.',
-  //     reason:
-  //       'Unnecessary transformations reduce correctness and add avoidable complexity.',
-  //     action:
-  //       'Do not add date parsing, substring extraction, derived projections, or extra selected columns unless explicitly requested or required by schema mismatch.',
-  //   }),
-  // ),
 ];
 function extractSql(output) {
   const match = output.match(/```sql\n?([\s\S]*?)```/);
@@ -1257,7 +1368,7 @@ import {
   ContextEngine as ContextEngine6,
   InMemoryContextStore as InMemoryContextStore6,
   fragment as fragment6,
-  guardrail as guardrail2,
+  guardrail as guardrail3,
   persona as personaFragment,
   structuredOutput as structuredOutput6,
   user as user6
@@ -1354,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(
@@ -1428,7 +1539,7 @@ import {
   ContextEngine as ContextEngine7,
   InMemoryContextStore as InMemoryContextStore7,
   fragment as fragment7,
-  guardrail as guardrail3,
+  guardrail as guardrail4,
   persona as persona6,
   structuredOutput as structuredOutput7,
   user as user7
@@ -1516,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}"`
     )
@@ -1655,7 +1766,7 @@ import {
   InMemoryContextStore as InMemoryContextStore8,
   XmlRenderer,
   fragment as fragment8,
-  guardrail as guardrail4,
+  guardrail as guardrail5,
   persona as personaFragment2,
   structuredOutput as structuredOutput8,
   user as user8
@@ -1739,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(
@@ -1774,18 +1885,18 @@ import {
   InMemoryContextStore as InMemoryContextStore9,
   analogy,
   clarification,
-  example,
+  example as example2,
   explain,
   fragment as fragment9,
-  guardrail as guardrail5,
-  hint,
+  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"),
@@ -1892,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(
@@ -1909,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(
@@ -1919,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,