Sql Ai Agent

SQL AI Agent — Natural Language to SQL, with a Safety-First Pipeline

A small, focused text-to-SQL agent: ask a question in plain English, get back the SQL query that answers it and the results, run against a real SQLite database.

The interesting part of this project isn't the LLM call — that's a handful of lines. It's everything *around* it: a validator that guarantees an LLM-generated query can never modify or damage the database, schema introspection that keeps the model grounded in the real table structure, row limits and logging for observability, and a test suite for the safety-critical parts.

Question: "What are the top 5 products by revenue?"
   │
   ▼
┌─────────────────────┐
│  Schema Introspection│   src/db.py — reads live schema from SQLite
│  (tables, columns,   │   (PRAGMA table_info / foreign_key_list)
│   foreign keys)      │
└──────────┬───────────┘
           ▼
┌─────────────────────┐
│   SQL Generation      │  src/llm.py — Claude API (or offline mock mode
│   (question + schema  │  with zero setup) turns question + schema into
│    → SQL text)        │  a single SQL statement
└──────────┬───────────┘
           ▼
┌─────────────────────┐
│   Safety Validator     │  src/validator.py — allow-lists SELECT/WITH only,
│   (reject anything     │  strips comments before inspection, blocks
│    unsafe)              │  multi-statement injection, DROP/DELETE/UPDATE/
└──────────┬───────────┘  INSERT/ALTER/PRAGMA/ATTACH/etc.
           ▼
┌─────────────────────┐
│  Safe Execution        │  src/db.py — read-only connection (PRAGMA
│  (row-limited, logged) │  query_only), hard row-count cap, per-run logging
└──────────┬───────────┘
           ▼
      Results + the SQL that produced them

Why this design

An LLM will happily write `DROP TABLE customers` if a question is phrased (or engineered) the wrong way. Any tool that lets a model generate SQL against a real database needs a validation layer that does **not** trust the model's output — that's the