@deepagents/text2sql 0.37.1 → 0.38.1

package/README.md

@@ -17,6 +17,15 @@ AI-powered natural language to SQL. Ask questions in plain English, get executab
 npm install @deepagents/text2sql
 ```
 
+Install the database driver or client library that matches your adapter:
+
+```bash
+npm install pg                       # PostgreSQL
+npm install mssql                    # SQL Server
+npm install mysql2                   # MySQL / MariaDB
+npm install @google-cloud/bigquery   # BigQuery
+```
+
 Requires Node.js LTS (20+).
 
 ## Quick Start
@@ -187,7 +196,7 @@ Control what schema metadata the AI receives:
 
 ## Conversations
 
-`chat()` persists history through the `ContextEngine` returned by your `context` factory. Reuse the same store, `chatId`, and `userId` to continue the same thread:
+`chat()` persists history through the `ContextEngine` returned by your `context` factory. Reuse the same store, `chatId`, and `userId` to continue the same thread. Pass only the new incoming message(s) for the current turn; do not replay earlier turns that are already stored in the context store:
 
 ```typescript
 const stream = await text2sql.chat([

package/dist/index.js

@@ -163,13 +163,14 @@ function relationship(input) {
 }
 
 // packages/text2sql/src/lib/adapters/groundings/context.ts
-function createGroundingContext() {
+function createGroundingContext(options = {}) {
   return {
     tables: [],
     views: [],
     relationships: [],
     info: void 0,
-    cache: /* @__PURE__ */ new Map()
+    cache: /* @__PURE__ */ new Map(),
+    onProgress: options.onProgress
   };
 }
 
@@ -315,7 +316,24 @@ var Adapter = class {
   async introspect(ctx = createGroundingContext()) {
     for (const fn of this.grounding) {
       const grounding = fn(this);
-      await grounding.execute(ctx);
+      if (grounding.phase) {
+        ctx.onProgress?.({
+          type: "phase:start",
+          phase: grounding.phase,
+          message: `Starting ${grounding.name} introspection...`
+        });
+      }
+      try {
+        await grounding.execute(ctx);
+      } finally {
+        if (grounding.phase) {
+          ctx.onProgress?.({
+            type: "phase:end",
+            phase: grounding.phase,
+            message: `Finished ${grounding.name} introspection.`
+          });
+        }
+      }
     }
     return this.#toSchemaFragments(ctx);
   }
@@ -521,26 +539,33 @@ var Adapter = class {
   async #checkScope(sql, allowedEntities) {
     const dialect = this.formatterLanguage;
     const scopeDialects = {
-      sqlite: "mysql",
-      postgresql: "postgresql",
-      bigquery: "bigquery",
-      transactsql: "transactsql",
-      mysql: "mysql"
+      sqlite: ["sqlite", "mysql"],
+      postgresql: ["postgresql"],
+      bigquery: ["bigquery"],
+      transactsql: ["transactsql"],
+      mysql: ["mysql"]
     };
-    const scopeDialect = scopeDialects[dialect];
-    if (!scopeDialect) {
+    const candidates = scopeDialects[dialect];
+    if (!candidates) {
       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) {
+    let references = null;
+    let lastError;
+    for (const candidate of candidates) {
+      try {
+        references = extractBaseEntityReferences(sql, candidate);
+        break;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if (references === null) {
       return buildScopeParseErrorPayload(
         sql,
         dialect,
-        error
+        lastError
       );
     }
     if (references.length === 0) return null;
@@ -5202,6 +5227,9 @@ function sqlSandboxExtension(adapters, options = {}) {
 }
 
 // packages/text2sql/src/lib/sql.ts
+import {
+  createUIMessageStream
+} from "ai";
 import "@deepagents/agent";
 import {
   agent as agent2,
@@ -5209,6 +5237,7 @@ import {
   errorRecoveryGuardrail,
   fragment as fragment3
 } from "@deepagents/context";
+var TEXT2SQL_INDEX_PROGRESS_CHUNK = "data-text2sql-index-progress";
 var Text2Sql = class {
   #config;
   #introspection;
@@ -5251,61 +5280,152 @@ var Text2Sql = class {
     return result.sql;
   }
   async index() {
+    return this.#index();
+  }
+  async #index(onProgress) {
     const entries = Object.entries(this.#config.adapters);
-    const wrapped = await Promise.all(
+    onProgress?.({
+      type: "index:start",
+      message: `Indexing ${entries.length} adapter${entries.length === 1 ? "" : "s"}...`,
+      current: 0,
+      total: entries.length
+    });
+    const settled = await Promise.allSettled(
       entries.map(async ([name, adapter]) => {
-        const schema = await this.#indexAdapter(name, adapter);
+        const schema = await this.#indexAdapter(name, adapter, onProgress);
         return fragment3(name, ...schema);
       })
     );
+    const failed = settled.find((result) => result.status === "rejected");
+    if (failed) {
+      onProgress?.({
+        type: "index:error",
+        message: failed.reason instanceof Error ? failed.reason.message : String(failed.reason)
+      });
+      throw failed.reason;
+    }
+    const wrapped = settled.map((result) => {
+      if (result.status === "rejected") {
+        throw result.reason;
+      }
+      return result.value;
+    });
+    onProgress?.({
+      type: "index:end",
+      message: "Finished indexing adapters.",
+      current: entries.length,
+      total: entries.length
+    });
     return wrapped;
   }
-  async #indexAdapter(name, adapter) {
+  async #indexAdapter(name, adapter, onProgress) {
+    onProgress?.({
+      type: "adapter:start",
+      adapter: name,
+      message: `Indexing adapter "${name}"...`
+    });
     const cache = this.#introspection.get(name);
     if (!cache) {
       throw new Error(`no introspection cache registered for "${name}"`);
     }
-    const cached = await cache.read();
-    if (cached) {
-      return cached;
-    }
     try {
-      const fragments = await adapter.introspect();
+      const cached = await cache.read();
+      if (cached) {
+        onProgress?.({
+          type: "adapter:cache-hit",
+          adapter: name,
+          message: `Using cached index for adapter "${name}".`,
+          cached: true
+        });
+        onProgress?.({
+          type: "adapter:end",
+          adapter: name,
+          message: `Finished indexing adapter "${name}".`,
+          cached: true
+        });
+        return cached;
+      }
+      onProgress?.({
+        type: "adapter:cache-miss",
+        adapter: name,
+        message: `No cached index for adapter "${name}".`,
+        cached: false
+      });
+      const ctx = createGroundingContext({
+        onProgress: (progress) => onProgress?.(this.#adapterProgressEvent(name, progress))
+      });
+      const fragments = await adapter.introspect(ctx);
       await cache.write(fragments);
+      onProgress?.({
+        type: "adapter:end",
+        adapter: name,
+        message: `Finished indexing adapter "${name}".`,
+        cached: false
+      });
       return fragments;
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error);
+      onProgress?.({
+        type: "adapter:error",
+        adapter: name,
+        message: `Failed indexing adapter "${name}": ${reason}`
+      });
       throw new Error(`introspecting adapter "${name}": ${reason}`, {
         cause: error
       });
     }
   }
+  #adapterProgressEvent(adapter, progress) {
+    return {
+      type: progress.type,
+      adapter,
+      phase: progress.phase,
+      table: progress.table,
+      message: progress.message,
+      current: progress.current,
+      total: progress.total,
+      cached: false
+    };
+  }
   async toPairs(adapterName, factory) {
     const adapter = this.#requireAdapter(adapterName);
     const producer = factory(adapter);
     return producer.toPairs();
   }
-  async chat(messages, options) {
-    if (messages.length === 0) {
-      throw new Error("messages must not be empty");
-    }
-    const context = this.#config.context(
-      ...guidelines(),
-      ...await this.index()
-    );
-    const chatAgent = agent2({
-      name: "text2sql",
-      sandbox: this.#config.sandbox,
-      model: this.#config.model,
-      context,
-      tools: this.#config.tools,
-      guardrails: [errorRecoveryGuardrail],
-      maxGuardrailRetries: 3
-    });
-    return chat(chatAgent, messages, {
-      abortSignal: options?.abortSignal,
-      generateTitle: options?.generateTitle,
-      transform: this.#config.transform
+  async chat(options) {
+    return createUIMessageStream({
+      execute: async ({ writer }) => {
+        const context = this.#config.context;
+        const head = await context.headMessage();
+        if (!head || head.name !== "assistant") {
+          throw new Error(
+            "text2sql.chat: expected head to be an assistant message \u2014 call context.continue() before chat()"
+          );
+        }
+        writer.write({ type: "start", messageId: head.id });
+        const progress = (event) => {
+          writer.write({
+            type: TEXT2SQL_INDEX_PROGRESS_CHUNK,
+            data: event
+          });
+        };
+        context.set(...guidelines(), ...await this.#index(progress));
+        const chatAgent = agent2({
+          name: "text2sql",
+          sandbox: this.#config.sandbox,
+          model: this.#config.model,
+          context,
+          tools: this.#config.tools,
+          guardrails: [errorRecoveryGuardrail],
+          maxGuardrailRetries: 3
+        });
+        const chatStream = await chat(chatAgent, {
+          abortSignal: options?.abortSignal,
+          generateTitle: options?.generateTitle,
+          transform: this.#config.transform
+        });
+        writer.merge(chatStream);
+      }
     });
   }
 };
@@ -5325,6 +5445,7 @@ export {
   SqlProxyEnforcementPlugin,
   SqlProxyViolationError,
   SqliteFs,
+  TEXT2SQL_INDEX_PROGRESS_CHUNK,
   Text2Sql,
   UnanswerableSQLError,
   applyTablesFilter,