@deepagents/text2sql 0.26.0 → 0.27.0

package/README.md

@@ -97,7 +97,7 @@ const text2sql = new Text2Sql({
 
 **Domain fragments** (11 types): `term`, `hint`, `guardrail`, `example`, `explain`, `clarification`, `workflow`, `quirk`, `styleGuide`, `analogy`, `glossary`.
 
-**User fragments** (6 types): `identity`, `persona`, `alias`, `preference`, `userContext`, `correction`.
+**User fragments** (5 types): `identity`, `persona`, `alias`, `preference`, `correction`.
 
 See [@deepagents/context](../context/README.md) for full fragment documentation.
 

package/dist/index.js

@@ -8,7 +8,8 @@ function dialectInfo(input) {
     data: {
       dialect: input.dialect,
       ...input.version && { version: input.version },
-      ...input.database && { database: input.database }
+      ...input.database && { database: input.database },
+      ...input.details && { details: input.details }
     }
   };
 }
@@ -415,6 +416,7 @@ function getTablesWithRelated(allTables, relationships, filter) {
 // packages/text2sql/src/lib/agents/exceptions.ts
 var sqlValidationMarker = Symbol("SQLValidationError");
 var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
+var sqlScopeMarker = Symbol("SQLScopeError");
 var SQLValidationError = class _SQLValidationError extends Error {
   [sqlValidationMarker];
   constructor(message) {
@@ -437,6 +439,21 @@ var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
     return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
   }
 };
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
 
 // packages/text2sql/src/lib/agents/result-tools.ts
 import { tool } from "ai";
@@ -4742,7 +4759,7 @@ function reasoningFramework() {
       "You are a very strong reasoner and planner. Use these critical instructions to structure your plans, thoughts, and responses."
     ),
     fragment2(
-      "meta-cognitive-reasoning-framework",
+      "meta_cognitive_reasoning_framework",
       hint2(
         "Before taking any action (either tool calls *or* responses to the user), you must proactively, methodically, and independently plan and reason about:"
       ),
@@ -4852,8 +4869,7 @@ function reasoningFramework() {
     )
   ];
 }
-function guidelines(options = {}) {
-  const { date = "strict" } = options;
+function guidelines() {
   const baseTeachings = [
     // Include the meta-cognitive reasoning framework
     ...reasoningFramework(),
@@ -4868,7 +4884,7 @@ function guidelines(options = {}) {
       policy2({
         rule: "YOU MUST resolve ambiguous business terms with the user",
         before: "making ANY assumptions about terminology meaning",
-        reason: "NEVER guess domain-specific language\u2014ask for clarification"
+        reason: "NEVER guess domain-specific language, instead ask for clarification"
       }),
       policy2({
         rule: "YOU MUST validate SQL syntax",
@@ -4883,7 +4899,7 @@ function guidelines(options = {}) {
     ),
     // Few-shot: Applying reasoning principles
     fragment2(
-      "reasoning-examples",
+      "reasoning_examples",
       example2({
         question: "Show me sales last month",
         answer: `Applying Principle 1 (Logical dependencies):
@@ -4924,15 +4940,19 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     // Schema adherence - consolidated into clear rules
     fragment2(
       "schema_adherence",
-      hint2(
-        "Use only tables and columns from the schema. For unspecified columns, use SELECT *. When showing related items, include IDs and requested details."
-      ),
-      hint2(
-        '"Show" means list items; "count" or "total" means aggregate. Use canonical values verbatim for filtering.'
-      )
+      guardrail2({
+        rule: "Use only tables and columns that exist in the schema.",
+        reason: "Inventing tables or columns produces invalid SQL and breaks schema grounding.",
+        action: "If the user requests unspecified fields, use SELECT *. When showing related items, include IDs and requested details."
+      }),
+      explain({
+        concept: "query intent words",
+        explanation: '"Show" asks for listing rows, while "count" or "total" asks for aggregation.',
+        therefore: 'Use listing queries for "show" requests, aggregate queries for "count" or "total", and use canonical schema values verbatim in filters.'
+      })
     ),
     fragment2(
-      "Column statistics",
+      "column_statistics",
       explain({
         concept: "nDistinct in column stats",
         explanation: "Positive values are the estimated count of distinct values. Negative values represent the fraction of unique rows (e.g., -1 means all rows are unique, -0.5 means 50% unique)",
@@ -4953,7 +4973,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     ),
     // Aggregations - explain the concepts
     fragment2(
-      "Aggregations",
+      "aggregations",
       hint2(
         "Apply COUNT, SUM, AVG when the question implies summarization. Use window functions for ranking, running totals, or row comparisons."
       ),
@@ -4965,7 +4985,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     ),
     // Query semantics - explain concepts and document quirks
     fragment2(
-      "Query interpretation",
+      "query_interpretation",
       explain({
         concept: "threshold language",
         explanation: 'Words like "reach", "hit", "exceed" with a value imply a threshold being met or passed',
@@ -4993,7 +5013,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     }),
     // Safety guardrails - consolidated
     fragment2(
-      "Query safety",
+      "query_safety",
       guardrail2({
         rule: "Generate only valid, executable SELECT/WITH statements.",
         reason: "Read-only access prevents data modification.",
@@ -5008,18 +5028,8 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
         rule: "Preserve query semantics.",
         reason: "Arbitrary modifications change results.",
         action: 'Only add LIMIT for explicit "top N" requests. Add ORDER BY for deterministic results.'
-      }),
-      guardrail2({
-        rule: "Seek clarification for genuine ambiguity.",
-        reason: "Prevents incorrect assumptions.",
-        action: "Ask a focused question before guessing."
       })
     ),
-    clarification({
-      when: "Ambiguous ranking language (top, best, active) without a metric.",
-      ask: "Clarify the ranking metric or definition.",
-      reason: "Ensures correct aggregation and ordering."
-    }),
     hint2(
       'Use sample cell values from schema hints to match exact casing and format in WHERE conditions (e.g., "Male" vs "male" vs "M").'
     ),
@@ -5079,7 +5089,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
       notes: "If reference is ambiguous, ask which previous result or entity the user means."
     }),
     fragment2(
-      "Bash tool usage",
+      "bash_tool_usage",
       workflow2({
         task: "Query execution",
         steps: [
@@ -5089,35 +5099,44 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
           "For large results, slice first: cat <path> | jq '.[:10]'"
         ]
       }),
-      hint2(
-        `You cannot access sql through a tool, it'll fail so the proper way to access it is through the bash tool using "sql run" and "sql validate" commands.`
-      ),
-      hint2(
-        "The sql command outputs: file path, column names (comma-separated), and row count. Use column names to construct precise jq queries."
-      ),
-      hint2(
-        'This is virtual bash environment and "sql" commands proxy to the database hence you cannot access sql files directly.'
-      ),
-      hint2(
-        "If a query fails, the sql command returns an error message in stderr."
-      )
-    )
-  ];
-  if (date === "strict") {
-    baseTeachings.push(
+      guardrail2({
+        rule: "Do not attempt SQL access through non-bash tools.",
+        reason: "SQL access is only available through the virtual bash environment.",
+        action: 'Use "sql run" and "sql validate" through bash.'
+      }),
+      explain({
+        concept: "sql command output format",
+        explanation: "The sql command returns a file path, comma-separated column names, and a row count.",
+        therefore: "Use the returned column names to build precise jq queries against the output file."
+      }),
+      quirk({
+        issue: "This is a virtual bash environment, so you cannot access underlying SQL files directly.",
+        workaround: "Treat the returned result path as the artifact to inspect, rather than trying to access SQL files themselves."
+      }),
+      quirk({
+        issue: "If a query fails, the sql command reports the error on stderr.",
+        workaround: "Read stderr first and classify the failure before retrying or changing the query."
+      })
+    ),
+    fragment2(
+      "clarifications",
+      guardrail2({
+        rule: "Do not invent an answer when the available schema, results, or user request are insufficient to determine it.",
+        reason: "Prevents hallucinations and improves trustworthiness.",
+        action: "State that you do not have enough information to determine the answer and ask a focused clarification question."
+      }),
+      clarification({
+        when: "Ambiguous ranking language (top, best, active) without a metric.",
+        ask: "Clarify the ranking metric or definition.",
+        reason: "Ensures correct aggregation and ordering."
+      }),
       clarification({
         when: "The request targets time-based data without a date range.",
         ask: "Confirm the intended timeframe (e.g., last 30/90 days, YTD, specific year).",
         reason: "Prevents large scans and irrelevant results."
       })
-    );
-  } else {
-    baseTeachings.push(
-      hint2(
-        'When a month, day, or time period is mentioned without a year (e.g., "in August", "on Monday"), assume ALL occurrences of that period in the data. Do not ask for year clarification.'
-      )
-    );
-  }
+    )
+  ];
   return baseTeachings;
 }
 
@@ -5143,7 +5162,6 @@ var Text2Sql = class {
   #config;
   constructor(config) {
     this.#config = {
-      teachingsOptions: config.teachingsOptions,
       adapter: config.adapter,
       context: config.context,
       tools: config.tools ?? {},
@@ -5207,7 +5225,7 @@ var Text2Sql = class {
     }
     const trackedFs = new TrackedFs(this.#config.filesystem);
     const context = this.#config.context(
-      ...guidelines(this.#config.teachingsOptions),
+      ...guidelines(),
       ...await this.index()
     );
     const lastItem = messages[messages.length - 1];
@@ -5318,6 +5336,7 @@ export {
   MssqlFs,
   Point,
   PostgresFs,
+  SQLScopeError,
   SQLValidationError,
   ScopedFs,
   SqliteFs,