Governed AI analytics
NL2SQLAgent
A self-service analytics interface that turns natural-language questions into inspectable SQL without allowing generated queries to modify the warehouse.
ScopePortfolio build using a seeded synthetic warehouse and a local SQLite database.
- synthetic warehouse
- 1.03M rows
- query latency
- <250 ms
- LLM inference latency
- 7–15 s
- FastAPI
- LangChain
- SQLite
- React
- Server-Sent Events
- ECharts
01 / Context
The problem
Business users need answers without writing SQL, while engineering still needs guardrails against destructive queries, opaque model behavior, and answers without visible evidence.
02 / Architecture
How the system fits together
- 01Questionnatural language
- 02Agentschema inspection
- 03SQL generatorquery + explanation
- 04Read-only guardreject writes before execution
- 05SQLite warehouse1.03M synthetic rows
- 06Answer + chartSSE streaming
Supporting systems
- Session memorylast 10 conversation rounds
- EChartsbar, line, pie, table
03 / Engineering
What I built
- Built a FastAPI and LangChain query path that inspects the schema, generates SQL, validates it, executes it, and explains the result.
- Added defense-in-depth read-only controls that reject write and schema-changing statements before execution.
- Streamed thinking, text, SQL, data, chart, and completion events to a React interface over Server-Sent Events.
- Built session persistence, context memory, chart heuristics, table and chart views, and deterministic end-to-end checks.
- Tested the application against a 1,028,160-row synthetic sales warehouse with indexed query paths.
04 / Evidence
Measured outcomes
warehouse rows
Deterministic synthetic sales data seeded locally.
NL2SQLAgent README — performance setup ↗query latency
Measured GROUP BY and date-range queries; documented path stays under 250 ms.
NL2SQLAgent README — performance ↗LLM latency
The documented end-to-end bottleneck with the configured deepseek-v4-flash model.
NL2SQLAgent README — performance ↗05 / Demo
Product evidence
06 / Boundaries
Trade-offs and limitations
- The warehouse is synthetic and the local SQLite setup is not a production data platform.
- End-to-end latency depends on the configured LLM provider; authentication and multi-tenant authorization are outside this portfolio build.
07 / Sources