joelgilbert/NL2SQL

1---2title: NL2SQL Query System3emoji: 🤖4colorFrom: blue5colorTo: purple  6sdk: streamlit7sdk_version: 1.32.08app_file: app.py9pinned: false10license: mit11---12 13# 🤖 Natural Language to SQL Query System14 15Transform your questions into SQL queries using AI! This application uses a multi-agent architecture to understand natural language questions, generate SQL queries, execute them safely, and explain the results in plain English.16 17## ✨ Features18 19- **🧠 Multi-Agent AI System**20  - Gatekeeper: Validates and classifies user intent21  - SQL Generator: Creates optimized queries using Cloudflare Workers AI22  - Explainer: Provides business-friendly result summaries23 24- **🔒 Enterprise-Grade Security**25  - Read-only mode by default (SELECT queries only)26  - DBA mode with password protection for write operations27  - SQL injection prevention28  - Comprehensive audit logging29 30- **🚀 Smart Query Generation**31  - Automatic error correction (up to 3 retries)32  - Semantic schema search using vector embeddings33  - Query optimization and validation34 35- **📊 Interactive Results**36  - Clean table visualization37  - Natural language explanations38  - Query execution metrics39  - Session statistics40 41## 🎯 How to Use42 43### Ask Questions in Plain English44 45**Examples:**46- "How many customers do we have?"47- "Show me total revenue by product category"48- "Who are our top 5 customers by spending?"49- "List orders from last week"50- "What's the average order value?"51 52### Two Modes53 54**🟢 Read-Only Mode** (Default)55- Safe for business intelligence queries56- SELECT queries only57- No data modification58 59**🔴 DBA Mode** (Password Protected)60- Full database access61- INSERT, UPDATE, DELETE operations62- Requires approval for destructive queries63 64## 🏗️ Architecture65 66```67User Question68     ↓69Agent 1: Gatekeeper (Groq/Llama-3.1)70  - Validates intent71  - Filters irrelevant questions72     ↓73Vector Search (Upstash Vector)74  - Finds relevant table schemas75  - Retrieves similar queries76     ↓77Agent 2: SQL Generator (Cloudflare/SQLCoder-7B-2)78  - Generates SQL query79  - Auto-corrects errors80  - Validates syntax81     ↓82Security Validator83  - Checks for SQL injection84  - Verifies permissions85  - Validates table access86     ↓87Query Executor (Neon PostgreSQL)88  - Executes query safely89  - Returns results90     ↓91Agent 3: Explainer (Groq/Llama-3.1)92  - Analyzes results93  - Generates insights94  - Creates human-friendly explanation95```96 97## 🛠️ Technology Stack98 99- **Frontend**: Streamlit100- **Database**: Neon Serverless PostgreSQL101- **Vector DB**: Upstash Vector (with BAAI/bge-m3 embeddings)102- **LLMs**: 103  - Groq API (Llama-3.1-70b-versatile)104  - Cloudflare Workers AI (SQLCoder-7B-2)105- **Security**: Custom query validation & audit logging106 107## 📊 Sample Database108 109The demo uses an e-commerce database with:110- **6 tables**: regions, customers, categories, products, orders, order_items111- **200+ rows** of realistic sample data112- **Full relationships**: foreign keys and indexes113 114## 🔐 Security Features115 116### Input Validation117- SQL injection pattern detection118- Multi-statement prevention119- Destructive operation blocking120 121### Access Control122- Two-tier permission model123- Password-based DBA access124- Session timeout (1 hour)125- Timing-attack resistant authentication126 127### Audit Trail128- All query attempts logged129- Execution results tracked130- Performance metrics recorded131 132## 💡 Use Cases133 134- **Business Intelligence**: Non-technical users can query data135- **Data Exploration**: Quick insights without writing SQL136- **Learning SQL**: See how natural language maps to SQL137- **Data Analysis**: Fast ad-hoc queries and reporting138 139## 🎓 Example Queries140 141### Easy142- "Count total orders"143- "List all product categories"144- "Show active customers"145 146### Medium147- "Total sales by region last month"148- "Average order value per customer"149- "Top 10 best-selling products"150 151### Advanced152- "Monthly revenue trend for last 6 months"153- "Customer lifetime value analysis"154- "Products with low stock (< 50 units)"155 156## ⚙️ Configuration157 158This app requires the following environment variables (set in Space Settings → Repository secrets):159 160- `NEON_READONLY_CONNECTION_STRING` - Database connection (read-only)161- `NEON_DBA_CONNECTION_STRING` - Database connection (full access)162- `GROQ_API_KEY` - Groq API for LLM inference163- `CLOUDFLARE_ACCOUNT_ID` - Cloudflare account164- `CLOUDFLARE_AUTH_TOKEN` - Cloudflare authentication165- `UPSTASH_VECTOR_URL` - Upstash Vector database URL166- `UPSTASH_VECTOR_TOKEN` - Upstash authentication token167- `DBA_PASSWORD` - Password for DBA mode168 169## 📝 License170 171MIT License - Feel free to use and modify!172 173## 🤝 Contributing174 175Built with ❤️ using open-source technologies. Contributions welcome!176 177## 🔗 Links178 179- **Documentation**: [Full README](https://github.com/YOUR_REPO)180- **Deployment Guide**: [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md)181- **Quick Start**: [QUICKSTART.md](./QUICKSTART.md)182 183---184 185**Note**: This is a demo application. For production use, ensure proper security review, API rate limiting, and cost monitoring.186