@deepagents/text2sql 0.34.0 → 0.36.0

package/README.md

@@ -5,7 +5,7 @@ AI-powered natural language to SQL. Ask questions in plain English, get executab
 ## Features
 
 - **Natural Language to SQL** - Convert questions to validated, executable queries
-- **Multi-Database Support** - PostgreSQL, SQLite, and SQL Server adapters
+- **Multi-Database Support** - PostgreSQL, SQLite, SQL Server, MySQL/MariaDB, and BigQuery adapters
 - **Schema-Aware** - Automatic introspection of tables, relationships, indexes, and constraints
 - **Domain Knowledge** - Inject business terms, guardrails, and query patterns via fragments
 - **Conversational** - Multi-turn conversations with context persistence
@@ -23,16 +23,18 @@ 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 { ContextEngine, InMemoryContextStore } from '@deepagents/context';
 import { Text2Sql } from '@deepagents/text2sql';
 import {
   Postgres,
+  columnValues,
   constraints,
   indexes,
   info,
-  lowCardinality,
+  rowCount,
   tables,
   views,
 } from '@deepagents/text2sql/postgres';
@@ -41,24 +43,37 @@ 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 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(),
-      lowCardinality(),
-    ],
-  }),
-  store: new InMemoryContextStore(),
+  model: groq('openai/gpt-oss-20b'),
+  filesystem: new InMemoryFs(),
+  adapter,
+  context: (...fragments) => {
+    const engine = new ContextEngine({
+      store,
+      chatId: 'chat-123',
+      userId: 'user-456',
+    });
+    engine.set(...fragments);
+    return engine;
+  },
 });
 
 // Generate SQL
@@ -72,14 +87,31 @@ Text2SQL works with any model provider supported by the [Vercel AI SDK](https://
 
 ## 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 +123,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`.
@@ -105,39 +140,53 @@ See [@deepagents/context](../context/README.md) for full fragment documentation.
 
 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         |
+| 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                     |
+| `columnValues()` | Enum-like and low-cardinality columns with sampled values |
 
 ## 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' },
+]);
+```
+
+## 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
@@ -145,13 +194,15 @@ const followUp = await text2sql.chat(
 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)
+- [Generate SQL](https://januarylabs.github.io/deepagents/docs/text2sql/to-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)
+- [MySQL / MariaDB](https://januarylabs.github.io/deepagents/docs/text2sql/mysql)
+- [BigQuery](https://januarylabs.github.io/deepagents/docs/text2sql/bigquery)
 
 ## Repository
 

package/dist/index.js

@@ -5295,7 +5295,7 @@ Action: Ask user: "Top by what metric\u2014total revenue, number of orders, or m
     // Style preferences
     styleGuide({
       prefer: "Full table names as aliases (users AS users). Descriptive column aliases (COUNT(*) AS total_count).",
-      never: "Abbreviated aliases (u, oi) or positional aliases (t1, t2, a, b)."
+      never: "Abbreviated aliases (u, oi) or positional aliases (t1, t2, a, b). Schema-qualified column references on aliased tables (e.g. dbo.users.id when table is aliased) \u2014 always use the alias (users.id)."
     }),
     styleGuide({
       prefer: "Concise, business-friendly summaries with key comparisons and helpful follow-ups."