nl2sql

Browser-first TypeScript toolkit for converting natural-language questions to SQL via an LLM agent loop with verification layers.

Why

Most NL2SQL libraries just translate a question to a single SQL string and call it done. Real users want trustworthy answers: the agent should plan, run queries, verify them, and iterate until the data actually answers the question. nl2sql packages that loop in a small, dependency-light, provider-agnostic library that works in the browser and Node.

• Plan -> Query -> Verify -> Answer loop powered by native LLM function-calling.
• Streaming: onToken callback streams answer tokens to the UI as they arrive.
• Configurable SQL requirement: requireSqlBeforeFinish: false lets the model answer greetings and non-data questions without running SQL.
• Stuck detection: after 3 consecutive query failures, the model is told to change approach or finish with what it has.
• Duplicate query cache: identical SQL is detected and cached — the model gets the cached result with a warning instead of re-executing.
• Reserved-word sanitization: AS total -> AS [total] automatically, preventing AlaSQL parse errors.
• Layered verification: hard checks (column/table existence), advisory warnings (zero rows, high row count, all-null columns).
• Provider-agnostic: ship your own LlmProvider (for any model) and SqlProvider (for any database). Reference OpenAI adapter included.
• Browser-first: works in Vite/Webpack/Next.js out of the box. No Node-only polyfills.
• Cancellable: pass an AbortSignal to bail out mid-flight.

Install

npm install nl2sql openai

openai is a peer dependency when you use the bundled OpenAI adapter. If you implement your own LlmProvider, you don't need it.

Quickstart

import { Nl2SqlAgent, createOpenAiProvider, createStaticSqlProvider } from "nl2sql";
import OpenAI from "openai";

const agent = new Nl2SqlAgent({
  provider: createOpenAiProvider(
    new OpenAI({ apiKey: process.env.OPENAI_API_KEY!, dangerouslyAllowBrowser: true }),
    { model: "gpt-4o-mini", temperature: 0.1 }
  ),
  language: "en",
  requireSqlBeforeFinish: true, // default; set false for conversational mode
});

const result = await agent.query("Top 5 customers by revenue last month", {
  sqlProvider: createStaticSqlProvider({
    schemas: [{ name: "orders", columns: [{ name: "customer", type: "STRING" }, { name: "revenue", type: "FLOAT" }, { name: "created_at", type: "DATETIME" }] }],
    executeSQL: async (sql) => myDb.exec(sql),
  }),
}, {
  onStep: (step) => console.log("ran:", step.sql),
  onToken: (token) => process.stdout.write(token), // streaming
  onAnswer: (answer) => console.log("done:", answer),
});

console.log(result.answer);
console.log(result.sql);
console.log(result.steps);

Configuration

AgentConfig

Option	Type	Default	Description
provider	LlmProvider	required	LLM provider (use createOpenAiProvider or implement your own)
language	string	"en"	Locale code for output formatting ("en", "fa", etc.)
maxSteps	number	20	Maximum LLM round-trips before forcing a final answer
requireSqlBeforeFinish	boolean	true	When false, the model can answer non-data questions (greetings, thanks) without running SQL. The finish tool only requires answer, not sql/explanation.
historyReducer	(messages, max) => messages	defaultHistoryReducer	Trims conversation history to fit context windows
sqlHints.maxRowsWarning	number	500	Advisory warning threshold for large result sets
sqlHints.allowNonSelect	boolean	false	Allow INSERT/UPDATE/DELETE statements

QueryCallbacks

Callback	Description
onStep(step)	Fired after each SQL query executes (includes sql, result, verification)
onToken(token)	Streams answer tokens as they arrive from the LLM
onAnswer(answer)	Fired when the model produces its final answer
onFinalSQL(sql)	Fired with the canonical SQL from the finish call
signal	AbortSignal to cancel mid-flight

How it works

1. The agent assembles a system prompt from composable sections (role, capabilities, schema, workflow, output rules, optional instructions).
2. It calls the LLM with two tools: run_sql and finish.
3. SQL is sanitized (sanitizeReservedAliases) and verified before execution: column references must match the schema (minimal SQL tokenizer + Levenshtein near-match).
4. Duplicate queries are detected via normalized SQL cache and return cached results.
5. After execution, advisory warnings are computed (zero rows, high row count, all-null columns) and attached to the tool result.
6. If 3 consecutive queries fail, a system message tells the model to change approach or finish.
7. The LLM may call run_sql again to verify, or call finish with the final answer.
8. Answer tokens stream to the UI via onToken as they arrive.

Documentation

• Getting started
• Custom providers
• Browser security

Examples

• examples/browser — Vite + AlaSQL demo with OpenAI
• examples/node — Node ESM script

Browser security note

Shipping OpenAI API keys in a browser exposes them to users. Use the OpenAI adapter's dangerouslyAllowBrowser: true flag only for local development or trusted internal tools. For production browser deployments, proxy requests through your own backend that injects the API key.

License

MIT