NL-to-SQL Analytics Agent
An agent that takes a plain-English question, generates SQL, runs it, and produces an answer as well as visualizations.
What I'm digging into
Turning a business question into a correct SQL query is a manual, repetitive step that eats analyst time, which can be an obstacle for anyone who doesn't know SQL at all. This project builds an agent that closes that gap. Given a plain-English question, it plans and writes the SQL query, runs it safely, and decides on its own whether a chart would help explain the answer.
Where the numbers come from
The Sample Superstore retail dataset (sales, profit, region, category, and time-series data), loaded into a local SQLite database.
Scope is intentionally narrow for now, one dataset and one schema, so the focus stays on getting the agent loop and safety constraints right before generalizing to arbitrary schemas.
How it works
- 1
A user question is passed to Claude via the Anthropic API, which plans and runs a multi-step tool-use loop rather than a single prompt-to-SQL call
- 2
Generates a SQL query from the question using a schema-aware prompt
- 3
Calls a run_sql tool to safely execute the query against a SQLite database (read-only, validated, and row-limited)
- 4
Decides whether a visualization would clarify the answer, and if so calls a generate_chart tool (matplotlib)
- 5
Returns a plain-English summary of the findings alongside the query, results table, and chart
- 6
Surfaces all of it, question, SQL, table, chart, explanation, in a Streamlit interface
Dashboard preview
Streamlit interface with question in, SQL query, results table, chart, and explanation out. Coming soon.
What the data says
Coming soon. This section will walk through example questions the agent handles well, where it still needs guardrails, and how its generated SQL compares to a hand-written query.
The bigger picture
This isn't a single prompt-to-SQL call. It's a true multi-tool agent that plans, executes, visualizes, and explains, closely mirroring real analyst workflows (like the manual Data Lake / PL-SQL querying I do professionally), but automated end to end.
Where things stand
Core agent loop and SQL execution tool are complete; building out the charting tool and Streamlit interface next. Live demo and repo link coming soon.