Data Analyst Agent Kit

Data Analyst Agent Kit

A natural-language-to-SQL analyst agent that is safe to point at a real warehouse: the LLM only proposes SQL;

a sqlglot AST guard decides what runs. Read-only enforcement, row cap, cost cap, Vega-Lite chart specs, a seeded

DuckDB demo warehouse, and execution-accuracy evals that compare result sets against golden queries.

It vendors the agent_forge core runtime (src/agent_forge, from Agent Forge Core 1.0.0), so the kit is

standalone. Everything runs offline against the deterministic MockLLM: tests need no keys and no network.

Quickstart

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest                                   # 29 tests, offline
python examples/quickstart.py            # ask -> guarded SQL -> rows -> Vega-Lite spec
python examples/run_evals.py             # execution accuracy vs evals/golden.yaml
python -m data_analyst.seed demo.duckdb  # write the demo warehouse to a file (seed 42)

Real model: implement the 1-method LLM protocol or use HTTPChatLLM (see examples/real_llm.py).

Real warehouse: pass any duckdb connection to Warehouse(con, GuardConfig(...)).

The guard (`data_analyst/guard.py`)

Exactly one statement, root must be SELECT/UNION (CTEs fine). Rejected anywhere in the AST: INSERT/UPDATE/DELETE/

MERGE/CREATE/DROP/ALTER/COPY/ATTACH/PRAGMA/SET..., data-modifying CTEs, SELECT INTO, file/network table

functions (read_csv, 'file.parquet'...), tables outside the allowlist. The row cap wraps the query in an outer

LIMIT, so a user LIMIT 999999 cannot raise it. The cost cap uses a deterministic proxy (rows scanned, times

table size for any join without ON/USING). See guide/GUARD.md.

Layout

src/data_analyst (seed, guard, warehouse, agent, charts, evals, mock) - src/agent_forge (vendored runtime) -

tests/ - evals/ - guide/ (ARCHITECTURE, GUARD, EVALS) - examples/.

What it is not

Not a security boundary on its own: also connect with a read-only database role/file. The cost proxy is an

estimate, not the DuckDB planner. The mock LLM only knows the demo questions. The vendored runtime's API/HITL

features are included but not required by the analyst.

License: MIT with a no-resale-as-template clause (see LICENSE).