Metadata-Version: 2.4
Name: nl2sql-engine
Version: 0.10.0
Summary: Ask a database questions in English: the model writes a typed query plan, never SQL, and the plan is checked against the schema and the caller's role before any SQL is generated
License-Expression: MIT
Project-URL: Homepage, https://github.com/nadeem4/nl2sql
Project-URL: Documentation, https://nadeem4.github.io/nl2sql/
Project-URL: Source, https://github.com/nadeem4/nl2sql
Project-URL: Issues, https://github.com/nadeem4/nl2sql/issues
Project-URL: Demo, https://nl2sql.codewithnk.com
Keywords: nl2sql,text-to-sql,natural language,sql,llm,langgraph,sqlglot,database
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: langgraph<2,>=1.2
Requires-Dist: langchain>=0.2.0
Requires-Dist: langchain-core<2,>=1.6
Requires-Dist: langchain-openai<2,>=1.6
Requires-Dist: chromadb<2,>=1.5
Requires-Dist: nl2sql-sdk[sqlalchemy]~=0.10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlglot>=23.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: pybreaker>=1.3.0
Requires-Dist: polars>=1.44
Requires-Dist: duckdb>=1.5
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: typing_extensions>=4.0
Requires-Dist: httpx<1,>=0.23
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic<2,>=1.7; extra == "anthropic"
Provides-Extra: aws
Requires-Dist: boto3; extra == "aws"
Provides-Extra: azure
Requires-Dist: azure-identity; extra == "azure"
Requires-Dist: azure-keyvault-secrets; extra == "azure"
Provides-Extra: duckdb
Requires-Dist: duckdb; extra == "duckdb"
Requires-Dist: duckdb-engine; extra == "duckdb"
Provides-Extra: hashicorp
Requires-Dist: hvac; extra == "hashicorp"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.10; extra == "mcp"
Requires-Dist: uvicorn>=0.20.0; extra == "mcp"
Provides-Extra: mssql
Requires-Dist: pyodbc>=4.0.0; extra == "mssql"
Requires-Dist: pymssql>=2.2.0; platform_system == "Linux" and extra == "mssql"
Provides-Extra: mysql
Requires-Dist: pymysql[rsa]>=1.1.0; extra == "mysql"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
Provides-Extra: all
Requires-Dist: duckdb; extra == "all"
Requires-Dist: duckdb-engine; extra == "all"
Requires-Dist: pyodbc>=4.0.0; extra == "all"
Requires-Dist: pymssql>=2.2.0; platform_system == "Linux" and extra == "all"
Requires-Dist: pymysql[rsa]>=1.1.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9; extra == "all"
Dynamic: license-file

# nl2sql-engine

The engine behind NL2SQL, for developers who embed it in Python or run it through the CLI and REST packages. The model returns a typed query plan, never SQL text; the plan is checked against the real schema and the caller's role before any SQL is generated.

This distribution holds the pipeline, the `nl2sql` Python facade and the database adapters (PostgreSQL, MySQL, SQL Server, SQLite, DuckDB). The `nl2sql` command is the separate `nl2sql-cli` package and the REST server and web app are `nl2sql-api`.

Requires Python 3.12 or newer.

## Try it

Hosted demo on three sample databases, nothing to install: <https://nl2sql.codewithnk.com>. To run it yourself:

```bash
pip install "nl2sql-cli[web]"
nl2sql demo
```

## Use it from Python

```python
from nl2sql import NL2SQL, UserContext

engine = NL2SQL.demo()      # the bundled databases; reads a provider key from the environment
engine.index.build()        # once: builds the search index
result = engine.run_query(
    "How many customers are there?",
    user_context=UserContext(roles=["admin"]),
)
print(result.final_answer["summary"] if result.final_answer else result.errors)
```

Your own config instead: `NL2SQL.from_config("nl2sql.yaml")`. Database drivers are extras (`pip install "nl2sql-engine[postgres]"`, `[mysql]`, `[mssql]`, `[duckdb]`, `[all]`); SQLite needs none.

## Security

The model returns a typed plan and never SQL; the plan is checked against the schema and the caller's role before any SQL is generated. The provider sees the question, the schema it needs and the result rows. Read the [security model](https://nadeem4.github.io/nl2sql/security/model/) before pointing it at real data.

## Documentation

Full documentation: <https://nadeem4.github.io/nl2sql/>

- [Get started](https://nadeem4.github.io/nl2sql/get-started/)
- [How it works](https://nadeem4.github.io/nl2sql/how-it-works/overview/)
- [Security model](https://nadeem4.github.io/nl2sql/security/model/)
- [Known limitations](https://nadeem4.github.io/nl2sql/reference/limitations/)

`nl2sql-sdk`, `nl2sql-engine`, `nl2sql-api` and `nl2sql-cli` are released together. MIT licensed.
