@deepagents/text2sql 0.2.2 → 0.3.0

package/dist/lib/adapters/groundings/grounding.js

@@ -0,0 +1,507 @@
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+function createGroundingContext() {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0
+  };
+}
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+import pluralize from "pluralize";
+
+// packages/text2sql/src/lib/adapters/grounding.ticket.ts
+var AbstractGrounding = class {
+  tag;
+  constructor(tag) {
+    this.tag = tag;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("tables");
+    this.#filter = config.filter;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered tables and relationships to the context.
+   */
+  async execute(ctx) {
+    const seedTables = await this.applyFilter();
+    const forward = this.#forward;
+    const backward = this.#backward;
+    if (!forward && !backward) {
+      const tables2 = await Promise.all(
+        seedTables.map((name) => this.getTable(name))
+      );
+      ctx.tables.push(...tables2);
+      return () => this.#describeTables(tables2);
+    }
+    const tables = {};
+    const allRelationships = [];
+    const seenRelationships = /* @__PURE__ */ new Set();
+    const forwardQueue = [];
+    const backwardQueue = [];
+    const forwardVisited = /* @__PURE__ */ new Set();
+    const backwardVisited = /* @__PURE__ */ new Set();
+    for (const name of seedTables) {
+      if (forward) forwardQueue.push({ name, depth: 0 });
+      if (backward) backwardQueue.push({ name, depth: 0 });
+    }
+    const forwardLimit = forward === true ? Infinity : forward || 0;
+    while (forwardQueue.length > 0) {
+      const item = forwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (forwardVisited.has(name)) continue;
+      forwardVisited.add(name);
+      if (!tables[name]) {
+        tables[name] = await this.getTable(name);
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!forwardVisited.has(rel.referenced_table)) {
+            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const backwardLimit = backward === true ? Infinity : backward || 0;
+    while (backwardQueue.length > 0) {
+      const item = backwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (backwardVisited.has(name)) continue;
+      backwardVisited.add(name);
+      if (!tables[name]) {
+        tables[name] = await this.getTable(name);
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!backwardVisited.has(rel.table)) {
+            backwardQueue.push({ name: rel.table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const tablesList = Object.values(tables);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
+    return () => this.#describeTables(tablesList);
+  }
+  /**
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+  /**
+   * Add a relationship to the collection, deduplicating by key.
+   */
+  addRelationship(rel, all, seen) {
+    const key = `${rel.table}:${rel.from.join(",")}:${rel.referenced_table}:${rel.to.join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      all.push(rel);
+    }
+  }
+  #describeTables(tables) {
+    if (!tables.length) {
+      return "Schema unavailable.";
+    }
+    return tables.map((table) => {
+      const rowCountInfo = table.rowCount != null ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ""}]` : "";
+      const pkConstraint = table.constraints?.find((c) => c.type === "PRIMARY_KEY");
+      const pkColumns = new Set(pkConstraint?.columns ?? []);
+      const columns = table.columns.map((column) => {
+        const annotations = [];
+        const isPrimaryKey = pkColumns.has(column.name);
+        if (isPrimaryKey) {
+          annotations.push("PK");
+        }
+        if (column.isIndexed && !isPrimaryKey) {
+          annotations.push("Indexed");
+        }
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const indexes = table.indexes?.length ? `
+  Indexes:
+${table.indexes.map((index) => {
+        const props = [];
+        if (index.unique) {
+          props.push("UNIQUE");
+        }
+        if (index.type) {
+          props.push(index.type);
+        }
+        const propsText = props.length ? ` (${props.join(", ")})` : "";
+        const columnsText = index.columns?.length ? index.columns.join(", ") : "expression";
+        return `    - ${index.name}${propsText}: ${columnsText}`;
+      }).join("\n")}` : "";
+      return `- Table: ${table.name}${rowCountInfo}
+  Columns:
+${columns}${indexes}`;
+    }).join("\n\n");
+  }
+  #formatTableLabel = (tableName) => {
+    const base = tableName.split(".").pop() ?? tableName;
+    return base.replace(/_/g, " ");
+  };
+  #describeRelationships = (tables, relationships) => {
+    if (!relationships.length) {
+      return "None detected";
+    }
+    const tableMap = new Map(tables.map((table) => [table.name, table]));
+    return relationships.map((relationship) => {
+      const sourceLabel = this.#formatTableLabel(relationship.table);
+      const targetLabel = this.#formatTableLabel(
+        relationship.referenced_table
+      );
+      const singularSource = pluralize.singular(sourceLabel);
+      const pluralSource = pluralize.plural(sourceLabel);
+      const singularTarget = pluralize.singular(targetLabel);
+      const pluralTarget = pluralize.plural(targetLabel);
+      const sourceTable = tableMap.get(relationship.table);
+      const targetTable = tableMap.get(relationship.referenced_table);
+      const sourceCount = sourceTable?.rowCount;
+      const targetCount = targetTable?.rowCount;
+      const ratio = sourceCount != null && targetCount != null && targetCount > 0 ? sourceCount / targetCount : null;
+      let cardinality = "each";
+      if (ratio != null) {
+        if (ratio > 5) {
+          cardinality = `many-to-one (\u2248${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 1.2 && ratio > 0.8) {
+          cardinality = `roughly 1:1 (${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 0.2) {
+          cardinality = `one-to-many (${sourceCount} vs ${targetCount})`;
+        }
+      }
+      const mappings = relationship.from.map((fromCol, idx) => {
+        const targetCol = relationship.to[idx] ?? relationship.to[0] ?? fromCol;
+        return `${relationship.table}.${fromCol} -> ${relationship.referenced_table}.${targetCol}`;
+      }).join(", ");
+      return `- ${relationship.table} (${relationship.from.join(", ")}) -> ${relationship.referenced_table} (${relationship.to.join(", ")}) [${cardinality}]`;
+    }).join("\n");
+  };
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
+var ColumnStatsGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("column_stats");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with statistics.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const stats = await this.collectStats(container.name, column);
+          if (stats) {
+            column.stats = stats;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting stats for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/low-cardinality.grounding.ts
+var LowCardinalityGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("low_cardinality");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with low cardinality values.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const lowCard = await this.collectLowCardinality(
+            container.name,
+            column
+          );
+          if (lowCard) {
+            column.kind = lowCard.kind;
+            column.values = lowCard.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting low cardinality values for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialect_info");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+    const lines = [`Dialect: ${ctx.info.dialect ?? "unknown"}`];
+    if (ctx.info.version) {
+      lines.push(`Version: ${ctx.info.version}`);
+    }
+    if (ctx.info.database) {
+      lines.push(`Database: ${ctx.info.database}`);
+    }
+    if (ctx.info.details && Object.keys(ctx.info.details).length) {
+      lines.push(`Details: ${JSON.stringify(ctx.info.details)}`);
+    }
+    return () => lines.join("\n");
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  constructor(config = {}) {
+    super("views");
+    this.#filter = config.filter;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered views to the context.
+   */
+  async execute(ctx) {
+    const viewNames = await this.applyFilter();
+    const views = await Promise.all(
+      viewNames.map((name) => this.getView(name))
+    );
+    ctx.views.push(...views);
+    return () => this.#describe(views);
+  }
+  #describe(views) {
+    if (!views.length) {
+      return "No views available.";
+    }
+    return views.map((view) => {
+      const columns = view.columns.map((column) => {
+        const annotations = [];
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const definition = view.definition ? `
+  Definition: ${view.definition.length > 200 ? view.definition.slice(0, 200) + "..." : view.definition}` : "";
+      return `- View: ${view.name}${definition}
+  Columns:
+${columns}`;
+    }).join("\n\n");
+  }
+  /**
+   * Apply the filter to get view names.
+   * If filter is an explicit array, skip querying all view names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllViewNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
+import { groq } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent from "dedent";
+import z from "zod";
+import {
+  agent,
+  generate,
+  toState,
+  user
+} from "@deepagents/agent";
+var ReportGrounding = class extends AbstractGrounding {
+  #adapter;
+  #model;
+  #cache;
+  #forceRefresh;
+  constructor(adapter, config = {}) {
+    super("business_context");
+    this.#adapter = adapter;
+    this.#model = config.model ?? groq("openai/gpt-oss-20b");
+    this.#cache = config.cache;
+    this.#forceRefresh = config.forceRefresh ?? false;
+  }
+  async execute(ctx) {
+    if (!this.#forceRefresh && this.#cache) {
+      const cached = await this.#cache.get();
+      if (cached) {
+        ctx.report = cached;
+        return () => cached;
+      }
+    }
+    const report = await this.#generateReport();
+    ctx.report = report;
+    if (this.#cache) {
+      await this.#cache.set(report);
+    }
+    return () => report;
+  }
+  async #generateReport() {
+    const reportAgent = agent({
+      name: "db-report-agent",
+      model: this.#model,
+      prompt: () => dedent`
+        <identity>
+          You are a database analyst expert. Your job is to understand what
+          a database represents and provide business context about it.
+          You have READ-ONLY access to the database.
+        </identity>
+
+        <instructions>
+          Write a business context that helps another agent answer questions accurately.
+
+          For EACH table, do queries ONE AT A TIME:
+          1. SELECT COUNT(*) to get row count
+          2. SELECT * LIMIT 3 to see sample data
+
+          Then write a report with:
+          - What business this database is for
+          - For each table: purpose, row count, and example of what the data looks like
+
+          Include concrete examples like "Track prices are $0.99",
+          "Customer names like 'Luís Gonçalves'", etc.
+
+          Keep it 400-600 words, conversational style.
+        </instructions>
+      `,
+      tools: {
+        query_database: tool({
+          description: "Execute a SELECT query to explore the database and gather insights.",
+          inputSchema: z.object({
+            sql: z.string().describe("The SELECT query to execute"),
+            purpose: z.string().describe(
+              "What insight you are trying to gather with this query"
+            )
+          }),
+          execute: ({ sql }, options) => {
+            const state = toState(options);
+            return state.adapter.execute(sql);
+          }
+        })
+      }
+    });
+    const { text } = await generate(
+      reportAgent,
+      [
+        user(
+          "Please analyze the database and write a contextual report about what this database represents."
+        )
+      ],
+      { adapter: this.#adapter }
+    );
+    return text;
+  }
+};
+export {
+  ColumnStatsGrounding,
+  InfoGrounding,
+  LowCardinalityGrounding,
+  ReportGrounding,
+  TableGrounding,
+  ViewGrounding,
+  createGroundingContext
+};
+//# sourceMappingURL=grounding.js.map

package/dist/lib/adapters/groundings/grounding.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/lib/adapters/groundings/context.ts", "../../../../src/lib/adapters/groundings/table.grounding.ts", "../../../../src/lib/adapters/grounding.ticket.ts", "../../../../src/lib/adapters/groundings/column-stats.grounding.ts", "../../../../src/lib/adapters/groundings/low-cardinality.grounding.ts", "../../../../src/lib/adapters/groundings/info.grounding.ts", "../../../../src/lib/adapters/groundings/view.grounding.ts", "../../../../src/lib/adapters/groundings/report.grounding.ts"],
+  "sourcesContent": ["import type { AdapterInfo, ColumnStats, Relationship, Table } from '../adapter.ts';\nimport type { View } from './view.grounding.ts';\n\n/**\n * Column type for grounding operations.\n * Common interface between Table.columns and View.columns.\n */\nexport interface Column {\n  name: string;\n  type: string;\n  kind?: 'LowCardinality';\n  values?: string[];\n  stats?: ColumnStats;\n}\n\n/**\n * Entity with columns (Table or View).\n */\nexport interface ColumnContainer {\n  name: string;\n  columns: Column[];\n}\n\n/**\n * Shared context object passed to all groundings.\n * Groundings read from and write to this context.\n */\nexport interface GroundingContext {\n  /** Tables discovered by TableGrounding */\n  tables: Table[];\n\n  /** Views discovered by ViewGrounding */\n  views: View[];\n\n  /** Relationships discovered by TableGrounding */\n  relationships: Relationship[];\n\n  /** Database info collected by InfoGrounding */\n  info?: AdapterInfo;\n\n  /** Business context report generated by ReportGrounding */\n  report?: string;\n}\n\n/**\n * Create a new empty grounding context.\n */\nexport function createGroundingContext(): GroundingContext {\n  return {\n    tables: [],\n    views: [],\n    relationships: [],\n    info: undefined,\n  };\n}\n", "import pluralize from 'pluralize';\n\nimport type { Filter, Relationship, Table } from '../adapter.ts';\nimport { AbstractGrounding } from '../grounding.ticket.ts';\nimport type { GroundingContext } from './context.ts';\n\n/**\n * Configuration for TableGrounding.\n */\nexport interface TableGroundingConfig {\n  /** Filter to select seed tables */\n  filter?: Filter;\n  /**\n   * Traverse forward (child\uFFFDparent) following FK direction.\n   * - true: unlimited depth\n   * - number: maximum depth\n   * - false/undefined: no forward traversal\n   */\n  forward?: boolean | number;\n  /**\n   * Traverse backward (parent\uFFFDchild) finding tables that reference us.\n   * - true: unlimited depth\n   * - number: maximum depth\n   * - false/undefined: no backward traversal\n   */\n  backward?: boolean | number;\n}\n\n/**\n * Abstract base class for table grounding.\n *\n * The `execute()` method implements a BFS traversal algorithm that discovers\n * tables and relationships. Subclasses implement the database-specific hooks:\n * - `getAllTableNames()` - list all tables\n * - `getTable()` - get table metadata\n * - `findOutgoingRelations()` - find FKs FROM a table\n * - `findIncomingRelations()` - find FKs TO a table\n */\nexport abstract class TableGrounding extends AbstractGrounding {\n  #filter?: Filter;\n  #forward?: boolean | number;\n  #backward?: boolean | number;\n\n  constructor(config: TableGroundingConfig = {}) {\n    super('tables');\n    this.#filter = config.filter;\n    this.#forward = config.forward;\n    this.#backward = config.backward;\n  }\n\n  /** Get all table names in the database */\n  protected abstract getAllTableNames(): Promise<string[]>;\n\n  /** Get full table metadata for a single table */\n  protected abstract getTable(tableName: string): Promise<Table>;\n\n  /** Find FKs FROM this table (outgoing relationships) */\n  protected abstract findOutgoingRelations(\n    tableName: string,\n  ): Promise<Relationship[]>;\n\n  /** Find FKs TO this table (incoming relationships) */\n  protected abstract findIncomingRelations(\n    tableName: string,\n  ): Promise<Relationship[]>;\n\n  /**\n   * Execute the grounding process.\n   * Writes discovered tables and relationships to the context.\n   */\n  async execute(ctx: GroundingContext) {\n    const seedTables = await this.applyFilter();\n    const forward = this.#forward;\n    const backward = this.#backward;\n\n    // No traversal at all - just add the seed tables\n    if (!forward && !backward) {\n      const tables = await Promise.all(\n        seedTables.map((name) => this.getTable(name)),\n      );\n      ctx.tables.push(...tables);\n      return () => this.#describeTables(tables);\n    }\n\n    const tables: Record<string, Table> = {};\n    const allRelationships: Relationship[] = [];\n    const seenRelationships = new Set<string>();\n\n    // Track depth separately for forward/backward using BFS\n    const forwardQueue: Array<{ name: string; depth: number }> = [];\n    const backwardQueue: Array<{ name: string; depth: number }> = [];\n    const forwardVisited = new Set<string>();\n    const backwardVisited = new Set<string>();\n\n    // Initialize queues with seed tables at depth 0\n    for (const name of seedTables) {\n      if (forward) forwardQueue.push({ name, depth: 0 });\n      if (backward) backwardQueue.push({ name, depth: 0 });\n    }\n\n    // Process forward (child\u2192parent)\n    const forwardLimit = forward === true ? Infinity : forward || 0;\n    while (forwardQueue.length > 0) {\n      const item = forwardQueue.shift();\n      if (!item) break;\n      const { name, depth } = item;\n\n      if (forwardVisited.has(name)) continue;\n      forwardVisited.add(name);\n\n      if (!tables[name]) {\n        tables[name] = await this.getTable(name);\n      }\n\n      if (depth < forwardLimit) {\n        const rels = await this.findOutgoingRelations(name);\n        for (const rel of rels) {\n          this.addRelationship(rel, allRelationships, seenRelationships);\n          if (!forwardVisited.has(rel.referenced_table)) {\n            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });\n          }\n        }\n      }\n    }\n\n    // Process backward (parent\u2192child)\n    const backwardLimit = backward === true ? Infinity : backward || 0;\n    while (backwardQueue.length > 0) {\n      const item = backwardQueue.shift();\n      if (!item) break;\n      const { name, depth } = item;\n\n      if (backwardVisited.has(name)) continue;\n      backwardVisited.add(name);\n\n      if (!tables[name]) {\n        tables[name] = await this.getTable(name);\n      }\n\n      if (depth < backwardLimit) {\n        const rels = await this.findIncomingRelations(name);\n        for (const rel of rels) {\n          this.addRelationship(rel, allRelationships, seenRelationships);\n          if (!backwardVisited.has(rel.table)) {\n            backwardQueue.push({ name: rel.table, depth: depth + 1 });\n          }\n        }\n      }\n    }\n\n    // Write to context\n    const tablesList = Object.values(tables);\n    ctx.tables.push(...tablesList);\n    ctx.relationships.push(...allRelationships);\n    return () => this.#describeTables(tablesList);\n  }\n\n  /**\n   * Apply the filter to get seed table names.\n   * If filter is an explicit array, skip querying all table names.\n   */\n  protected async applyFilter(): Promise<string[]> {\n    const filter = this.#filter;\n    if (Array.isArray(filter)) {\n      return filter;\n    }\n    const names = await this.getAllTableNames();\n    if (!filter) {\n      return names;\n    }\n    if (filter instanceof RegExp) {\n      return names.filter((name) => filter.test(name));\n    }\n    return names.filter(filter);\n  }\n\n  /**\n   * Add a relationship to the collection, deduplicating by key.\n   */\n  protected addRelationship(\n    rel: Relationship,\n    all: Relationship[],\n    seen: Set<string>,\n  ): void {\n    const key = `${rel.table}:${rel.from.join(',')}:${rel.referenced_table}:${rel.to.join(',')}`;\n    if (!seen.has(key)) {\n      seen.add(key);\n      all.push(rel);\n    }\n  }\n\n  #describeTables(tables: Table[]): string {\n    if (!tables.length) {\n      return 'Schema unavailable.';\n    }\n\n    return tables\n      .map((table) => {\n        const rowCountInfo =\n          table.rowCount != null\n            ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ''}]`\n            : '';\n        // Get primary key columns from constraints\n        const pkConstraint = table.constraints?.find((c) => c.type === 'PRIMARY_KEY');\n        const pkColumns = new Set(pkConstraint?.columns ?? []);\n\n        const columns = table.columns\n          .map((column) => {\n            const annotations: string[] = [];\n            const isPrimaryKey = pkColumns.has(column.name);\n            if (isPrimaryKey) {\n              annotations.push('PK');\n            }\n            if (column.isIndexed && !isPrimaryKey) {\n              annotations.push('Indexed');\n            }\n            if (column.kind === 'LowCardinality' && column.values?.length) {\n              annotations.push(`LowCardinality: ${column.values.join(', ')}`);\n            }\n            if (column.stats) {\n              const statParts: string[] = [];\n              if (column.stats.min != null || column.stats.max != null) {\n                const minText = column.stats.min ?? 'n/a';\n                const maxText = column.stats.max ?? 'n/a';\n                statParts.push(`range ${minText} \u2192 ${maxText}`);\n              }\n              if (\n                column.stats.nullFraction != null &&\n                Number.isFinite(column.stats.nullFraction)\n              ) {\n                const percent =\n                  Math.round(column.stats.nullFraction * 1000) / 10;\n                statParts.push(`null\u2248${percent}%`);\n              }\n              if (statParts.length) {\n                annotations.push(statParts.join(', '));\n              }\n            }\n            const annotationText = annotations.length\n              ? ` [${annotations.join(', ')}]`\n              : '';\n            return `    - ${column.name} (${column.type})${annotationText}`;\n          })\n          .join('\\n');\n        const indexes = table.indexes?.length\n          ? `\\n  Indexes:\\n${table.indexes\n              .map((index) => {\n                const props: string[] = [];\n                if (index.unique) {\n                  props.push('UNIQUE');\n                }\n                if (index.type) {\n                  props.push(index.type);\n                }\n                const propsText = props.length ? ` (${props.join(', ')})` : '';\n                const columnsText = index.columns?.length\n                  ? index.columns.join(', ')\n                  : 'expression';\n                return `    - ${index.name}${propsText}: ${columnsText}`;\n              })\n              .join('\\n')}`\n          : '';\n        return `- Table: ${table.name}${rowCountInfo}\\n  Columns:\\n${columns}${indexes}`;\n      })\n      .join('\\n\\n');\n  }\n\n  #formatTableLabel = (tableName: string) => {\n    const base = tableName.split('.').pop() ?? tableName;\n    return base.replace(/_/g, ' ');\n  };\n\n  #describeRelationships = (tables: Table[], relationships: Relationship[]) => {\n    if (!relationships.length) {\n      return 'None detected';\n    }\n\n    const tableMap = new Map(tables.map((table) => [table.name, table]));\n\n    return relationships\n      .map((relationship) => {\n        const sourceLabel = this.#formatTableLabel(relationship.table);\n        const targetLabel = this.#formatTableLabel(\n          relationship.referenced_table,\n        );\n        const singularSource = pluralize.singular(sourceLabel);\n        const pluralSource = pluralize.plural(sourceLabel);\n        const singularTarget = pluralize.singular(targetLabel);\n        const pluralTarget = pluralize.plural(targetLabel);\n        const sourceTable = tableMap.get(relationship.table);\n        const targetTable = tableMap.get(relationship.referenced_table);\n        const sourceCount = sourceTable?.rowCount;\n        const targetCount = targetTable?.rowCount;\n        const ratio =\n          sourceCount != null && targetCount != null && targetCount > 0\n            ? sourceCount / targetCount\n            : null;\n\n        let cardinality = 'each';\n        if (ratio != null) {\n          if (ratio > 5) {\n            cardinality = `many-to-one (\u2248${sourceCount} vs ${targetCount})`;\n          } else if (ratio < 1.2 && ratio > 0.8) {\n            cardinality = `roughly 1:1 (${sourceCount} vs ${targetCount})`;\n          } else if (ratio < 0.2) {\n            cardinality = `one-to-many (${sourceCount} vs ${targetCount})`;\n          }\n        }\n        const mappings = relationship.from\n          .map((fromCol, idx) => {\n            const targetCol =\n              relationship.to[idx] ?? relationship.to[0] ?? fromCol;\n            return `${relationship.table}.${fromCol} -> ${relationship.referenced_table}.${targetCol}`;\n          })\n          .join(', ');\n\n        return `- ${relationship.table} (${relationship.from.join(', ')}) -> ${relationship.referenced_table} (${relationship.to.join(', ')}) [${cardinality}]`;\n      })\n      .join('\\n');\n  };\n}\n", "import type { Adapter } from './adapter.ts';\nimport type { GroundingContext } from './groundings/context.ts';\n\n/**\n * Filter type for table names.\n * - string[]: explicit list of table names\n * - RegExp: pattern to match table names\n * - function: predicate to filter table names\n */\nexport type Filter = string[] | RegExp | ((tableName: string) => boolean);\n\nexport interface AdapterInfo {\n  dialect: string;\n  version?: string;\n  database?: string;\n  details?: Record<string, unknown>;\n}\nexport type AdapterInfoProvider =\n  | AdapterInfo\n  | (() => Promise<AdapterInfo> | AdapterInfo);\n\nexport abstract class AbstractGrounding {\n  tag: string;\n  constructor(tag: string) {\n    this.tag = tag;\n  }\n\n  abstract execute(ctx: GroundingContext): Promise<() => string | null>;\n}\n\nclass SampleDataGrounding {\n  // this will fetch sample data for tables matching the filter\n}\nclass ExampleQueryGrounding {\n  // this will create example queries for tables matching the filter\n}\nclass FunctionGrounding {\n  #filter: Filter;\n  #adapter: Adapter;\n  constructor(adapter: Adapter, filter: Filter) {\n    this.#filter = filter;\n    this.#adapter = adapter;\n  }\n}\n", "import type { ColumnStats } from '../adapter.ts';\nimport { AbstractGrounding } from '../grounding.ticket.ts';\nimport type { Column, ColumnContainer, GroundingContext } from './context.ts';\n\n/**\n * Configuration for ColumnStatsGrounding.\n */\nexport interface ColumnStatsGroundingConfig {\n  // Future: filter which tables/columns to collect stats for\n}\n\n/**\n * Abstract base class for column statistics grounding.\n *\n * Reads tables and views from the context and annotates their columns\n * with statistics (min, max, nullFraction).\n *\n * Subclasses implement database-specific hooks:\n * - `collectStats()` - collect min/max/nullFraction for a column\n */\nexport abstract class ColumnStatsGrounding extends AbstractGrounding {\n  constructor(config: ColumnStatsGroundingConfig = {}) {\n    super('column_stats');\n  }\n\n  /**\n   * Collect min/max/nullFraction statistics for a column.\n   * Return undefined to skip this column.\n   */\n  protected abstract collectStats(\n    tableName: string,\n    column: Column,\n  ): Promise<ColumnStats | undefined>;\n\n  /**\n   * Execute the grounding process.\n   * Annotates columns in ctx.tables and ctx.views with statistics.\n   */\n  async execute(ctx: GroundingContext) {\n    // Process both tables and views\n    const allContainers: ColumnContainer[] = [...ctx.tables, ...ctx.views];\n    for (const container of allContainers) {\n      for (const column of container.columns) {\n        // Collect min/max/nullFraction\n        try {\n          const stats = await this.collectStats(container.name, column);\n          if (stats) {\n            column.stats = stats;\n          }\n        } catch (error) {\n          // Skip on error\n          console.warn(\n            'Error collecting stats for',\n            container.name,\n            column.name,\n            error,\n          );\n        }\n      }\n    }\n    return () => this.#describe();\n  }\n\n  #describe() {\n    return null;\n  }\n}\n", "import { AbstractGrounding } from '../grounding.ticket.ts';\nimport type { Column, ColumnContainer, GroundingContext } from './context.ts';\n\nexport type { Column, ColumnContainer };\n\n/**\n * Configuration for LowCardinalityGrounding.\n */\nexport interface LowCardinalityGroundingConfig {\n  // Future: filter which tables/columns to collect low cardinality values for\n}\n\n/**\n * Abstract base class for low cardinality column grounding.\n *\n * Reads tables and views from the context and annotates their columns\n * with low cardinality values (columns with few distinct values).\n *\n * Subclasses implement database-specific hooks:\n * - `collectLowCardinality()` - collect distinct values for low cardinality columns\n */\nexport abstract class LowCardinalityGrounding extends AbstractGrounding {\n  constructor(config: LowCardinalityGroundingConfig = {}) {\n    super('low_cardinality');\n  }\n\n  /**\n   * Collect distinct values for low cardinality columns.\n   * Return undefined if column has too many distinct values.\n   */\n  protected abstract collectLowCardinality(\n    tableName: string,\n    column: Column,\n  ): Promise<{ kind: 'LowCardinality'; values: string[] } | undefined>;\n\n  /**\n   * Execute the grounding process.\n   * Annotates columns in ctx.tables and ctx.views with low cardinality values.\n   */\n  async execute(ctx: GroundingContext) {\n    // Process both tables and views\n    const allContainers: ColumnContainer[] = [...ctx.tables, ...ctx.views];\n    for (const container of allContainers) {\n      for (const column of container.columns) {\n        // Collect low cardinality values\n        try {\n          const lowCard = await this.collectLowCardinality(\n            container.name,\n            column,\n          );\n          if (lowCard) {\n            column.kind = lowCard.kind;\n            column.values = lowCard.values;\n          }\n        } catch (error) {\n          // Skip on error\n          console.warn(\n            'Error collecting low cardinality values for',\n            container.name,\n            column.name,\n            error,\n          );\n        }\n      }\n    }\n    return () => this.#describe();\n  }\n\n  #describe() {\n    return null;\n  }\n}\n", "import type { AdapterInfo } from '../adapter.ts';\nimport { AbstractGrounding } from '../grounding.ticket.ts';\nimport type { GroundingContext } from './context.ts';\n\n/**\n * Configuration for InfoGrounding.\n */\nexport interface InfoGroundingConfig {\n  // Future: options to control what info to collect\n}\n\n/**\n * Abstract base class for database info grounding.\n *\n * Collects database dialect, version, and connection info.\n *\n * Subclasses implement the database-specific hook:\n * - `collectInfo()` - collect database info\n */\nexport abstract class InfoGrounding extends AbstractGrounding {\n  constructor(config: InfoGroundingConfig = {}) {\n    super('dialect_info');\n  }\n\n  /**\n   * Collect database dialect, version, and other info.\n   */\n  protected abstract collectInfo(): Promise<AdapterInfo>;\n\n  /**\n   * Execute the grounding process.\n   * Writes database info to ctx.info.\n   */\n  async execute(ctx: GroundingContext) {\n    ctx.info = await this.collectInfo();\n    const lines = [`Dialect: ${ctx.info.dialect ?? 'unknown'}`];\n    if (ctx.info.version) {\n      lines.push(`Version: ${ctx.info.version}`);\n    }\n    if (ctx.info.database) {\n      lines.push(`Database: ${ctx.info.database}`);\n    }\n    if (ctx.info.details && Object.keys(ctx.info.details).length) {\n      lines.push(`Details: ${JSON.stringify(ctx.info.details)}`);\n    }\n    return () => lines.join('\\n');\n  }\n}\n", "import type { ColumnStats, Filter } from '../adapter.ts';\nimport { AbstractGrounding } from '../grounding.ticket.ts';\nimport type { GroundingContext } from './context.ts';\n\n/**\n * Represents a database view with its metadata.\n */\nexport interface View {\n  name: string;\n  schema?: string;\n  rawName?: string;\n  /** The SQL definition of the view (CREATE VIEW statement or query) */\n  definition?: string;\n  columns: {\n    name: string;\n    type: string;\n    /** Low cardinality marker */\n    kind?: 'LowCardinality';\n    /** Distinct values for low cardinality columns */\n    values?: string[];\n    /** Column statistics (min, max, nullFraction) */\n    stats?: ColumnStats;\n  }[];\n}\n\n/**\n * Configuration for ViewGrounding.\n */\nexport interface ViewGroundingConfig {\n  /** Filter to select views */\n  filter?: Filter;\n}\n\n/**\n * Abstract base class for view grounding\n *\n * The `execute()` method implements the algorithm that discovers views.\n * Subclasses implement the database-specific hooks:\n * - `getAllViewNames()` - list all views\n * - `getView()` - get view metadata\n */\nexport abstract class ViewGrounding extends AbstractGrounding {\n  #filter?: Filter;\n\n  constructor(config: ViewGroundingConfig = {}) {\n    super('views');\n    this.#filter = config.filter;\n  }\n\n  /** Get all view names in the database */\n  protected abstract getAllViewNames(): Promise<string[]>;\n\n  /** Get full view metadata for a single view */\n  protected abstract getView(viewName: string): Promise<View>;\n\n  /**\n   * Execute the grounding process.\n   * Writes discovered views to the context.\n   */\n  async execute(ctx: GroundingContext) {\n    const viewNames = await this.applyFilter();\n    const views = await Promise.all(\n      viewNames.map((name) => this.getView(name)),\n    );\n    ctx.views.push(...views);\n    return () => this.#describe(views);\n  }\n\n  #describe(views: View[]): string {\n    if (!views.length) {\n      return 'No views available.';\n    }\n\n    return views\n      .map((view) => {\n        const columns = view.columns\n          .map((column) => {\n            const annotations: string[] = [];\n            if (column.kind === 'LowCardinality' && column.values?.length) {\n              annotations.push(`LowCardinality: ${column.values.join(', ')}`);\n            }\n            if (column.stats) {\n              const statParts: string[] = [];\n              if (column.stats.min != null || column.stats.max != null) {\n                const minText = column.stats.min ?? 'n/a';\n                const maxText = column.stats.max ?? 'n/a';\n                statParts.push(`range ${minText} \u2192 ${maxText}`);\n              }\n              if (\n                column.stats.nullFraction != null &&\n                Number.isFinite(column.stats.nullFraction)\n              ) {\n                const percent =\n                  Math.round(column.stats.nullFraction * 1000) / 10;\n                statParts.push(`null\u2248${percent}%`);\n              }\n              if (statParts.length) {\n                annotations.push(statParts.join(', '));\n              }\n            }\n            const annotationText = annotations.length\n              ? ` [${annotations.join(', ')}]`\n              : '';\n            return `    - ${column.name} (${column.type})${annotationText}`;\n          })\n          .join('\\n');\n\n        const definition = view.definition\n          ? `\\n  Definition: ${view.definition.length > 200 ? view.definition.slice(0, 200) + '...' : view.definition}`\n          : '';\n\n        return `- View: ${view.name}${definition}\\n  Columns:\\n${columns}`;\n      })\n      .join('\\n\\n');\n  }\n\n  /**\n   * Apply the filter to get view names.\n   * If filter is an explicit array, skip querying all view names.\n   */\n  protected async applyFilter(): Promise<string[]> {\n    const filter = this.#filter;\n    if (Array.isArray(filter)) {\n      return filter;\n    }\n    const names = await this.getAllViewNames();\n    if (!filter) {\n      return names;\n    }\n    if (filter instanceof RegExp) {\n      return names.filter((name) => filter.test(name));\n    }\n    return names.filter(filter);\n  }\n}\n", "import { groq } from '@ai-sdk/groq';\nimport { tool } from 'ai';\nimport dedent from 'dedent';\nimport z from 'zod';\n\nimport {\n  type AgentModel,\n  agent,\n  generate,\n  toState,\n  user,\n} from '@deepagents/agent';\n\nimport type { Adapter } from '../adapter.ts';\nimport { AbstractGrounding } from '../grounding.ticket.ts';\nimport type { GroundingContext } from './context.ts';\n\n/**\n * Cache interface for storing generated reports.\n */\nexport interface ReportCache {\n  get(): Promise<string | null>;\n  set(value: string): Promise<void>;\n}\n\n/**\n * Configuration for ReportGrounding.\n */\nexport interface ReportGroundingConfig {\n  /** LLM model to use for generating the report */\n  model?: AgentModel;\n  /** Optional cache for storing generated reports */\n  cache?: ReportCache;\n  /** Force regeneration even if cached */\n  forceRefresh?: boolean;\n}\n\n/**\n * Grounding that generates a business context report about the database.\n *\n * Uses an LLM agent to:\n * 1. Query COUNT(*) for each table\n * 2. Query SELECT * LIMIT 3 for sample data\n * 3. Generate a 400-600 word business context report\n *\n * The report helps downstream agents understand what the database represents.\n */\nexport class ReportGrounding extends AbstractGrounding {\n  #adapter: Adapter;\n  #model: AgentModel;\n  #cache?: ReportCache;\n  #forceRefresh: boolean;\n\n  constructor(adapter: Adapter, config: ReportGroundingConfig={}) {\n    super('business_context');\n    this.#adapter = adapter;\n    this.#model = config.model ?? groq('openai/gpt-oss-20b');\n    this.#cache = config.cache;\n    this.#forceRefresh = config.forceRefresh ?? false;\n  }\n\n  async execute(ctx: GroundingContext): Promise<() => string | null> {\n    // Check cache first (unless forcing refresh)\n    if (!this.#forceRefresh && this.#cache) {\n      const cached = await this.#cache.get();\n      if (cached) {\n        ctx.report = cached;\n        return () => cached;\n      }\n    }\n\n    // Generate report using LLM\n    const report = await this.#generateReport();\n    ctx.report = report;\n\n    // Cache the result\n    if (this.#cache) {\n      await this.#cache.set(report);\n    }\n\n    return () => report;\n  }\n\n  async #generateReport(): Promise<string> {\n    const reportAgent = agent<unknown, { adapter: Adapter }>({\n      name: 'db-report-agent',\n      model: this.#model,\n      prompt: () => dedent`\n        <identity>\n          You are a database analyst expert. Your job is to understand what\n          a database represents and provide business context about it.\n          You have READ-ONLY access to the database.\n        </identity>\n\n        <instructions>\n          Write a business context that helps another agent answer questions accurately.\n\n          For EACH table, do queries ONE AT A TIME:\n          1. SELECT COUNT(*) to get row count\n          2. SELECT * LIMIT 3 to see sample data\n\n          Then write a report with:\n          - What business this database is for\n          - For each table: purpose, row count, and example of what the data looks like\n\n          Include concrete examples like \"Track prices are $0.99\",\n          \"Customer names like 'Lu\u00EDs Gon\u00E7alves'\", etc.\n\n          Keep it 400-600 words, conversational style.\n        </instructions>\n      `,\n      tools: {\n        query_database: tool({\n          description:\n            'Execute a SELECT query to explore the database and gather insights.',\n          inputSchema: z.object({\n            sql: z.string().describe('The SELECT query to execute'),\n            purpose: z\n              .string()\n              .describe(\n                'What insight you are trying to gather with this query',\n              ),\n          }),\n          execute: ({ sql }, options) => {\n            const state = toState<{ adapter: Adapter }>(options);\n            return state.adapter.execute(sql);\n          },\n        }),\n      },\n    });\n\n    const { text } = await generate(\n      reportAgent,\n      [\n        user(\n          'Please analyze the database and write a contextual report about what this database represents.',\n        ),\n      ],\n      { adapter: this.#adapter },\n    );\n\n    return text;\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["tables"]
+}

package/dist/lib/adapters/groundings/indexes.grounding.d.ts

@@ -0,0 +1,30 @@
+import type { TableIndex } from '../adapter.ts';
+import { AbstractGrounding } from '../grounding.ticket.ts';
+import type { GroundingContext } from './context.ts';
+/**
+ * Configuration for IndexesGrounding.
+ */
+export interface IndexesGroundingConfig {
+}
+/**
+ * Abstract base class for indexes grounding.
+ *
+ * Reads tables from the context and annotates them with index metadata.
+ * This grounding must run AFTER TableGrounding since it reads from ctx.tables.
+ *
+ * Subclasses implement the database-specific hook:
+ * - `getIndexes()` - fetch indexes for a table
+ */
+export declare abstract class IndexesGrounding extends AbstractGrounding {
+    constructor(config?: IndexesGroundingConfig);
+    /**
+     * Fetch indexes for a specific table.
+     */
+    protected abstract getIndexes(tableName: string): Promise<TableIndex[]>;
+    /**
+     * Execute the grounding process.
+     * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+     */
+    execute(ctx: GroundingContext): Promise<() => null>;
+}
+//# sourceMappingURL=indexes.grounding.d.ts.map

package/dist/lib/adapters/groundings/indexes.grounding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.grounding.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/groundings/indexes.grounding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,sBAAsB;CAEtC;AAED;;;;;;;;GAQG;AACH,8BAAsB,gBAAiB,SAAQ,iBAAiB;gBAClD,MAAM,GAAE,sBAA2B;IAI/C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAEvE;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,gBAAgB;CAgBpC"}

package/dist/lib/adapters/groundings/info.grounding.d.ts

@@ -0,0 +1,29 @@
+import type { AdapterInfo } from '../adapter.ts';
+import { AbstractGrounding } from '../grounding.ticket.ts';
+import type { GroundingContext } from './context.ts';
+/**
+ * Configuration for InfoGrounding.
+ */
+export interface InfoGroundingConfig {
+}
+/**
+ * Abstract base class for database info grounding.
+ *
+ * Collects database dialect, version, and connection info.
+ *
+ * Subclasses implement the database-specific hook:
+ * - `collectInfo()` - collect database info
+ */
+export declare abstract class InfoGrounding extends AbstractGrounding {
+    constructor(config?: InfoGroundingConfig);
+    /**
+     * Collect database dialect, version, and other info.
+     */
+    protected abstract collectInfo(): Promise<AdapterInfo>;
+    /**
+     * Execute the grounding process.
+     * Writes database info to ctx.info.
+     */
+    execute(ctx: GroundingContext): Promise<() => string>;
+}
+//# sourceMappingURL=info.grounding.d.ts.map

package/dist/lib/adapters/groundings/info.grounding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"info.grounding.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/groundings/info.grounding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,mBAAmB;CAEnC;AAED;;;;;;;GAOG;AACH,8BAAsB,aAAc,SAAQ,iBAAiB;gBAC/C,MAAM,GAAE,mBAAwB;IAI5C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAEtD;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,gBAAgB;CAcpC"}