A full-stack NL2SQL agent that actually checks its SQL

What it does

Business users ask questions in plain Chinese (“total sales in North China”) and the system answers from a MySQL data warehouse. Before any SQL is generated, it retrieves relevant fields, metrics, and field values from a metadata knowledge base, then uses LangGraph to orchestrate multi-step reasoning, SQL generation, validation, correction, and execution. Results stream back to a React frontend over SSE, including the intermediate agent steps.

The interesting bit

The core bet is that retrieval beats prompting: instead of handing the schema to the LLM and hoping, it splits metadata across three stores — Qdrant for semantic recall of fields and metrics, Elasticsearch for full-text search over actual field values, MySQL as the authoritative structured source. That three-way recall of fields, metrics, and value domains is closer to how a real analyst works than typical table-level RAG.

Key highlights

• Full runnable stack: FastAPI backend, React/Vite frontend, Docker Compose for MySQL, Elasticsearch, Qdrant, and a TEI-hosted bge-large-zh-v1.5 embedding service.
• LangGraph workflow covers generation, validation, and self-correction of SQL — not just one-shot generation.
• Clean layering: repositories, client managers, services, and agent nodes are separated, so it reads like production code rather than a notebook.
• Ships with a free companion tutorial (ai-agents-from-zero) and per-chapter Git branches, so you can follow the codebase’s evolution.
• Request-scoped logging via ContextVar/loguru injects a request_id for tracing concurrent queries.

Caveats

• It’s a teaching project first — the warehouse is a simulated e-commerce dataset, not real enterprise data.
• Setup is heavier than a typical demo: you need Docker, an LLM API key, and a locally downloaded embedding model (~GBs) before anything runs.
• Requires Python 3.14+, which is bleeding-edge for most environments.

Verdict

If you want to learn LangGraph with something meatier than toy nodes — or need a reference architecture for enterprise NL2SQL — this is one of the better open textbooks. If you just want a quick chat-with-your-database script, the multi-service setup will feel like overkill.