NL2SQL Platform

Production-Grade Natural Language to SQL Engine.

The NL2SQL Platform is a modular, agentic system designed to convert natural language questions into accurate, authorized SQL queries across multiple database engines (Postgres, MySQL, MSSQL, SQLite).

It features:

• Defense-in-Depth Security: RBAC and Read-Only enforcement at multiple layers. Learn more.
• Multi-Database Routing: Federated queries across silos.
• Agentic Reasoning: Iterative planning, self-correction, and validation.

---

📚 Documentation

Detailed documentation is available in the docs/ directory.

• Architecture: Understand the SQL Agent, Map-Reduce routing, and Plugins.
• Security: Authentication, RBAC, and Validation.
• Guides: Installation, Configuration, and Benchmarking.
• Reference: CLI arguments and API specs.

---

🚀 Quick Start

1. Installation

The platform is a monorepo. Install the CLI application:

# Core & SDK
pip install -e packages/adapter-sdk
pip install -e packages/cli  # Installs 'nl2sql' command

# Database Adapters (install as needed, or let setup wizard handle it)
# pip install -e packages/adapters/postgres

2. Setup

Run the interactive wizard to configure your database and LLM:

nl2sql setup

This will create your configuration files and index your schema.

3. Usage

Querying

nl2sql run "Show me the top 5 users by sales"

Other Commands

• nl2sql doctor - Diagnose environment issues.
• nl2sql list-adapters - Show installed database adapters.
• nl2sql benchmark - Run evaluation suite.

---

🏗️ Architecture

The system uses a directed graph of AI Agents (Planner -> Validator -> Generator).

graph TD
    UserQuery["User Query"] --> Semantic["Semantic Analysis"]
    Semantic --> Decomposer["Decomposer Node"]
    Decomposer -- "Splits Query" --> MapBranching["Fan Out (Map)"]

    subgraph Execution_Layer ["Execution Layer (Parallel)"]
        MapBranching --> SQL_Agent["SQL Agent (Planner + Validator + Executor)"]
    end

    SQL_Agent -- "Result Set" --> Reducer["State Aggregation"]
    Reducer --> Aggregator["Aggregator Node"]

Loading

Read more in the Architecture Overview.

---

🤝 Contributing

See Development Guide.