An enterprise-grade, conversational Text-to-SQL (NL2SQL) and Voice-driven RAG data exploration platform powered by a 4-tier LLM Circuit Breaker, local vector embeddings, and an interactive React 19 Data Studio.
Key Features • System Architecture • LLM Circuit Breaker • Quick Start • API Reference • Security & Guardrails
Advanced RAG System (SQL-based) bridges relational enterprise databases and unstructured qualitative catalogs into a unified conversational experience. Users can query complex business data using plain natural language or spoken voice—without writing a single line of SQL.
The platform automatically classifies user queries into Structured Relational Retrieval (dynamic T-SQL generation against Microsoft SQL Server 2022) or Semantic Vector Retrieval (qualitative catalog search via ChromaDB). It incorporates a resilient 4-tier LLM Circuit Breaker to guarantee zero downtime during API rate limits, strict Defense-in-Depth SQL Guardrails to prevent unauthorized mutations, and an interactive React 19 Data Studio with multi-turn session chaining and 1-click contextual drill-downs.
- 🧠 Universal NL2SQL Engine: Performs dynamic schema introspection over active tables, views, primary keys, and foreign keys across
Sales,Production, andPurchasingschemas. Synthesizes optimized Microsoft SQL Server T-SQL (usingTOP N, dialect-safe subqueries, and enterprise views). - 🛡️ Defense-in-Depth Security: Code-level AST and regex guardrails strip SQL comments (
--,/* */), block statement chaining (;), enforceSELECT/WITHqueries, and blacklist destructive DDL/DML keywords. Executed through a strictly isolated read-only database credential (rag_readonly). - ⚡ 4-Tier LLM Circuit Breaker: Real-time provider health tracking with instantaneous failover:
$$\text{Groq (Primary)} \longrightarrow \text{OpenRouter (Nemotron)} \longrightarrow \text{NVIDIA NIM (Minimax)} \longrightarrow \text{Google Gemini 3.7 Flash (Emergency)}$$ - 🔍 Hybrid Semantic Vector Retrieval: Employs local
BAAI/bge-base-en-v1.5embeddings (768-dim) and ChromaDB to perform semantic similarity search over qualitative product catalogs, specifications, and model descriptions. - 🎙️ Sub-500ms Voice-to-Data Pipeline: Integrated speech-to-text powered by
faster-whisper(int8quantization) for low-latency in-memory transcription directly into the query execution pipeline. - 🔄 Contextual Multi-Turn Session Chaining: Tracks conversation history and previous query results to support natural drill-downs (e.g., "Show top selling road bikes" ➔ "Drill down on inventory for the top item").
- 💻 Modern React 19 Data Studio: High-performance interactive data grid with smart cell formatting (currency, numeric metrics, status badges), multi-column sorting, instant text filtering, 1-click CSV export, SQL inspector drawer, and visual session breadcrumb navigation.
- 📊 Streamlit Prototype Included: Complete standalone Streamlit application (
app.py) for rapid local testing and demonstrations.
┌─────────────────────────────────────────┐
│ User Input: Text or Voice 🎙️ │
└────────────────────┬────────────────────┘
│
[ Speech-to-Text: Faster-Whisper ]
│
[ Dynamic Intent Router ]
/ \
/ \
[Structured Intent] [Semantic Intent]
/ \
┌───────────────────────▼────────┐ ┌────────────▼──────────────────┐
│ Universal NL2SQL Engine │ │ Semantic Vector Retrieval │
│ - Dynamic Schema Reflection │ │ - ChromaDB Vector Store │
│ - T-SQL Synthesis (Circuit │ │ - BAAI/bge-base-en-v1.5 │
│ Breaker LLM Client) │ │ - 294 Product Descriptions │
│ - Defense-in-Depth SQL Guard │ └────────────┬──────────────────┘
└───────────────┬────────────────┘ │
│ │
┌───────────────▼────────────────┐ │
│ SQL Server 2022 DB │ │
│ (AdventureWorks2022) │ │
└───────────────┬────────────────┘ │
└─────────────────────┬───────────────────────┘
│
[ Raw Tabular SQL Records ]
│
┌────────────▼────────────┐
│ High-Performance Grid │
│ (React 19 Data Studio) │
└─────────────────────────┘
The system implements a resilient circuit breaker (services/llm_client.py) that monitors provider status, latency, and HTTP status codes (429 Too Many Requests, 503 Service Unavailable). When an error occurs, it trips a dynamic cooldown and immediately redirects execution to the next provider tier.
[Incoming Request] ──► [Tier 0: Groq] (Active) ──► Ultra-Fast Execution (~2.67s fast-path)
│ (On 429 / 503 / Error)
▼ Trips Dynamic Cooldown (<5ms)
[Tier 1: OpenRouter Nemotron] ──► Tier-1 Fallback
│ (On Error)
▼ Trips Cooldown
[Tier 2: NVIDIA NIM Minimax] ──► Tier-2 Fallback
│ (On Error)
▼ Trips Cooldown
[Tier 3: Google Gemini 3.7 Flash] ──► Emergency Failover
| Tier | Provider & Model | Accuracy | Avg Latency | Rate Limit Profile | Role |
|---|---|---|---|---|---|
| 0 | Groq (openai/gpt-oss-120b) |
11 / 12 (91.7%) | 7.54s (2.67s fast-path) | High RPM / Zero rate limit errors | 🥇 Primary Engine |
| 1 | OpenRouter (nvidia/nemotron-3-ultra-550b-a55b:free) |
11 / 12 (91.7%) | 13.77s | Free tier (recommended 15s pacing) | 🥈 Tier-1 Fallback |
| 2 | NVIDIA NIM (minimaxai/minimax-m3) |
3 / 12 (10/12 w/ breaker) | 22.06s (8.89s fast-path) | Strict ~4k TPM / 2–4 RPM limit | 🥉 Tier-2 Fallback |
| 3 | Google Gemini (gemini-3.7-flash) |
Connected | ~3.0s | 5 RPM & 20 RPD free tier cap | 🚨 Emergency Failover |
- Dynamic Schema Context: ~2,150 tokens (compact table columns, keys, and foreign relations).
- System Dialect Instructions: ~850 tokens.
- User Prompt & Chained History: ~25–100 tokens.
- Synthesized T-SQL Output: ~30–80 tokens.
- Total Single Query Cost: ~3,100 – 3,300 tokens (zero unnecessary token overhead).
User Query ──► [ NL2SQL Prompt ] ──► Generated T-SQL
│
▼
┌────────────────────────────────────────┐
│ Layer 1: Code-Level AST & Regex Guard │
│ - Strip comments (-- and /* */) │
│ - Block query chaining (semicolons) │
│ - Enforce SELECT / WITH prefix │
│ - Block DROP, INSERT, UPDATE, DELETE │
│ - Block EXEC, XP_CMDSHELL, ALTER │
└────────────────────┬───────────────────┘
│ (Sanitized & Validated)
▼
┌────────────────────────────────────────┐
│ Layer 2: Database-Level Permissions │
│ - Role: rag_readonly │
│ - Rights: CONNECT, SELECT only │
│ - No DDL or DML write access │
└────────────────────┬───────────────────┘
│
▼
[ SQL Server 2022 DB ]
| Layer | Technologies |
|---|---|
| Backend Framework | FastAPI, Uvicorn, Pydantic v2 |
| Relational Database | Microsoft SQL Server 2022 (AdventureWorks2022), SQLAlchemy, pyodbc |
| Vector Database & Embeddings | ChromaDB, BAAI/bge-base-en-v1.5 (via sentence-transformers) |
| LLM Providers | Groq, OpenRouter, NVIDIA NIM, Google Gemini |
| Speech-to-Text | Faster-Whisper (small model, int8 CPU quantization) |
| Frontend UI | React 19, Vite, Tailwind CSS 4, Lucide Icons |
| Rapid Prototyping | Streamlit, streamlit-mic-recorder |
├── .env.example # Environment configuration template
├── .gitignore # Production git exclusion rules
├── api_models.py # Pydantic request and response schemas
├── app.py # Streamlit interactive UI application
├── config.py # Centralized Pydantic application settings
├── main.py # FastAPI application backend entrypoint
├── requirements.txt # Python backend dependencies
├── static/
│ ├── index.html # Lightweight standalone demo UI
│ └── recorder.js # Standalone audio recording module
├── data/
│ ├── bootstrap_schema.py # Database schema bootstrapping script
│ ├── create_database.sql # SQL Server database creation script
│ ├── create_readonly_login.sql # Security script for rag_readonly login
│ ├── index_chroma.py # ChromaDB vector indexer for product catalog
│ └── seed_data.py # Data seeding utility
├── db/
│ ├── __init__.py # Database package initialization
│ └── models.py # SQLAlchemy ORM database models
├── services/
│ ├── __init__.py # Services package initialization
│ ├── embedding_service.py # Local SentenceTransformer embeddings wrapper
│ ├── intent_router.py # Dynamic query intent router (Structured vs Semantic)
│ ├── llm_client.py # 4-tier Circuit Breaker LLM client
│ ├── nl2sql_service.py # Universal schema reflection & T-SQL generator
│ ├── semantic_search_service.py # ChromaDB vector search interface
│ ├── session_manager.py # Multi-turn conversational history manager
│ ├── speech_to_text_service.py # Faster-Whisper audio transcription engine
│ └── sql_guard.py # AST/regex T-SQL validation & comment stripper
└── frontend/ # React 19 + Vite Data Studio
├── index.html # HTML entrypoint
├── package.json # Frontend dependencies (React 19, Tailwind 4)
├── vite.config.js # Vite configuration with backend proxy
└── src/
├── App.jsx # Main Data Studio layout & session orchestration
├── index.css # Global Tailwind CSS 4 styles
├── main.jsx # React root mounting
├── components/
│ ├── DataGrid.jsx # High-performance tabular data grid with drill-downs
│ ├── ErrorBanner.jsx # Error notification banner
│ ├── MetricsBar.jsx # Execution latency, intent pill & CSV export
│ ├── Navbar.jsx # Widescreen navigation with API health status
│ ├── QueryInput.jsx # Text input, microphone recorder & follow-up mode
│ ├── SessionBreadcrumbs.jsx # Multi-turn query chain visualizer
│ ├── Sidebar.jsx # Query history & categorized query presets
│ ├── SqlInspector.jsx # Generated T-SQL syntax inspector drawer
│ └── ThinkingIndicator.jsx # Live pipeline execution skeleton loader
└── services/
└── api.js # Frontend API client module
- Python:
3.10or higher - Node.js:
18.0or higher &npm - Database: Microsoft SQL Server 2022 (or Express) with
AdventureWorks2022database installed - ODBC Driver: ODBC Driver 18 for SQL Server
- API Keys: At least one LLM key (Groq, OpenRouter, NVIDIA NIM, or Google AI Studio)
git clone https://github.com/Afaque-Khan04/NL2SQL-Analytics-Platform.git
cd NL2SQL-Analytics-Platform# Create virtual environment
python -m venv venv
# Activate virtual environment
# On Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# On Linux / macOS:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txtCopy .env.example to .env and fill in your database credentials and API keys:
cp .env.example .envEdit .env:
# Primary LLM Provider
LLM_PROVIDER=groq
GROQ_API_KEY=your_groq_api_key_here
# Fallback API Keys (Optional but recommended for circuit breaker)
OPENROUTER_API_KEY=your_openrouter_api_key_here
NVIDIA_API_KEY=your_nvidia_api_key_here
GOOGLE_API_KEY=your_gemini_api_key_here
# Database Configuration (SQL Server 2022)
SQL_SERVER_HOST=.\SQLEXPRESS
SQL_SERVER_DB=AdventureWorks2022
USE_WINDOWS_AUTH=True
SQL_SERVER_DRIVER=ODBC Driver 18 for SQL Server
SQL_SERVER_READONLY_USER=rag_readonly
SQL_SERVER_READONLY_PASSWORD=YourSecurePassword123!Create the restricted rag_readonly database credential used by the NL2SQL engine:
-- Run inside SQL Server Management Studio (SSMS) on AdventureWorks2022:
USE [AdventureWorks2022];
CREATE LOGIN [rag_readonly] WITH PASSWORD=N'YourSecurePassword123!', CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF;
CREATE USER [rag_readonly] FOR LOGIN [rag_readonly];
ALTER ROLE [db_datareader] ADD MEMBER [rag_readonly];
GRANT CONNECT TO [rag_readonly];(Alternatively, execute data/create_readonly_login.sql)
Extract qualitative product descriptions from AdventureWorks and build the local Chroma vector index:
python data/index_chroma.pyTerminal 1 — Backend:
uvicorn main:app --port 8100 --reloadBackend API available at: http://localhost:8100 (Swagger docs: http://localhost:8100/docs)
Terminal 2 — Frontend:
cd frontend
npm install
npm run devFrontend Data Studio available at: http://localhost:5100
streamlit run app.pyStreamlit UI available at: http://localhost:8501
| Method | Endpoint | Description | Request Payload | Response Attributes |
|---|---|---|---|---|
POST |
/query |
Execute natural language query | QueryRequest (query, session_id, is_follow_up, selected_row_context) |
query, intent, generated_sql, results, answer, execution_time_ms, session_id, turn_index |
POST |
/query_audio |
Full voice-to-retrieval pipeline | multipart/form-data (file, session_id, is_follow_up) |
transcribed_text, language, audio_duration_seconds, intent, generated_sql, results, answer, execution_time_ms |
POST |
/transcribe |
Transcribe speech audio to text | multipart/form-data (file) |
text, language, duration |
POST |
/session/new |
Initialize fresh conversational session | None | session_id, status |
GET |
/session/{id}/history |
Fetch complete query turn sequence | id path parameter |
session_id, turns (array of TurnContext) |
GET |
/health |
Health and connectivity probe | None | status, database, vector_store |
{
"query": "Show top 5 sales persons by total sales in 2013",
"is_follow_up": false
}{
"query": "Show top 5 sales persons by total sales in 2013",
"intent": "structured",
"generated_sql": "SELECT TOP 5 sp.BusinessEntityID, p.FirstName, p.LastName, sp.SalesYTD FROM Sales.SalesPerson sp JOIN Person.Person p ON sp.BusinessEntityID = p.BusinessEntityID ORDER BY sp.SalesYTD DESC;",
"results": [
{
"BusinessEntityID": 276,
"FirstName": "Linda",
"LastName": "Mitchell",
"SalesYTD": 4251368.55
}
],
"answer": "Here are the top 5 sales persons for 2013 led by Linda Mitchell with $4.25M in sales.",
"execution_time_ms": 2840.5,
"session_id": "9f71c4c8-3e4b-4b2a-8b1e-927164923f11",
"turn_index": 1,
"parent_query": null
}The multi-turn session architecture allows continuous conversational exploration without re-explaining context:
- Query 1 (Broad Query):
"Show me top 5 highest grossing products in 2013" ➔ Returns tabular list of products sorted by revenue.
- Interactive Row Drill-Down:
User clicks on Row 1 (Product ID 794 - Road-250 Red, 48).
- Query 2 (Contextual Follow-up):
"Show current inventory levels and shelf locations for this item" ➔ The engine resolves the context from Turn 1, synthesizes the relational join with
Production.ProductInventory, and retrieves exact bin and shelf records. - Session Breadcrumbs:
User can navigate back to Turn 1 or reset to a fresh session with one click.
Contributions are welcome! To contribute:
- Fork the repository.
- Create your feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
Distributed under the MIT License. See LICENSE for more information.