@deepagents/text2sql 0.29.1 → 0.31.0

package/dist/lib/adapters/postgres/postgres.d.ts

@@ -18,8 +18,8 @@ export declare class Postgres extends Adapter {
     readonly systemSchemas: string[];
     readonly formatterLanguage = "postgresql";
     constructor(options: PostgresAdapterOptions);
-    execute(sql: string): Promise<any>;
-    validate(sql: string): Promise<string | void>;
+    executeImpl(sql: string): Promise<any>;
+    validateImpl(sql: string): Promise<string | void>;
     runQuery<Row>(sql: string): Promise<Row[]>;
     quoteIdentifier(name: string): string;
     escape(value: string): string;

package/dist/lib/adapters/postgres/postgres.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/postgres/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,WAAW,EAKhB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAwEF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;;;;;EA0B9D;AAED,qBAAa,QAAS,SAAQ,OAAO;;IAEnC,SAAkB,SAAS,EAAE,WAAW,EAAE,CAAC;IAC3C,SAAkB,aAAa,YAAY;IAC3C,SAAkB,aAAa,WAAwC;IACvE,SAAkB,iBAAiB,gBAAgB;gBAEvC,OAAO,EAAE,sBAAsB;IAY5B,OAAO,CAAC,GAAG,EAAE,MAAM;IAInB,QAAQ,CAAC,GAAG,EAAE,MAAM;IAcpB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAIhD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI7B,oBAAoB,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GACZ,MAAM;CAmdV"}
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/postgres/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,WAAW,EAKhB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAwEF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;;;;;EA0B9D;AAED,qBAAa,QAAS,SAAQ,OAAO;;IAEnC,SAAkB,SAAS,EAAE,WAAW,EAAE,CAAC;IAC3C,SAAkB,aAAa,YAAY;IAC3C,SAAkB,aAAa,WAAwC;IACvE,SAAkB,iBAAiB,gBAAgB;gBAEvC,OAAO,EAAE,sBAAsB;IAY5B,WAAW,CAAC,GAAG,EAAE,MAAM;IAIvB,YAAY,CAAC,GAAG,EAAE,MAAM;IAcxB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAIhD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI7B,oBAAoB,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GACZ,MAAM;CAmdV"}

package/dist/lib/adapters/spreadsheet/index.js

@@ -1,6 +1,48 @@
 // packages/text2sql/src/lib/adapters/adapter.ts
 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 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;
+  }
+};
+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/fragments/schema.ts
 function dialectInfo(input) {
   return {
@@ -104,6 +146,134 @@ function createGroundingContext() {
   };
 }
 
+// packages/text2sql/src/lib/adapters/runtime-scope.ts
+import nodeSqlParser from "node-sql-parser";
+var { Parser } = nodeSqlParser;
+var parser = new Parser();
+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 Adapter = class {
   /**
@@ -133,10 +303,7 @@ var Adapter = class {
       const grounding = fn(this);
       await grounding.execute(ctx);
     }
-    return [
-      ...ctx.tables.map((t) => t.name),
-      ...ctx.views.map((v) => v.name)
-    ];
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
   }
   /**
    * Convert complete grounding context to schema fragments.
@@ -149,7 +316,8 @@ var Adapter = class {
         dialectInfo({
           dialect: ctx.info.dialect,
           version: ctx.info.version,
-          database: ctx.info.database
+          database: ctx.info.database,
+          details: ctx.info.details
         })
       );
     }
@@ -160,7 +328,18 @@ var Adapter = class {
       fragments.push(this.#viewToFragment(v));
     }
     const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
+    const tableColumnSets = new Map(
+      ctx.tables.map((t) => [t.name, new Set(t.columns.map((c) => c.name))])
+    );
     for (const rel of ctx.relationships) {
+      const sourceColumns = tableColumnSets.get(rel.table);
+      const targetColumns = tableColumnSets.get(rel.referenced_table);
+      if (sourceColumns && rel.from.some((column2) => !sourceColumns.has(column2))) {
+        continue;
+      }
+      if (targetColumns && rel.to.some((column2) => !targetColumns.has(column2))) {
+        continue;
+      }
       const sourceTable = tableMap.get(rel.table);
       const targetTable = tableMap.get(rel.referenced_table);
       fragments.push(
@@ -215,7 +394,10 @@ var Adapter = class {
         stats: col.stats
       })
     );
-    const indexFragments = (t.indexes ?? []).map(
+    const presentColumns = new Set(t.columns.map((c) => c.name));
+    const indexFragments = (t.indexes ?? []).filter(
+      (idx) => idx.columns.every((column2) => presentColumns.has(column2))
+    ).map(
       (idx) => index({
         name: idx.name,
         columns: idx.columns,
@@ -225,6 +407,8 @@ var Adapter = class {
     );
     const constraintFragments = (t.constraints ?? []).filter(
       (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).filter(
+      (c) => !c.columns?.length || c.columns.every((column2) => presentColumns.has(column2))
     ).map(
       (c) => constraint({
         name: c.name,
@@ -293,6 +477,78 @@ var Adapter = class {
       return sql;
     }
   }
+  #cachedAllowedEntities = null;
+  async #resolveScope() {
+    if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
+    this.#cachedAllowedEntities = await this.resolveAllowedEntities();
+    return this.#cachedAllowedEntities;
+  }
+  async #checkScope(sql, allowedEntities) {
+    const dialect = this.formatterLanguage;
+    const scopeDialects = {
+      sqlite: "mysql",
+      postgresql: "postgresql",
+      bigquery: "bigquery",
+      transactsql: "transactsql",
+      mysql: "mysql"
+    };
+    const scopeDialect = scopeDialects[dialect];
+    if (!scopeDialect) {
+      throw new TypeError(
+        `No scope dialect mapping for formatter language "${dialect}". Add it to the scopeDialects map in Adapter.#checkScope.`
+      );
+    }
+    let references;
+    try {
+      references = extractBaseEntityReferences(sql, scopeDialect);
+    } catch (error) {
+      return buildScopeParseErrorPayload(
+        sql,
+        dialect,
+        error
+      );
+    }
+    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);
+    });
+    if (outOfScope.length === 0) return null;
+    return buildOutOfScopePayload(sql, outOfScope, allowedEntities);
+  }
+  async validate(sql) {
+    const allowed = await this.#resolveScope();
+    const scopeError = await this.#checkScope(sql, allowed);
+    if (scopeError) return JSON.stringify(scopeError);
+    return this.validateImpl(sql);
+  }
+  async execute(sql) {
+    const allowed = await this.#resolveScope();
+    const scopeError = await this.#checkScope(sql, allowed);
+    if (scopeError) throw new SQLScopeError(scopeError);
+    return this.executeImpl(sql);
+  }
   /**
    * Convert unknown database value to number.
    * Handles number, bigint, and string types.
@@ -346,6 +602,21 @@ var Adapter = class {
 };
 
 // packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
+function filterColumns(columns, filter) {
+  if (Array.isArray(filter)) {
+    return columns.filter((col) => filter.includes(col.name));
+  }
+  if (filter instanceof RegExp) {
+    return columns.filter((col) => filter.test(col.name));
+  }
+  return columns.filter((col) => filter(col.name));
+}
+function applyColumnFilter(entity, columnsConfig) {
+  if (!columnsConfig) return entity;
+  const filter = columnsConfig[entity.name];
+  if (!filter) return entity;
+  return { ...entity, columns: filterColumns(entity.columns, filter) };
+}
 var AbstractGrounding = class {
   /**
    * Grounding identifier for debugging/logging.
@@ -588,11 +859,13 @@ var RowCountGrounding = class extends AbstractGrounding {
 // packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
 var TableGrounding = class extends AbstractGrounding {
   #filter;
+  #columns;
   #forward;
   #backward;
   constructor(config = {}) {
     super("table");
     this.#filter = config.filter;
+    this.#columns = config.columns;
     this.#forward = config.forward;
     this.#backward = config.backward;
   }
@@ -606,7 +879,9 @@ var TableGrounding = class extends AbstractGrounding {
     const backward = this.#backward;
     if (!forward && !backward) {
       const tables3 = await Promise.all(
-        seedTables.map((name) => this.getTable(name))
+        seedTables.map(
+          async (name) => applyColumnFilter(await this.getTable(name), this.#columns)
+        )
       );
       ctx.tables.push(...tables3);
       return;
@@ -630,11 +905,15 @@ var TableGrounding = class extends AbstractGrounding {
       if (forwardVisited.has(name)) continue;
       forwardVisited.add(name);
       if (!tables2[name]) {
-        tables2[name] = await this.getTable(name);
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
       }
       if (depth < forwardLimit) {
         const rels = await this.findOutgoingRelations(name);
         for (const rel of rels) {
+          if (!this.isRelationshipVisible(rel)) continue;
           this.addRelationship(rel, allRelationships, seenRelationships);
           if (!forwardVisited.has(rel.referenced_table)) {
             forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
@@ -650,11 +929,15 @@ var TableGrounding = class extends AbstractGrounding {
       if (backwardVisited.has(name)) continue;
       backwardVisited.add(name);
       if (!tables2[name]) {
-        tables2[name] = await this.getTable(name);
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
       }
       if (depth < backwardLimit) {
         const rels = await this.findIncomingRelations(name);
         for (const rel of rels) {
+          if (!this.isRelationshipVisible(rel)) continue;
           this.addRelationship(rel, allRelationships, seenRelationships);
           if (!backwardVisited.has(rel.table)) {
             backwardQueue.push({ name: rel.table, depth: depth + 1 });
@@ -694,6 +977,16 @@ var TableGrounding = class extends AbstractGrounding {
       all.push(rel);
     }
   }
+  isRelationshipVisible(rel) {
+    return this.areColumnsVisible(rel.from, this.#columns?.[rel.table]) && this.areColumnsVisible(rel.to, this.#columns?.[rel.referenced_table]);
+  }
+  areColumnsVisible(names, filter) {
+    if (!filter) return true;
+    return filterColumns(
+      names.map((name) => ({ name })),
+      filter
+    ).length === names.length;
+  }
 };
 
 // packages/text2sql/src/lib/adapters/sqlite/column-stats.sqlite.grounding.ts
@@ -919,10 +1212,10 @@ var Sqlite = class extends Adapter {
     this.#options = options;
     this.grounding = options.grounding;
   }
-  async execute(sql) {
+  async executeImpl(sql) {
     return this.#options.execute(sql);
   }
-  async validate(sql) {
+  async validateImpl(sql) {
     const validator = this.#options.validate ?? (async (text) => {
       await this.#options.execute(`EXPLAIN ${text}`);
     });