@deepagents/text2sql 0.37.0 → 0.38.0

package/README.md

@@ -100,6 +100,11 @@ The adapter-map key (`main` here) is the adapter name. Reuse that same key in
 `text2sql.toSql(..., 'main')` and in any `sql validate <db> "..."` /
 `sql run <db> "..."` sandbox calls.
 
+Adapter names must match `/^[A-Za-z_][A-Za-z0-9_]*$/`. If you build adapter
+maps dynamically, use `isValidAdapterName(name)` to check one key or
+`validateAdapterNames(names)` to fail fast before constructing `Text2Sql` or
+`sqlSandboxExtension`.
+
 ## AI Model Providers
 
 Text2SQL works with any model provider supported by the [Vercel AI SDK](https://sdk.vercel.ai/docs), including OpenAI, Anthropic, Google, Groq, and more.
@@ -111,7 +116,8 @@ returns a `SandboxExtension` that bundles the `sql` subcommand, transform
 plugins, and arg-repair hook. In the simplest case, that map is
 `{ main: adapter }`. Compose it (alongside any of your own extensions) via
 `createBashTool` + `createRoutingSandbox` + `createVirtualSandbox`.
-See [sqlv3.md](./sqlv3.md) for composition patterns.
+See [Caller-Owned Sandbox](https://januarylabs.github.io/deepagents/docs/text2sql/sqlv3)
+for composition patterns.
 
 ## Fragments
 
@@ -203,6 +209,9 @@ write messages, titles, or usage into your context store.
 
 ## Direct SQL Generation with Extra Fragments
 
+This lower-level helper still takes a single `adapter` because it bypasses the
+multi-adapter `Text2Sql` wrapper entirely.
+
 ```typescript
 import { term } from '@deepagents/context';
 import { toSql } from '@deepagents/text2sql';

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,35 +5280,113 @@ 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);
@@ -5289,23 +5396,34 @@ var Text2Sql = class {
     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
+    return createUIMessageStream({
+      execute: async ({ writer }) => {
+        const progress = (event) => {
+          writer.write({
+            type: TEXT2SQL_INDEX_PROGRESS_CHUNK,
+            data: event
+          });
+        };
+        const context = this.#config.context(
+          ...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, messages, {
+          abortSignal: options?.abortSignal,
+          generateTitle: options?.generateTitle,
+          transform: this.#config.transform
+        });
+        writer.merge(chatStream);
+      }
     });
   }
 };
@@ -5325,6 +5443,7 @@ export {
   SqlProxyEnforcementPlugin,
   SqlProxyViolationError,
   SqliteFs,
+  TEXT2SQL_INDEX_PROGRESS_CHUNK,
   Text2Sql,
   UnanswerableSQLError,
   applyTablesFilter,