✅ Verified end-to-end on Windows with local Ollama (llama3.1, num_ctx=8192) — every command below is from a real run.

sql-analyst-agent answers business questions in plain English by writing DuckDB SQL — and when its SQL fails, it reads the database error, fixes the query, and tries again. Up to three attempts, every attempt visible. That self-correction loop is the difference between a demo and something a non-technical operator can actually use.

Ships with a seeded 200-customer retail warehouse so git clone → question → answer takes under a minute.

How the loop works

flowchart LR
    Q[question] --> W[LLM writes SQL<br/>schema-aware, SELECT-only]
    W --> X{execute on DuckDB}
    X -->|rows| R[table + auto chart + CSV]
    X -->|error| F[error fed back to LLM]
    F --> W

    style W stroke:#79c0ff,stroke-width:2px
    style F stroke:#ff5f56,stroke-width:2px
    style R stroke:#7ee787,stroke-width:2px

Loading

Safety rails: a regex firewall blocks anything but SELECT (INSERT/UPDATE/ DROP/... are rejected before execution), and results are capped so a bad query can't flood the UI.

Quickstart

pip install -r requirements.txt
ollama pull llama3.1            # or set GROQ_API_KEY

# UI
streamlit run app.py

# CLI
python cli.py "top 5 products by revenue in the North region" --chart

SELECT p.name, SUM(oi.quantity * oi.unit_price) AS revenue
FROM order_items oi
JOIN orders o ON o.order_id = oi.order_id
JOIN products p ON p.product_id = oi.product_id
JOIN customers c ON c.customer_id = o.customer_id
WHERE c.region = 'North' AND o.status = 'completed'
GROUP BY p.name ORDER BY revenue DESC LIMIT 5

Questions to try: "monthly revenue trend for 2025", "which region returns the most orders?", "average order value by signup year".

Real output

python cli.py "top 5 products by revenue in the North region" --chart — SQL written by the agent on the first attempt, chart auto-generated.

Point it at your own data

warehouse.build() is the only demo-specific code. Replace it with duckdb.connect("your.db") — or DuckDB's Postgres/Parquet/CSV attach — and schema_text() will describe whatever it finds.

Configuration

Variable	Default	Purpose
OLLAMA_MODEL	llama3.1	Local model (default provider)
GROQ_API_KEY	—	Switch to Groq free tier

---

Built by Ahmad Bukhari — AI & Automation Architect · agentic systems that run real businesses, not just demos