@deepagents/text2sql 0.35.0 → 0.37.0

package/README.md

@@ -23,16 +23,24 @@ Requires Node.js LTS (20+).
 
 ```typescript
 import { groq } from '@ai-sdk/groq';
+import { InMemoryFs } from 'just-bash';
 import pg from 'pg';
 
-import { InMemoryContextStore } from '@deepagents/context';
-import { Text2Sql } from '@deepagents/text2sql';
+import {
+  ContextEngine,
+  InMemoryContextStore,
+  createBashTool,
+  createRoutingSandbox,
+  createVirtualSandbox,
+} from '@deepagents/context';
+import { Text2Sql, sqlSandboxExtension } from '@deepagents/text2sql';
 import {
   Postgres,
   columnValues,
   constraints,
   indexes,
   info,
+  rowCount,
   tables,
   views,
 } from '@deepagents/text2sql/postgres';
@@ -41,45 +49,97 @@ const pool = new pg.Pool({
   connectionString: process.env.DATABASE_URL,
 });
 
+const store = new InMemoryContextStore();
+const adapter = new Postgres({
+  execute: async (sql) => {
+    const result = await pool.query(sql);
+    return result.rows;
+  },
+  grounding: [
+    tables(),
+    views(),
+    info(),
+    indexes(),
+    constraints(),
+    rowCount(),
+    columnValues(),
+  ],
+});
+const sandbox = await createBashTool({
+  sandbox: await createRoutingSandbox({
+    backend: await createVirtualSandbox({ fs: new InMemoryFs() }),
+    hostExtensions: [sqlSandboxExtension({ main: adapter })],
+  }),
+});
+
 const text2sql = new Text2Sql({
   version: 'v1',
-  model: groq('gpt-oss-20b'),
-  adapter: new Postgres({
-    execute: async (sql) => {
-      const result = await pool.query(sql);
-      return result.rows;
-    },
-    grounding: [
-      tables(),
-      views(),
-      info(),
-      indexes(),
-      constraints(),
-      columnValues(),
-    ],
-  }),
-  store: new InMemoryContextStore(),
+  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;
+  },
 });
 
 // Generate SQL
-const sql = await text2sql.toSql('Show me the top 10 customers by revenue');
+const sql = await text2sql.toSql(
+  'Show me the top 10 customers by revenue',
+  'main',
+);
 console.log(sql);
 ```
 
+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.
+
 ## 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.
 
+## Advanced: Composing Sandbox Extensions
+
+`Text2Sql` takes a caller-owned `sandbox`. `sqlSandboxExtension(adaptersMap)`
+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.
+
 ## Fragments
 
-Inject domain knowledge using fragments from `@deepagents/context` to improve query accuracy. Pass instructions via the constructor:
+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`.
 
 ```typescript
-import { example, guardrail, hint, term } from '@deepagents/context';
-
-const text2sql = new Text2Sql({
-  // ... other config
-  instructions: [
+import {
+  ContextEngine,
+  InMemoryContextStore,
+  example,
+  guardrail,
+  hint,
+  term,
+} from '@deepagents/context';
+
+const store = new InMemoryContextStore();
+
+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({
@@ -91,8 +151,11 @@ const text2sql = new Text2Sql({
       question: 'show me churned customers',
       answer: `SELECT * FROM customers WHERE status = 'churned' ORDER BY churned_at DESC`,
     }),
-  ],
-});
+    ...fragments,
+  );
+
+  return engine;
+};
 ```
 
 **Domain fragments** (11 types): `term`, `hint`, `guardrail`, `example`, `explain`, `clarification`, `workflow`, `quirk`, `styleGuide`, `analogy`, `glossary`.
@@ -118,26 +181,43 @@ Control what schema metadata the AI receives:
 
 ## Conversations
 
-Build multi-turn conversations with context:
+`chat()` persists history through the `ContextEngine` returned by your `context` factory. Reuse the same store, `chatId`, and `userId` to continue the same thread:
 
 ```typescript
-const chatId = 'chat-123';
-const userId = 'user-456';
-
-const stream = await text2sql.chat(
-  [{ role: 'user', content: 'Show me orders from last month' }],
-  { chatId, userId },
-);
+const stream = await text2sql.chat([
+  { role: 'user', content: 'Show me orders from last month' },
+]);
 
 for await (const chunk of stream) {
   // handle streaming response
 }
 
-// Continue the conversation with the same chatId
-const followUp = await text2sql.chat(
-  [{ role: 'user', content: 'Now filter to only completed ones' }],
-  { chatId, userId },
-);
+// Continue the same conversation
+const followUp = await text2sql.chat([
+  { role: 'user', content: 'Now filter to only completed ones' },
+]);
+```
+
+`toSql()` is stateless. It reads the current schema fragments, but it does not
+write messages, titles, or usage into your context store.
+
+## Direct SQL Generation with Extra Fragments
+
+```typescript
+import { term } from '@deepagents/context';
+import { toSql } from '@deepagents/text2sql';
+
+const result = await toSql({
+  input: 'Show ARR by plan',
+  adapter,
+  model: groq('openai/gpt-oss-20b'),
+  fragments: [
+    ...(await adapter.introspect()),
+    term('ARR', 'annual recurring revenue'),
+  ],
+});
+
+console.log(result.sql);
 ```
 
 ## Documentation
@@ -146,6 +226,7 @@ Full documentation available at [januarylabs.github.io/deepagents](https://janua
 
 - [Getting Started](https://januarylabs.github.io/deepagents/docs/text2sql/getting-started)
 - [Generate SQL](https://januarylabs.github.io/deepagents/docs/text2sql/to-sql)
+- [Caller-Owned Sandbox](https://januarylabs.github.io/deepagents/docs/text2sql/sqlv3)
 - [Teach the System](https://januarylabs.github.io/deepagents/docs/text2sql/teach-the-system)
 - [Build Conversations](https://januarylabs.github.io/deepagents/docs/text2sql/build-conversations)
 - [Grounding](https://januarylabs.github.io/deepagents/docs/text2sql/grounding)

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+export { isValidAdapterName, validateAdapterNames, } from './lib/adapter-name.ts';
 export * from './lib/adapters/adapter.ts';
 export * from './lib/agents/exceptions.ts';
-export * from './lib/agents/result-tools.ts';
+export * from './lib/agents/sql-command.ts';
+export * from './lib/agents/sql-transform-plugins.ts';
 export * from './lib/agents/sql.agent.ts';
 export * from './lib/agents/suggestions.agents.ts';
 export * from './lib/checkpoint.ts';
@@ -8,5 +10,6 @@ export * from './lib/file-cache.ts';
 export * from './lib/fragments/schema.ts';
 export * from './lib/fs/index.ts';
 export * from './lib/instructions.ts';
+export * from './lib/sandbox.ts';
 export * from './lib/sql.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC"}