Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Text-to-SQL Agent

A production-grade AI agent that converts natural language questions into SQL queries and returns results — powered by Mistral 7B running fully offline.


Demo

"Show me top 5 customers by revenue"

SELECT c.name, SUM(o.total_amount) as total_revenue
FROM customers c
JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_id
ORDER BY total_revenue DESC
LIMIT 5;

Returns a clean table with results instantly.


What It Does

Most people in a company cannot write SQL. This tool lets anyone — managers, analysts, HR — query a database using plain English, without any SQL knowledge.

  • Type a question in plain English
  • The agent understands your intent
  • Generates accurate SQL using a local LLM
  • Validates it through a 4-level safety pipeline
  • Executes it and returns results in a clean table

Architecture

User Question
     ↓
NLP Processor       → detects intent, tables, aggregations
     ↓
SQL Generator       → Mistral 7B via Ollama (runs locally)
     ↓
Validator           → 4-level safety check (blacklist, syntax, SELECT-only, LLM critique)
     ↓
Executor            → SQLite database
     ↓
Response Formatter  → JSON + table + summary
     ↓
Streamlit UI

Tech Stack

Layer Technology
LLM Mistral 7B via Ollama
Backend FastAPI
Database SQLite + SQLAlchemy
SQL Validation SQLGlot
Frontend Streamlit
Language Python 3.11

Key Features

  • Fully offline — no data sent to external APIs
  • 4-level SQL safety validation pipeline
  • Auto retry loop with LLM self-correction
  • ReAct-style agent orchestration
  • Production-grade logging and error handling
  • Modular, clean codebase following real-world structure

Project Structure

text2sql-agent/
├── app/
│   ├── agent/          # NLP processor, SQL generator, orchestrator
│   ├── tools/          # Validator, executor
│   ├── llm/            # Mistral client
│   ├── db/             # Models, connection, schema loader
│   ├── api/            # FastAPI routes
│   └── formatter/      # Response formatter
├── data/               # Database + seed script
├── ui/                 # Streamlit frontend
├── tests/              # Unit tests
└── eval/               # Benchmark evaluation

Setup & Run

Prerequisites

  • Python 3.11
  • Ollama installed

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/text2sql-agent.git
cd text2sql-agent

2. Create virtual environment

py -3.11 -m venv venv
venv\Scripts\activate.bat   # Windows
source venv/bin/activate    # Mac/Linux

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables

copy .env.example .env

5. Seed the database

python data/seed.py

6. Pull the LLM model

ollama pull mistral

7. Run the project (3 terminals)

Terminal 1:

ollama serve

Terminal 2:

uvicorn app.main:app --reload --port 8000

Terminal 3:

streamlit run ui/streamlit_app.py

Open http://localhost:8501 in your browser.


Sample Questions to Try

Show me top 5 customers by revenue
What is the total revenue from delivered orders
List all products with price less than 1000
Which city has the most customers
How many orders were placed this year
Show me all Electronics products
What is the average order value
List customers from Maharashtra

API Endpoints

Method Endpoint Description
GET /api/v1/health Check API and LLM status
POST /api/v1/query Submit a natural language question
GET /api/v1/schema View the database schema

Why Offline / Local LLM?

Companies in banking, healthcare, and government cannot send data to external APIs due to privacy regulations (GDPR, India's DPDP Act). This project runs entirely on-premise — no data ever leaves the machine.


Future Improvements

  • Fine-tune Mistral on Spider dataset for higher accuracy
  • Add PostgreSQL support
  • Add user authentication
  • Deploy on Railway / Render
  • Support multi-turn conversation memory

Author

Bhanu Teja Challa
LinkedIn | GitHub

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages