@deepagents/text2sql 5.0.0 → 6.1.0

package/dist/index.js

@@ -22,10 +22,10 @@ function validateAdapterNames(names) {
 import { format as formatSql } from "sql-formatter";
 
 // packages/text2sql/src/lib/agents/exceptions.ts
-var sqlValidationMarker = Symbol("SQLValidationError");
-var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
-var sqlScopeMarker = Symbol("SQLScopeError");
-var sqlReadOnlyMarker = Symbol("SQLReadOnlyError");
+var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
+var unanswerableSqlMarker = /* @__PURE__ */ Symbol("UnanswerableSQLError");
+var sqlScopeMarker = /* @__PURE__ */ Symbol("SQLScopeError");
+var sqlReadOnlyMarker = /* @__PURE__ */ Symbol("SQLReadOnlyError");
 var SQLValidationError = class _SQLValidationError extends Error {
   [sqlValidationMarker];
   constructor(message) {
@@ -185,164 +185,21 @@ function createGroundingContext(options = {}) {
     views: [],
     relationships: [],
     info: void 0,
+    fragments: [],
     cache: /* @__PURE__ */ new Map(),
     onProgress: timestampProgress(options.onProgress)
   };
 }
 
-// packages/text2sql/src/lib/adapters/runtime-scope.ts
-import nodeSqlParser from "node-sql-parser";
-var { Parser } = nodeSqlParser;
-var parser = new Parser();
-function parseStatementTypes(sql, dialect) {
-  const ast = parser.astify(sql, { database: dialect });
-  const statements = Array.isArray(ast) ? ast : [ast];
-  return statements.flatMap(
-    (statement) => isAstLike(statement) && typeof statement.type === "string" ? [statement.type] : []
-  );
-}
-function extractBaseEntityReferences(sql, dialect) {
-  const ast = parser.astify(sql, { database: dialect });
-  const state = {
-    cteNames: /* @__PURE__ */ new Set(),
-    references: /* @__PURE__ */ new Map()
-  };
-  visitNode(ast, state);
-  return Array.from(state.references.values());
-}
-function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
-  return {
-    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
-    error_type: "OUT_OF_SCOPE",
-    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
-    sql_attempted: sql,
-    referenced_entities: referencedEntities,
-    allowed_entities: allowedEntities
-  };
-}
-function buildScopeParseErrorPayload(sql, dialect, error) {
-  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
-  return {
-    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
-    error_type: "SQL_SCOPE_PARSE_ERROR",
-    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
-    sql_attempted: sql,
-    parser_dialect: dialect,
-    parser_error: parserError
-  };
-}
-function visitNode(node, state) {
-  if (Array.isArray(node)) {
-    for (const item of node) {
-      visitNode(item, state);
-    }
-    return;
-  }
-  if (!isAstLike(node)) {
-    return;
-  }
-  if (isStatementNode(node)) {
-    visitStatement(node, state);
-    return;
-  }
-  if (isTableReferenceNode(node)) {
-    addReference(node, state);
-  }
-  for (const value of Object.values(node)) {
-    visitNode(value, state);
-  }
-}
-function visitStatement(node, parentState) {
-  const localState = {
-    cteNames: new Set(parentState.cteNames),
-    references: parentState.references
-  };
-  const withItems = Array.isArray(node.with) ? node.with : [];
-  for (const item of withItems) {
-    if (!isAstLike(item)) {
-      continue;
-    }
-    const cteName = readCteName(item);
-    if (cteName) {
-      localState.cteNames.add(caseFold(cteName));
-    }
-  }
-  for (const item of withItems) {
-    if (!isAstLike(item)) {
-      continue;
-    }
-    visitNode(item.stmt, localState);
-  }
-  for (const [key, value] of Object.entries(node)) {
-    if (key === "with") {
-      continue;
-    }
-    visitNode(value, localState);
-  }
-}
-function addReference(node, state) {
-  const table2 = typeof node.table === "string" ? node.table : null;
-  if (!table2) {
-    return;
-  }
-  if (state.cteNames.has(caseFold(table2))) {
-    return;
-  }
-  const db = typeof node.db === "string" ? node.db : null;
-  const key = db ? `${db}.${table2}` : table2;
-  if (!state.references.has(key)) {
-    state.references.set(key, { db, table: table2 });
-  }
-}
-function readCteName(node) {
-  const name = node.name;
-  if (typeof name === "string") {
-    return name;
-  }
-  if (!isAstLike(name)) {
-    return void 0;
-  }
-  const value = name.value;
-  return typeof value === "string" ? value : void 0;
-}
-function isStatementNode(node) {
-  const type = node.type;
-  return typeof type === "string" && ["delete", "insert", "replace", "select", "update"].includes(type);
-}
-function isTableReferenceNode(node) {
-  if (node.type === "column_ref") {
-    return false;
-  }
-  if (typeof node.table !== "string") {
-    return false;
-  }
-  return "addition" in node || "as" in node || "db" in node || "join" in node || "operator" in node || "surround" in node || "table_hint" in node || "temporal_table" in node;
-}
-function isAstLike(value) {
-  return typeof value === "object" && value !== null;
-}
-function caseFold(value) {
-  return value.toLowerCase();
-}
-
 // packages/text2sql/src/lib/adapters/adapter.ts
-var PARSER_DIALECTS_BY_FORMATTER_LANGUAGE = {
-  sqlite: ["sqlite", "mysql"],
-  postgresql: ["postgresql"],
-  bigquery: ["bigquery"],
-  transactsql: ["transactsql"],
-  mysql: ["mysql"]
-};
-function parserDialectsFor(formatterLanguage) {
-  const candidates = PARSER_DIALECTS_BY_FORMATTER_LANGUAGE[formatterLanguage];
-  if (!candidates) {
-    throw new TypeError(
-      `No scope dialect mapping for formatter language "${formatterLanguage}". Add it to PARSER_DIALECTS_BY_FORMATTER_LANGUAGE in adapter.ts.`
-    );
-  }
-  return candidates;
-}
 var Adapter = class {
+  #policyAnalyzer;
+  /**
+   * Injects the strategy that guards validate() and execute().
+   */
+  constructor(policyAnalyzer) {
+    this.#policyAnalyzer = policyAnalyzer;
+  }
   /**
    * Introspect the database schema and return context fragments.
    *
@@ -378,14 +235,14 @@ var Adapter = class {
   }
   /**
    * Resolve the allowed entity names (tables + views) from grounding config.
-   * Runs all configured groundings and returns the resolved set of names.
+   * Asks each grounding to contribute its entities; annotators contribute
+   * nothing, so their metadata scans are skipped.
    * Results are NOT cached — call once and store the result.
    */
   async resolveAllowedEntities() {
     const ctx = createGroundingContext();
     for (const fn of this.grounding) {
-      const grounding = fn(this);
-      await grounding.execute(ctx);
+      await fn(this).contributeEntities(ctx);
     }
     return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
   }
@@ -430,6 +287,7 @@ var Adapter = class {
         this.#relationshipToFragment(rel, sourceTable, targetTable)
       );
     }
+    fragments.push(...ctx.fragments ?? []);
     return fragments;
   }
   /**
@@ -562,120 +420,33 @@ var Adapter = class {
   #decodeShellEscapes(sql) {
     return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*])/g, "$1").replace(/\\(?=$)/gm, "");
   }
-  #checkReadOnly(sql) {
-    const statementTypes = this.#readParsedStatementTypes(sql);
-    if (statementTypes) {
-      if (statementTypes.length === 1 && statementTypes[0] === "select") {
-        return null;
-      }
-      return "only SELECT or WITH queries allowed";
-    }
-    const keyword = this.#firstStatementKeyword(sql);
-    if (keyword === "SELECT" || keyword === "WITH") return null;
-    return "only SELECT or WITH queries allowed";
-  }
-  #readParsedStatementTypes(sql) {
-    for (const dialect of parserDialectsFor(this.formatterLanguage)) {
-      try {
-        return parseStatementTypes(sql, dialect);
-      } catch {
-      }
-    }
-    return null;
-  }
-  #firstStatementKeyword(sql) {
-    let offset = 0;
-    while (offset < sql.length) {
-      if (/\s/.test(sql[offset])) {
-        offset++;
-        continue;
-      }
-      if (sql.startsWith("--", offset)) {
-        offset += 2;
-        while (offset < sql.length && sql[offset] !== "\n" && sql[offset] !== "\r") {
-          offset++;
-        }
-        continue;
-      }
-      if (sql.startsWith("/*", offset)) {
-        const commentEnd = sql.indexOf("*/", offset + 2);
-        if (commentEnd === -1) return null;
-        offset = commentEnd + 2;
-        continue;
-      }
-      const keyword = /^[A-Za-z]+/.exec(sql.slice(offset));
-      return keyword ? keyword[0].toUpperCase() : null;
-    }
-    return null;
-  }
   #cachedAllowedEntities = null;
   async #resolveScope() {
     if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
     this.#cachedAllowedEntities = await this.resolveAllowedEntities();
     return this.#cachedAllowedEntities;
   }
-  async #checkScope(sql, allowedEntities) {
-    const candidates = parserDialectsFor(this.formatterLanguage);
-    let references = null;
-    let lastError;
-    let lastDialect = candidates[0];
-    for (const candidate of candidates) {
-      try {
-        references = extractBaseEntityReferences(sql, candidate);
-        break;
-      } catch (error) {
-        lastDialect = candidate;
-        lastError = error;
-      }
-    }
-    if (references === null) {
-      return buildScopeParseErrorPayload(sql, lastDialect, lastError);
-    }
-    if (references.length === 0) return null;
-    const allowedQualified = new Set(
-      allowedEntities.map((e) => e.toLowerCase())
-    );
-    const allowedUnqualified = /* @__PURE__ */ new Set();
-    for (const entity of allowedEntities) {
-      const dot = entity.lastIndexOf(".");
-      if (dot !== -1) {
-        allowedUnqualified.add(entity.slice(dot + 1).toLowerCase());
-      } else {
-        allowedUnqualified.add(entity.toLowerCase());
-      }
-    }
-    const outOfScope = references.map((ref) => ref.db ? `${ref.db}.${ref.table}` : ref.table).filter((name) => {
-      const lower = name.toLowerCase();
-      if (name.includes(".")) {
-        if (allowedQualified.has(lower)) return false;
-        const parts = lower.split(".");
-        if (parts.length >= 3) {
-          const datasetTable = parts.slice(-2).join(".");
-          if (allowedQualified.has(datasetTable)) return false;
-        }
-        return true;
-      }
-      return !allowedQualified.has(lower) && !allowedUnqualified.has(lower);
+  async #analyzePolicy(sql) {
+    return this.#policyAnalyzer.analyze(sql, {
+      resolveAllowedEntities: () => this.#resolveScope()
     });
-    if (outOfScope.length === 0) return null;
-    return buildOutOfScopePayload(sql, outOfScope, allowedEntities);
   }
   async validate(sql) {
     const decoded = this.#decodeShellEscapes(sql);
-    const readOnlyError = this.#checkReadOnly(decoded);
-    if (readOnlyError) return readOnlyError;
-    const allowed = await this.#resolveScope();
-    const scopeError = await this.#checkScope(decoded, allowed);
-    if (scopeError) return JSON.stringify(scopeError);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") return violation.message;
+    if (violation?.kind === "scope") return JSON.stringify(violation.payload);
     return this.validateImpl(decoded);
   }
   async execute(sql) {
     const decoded = this.#decodeShellEscapes(sql);
-    const readOnlyError = this.#checkReadOnly(decoded);
-    if (readOnlyError) throw new SQLReadOnlyError(readOnlyError);
-    const allowed = await this.#resolveScope();
-    const scopeError = await this.#checkScope(decoded, allowed);
-    if (scopeError) throw new SQLScopeError(scopeError);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") {
+      throw new SQLReadOnlyError(violation.message);
+    }
+    if (violation?.kind === "scope") {
+      throw new SQLScopeError(violation.payload);
+    }
     return this.executeImpl(decoded);
   }
   /**
@@ -827,16 +598,24 @@ import {
   user,
   workflow
 } from "@deepagents/context";
+
+// packages/text2sql/src/lib/sql-scope-error.ts
+function buildScopeParseErrorPayload(sql, parserDialect, error) {
+  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
+    error_type: "SQL_SCOPE_PARSE_ERROR",
+    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
+    sql_attempted: sql,
+    parser_dialect: parserDialect,
+    parser_error: parserError
+  };
+}
+
+// packages/text2sql/src/lib/agents/sql.agent.ts
 var RETRY_TEMPERATURES = [0, 0.2, 0.3];
 var SQL_AGENT_ROLE = "Expert SQL query generator.";
 var SQL_AGENT_OBJECTIVE = "Generate precise SQL grounded in provided schema.";
-var FORMATTER_SCOPE_DIALECTS = /* @__PURE__ */ new Map([
-  ["sqlite", "sqlite"],
-  ["postgresql", "postgresql"],
-  ["bigquery", "bigquery"],
-  ["transactsql", "transactsql"],
-  ["mysql", "mysql"]
-]);
 var SQL_AGENT_POLICIES = [
   fragment(
     "schema_mapping",
@@ -1042,26 +821,6 @@ function extractSql(output) {
   const match = output.match(/```sql\n?([\s\S]*?)```/);
   return match ? match[1].trim() : output.trim();
 }
-function scopeDialectFor(adapter) {
-  const dialect = FORMATTER_SCOPE_DIALECTS.get(adapter.formatterLanguage);
-  if (!dialect) {
-    throw new TypeError(
-      `No scope dialect mapping for formatter language "${adapter.formatterLanguage}".`
-    );
-  }
-  return dialect;
-}
-function fencedMarkdownParseError(sql, adapter) {
-  return new SQLValidationError(
-    JSON.stringify(
-      buildScopeParseErrorPayload(
-        sql,
-        scopeDialectFor(adapter),
-        new Error("SQL response was fenced markdown, not executable SQL.")
-      )
-    )
-  );
-}
 async function toSql(options) {
   const { maxRetries = 3 } = options;
   return withRetry(
@@ -1143,7 +902,17 @@ Question: ${options.input}
         }
         const sql = options.adapter.format(extractedSql);
         if (rawSql.trimStart().startsWith("```") && extractedSql === rawSql.trim()) {
-          throw fencedMarkdownParseError(sql, options.adapter);
+          throw new SQLValidationError(
+            JSON.stringify(
+              buildScopeParseErrorPayload(
+                sql,
+                options.adapter.formatterLanguage,
+                new Error(
+                  "SQL response was fenced markdown, not executable SQL."
+                )
+              )
+            )
+          );
         }
         const validationError = await options.adapter.validate(sql);
         if (validationError) {
@@ -5623,8 +5392,8 @@ import {
 
 // packages/text2sql/src/lib/sql.ts
 import "@deepagents/agent";
-var text2SqlValidationMarker = Symbol("Text2SqlValidationError");
-var text2SqlUnknownAdapterMarker = Symbol("Text2SqlUnknownAdapterError");
+var text2SqlValidationMarker = /* @__PURE__ */ Symbol("Text2SqlValidationError");
+var text2SqlUnknownAdapterMarker = /* @__PURE__ */ Symbol("Text2SqlUnknownAdapterError");
 var Text2SqlValidationError = class _Text2SqlValidationError extends Error {
   [text2SqlValidationMarker];
   constructor(message) {
@@ -5652,7 +5421,7 @@ var Text2SqlUnknownAdapterError = class _Text2SqlUnknownAdapterError extends Err
     return error instanceof _Text2SqlUnknownAdapterError && error[text2SqlUnknownAdapterMarker] === true;
   }
 };
-var text2SqlUnknownDatabaseMarker = Symbol("Text2SqlUnknownDatabaseError");
+var text2SqlUnknownDatabaseMarker = /* @__PURE__ */ Symbol("Text2SqlUnknownDatabaseError");
 var Text2SqlUnknownDatabaseError = class _Text2SqlUnknownDatabaseError extends Error {
   [text2SqlUnknownDatabaseMarker];
   requested;