How olsongl/sql-agent works
sql-analyst-agent is a command-line, multi-agent natural-language-to-SQL analyst. A user question enters through the CLI; the orchestrator introspects the database, gathers relevant schema, plans the query, and runs a writer–validator retry loop before executing safe SQL and summarizing the result. It also records JSONL traces. The graph preserves the documented safety, read-only execution, row-cap, timeout, and retry capabilities. Relationships reflect the README and sampled source; unsampled implementation details are not inferred.
Main entry points: orchestrator.py Orchestrator · llm.py LLM Client · cli.py CLI · db.py SQLite Helpers
Components 16
User Interface
- CLI
src/sql_analyst/cli.py
Workflow Control
- Orchestrator
src/sql_analyst/orchestrator.py
Analysis Agents
- Schema Explorer
src/sql_analyst/agents/schema_explorer.py - Planner
src/sql_analyst/agents/planner.py - SQL Writer
src/sql_analyst/agents/writer.py - Validator
src/sql_analyst/agents/validator.py - Executor
src/sql_analyst/agents/executor.py - Summarizer
src/sql_analyst/agents/summarizer.py
Query Runtime
- SQLite Helpers
src/sql_analyst/db.py - SQL Safety
src/sql_analyst/safety.py - SQLite Database
data/chinook.db
Runtime Foundations
- Configuration
src/sql_analyst/config.py - LLM Client
src/sql_analyst/llm.py - Trace Logger
src/sql_analyst/trace.py
Other components
- Analyst
- Anthropic API
Connections 23
- Analyst → CLI: asks question
src/sql_analyst/cli.py - CLI → Orchestrator: starts analysis
src/sql_analyst/cli.py - CLI → Configuration: loads settings
src/sql_analyst/cli.py - CLI → LLM Client: creates client
src/sql_analyst/cli.py - CLI → Analyst: shows answer
src/sql_analyst/cli.py - Orchestrator → SQLite Helpers: introspects schema
src/sql_analyst/orchestrator.py - SQLite Helpers → SQLite Database: reads schema and rows
src/sql_analyst/db.py - Orchestrator → Schema Explorer: selects tables
src/sql_analyst/orchestrator.py - Orchestrator → Planner: requests plan
src/sql_analyst/orchestrator.py - Orchestrator → SQL Writer: requests SQL
src/sql_analyst/orchestrator.py - Orchestrator → Validator: checks SQL
src/sql_analyst/orchestrator.py - Validator → SQL Writer: returns errors
- Orchestrator → Executor: runs validated SQL
src/sql_analyst/orchestrator.py - Executor → SQLite Helpers: executes query
src/sql_analyst/agents/executor.py - SQLite Helpers → SQL Safety: checks and bounds SQL
src/sql_analyst/db.py - Validator → SQL Safety: checks policy
src/sql_analyst/agents/validator.py - Orchestrator → Summarizer: requests explanation
src/sql_analyst/orchestrator.py - Orchestrator → Trace Logger: records run
src/sql_analyst/orchestrator.py - Schema Explorer → LLM Client: requests completion
src/sql_analyst/agents/schema_explorer.py - Planner → LLM Client: requests completion
src/sql_analyst/agents/planner.py - SQL Writer → LLM Client: requests completion
src/sql_analyst/agents/writer.py - Summarizer → LLM Client: requests completion
src/sql_analyst/agents/summarizer.py - LLM Client → Anthropic API: streams completions
src/sql_analyst/llm.py