Metadata-Version: 2.4
Name: nl2sql-agent
Version: 0.1.0
Summary: Natural-language-to-SQL agent loop with schema and execution tools, hints, feedback store, and eval harness. Imports as `nl2sql`.
Author: Marco Kotrotsos
License: MIT
Project-URL: Homepage, https://github.com/Kotrotsos/nl2sql
Project-URL: Repository, https://github.com/Kotrotsos/nl2sql
Project-URL: Issues, https://github.com/Kotrotsos/nl2sql/issues
Keywords: sql,nlp,agent,llm,anthropic,openai,text-to-sql,nl2sql
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlglot>=25.0
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.7
Requires-Dist: PyYAML>=6.0
Requires-Dist: prompt_toolkit>=3.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.39; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == "openai"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: all
Requires-Dist: anthropic>=0.39; extra == "all"
Requires-Dist: openai>=1.40; extra == "all"
Requires-Dist: psycopg[binary]>=3.1; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-html>=4.1; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# nl2sql

Natural-language-to-SQL with a single agent loop, real schema introspection, executed validation, domain hints, and a feedback store.

Distilled from the Microsoft ISE article *SQL query generation from natural language* (Ashley Costigane, May 2026). The article shows the load-bearing primitives are: (a) a small set of schema and execution tools, (b) live query execution, (c) injected domain hints (+10 to 14 points accuracy), and (d) a feedback store of corrected SQL (+19 points). This library implements all four behind a clean Python API and a Typer/Rich CLI.

## Install

```bash
pip install nl2sql-agent                    # core, imports as `nl2sql`
pip install "nl2sql-agent[anthropic]"       # + Anthropic
pip install "nl2sql-agent[openai]"          # + OpenAI
pip install "nl2sql-agent[postgres]"        # + Postgres driver
pip install "nl2sql-agent[all]"             # everything
```

> The PyPI distribution name is `nl2sql-agent` because the unqualified `nl2sql` namespace was already taken by an unrelated stub. The Python import path is unchanged: `from nl2sql import Nl2Sql`.

## Quickstart

```python
from nl2sql import Nl2Sql
from nl2sql.db import SqliteDatabase
from nl2sql.llm import AnthropicClient

n2s = Nl2Sql(
    db=SqliteDatabase("./customers.db"),
    llm=AnthropicClient(model="claude-opus-4-7"),
)

result = n2s.ask("How many customers signed up last quarter?")
print(result.sql)
print(result.rows)
```

## CLI

```bash
nl2sql init                              # scaffold .nl2sql.yaml
nl2sql ask "How many orders this month?"
nl2sql repl                              # interactive
nl2sql inspect tables
nl2sql inspect schema --table households
nl2sql eval run ./datasets/livesqlbench-medium --output ./reports/run-001
nl2sql feedback list
nl2sql hints validate ./hints.yaml
```

Every command supports `--json` for piping, `--profile`, `--db`, `--model`, `--quiet`, `--no-color`.

## Library shape

- `nl2sql.Nl2Sql` — public entry point
- `nl2sql.db` — `SqliteDatabase`, `PostgresDatabase`, `Database` ABC
- `nl2sql.llm` — `AnthropicClient`, `OpenAIClient`, `LLMClient` ABC, `MockLLMClient` for testing
- `nl2sql.tools` — the four core tools the agent calls
- `nl2sql.hints` — `DomainHints`, `KnowledgeStore`
- `nl2sql.feedback` — `FeedbackStore`, `JsonFeedbackStore`
- `nl2sql.safety` — SELECT-only check, single-statement, identifier denylist
- `nl2sql.eval` — `run_eval`, `FlexibleMatcher`, `LiveSQLBenchDataset`
- `nl2sql.cli` — Typer app

## Safety

By default the agent can only run `SELECT`. The safety layer parses with `sqlglot`, rejects multi-statement input, rejects non-`SELECT` roots, and refuses to touch `pg_*`, `information_schema`, `sqlite_master`, `sqlite_sequence`. Result rows are capped (default 200) and queries are timed out (default 10 s).

## Testing

```bash
pip install -e ".[dev,all]"
pytest -q
pytest --html=test-report.html --self-contained-html
```

## Documentation

See `docs/index.html` (light/dark mode, print-friendly) for the full reference.

## License

MIT.
