@deepagents/text2sql 1.0.0 → 2.2.0

package/README.md

@@ -26,7 +26,7 @@ npm install mysql2                   # MySQL / MariaDB
 npm install @google-cloud/bigquery   # BigQuery
 ```
 
-Requires Node.js LTS (20+).
+Requires Node.js LTS
 
 ## Quick Start
 
@@ -95,10 +95,9 @@ Text2SQL works with any model provider supported by the [Vercel AI SDK](https://
 
 ## Building a Conversational Agent
 
-`Text2Sql` ships only the SQL-aware primitives: `toSql`, `toPairs`,
-`AdapterIndexer`, and `instructions()`. You build the chat agent yourself by
-composing a `ContextEngine`, a sandbox, and `agent` + `chat` from
-`@deepagents/context`:
+`Text2Sql` owns SQL generation and schema indexing, but you own the chat loop.
+Build the agent by composing a `ContextEngine`, a sandbox, and `agent` +
+`chat` from `@deepagents/context`:
 
 ```typescript
 import {
@@ -107,7 +106,8 @@ import {
   InMemoryContextStore,
   agent,
   chat,
-  createContainerTool,
+  createBashTool,
+  createDockerSandbox,
   errorRecoveryGuardrail,
   npm,
   user,
@@ -121,11 +121,22 @@ const context = new ContextEngine({
   userId: 'user-456',
 });
 
-const sandbox = await createContainerTool({
+const backend = await createDockerSandbox({
   installers: [npm('@deepagents/text2sql', { ensureRuntime: true })],
+  volumes: [
+    {
+      type: 'bind',
+      hostPath: process.cwd(),
+      containerPath: '/workspace',
+      readOnly: true,
+    },
+  ],
   env: {
     TEXT2SQL_ADAPTERS: '/workspace/text2sql-adapters.ts',
   },
+});
+const sandbox = await createBashTool({
+  sandbox: backend,
   ...createSqlCommandHooks({ adapters: { main: adapter } }),
 });
 
@@ -154,6 +165,10 @@ for await (const chunk of stream) {
 }
 ```
 
+The `/workspace/text2sql-adapters.ts` module must exist in the sandbox and
+default-export your adapter map. Mount your project into `/workspace` (as above)
+or upload/write that module before you call `sql index` or `chat()`.
+
 `instructions()` returns the SQL-flavored system fragments (policies, workflows,
 clarifications, style guides) — spread them into `context.set()` alongside the
 schema fragments returned by `sql index`. Add or replace them with your
@@ -162,14 +177,62 @@ own domain fragments as needed.
 ## Advanced: SQL CLI in Sandboxes
 
 `sql validate <db> "..."` and `sql run <db> "..."` are real commands from the
-`@deepagents/text2sql` package. `sql index [adapter ...]` writes schema
-fragments plus progress events for chat setup. Install the package inside the
-sandbox and set `TEXT2SQL_ADAPTERS` to a module whose default export is
-`Record<string, Adapter>`. Missing `sql` means the sandbox was not prepared
-correctly.
-
-Spread `createSqlCommandHooks({ adapters })` into `createBashTool()` or
-`createContainerTool()` for model-driven bash calls. The before hook preserves
+`@deepagents/text2sql` package. `sql index` writes schema fragments plus
+progress events for chat setup, indexing all configured adapters by default
+(same as `--all`) unless adapter names are provided.
+
+Install the package inside the sandbox and set `TEXT2SQL_ADAPTERS` to a module
+whose default export is `Record<string, Adapter>`. Missing `sql` means the
+sandbox was not prepared correctly.
+
+`sql index` output details:
+
+- `stdout`: JSON manifest with `fragmentsPath`, `eventsPath`, adapters, and
+  fragment count.
+- `--verbose pretty` or `--verbose json`: mirrors progress events to `stderr`
+  while keeping `stdout` as the manifest.
+- `--out-dir <path>`: writes artifacts under that path (default:
+  `$TEXT2SQL_OUT_DIR` or `./sql`).
+
+Set `TEXT2SQL_INDEX_VERSION` to manage cache invalidation across runs. Cache
+keys are `index-<version>-<adapter>`, so bump the version when schema changes.
+
+For in-process or virtual-sandbox usage (without installing the package CLI),
+wrap an existing `Text2Sql` instance as a just-bash custom command:
+
+```typescript
+import {
+  Text2Sql,
+  createSqlCommand,
+  type CreateSqlCommandOptions,
+  type CreateSqlCommandResult,
+} from '@deepagents/text2sql';
+import { InMemoryFs, createVirtualSandbox } from '@deepagents/context';
+
+const text2sql = new Text2Sql({ model, adapters: { main: adapter } });
+
+const commandOptions: CreateSqlCommandOptions = {
+  outputDir: '/sql-artifacts',
+};
+const sqlCommand: CreateSqlCommandResult = createSqlCommand(
+  text2sql,
+  commandOptions,
+);
+
+const sandbox = await createVirtualSandbox({
+  fs: new InMemoryFs(),
+  customCommands: [sqlCommand.command],
+});
+
+await sandbox.executeCommand('sql validate main "SELECT 1"');
+```
+
+`CreateSqlCommandOptions` configures command defaults (currently `outputDir`).
+`CreateSqlCommandResult` returns the command plus a `repair(raw)` helper for
+normalizing model-generated argv before execution.
+
+Spread `createSqlCommandHooks({ adapters })` into `createBashTool()` for
+model-driven bash calls. The before hook preserves
 the old virtual-command tolerance for common LLM quote mistakes, rewrites SQL
 identifier backticks so bash does not run them as command substitutions, and
 blocks raw database access so read-only and scope checks stay behind
@@ -177,6 +240,10 @@ blocks raw database access so read-only and scope checks stay behind
 metadata from the host adapter map without putting that concern into the real
 CLI.
 
+Read-only enforcement accepts a single `SELECT`/`WITH` statement even when it
+starts with whitespace or SQL comments (`-- ...`, `/* ... */`). It still
+rejects comment-only input, multi-statement batches, and write operations.
+
 ## Fragments
 
 Inject domain knowledge by setting fragments on the `ContextEngine` you build
@@ -339,6 +406,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)
+- [Agent + SQLite Store Recipe](https://januarylabs.github.io/deepagents/docs/text2sql/recipes/agent-sqlite-store)
 - [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)