The Problem
Business users often need answers from relational databases but don’t write SQL.
Dashboards answer predefined questions, while unrestricted LLMs introduce risk when
connected directly to production data.
The challenge is building an AI system that translates natural-language questions into correct SQL, while enforcing safety, performance, and auditability.
The Solution
This SQL Analytics Agent acts as a controlled intermediary between users and a relational database.
It converts natural-language questions into SQL, validates and constrains queries, executes them
under read-only access, and returns structured results.
- Natural language → SQL generation with schema grounding
- Read-only execution + guardrails
- Structured results suitable for analytics workflows
Architecture Overview
User
→
SvelteKit UI
→
Flask API
→
LLM + Schema Context
→
SQL Validation
→
Read-Only DB
→
Results
- User asks an analytics question in natural language.
- Backend injects approved schema context into the prompt.
- LLM generates SQL (not free-form answers).
- SQL is validated, constrained, and executed in read-only mode.
- Structured results return to the UI for display.
Safety & Guardrails
- Read-only role: prevents INSERT/UPDATE/DELETE/DDL
- Schema allowlist: only approved tables/columns exposed
- Row limits: blocks large result sets
- Timeouts: prevents long-running queries
- No direct user SQL execution: queries are generated + validated
These constraints make the agent safer for real organizational data, not just demos.
Explainability
Trust matters. The system is designed to show how answers are produced:
- Generated SQL can be reviewed
- Results map directly to database fields
- Failures return structured errors instead of hallucinations
- Query logic aligns with the relational model
Example Questions
Use these prompts to explore the demo quickly:
Which customers have the highest total purchases?
Show monthly sales trends by category.
Which products have declining revenue over the last year?
What are the top artists by total track sales?
Each question is translated into SQL, executed safely, and returned as structured data.
Technology Stack
Frontend
- SvelteKit
- Scoped component CSS
- Fetch-based API integration
Backend
- Python + Flask API
- Prompt-driven SQL generation
Data
- Relational database (example: Chinook)
- Explicit schema context exposure
What This Demonstrates
- Safe AI design for structured data
- Analytics-focused SQL generation
- Data governance mindset (constraints + auditability)
- Full-stack delivery (UI + API + data)
- Production-oriented thinking beyond “chatbots”
Limitations & Future Work
- Query plan inspection / cost estimation
- Chart-based visualization of results
- Multi-database backends (Postgres, SQL Server)
- Evaluation harness for SQL accuracy
- Role-based access control
Try the Live Demo
Explore natural-language analytics with read-only constraints and structured results.
