Skip to content

README.md

Latest commit

 

History

History
148 lines (120 loc) · 4.11 KB

README.md

File metadata and controls

148 lines (120 loc) · 4.11 KB

SQL Insight Agent

Ask your database anything in plain English — powered by Claude AI and LangChain.

What It Does

SQL Insight Agent translates natural language questions into SQL queries, executes them against a real database, and returns plain English answers. No SQL knowledge required.

Example questions:

  • "Who are the top 5 customers by total spending?"
  • "Which genre has the most tracks?"
  • "Which country has the most customers?"
  • "Who is the employee that supports the most valuable customers?"

Architecture

User Question
     ↓
Streamlit UI
     ↓
FastAPI Backend (REST API)
     ↓
LangChain SQL Agent (powered by Claude)
     ↓
SQLite Database (Chinook)
     ↓
Plain English Answer

Key Features

  • Natural language to SQL — Claude writes the SQL query automatically
  • Self-correcting — if a query fails, the agent diagnoses the error and retries
  • Schema-aware — agent inspects the database structure before writing queries
  • Honest about limits — if data doesn't exist, it says so instead of hallucinating
  • Production-ready — containerized with Docker, deployed on Render

Tech Stack

Tool Purpose
Python Core language
LangChain SQL agent orchestration
Claude (Anthropic) LLM powering the agent
FastAPI REST API wrapper
SQLite + Chinook DB Sample business database
Pydantic Request/response validation
Docker Containerization
Render Cloud deployment
Streamlit Interactive UI

Live Demo

Note: Free tier on Render spins down after inactivity. First request may take 30-60 seconds to wake up.

Run Locally

1. Clone the repo

git clone https://github.com/nikhilll30/sql-insight-agent.git
cd sql-insight-agent

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # Mac/Linux
venv\Scripts\activate     # Windows

3. Install dependencies

pip install -r requirements.txt

4. Download the database

curl -L -o chinook.db https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite

5. Set up environment variables

echo "ANTHROPIC_API_KEY=your-key-here" > .env

6. Run the API

uvicorn main:app --reload

7. Run the UI (separate terminal)

streamlit run app.py

Run with Docker

docker build -t sql-insight-agent .
docker run -p 8000:8000 --env-file .env sql-insight-agent

API Usage

curl -X POST https://sql-insight-agent.onrender.com/query \
  -H "Content-Type: application/json" \
  -d '{"question": "Who are the top 5 customers by spending?"}'

Response:

{
  "question": "Who are the top 5 customers by spending?",
  "answer": "The top 5 customers by total spending are:\n1. Helena Holy - $49.62\n...",
  "time_taken_seconds": 12.4
}

Design Decisions

  • Agent loads at startup — not per request, avoiding cold-start latency
  • handle_parsing_errors=True — enables automatic retry on SQL errors
  • verbose=True — full reasoning chain logged for transparency
  • Chinook database — mirrors real business data making demo questions meaningful

Project Structure

sql-insight-agent/
├── main.py           # FastAPI app and agent initialization
├── app.py            # Streamlit UI
├── agent.py          # Standalone agent testing
├── error_recovery.py # Error handling tests
├── test_db.py        # Database connection test
├── Dockerfile        # Container definition
├── requirements.txt  # Dependencies
└── .env.example      # Environment variable template

What I Learned

  • How LangChain SQL agents use a Think-Act-Observe loop
  • How to wrap an AI agent in a production REST API
  • How to containerize and deploy a Python AI application
  • Why error recovery matters more than happy-path performance
  • How to keep secrets out of source code and Docker images