@deepagents/text2sql 0.29.1 → 0.31.0

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

@@ -1,5 +1,5 @@
 import { type SqlLanguage } from 'sql-formatter';
-import type { ContextFragment } from '@deepagents/context';
+import type { ContextFragment, FragmentObject } from '@deepagents/context';
 import type { AbstractGrounding } from './groundings/abstract.grounding.ts';
 import { type GroundingContext } from './groundings/context.ts';
 /**
@@ -63,7 +63,7 @@ export interface AdapterInfo {
     dialect: string;
     version?: string;
     database?: string;
-    details?: Record<string, unknown>;
+    details?: FragmentObject;
 }
 export type AdapterInfoProvider = AdapterInfo | (() => Promise<AdapterInfo> | AdapterInfo);
 export type IntrospectionPhase = 'tables' | 'row_counts' | 'primary_keys' | 'indexes' | 'column_stats' | 'low_cardinality' | 'relationships';
@@ -110,8 +110,10 @@ export declare abstract class Adapter {
      */
     resolveAllowedEntities(): Promise<string[]>;
     format(sql: string): string;
-    abstract execute(sql: string): Promise<any[]> | any[];
-    abstract validate(sql: string): Promise<string | void> | string | void;
+    validate(sql: string): Promise<string | void>;
+    execute(sql: string): Promise<any[]>;
+    abstract executeImpl(sql: string): Promise<any[]> | any[];
+    abstract validateImpl(sql: string): Promise<string | void> | string | void;
     abstract runQuery<Row>(sql: string): Promise<Row[]> | Row[];
     /**
      * Quote an identifier (table/column name) for safe use in SQL.

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

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/adapter.ts"],"names":[],"mappings":"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"}

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

@@ -32,8 +32,8 @@ export declare class BigQuery extends Adapter {
      * Uses standard BigQuery backtick quoting on the full path.
      */
     infoSchemaView(dataset: string, viewName: string): string;
-    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/bigquery/bigquery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bigquery.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/bigquery/bigquery.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2BF,qBAAa,QAAS,SAAQ,OAAO;;IAInC,SAAkB,SAAS,EAAE,WAAW,EAAE,CAAC;IAC3C,SAAkB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IACpD,SAAkB,aAAa,EAAE,MAAM,EAAE,CAAM;IAC/C,SAAkB,iBAAiB,cAAc;gBAErC,OAAO,EAAE,sBAAsB;IA2B3C,IAAI,QAAQ,IAAI,SAAS,MAAM,EAAE,CAEhC;IAED,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI1C;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAK1C,OAAO,CAAC,GAAG,EAAE,MAAM;IAInB,QAAQ,CAAC,GAAG,EAAE,MAAM;IAQpB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAqBhD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASrC,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;CAsBV"}
+{"version":3,"file":"bigquery.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/bigquery/bigquery.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB;;OAEG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2BF,qBAAa,QAAS,SAAQ,OAAO;;IAInC,SAAkB,SAAS,EAAE,WAAW,EAAE,CAAC;IAC3C,SAAkB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IACpD,SAAkB,aAAa,EAAE,MAAM,EAAE,CAAM;IAC/C,SAAkB,iBAAiB,cAAc;gBAErC,OAAO,EAAE,sBAAsB;IA2B3C,IAAI,QAAQ,IAAI,SAAS,MAAM,EAAE,CAEhC;IAED,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI1C;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAK1C,WAAW,CAAC,GAAG,EAAE,MAAM;IAIvB,YAAY,CAAC,GAAG,EAAE,MAAM;IAQxB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAqBhD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASrC,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;CAsBV"}

package/dist/lib/adapters/bigquery/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.
@@ -547,11 +818,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;
   }
@@ -565,7 +838,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;
@@ -589,11 +864,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 });
@@ -609,11 +888,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 });
@@ -653,6 +936,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/bigquery/bigquery.ts
@@ -710,14 +1003,14 @@ var BigQuery = class extends Adapter {
     const projectPrefix = this.projectId ? `${this.projectId}.` : "";
     return `\`${projectPrefix}${dataset}.INFORMATION_SCHEMA.${viewName}\``;
   }
-  async execute(sql) {
+  async executeImpl(sql) {
     return this.#options.execute(sql);
   }
-  async validate(sql) {
+  async validateImpl(sql) {
     try {
       return await this.#options.validate(sql);
     } catch (error) {
-      return JSON.stringify(formatBigQueryError(sql, error));
+      return JSON.stringify(formatBigQueryError(this.format(sql), error));
     }
   }
   async runQuery(sql) {
@@ -1364,10 +1657,12 @@ var BigQueryTableGrounding = class extends TableGrounding {
 // packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
 var ViewGrounding = class extends AbstractGrounding {
   #filter;
+  #columns;
   includeDefinition;
   constructor(config = {}) {
     super("view");
     this.#filter = config.filter;
+    this.#columns = config.columns;
     this.includeDefinition = config.includeDefinition ?? true;
   }
   /**
@@ -1377,7 +1672,9 @@ var ViewGrounding = class extends AbstractGrounding {
   async execute(ctx) {
     const viewNames = await this.applyFilter();
     const views2 = await Promise.all(
-      viewNames.map((name) => this.getView(name))
+      viewNames.map(
+        async (name) => applyColumnFilter(await this.getView(name), this.#columns)
+      )
     );
     ctx.views.push(...views2);
   }