@deepagents/text2sql 0.38.0 → 0.39.0

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
@@ -32,6 +41,7 @@ import {
   createBashTool,
   createRoutingSandbox,
   createVirtualSandbox,
+  user,
 } from '@deepagents/context';
 import { Text2Sql, sqlSandboxExtension } from '@deepagents/text2sql';
 import {
@@ -50,6 +60,11 @@ const pool = new pg.Pool({
 });
 
 const store = new InMemoryContextStore();
+const engine = new ContextEngine({
+  store,
+  chatId: 'chat-123',
+  userId: 'user-456',
+});
 const adapter = new Postgres({
   execute: async (sql) => {
     const result = await pool.query(sql);
@@ -77,15 +92,7 @@ const text2sql = new Text2Sql({
   model: groq('openai/gpt-oss-20b'),
   sandbox,
   adapters: { main: adapter },
-  context: (...fragments) => {
-    const engine = new ContextEngine({
-      store,
-      chatId: 'chat-123',
-      userId: 'user-456',
-    });
-    engine.set(...fragments);
-    return engine;
-  },
+  context: engine,
 });
 
 // Generate SQL
@@ -121,10 +128,10 @@ for composition patterns.
 
 ## Fragments
 
-Inject domain knowledge using fragments from `@deepagents/context` inside the
-`context` factory you pass to `Text2Sql`. Those fragments affect `chat()`
-sessions. If you need direct SQL generation with extra fragments, use the
-lower-level `toSql({ fragments })` helper exported from `@deepagents/text2sql`.
+Inject domain knowledge by setting fragments on the `ContextEngine` you pass to
+`Text2Sql`. Those fragments affect `chat()` sessions. If you need direct SQL
+generation with extra fragments, use the lower-level `toSql({ fragments })`
+helper exported from `@deepagents/text2sql`.
 
 ```typescript
 import {
@@ -137,31 +144,25 @@ import {
 } from '@deepagents/context';
 
 const store = new InMemoryContextStore();
+const engine = new ContextEngine({
+  store,
+  chatId: 'chat-123',
+  userId: 'user-456',
+});
 
-const context = (...fragments) => {
-  const engine = new ContextEngine({
-    store,
-    chatId: 'chat-123',
-    userId: 'user-456',
-  });
-
-  engine.set(
-    term('MRR', 'monthly recurring revenue'),
-    hint('Always exclude test accounts with email ending in @test.com'),
-    guardrail({
-      rule: 'Never expose individual salaries',
-      reason: 'Confidential HR data',
-      action: 'Aggregate by department instead',
-    }),
-    example({
-      question: 'show me churned customers',
-      answer: `SELECT * FROM customers WHERE status = 'churned' ORDER BY churned_at DESC`,
-    }),
-    ...fragments,
-  );
-
-  return engine;
-};
+engine.set(
+  term('MRR', 'monthly recurring revenue'),
+  hint('Always exclude test accounts with email ending in @test.com'),
+  guardrail({
+    rule: 'Never expose individual salaries',
+    reason: 'Confidential HR data',
+    action: 'Aggregate by department instead',
+  }),
+  example({
+    question: 'show me churned customers',
+    answer: `SELECT * FROM customers WHERE status = 'churned' ORDER BY churned_at DESC`,
+  }),
+);
 ```
 
 **Domain fragments** (11 types): `term`, `hint`, `guardrail`, `example`, `explain`, `clarification`, `workflow`, `quirk`, `styleGuide`, `analogy`, `glossary`.
@@ -187,23 +188,68 @@ 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` you pass to `Text2Sql`.
+Reuse the same store, `chatId`, and `userId` to continue the same thread.
+Before each turn, append only the new incoming message to the engine; do not
+replay earlier turns that are already stored in the context store:
 
 ```typescript
-const stream = await text2sql.chat([
-  { role: 'user', content: 'Show me orders from last month' },
-]);
+await engine.continue(user('Show me orders from last month'));
+const stream = await text2sql.chat();
 
 for await (const chunk of stream) {
   // handle streaming response
 }
 
 // Continue the same conversation
-const followUp = await text2sql.chat([
-  { role: 'user', content: 'Now filter to only completed ones' },
-]);
+await engine.continue(user('Now filter to only completed ones'));
+const followUp = await text2sql.chat();
+for await (const chunk of followUp) {
+  // handle streaming response
+}
 ```
 
+While `chat()` builds or reads cached schema context, it emits progress chunks
+before assistant text starts:
+
+```typescript
+import {
+  TEXT2SQL_INDEX_PROGRESS_CHUNK,
+  type Text2SqlIndexProgressEvent,
+} from '@deepagents/text2sql';
+
+await engine.continue(user('Show me top 10 customers'));
+const stream = await text2sql.chat();
+const startedAt = new Map<string, number>();
+
+for await (const chunk of stream) {
+  if (chunk.type === TEXT2SQL_INDEX_PROGRESS_CHUNK) {
+    const event = chunk.data as Text2SqlIndexProgressEvent;
+    const scope =
+      [event.adapter, event.phase].filter(Boolean).join(':') || 'index';
+
+    if (event.type.endsWith(':start') || event.type === 'index:start') {
+      startedAt.set(scope, event.timestampMs ?? Date.now());
+    }
+
+    if (event.type.endsWith(':end') || event.type.endsWith(':error')) {
+      const durationMs =
+        (event.timestampMs ?? Date.now()) -
+        (startedAt.get(scope) ?? event.timestampMs ?? Date.now());
+      console.log(event.message, durationMs);
+    }
+
+    continue;
+  }
+
+  // handle assistant stream chunks
+}
+```
+
+Each progress event includes a generic Unix epoch `timestampMs` so clients can
+calculate per-index, per-adapter, or per-phase durations without Text2SQL
+imposing one duration policy.
+
 `toSql()` is stateless. It reads the current schema fragments, but it does not
 write messages, titles, or usage into your context store.
 

package/dist/index.js

@@ -163,6 +163,17 @@ function relationship(input) {
 }
 
 // packages/text2sql/src/lib/adapters/groundings/context.ts
+var noopProgress = () => {
+};
+function timestampProgress(onProgress) {
+  if (!onProgress) return noopProgress;
+  return (progress) => {
+    onProgress({
+      ...progress,
+      timestampMs: progress.timestampMs ?? Date.now()
+    });
+  };
+}
 function createGroundingContext(options = {}) {
   return {
     tables: [],
@@ -170,7 +181,7 @@ function createGroundingContext(options = {}) {
     relationships: [],
     info: void 0,
     cache: /* @__PURE__ */ new Map(),
-    onProgress: options.onProgress
+    onProgress: timestampProgress(options.onProgress)
   };
 }
 
@@ -317,7 +328,7 @@ var Adapter = class {
     for (const fn of this.grounding) {
       const grounding = fn(this);
       if (grounding.phase) {
-        ctx.onProgress?.({
+        ctx.onProgress({
           type: "phase:start",
           phase: grounding.phase,
           message: `Starting ${grounding.name} introspection...`
@@ -327,7 +338,7 @@ var Adapter = class {
         await grounding.execute(ctx);
       } finally {
         if (grounding.phase) {
-          ctx.onProgress?.({
+          ctx.onProgress({
             type: "phase:end",
             phase: grounding.phase,
             message: `Finished ${grounding.name} introspection.`
@@ -5238,6 +5249,17 @@ import {
   fragment as fragment3
 } from "@deepagents/context";
 var TEXT2SQL_INDEX_PROGRESS_CHUNK = "data-text2sql-index-progress";
+var noopProgressHandler = () => {
+};
+function timestampProgressHandler(onProgress) {
+  if (!onProgress) return noopProgressHandler;
+  return (event) => {
+    onProgress({
+      ...event,
+      timestampMs: event.timestampMs ?? Date.now()
+    });
+  };
+}
 var Text2Sql = class {
   #config;
   #introspection;
@@ -5283,8 +5305,9 @@ var Text2Sql = class {
     return this.#index();
   }
   async #index(onProgress) {
+    const progress = timestampProgressHandler(onProgress);
     const entries = Object.entries(this.#config.adapters);
-    onProgress?.({
+    progress({
       type: "index:start",
       message: `Indexing ${entries.length} adapter${entries.length === 1 ? "" : "s"}...`,
       current: 0,
@@ -5292,13 +5315,13 @@ var Text2Sql = class {
     });
     const settled = await Promise.allSettled(
       entries.map(async ([name, adapter]) => {
-        const schema = await this.#indexAdapter(name, adapter, onProgress);
+        const schema = await this.#indexAdapter(name, adapter, progress);
         return fragment3(name, ...schema);
       })
     );
     const failed = settled.find((result) => result.status === "rejected");
     if (failed) {
-      onProgress?.({
+      progress({
         type: "index:error",
         message: failed.reason instanceof Error ? failed.reason.message : String(failed.reason)
       });
@@ -5310,7 +5333,7 @@ var Text2Sql = class {
       }
       return result.value;
     });
-    onProgress?.({
+    progress({
       type: "index:end",
       message: "Finished indexing adapters.",
       current: entries.length,
@@ -5318,8 +5341,8 @@ var Text2Sql = class {
     });
     return wrapped;
   }
-  async #indexAdapter(name, adapter, onProgress) {
-    onProgress?.({
+  async #indexAdapter(name, adapter, onProgress = noopProgressHandler) {
+    onProgress({
       type: "adapter:start",
       adapter: name,
       message: `Indexing adapter "${name}"...`
@@ -5331,13 +5354,13 @@ var Text2Sql = class {
     try {
       const cached = await cache.read();
       if (cached) {
-        onProgress?.({
+        onProgress({
           type: "adapter:cache-hit",
           adapter: name,
           message: `Using cached index for adapter "${name}".`,
           cached: true
         });
-        onProgress?.({
+        onProgress({
           type: "adapter:end",
           adapter: name,
           message: `Finished indexing adapter "${name}".`,
@@ -5345,18 +5368,18 @@ var Text2Sql = class {
         });
         return cached;
       }
-      onProgress?.({
+      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))
+        onProgress: (event) => onProgress(this.#adapterProgressEvent(name, event))
       });
       const fragments = await adapter.introspect(ctx);
       await cache.write(fragments);
-      onProgress?.({
+      onProgress({
         type: "adapter:end",
         adapter: name,
         message: `Finished indexing adapter "${name}".`,
@@ -5365,7 +5388,7 @@ var Text2Sql = class {
       return fragments;
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error);
-      onProgress?.({
+      onProgress({
         type: "adapter:error",
         adapter: name,
         message: `Failed indexing adapter "${name}": ${reason}`
@@ -5384,7 +5407,8 @@ var Text2Sql = class {
       message: progress.message,
       current: progress.current,
       total: progress.total,
-      cached: false
+      cached: false,
+      timestampMs: progress.timestampMs
     };
   }
   async toPairs(adapterName, factory) {
@@ -5392,22 +5416,24 @@ var Text2Sql = class {
     const producer = factory(adapter);
     return producer.toPairs();
   }
-  async chat(messages, options) {
-    if (messages.length === 0) {
-      throw new Error("messages must not be empty");
-    }
+  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
           });
         };
-        const context = this.#config.context(
-          ...guidelines(),
-          ...await this.#index(progress)
-        );
+        context.set(...guidelines(), ...await this.#index(progress));
         const chatAgent = agent2({
           name: "text2sql",
           sandbox: this.#config.sandbox,
@@ -5417,7 +5443,7 @@ var Text2Sql = class {
           guardrails: [errorRecoveryGuardrail],
           maxGuardrailRetries: 3
         });
-        const chatStream = await chat(chatAgent, messages, {
+        const chatStream = await chat(chatAgent, {
           abortSignal: options?.abortSignal,
           generateTitle: options?.generateTitle,
           transform: this.#config.transform