@deepagents/text2sql 0.3.1 → 0.6.0

package/README.md

@@ -0,0 +1,167 @@
+# @deepagents/text2sql
+
+AI-powered natural language to SQL. Ask questions in plain English, get executable queries.
+
+## Features
+
+- **Natural Language to SQL** - Convert questions to validated, executable queries
+- **Multi-Database Support** - PostgreSQL, SQLite, and SQL Server adapters
+- **Schema-Aware** - Automatic introspection of tables, relationships, indexes, and constraints
+- **Domain Knowledge** - Teach business terms, guardrails, and query patterns via teachables
+- **Conversational** - Multi-turn conversations with history and user memory
+- **Explainable** - Convert SQL back to plain English explanations
+- **Safe by Default** - Read-only queries, validation, and configurable guardrails
+
+## Installation
+
+```bash
+npm install @deepagents/text2sql
+```
+
+Requires Node.js LTS (20+).
+
+## Quick Start
+
+```typescript
+import pg from 'pg';
+
+import { InMemoryHistory, Text2Sql } from '@deepagents/text2sql';
+import {
+  Postgres,
+  constraints,
+  indexes,
+  info,
+  lowCardinality,
+  tables,
+  views,
+} from '@deepagents/text2sql/postgres';
+
+const pool = new pg.Pool({
+  connectionString: process.env.DATABASE_URL,
+});
+
+const text2sql = new Text2Sql({
+  version: 'v1',
+  adapter: new Postgres({
+    execute: async (sql) => {
+      const result = await pool.query(sql);
+      return result.rows;
+    },
+    grounding: [
+      tables(),
+      views(),
+      info(),
+      indexes(),
+      constraints(),
+      lowCardinality(),
+    ],
+  }),
+  history: new InMemoryHistory(),
+});
+
+// Generate SQL
+const sql = await text2sql.toSql('Show me the top 10 customers by revenue');
+console.log(sql);
+```
+
+## 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.
+
+## Teachables
+
+Inject domain knowledge to improve query accuracy:
+
+```typescript
+import {
+  example,
+  guardrail,
+  hint,
+  term,
+} from '@deepagents/text2sql/instructions';
+
+text2sql.instruct(
+  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`,
+  }),
+);
+```
+
+10 teachable types available: `term`, `hint`, `guardrail`, `example`, `explain`, `clarification`, `workflow`, `quirk`, `styleGuide`, `analogy`.
+
+## Grounding
+
+Control what schema metadata the AI receives:
+
+| Function           | Description                                    |
+| ------------------ | ---------------------------------------------- |
+| `tables()`         | Tables, columns, and primary keys              |
+| `views()`          | Database views                                 |
+| `info()`           | Database version and info                      |
+| `indexes()`        | Index information for performance hints        |
+| `constraints()`    | Foreign keys and other constraints             |
+| `rowCount()`       | Table sizes (tiny, small, medium, large, huge) |
+| `columnStats()`    | Min/max/null distribution for columns          |
+| `lowCardinality()` | Enum-like columns with distinct values         |
+
+## Conversations
+
+Build multi-turn conversations with context:
+
+```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 },
+);
+
+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 },
+);
+```
+
+## Explain Queries
+
+Convert SQL to plain English:
+
+```typescript
+const explanation = await text2sql.explain(`
+  SELECT department, AVG(salary)
+  FROM employees
+  GROUP BY department
+`);
+// "This query calculates the average salary for each department..."
+```
+
+## Documentation
+
+Full documentation available at [januarylabs.github.io/deepagents](https://januarylabs.github.io/deepagents/docs/text2sql):
+
+- [Getting Started](https://januarylabs.github.io/deepagents/docs/text2sql/getting-started)
+- [Generate SQL](https://januarylabs.github.io/deepagents/docs/text2sql/generate-sql)
+- [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)
+- [PostgreSQL](https://januarylabs.github.io/deepagents/docs/text2sql/postgresql)
+- [SQLite](https://januarylabs.github.io/deepagents/docs/text2sql/sqlite)
+- [SQL Server](https://januarylabs.github.io/deepagents/docs/text2sql/sqlserver)
+
+## Repository
+
+[github.com/JanuaryLabs/deepagents](https://github.com/JanuaryLabs/deepagents)

package/dist/finetune/convert-to-gguf.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Convert HuggingFace model to GGUF format using Docker
+ * Uses the official llama.cpp image - no local installation needed
+ *
+ * Usage: node convert-to-gguf.ts <model_dir> <output.gguf> [quantization]
+ *
+ * Arguments:
+ *   model_dir     Path to HuggingFace model directory (contains model.safetensors)
+ *   output.gguf   Output path for the GGUF file
+ *   quantization  Quantization type (default: q8_0)
+ *                 Options: f32, f16, bf16, q8_0, q4_0, q4_1, q5_0, q5_1
+ *
+ * Examples:
+ *   node convert-to-gguf.ts ./qwen3-sql-final ./qwen3-sql.gguf
+ *   node convert-to-gguf.ts ./qwen3-sql-final ./qwen3-sql-q4.gguf q4_0
+ */
+export {};
+//# sourceMappingURL=convert-to-gguf.d.ts.map

package/dist/finetune/convert-to-gguf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-to-gguf.d.ts","sourceRoot":"","sources":["../../src/finetune/convert-to-gguf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/finetune/run-finetune.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TypeScript runner for the Python fine-tuning script.
+ * Uses an isolated virtual environment - no global Python pollution.
+ *
+ * Usage:
+ *   npx tsx packages/text2sql/src/finetune/run-finetune.ts [options]
+ *
+ * Options:
+ *   --epochs <n>        Number of training epochs (default: 3)
+ *   --batch-size <n>    Per-device batch size (default: 4)
+ *   --lr <rate>         Learning rate (default: 1e-4)
+ *   --output-dir <dir>  Output directory (default: ./.finetune/qwen3-sql)
+ *   --max-samples <n>   Limit training samples
+ *   --use-hf            Use HuggingFace dataset instead of local
+ *   --model <name>      Base model (default: Qwen/Qwen3-0.6B)
+ *   --no-gguf           Disable automatic GGUF conversion
+ *   --gguf-type <type>  GGUF quantization type (default: q8_0)
+ *
+ * Prerequisites:
+ *   brew install llama.cpp  # Required for GGUF conversion
+ */
+export {};
+//# sourceMappingURL=run-finetune.d.ts.map

package/dist/finetune/run-finetune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-finetune.d.ts","sourceRoot":"","sources":["../../src/finetune/run-finetune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/finetune/run-mlx.d.ts

@@ -0,0 +1,22 @@
+/**
+ * TypeScript runner for the MLX fine-tuning script.
+ * Uses an isolated virtual environment - no global Python pollution.
+ *
+ * Native Apple Silicon support (M1/M2/M3/M4).
+ *
+ * Usage:
+ *   node packages/text2sql/src/finetune/run-mlx.ts [options]
+ *
+ * Options:
+ *   --iters <n>         Number of training iterations (default: 1000)
+ *   --batch-size <n>    Batch size (default: 4)
+ *   --lr <rate>         Learning rate (default: 1e-5)
+ *   --output-dir <dir>  Output directory (default: ./qwen3-sql-mlx)
+ *   --max-samples <n>   Limit training samples
+ *   --use-hf            Use HuggingFace dataset instead of local
+ *   --model <name>      Base model (default: Qwen/Qwen3-0.5B)
+ *   --num-layers <n>    Number of LoRA layers (default: 16)
+ *   --no-gguf           Disable GGUF export
+ */
+export {};
+//# sourceMappingURL=run-mlx.d.ts.map

package/dist/finetune/run-mlx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-mlx.d.ts","sourceRoot":"","sources":["../../src/finetune/run-mlx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+export * from './lib/adapters/adapter.ts';
 export * from './lib/agents/suggestions.agents.ts';
 export * from './lib/agents/text2sql.agent.ts';
+export * from './lib/checkpoint.ts';
 export * from './lib/file-cache.ts';
 export * from './lib/history/history.ts';
 export * from './lib/history/memory.history.ts';
@@ -8,4 +10,5 @@ export * from './lib/memory/memory.store.ts';
 export * from './lib/memory/sqlite.store.ts';
 export * from './lib/memory/store.ts';
 export * from './lib/sql.ts';
+export * from './lib/teach/teachings.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,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC"}