QueryMind — Enterprise AI Text-to-SQL Engine

QueryMind is an enterprise-grade AI Text-to-SQL platform that translates complex natural language questions into safe, verified, schema-grounded SQL queries against SQL databases (PostgreSQL/SQLite) and returns tabular execution results without requiring manual SQL authoring.

Unlike naive LLM SQL generators, QueryMind enforces strict schema grounding, multi-stage read-only safety guardrails, pre-execution dry-runs (EXPLAIN), self-checking validation, targeted ambiguity clarification, and deterministic state machine pipeline orchestration.

---

🏛️ System Architecture

QueryMind decouples schema grounding, intent parsing, candidate SQL generation, safety verification, database execution, and orchestration into isolated modules with strongly typed Pydantic stage boundaries.

                         ┌─────────────────────────────────┐
                         │   Natural Language Question     │
                         └────────────────┬────────────────┘
                                          │
                                          ▼
                         ┌─────────────────────────────────┐
                         │    1. PARSING_INTENT (Pydantic) │
                         └────────────────┬────────────────┘
                                          │
              ┌───────────────────────────┼──────────────────────────┐
              ▼                           ▼                          ▼
     [Ambiguous Query]           [Unanswerable Query]        [Valid Question Intent]
     AWAITING_CLARIFICATION       FAILED (Schema Alert)              │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 2. RETRIEVING_SCHEMA (Llama)  │
                                                     └───────────────┬───────────────┘
                                                                     │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 3. GENERATING_SQL (LLM Core)  │
                                                     └───────────────┬───────────────┘
                                                                     │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 4. VALIDATING (AST/Read-Only) │
                                                     └───────────────┬───────────────┘
                                                                     │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 5. EXECUTING (Read-Only DB)   │
                                                     └───────────────┬───────────────┘
                                                                     │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 6. SELF_CHECKING (Verification│
                                                     └───────────────┬───────────────┘
                                                                     │
                                                                     ▼
                                                     ┌───────────────────────────────┐
                                                     │ 7. DONE (Interactive Table)   │
                                                     └───────────────────────────────┘

---

✨ Key Capabilities & Technical Innovations

1. Schema Grounding & Retrieval (LlamaIndex Layer)

• Compact Context: Dynamically indexes database metadata (tables, columns, data types, primary/foreign keys, and distinct column sample values).
• Sub-schema Retrieval: Isolates only the minimal relevant schema subset for each question rather than injecting entire database schemas into the LLM prompt.
• Schema Drift Protection: Re-indexing updates the vector/metadata cache automatically without requiring code rewrites.

2. Multi-Stage Read-Only Safety & Guardrails Layer

• AST & Regex Read-Only Validator: Rejects any non-SELECT / WITH statement (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, multi-statement injection ;, or SQL comments).
• Automatic Query Bounds: Auto-injects LIMIT 100 if missing and blocks unbounded wildcard queries on large tables.
• EXPLAIN Dry-Run: Validates syntax correctness and query execution plan before executing against live databases.

3. Deterministic Pipeline Orchestration State Machine

• State machine governing execution states: PARSING_INTENT ➔ RETRIEVING_SCHEMA ➔ GENERATING_SQL ➔ VALIDATING ➔ EXECUTING ➔ SELF_CHECKING ➔ DONE.
• Bounded Retry Loop: Retries query generation up to 3 times with feedback loop if AST validation or self-check critique fails.
• Explicit state handling for AWAITING_CLARIFICATION and FAILED (unanswerable questions).

4. Enterprise Web Studio & CLI Walkthrough

• Next.js 15 TypeScript UI: Dark-theme glassmorphism web app displaying live pipeline state transitions, grounded schema viewer, Pydantic intent JSON, syntax-highlighted SQL preview with copy button, and interactive data tables.
• CLI Runner: Interactive walkthrough script (run_demo.py) demonstrating all pipeline states offline or online.

---

📁 Repository Structure

QueryMind/
├── backend/
│   ├── app/
│   │   ├── models/            # Pydantic Schemas (QueryIntent, SchemaContext, SQLCandidate, etc.)
│   │   ├── schema/            # LlamaIndex Schema Grounding Indexer & Subset Retriever
│   │   ├── intent/            # Natural Language Intent Parser & Ambiguity Detector
│   │   ├── generation/        # Grounded Candidate SQL Generation Engine
│   │   ├── validation/        # Read-Only AST/Regex Parser, Bounds Injector & EXPLAIN Dry-Run
│   │   ├── execution/         # Read-Only Database Executor with Timeout Guardrails
│   │   ├── self_check/        # Result Shape & Answerability Verifier
│   │   ├── orchestration/     # Deterministic Pipeline State Machine
│   │   ├── db/                # PostgreSQL/SQLite Connection Pool & Seed Database
│   │   ├── llm/               # API Provider (Gemini/OpenAI) + Hybrid Offline Engine
│   │   └── api_server.py      # FastAPI REST Server
│   ├── tests/                 # Pytest Automated Test Suite
│   ├── requirements.txt       # Backend Python Dependencies
│   └── run_demo.py            # Standalone CLI Walkthrough Runner
├── frontend/                  # Next.js 15 TypeScript Application
│   ├── src/
│   │   ├── app/               # Next.js App Router Page & Layout
│   │   ├── components/        # Header, StateTracker, SchemaViewer, SqlPreview, ResultsTable, ClarificationCard
│   │   └── lib/               # API Client Library
│   ├── next.config.js
│   ├── package.json
│   └── tsconfig.json
└── README.md

---

🚀 Quick Start Guide

Prerequisites

• Python 3.10+
• Node.js 18+ and npm

1. Backend Setup & Seeding

# Navigate to backend directory
cd backend

# Install Python dependencies
pip install -r requirements.txt

# Seed Database (Sets up e-commerce database with customers, products, orders, order_items, reviews)
python -m app.db.seed

# Run Pytest Automated Verification Suite
python -m pytest

# Run Standalone CLI Scenario Walkthrough
python run_demo.py

# Launch FastAPI Server (Runs on http://localhost:8000)
python -m app.api_server

2. Frontend Studio Setup

# In a new terminal, navigate to frontend directory
cd frontend

# Install Node dependencies
npm install

# Launch Next.js Development Studio (Runs on http://localhost:3000)
npm run dev

Open http://localhost:3000 in your browser to interact with QueryMind Studio!

---

🔬 Core Test & Scenario Coverage

Run python run_demo.py inside backend/ to verify all evaluation scenarios:

1. Straightforward Natural Query:

   • Query: "How many orders shipped late last month by region?"
   • Returns grounded orders schema, generates valid SELECT shipping_region, COUNT(*)... GROUP BY shipping_region, and executes in <1ms.

2. Ambiguous Query Detection:

   • Query: "Show me top customers"
   • Triggers AWAITING_CLARIFICATION state with targeted options ("Rank by total spend or by total order count?").

3. Unanswerable Query Detection:

   • Query: "What is the average employee salary by department?"
   • Detects non-existent schema entities and returns explicit unanswerable response without fabricating non-existent columns.

4. Multi-Turn Query Refinement:

   • Follow-up Query: "now filter for orders shipped in 2025"
   • Refines prior query using conversational context.

5. Security Violation Block:

   • Query: "DELETE FROM customers WHERE id = 1"
   • Rejected by safety validator prior to database execution.

---

🛠️ Schema Grounding & Tradeoffs Note

Schema Grounding Approach

QueryMind uses a two-pass indexing strategy:

1. Indexing Pass: Extracts table schemas, column data types, foreign keys, and distinct column sample values.
2. Sub-schema Isolation: Uses question intent to filter and extract top-K relevant tables/columns, reducing LLM context window cost and eliminating hallucinations over non-relevant database tables.

Architecture Tradeoffs & Limitations

• Deep Multi-Hop Joins (>4 Tables): Queries spanning multiple intermediary tables benefit from explicit foreign-key hints in table descriptions.
• Advanced Analytical Queries: Queries requiring specialized SQL constructs (WINDOW functions, CUBE, ROLLUP) require explicit LLM prompt directives.
• Ambiguity Resolution: Queries containing subjective adjectives ("top products", "recent orders") trigger targeted clarification prompts rather than making unverified assumptions.

---

📄 License

Released under the MIT License.