# olsongl/sql-agent architecture

> Architecture diagram of the GitHub repository olsongl/sql-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/olsongl/sql-agent
- Repository: https://github.com/olsongl/sql-agent

## Overview

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: [`src/sql_analyst/orchestrator.py`](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/orchestrator.py) (Orchestrator), [`src/sql_analyst/llm.py`](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/llm.py) (LLM Client), [`src/sql_analyst/cli.py`](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/cli.py) (CLI), [`src/sql_analyst/db.py`](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/db.py) (SQLite Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_control["Workflow Control"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_agents["Analysis Agents"]
  node_schema_explorer["Schema Explorer<br/>[schema_explorer.py]"]
  node_planner["Planner<br/>[planner.py]"]
  node_writer["SQL Writer<br/>[writer.py]"]
  node_validator["Validator<br/>[validator.py]"]
  node_executor["Executor<br/>[executor.py]"]
  node_summarizer["Summarizer<br/>[summarizer.py]"]
end

subgraph group_runtime["Query Runtime"]
  node_database_helpers["SQLite Helpers<br/>[db.py]"]
  node_safety["SQL Safety<br/>[safety.py]"]
  node_chinook[("SQLite Database<br/>[chinook.db]")]
end

subgraph group_foundation["Runtime Foundations"]
  node_config["Configuration<br/>[config.py]"]
  node_llm_client["LLM Client<br/>[llm.py]"]
  node_trace_logger["Trace Logger<br/>[trace.py]"]
end

node_user(("Analyst"))
node_anthropic{{"Anthropic API"}}

node_user -->|"asks question"| node_cli
node_cli -->|"starts analysis"| node_orchestrator
node_cli -->|"loads settings"| node_config
node_cli -->|"creates client"| node_llm_client
node_cli -->|"shows answer"| node_user
node_orchestrator -->|"introspects schema"| node_database_helpers
node_database_helpers -->|"reads schema and rows"| node_chinook
node_orchestrator -->|"selects tables"| node_schema_explorer
node_orchestrator -->|"requests plan"| node_planner
node_orchestrator -->|"requests SQL"| node_writer
node_orchestrator -->|"checks SQL"| node_validator
node_validator -->|"returns errors"| node_writer
node_orchestrator -->|"runs validated SQL"| node_executor
node_executor -->|"executes query"| node_database_helpers
node_database_helpers -->|"checks and bounds SQL"| node_safety
node_validator -->|"checks policy"| node_safety
node_orchestrator -->|"requests explanation"| node_summarizer
node_orchestrator -->|"records run"| node_trace_logger
node_schema_explorer -->|"requests completion"| node_llm_client
node_planner -->|"requests completion"| node_llm_client
node_writer -->|"requests completion"| node_llm_client
node_summarizer -->|"requests completion"| node_llm_client
node_llm_client -->|"streams completions"| node_anthropic

click node_cli "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/cli.py"
click node_orchestrator "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/orchestrator.py"
click node_schema_explorer "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/schema_explorer.py"
click node_planner "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/planner.py"
click node_writer "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/writer.py"
click node_validator "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/validator.py"
click node_executor "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/executor.py"
click node_summarizer "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/summarizer.py"
click node_database_helpers "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/db.py"
click node_safety "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/safety.py"
click node_chinook "https://github.com/olsongl/sql-agent/blob/master/data/chinook.db"
click node_config "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/config.py"
click node_llm_client "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/llm.py"
click node_trace_logger "https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/trace.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_orchestrator toneAmber
class node_schema_explorer,node_planner,node_writer,node_validator,node_executor,node_summarizer,node_anthropic toneMint
class node_database_helpers,node_safety,node_chinook toneRose
class node_config,node_llm_client,node_trace_logger,node_user toneIndigo
```

## Components

### User Interface

- [CLI](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/cli.py): `src/sql_analyst/cli.py`

### Workflow Control

- [Orchestrator](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/orchestrator.py): `src/sql_analyst/orchestrator.py`

### Analysis Agents

- [Schema Explorer](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/schema_explorer.py): `src/sql_analyst/agents/schema_explorer.py`
- [Planner](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/planner.py): `src/sql_analyst/agents/planner.py`
- [SQL Writer](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/writer.py): `src/sql_analyst/agents/writer.py`
- [Validator](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/validator.py): `src/sql_analyst/agents/validator.py`
- [Executor](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/executor.py): `src/sql_analyst/agents/executor.py`
- [Summarizer](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/agents/summarizer.py): `src/sql_analyst/agents/summarizer.py`

### Query Runtime

- [SQLite Helpers](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/db.py): `src/sql_analyst/db.py`
- [SQL Safety](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/safety.py): `src/sql_analyst/safety.py`
- [SQLite Database](https://github.com/olsongl/sql-agent/blob/master/data/chinook.db): `data/chinook.db`

### Runtime Foundations

- [Configuration](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/config.py): `src/sql_analyst/config.py`
- [LLM Client](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/llm.py): `src/sql_analyst/llm.py`
- [Trace Logger](https://github.com/olsongl/sql-agent/blob/master/src/sql_analyst/trace.py): `src/sql_analyst/trace.py`

### Other components

- **Analyst**
- **Anthropic API**

## Connections

- Analyst → CLI: asks question (evidence: `src/sql_analyst/cli.py`)
- CLI → Orchestrator: starts analysis (evidence: `src/sql_analyst/cli.py`)
- CLI → Configuration: loads settings (evidence: `src/sql_analyst/cli.py`)
- CLI → LLM Client: creates client (evidence: `src/sql_analyst/cli.py`)
- CLI → Analyst: shows answer (evidence: `src/sql_analyst/cli.py`)
- Orchestrator → SQLite Helpers: introspects schema (evidence: `src/sql_analyst/orchestrator.py`)
- SQLite Helpers → SQLite Database: reads schema and rows (evidence: `src/sql_analyst/db.py`)
- Orchestrator → Schema Explorer: selects tables (evidence: `src/sql_analyst/orchestrator.py`)
- Orchestrator → Planner: requests plan (evidence: `src/sql_analyst/orchestrator.py`)
- Orchestrator → SQL Writer: requests SQL (evidence: `src/sql_analyst/orchestrator.py`)
- Orchestrator → Validator: checks SQL (evidence: `src/sql_analyst/orchestrator.py`)
- Validator → SQL Writer: returns errors
- Orchestrator → Executor: runs validated SQL (evidence: `src/sql_analyst/orchestrator.py`)
- Executor → SQLite Helpers: executes query (evidence: `src/sql_analyst/agents/executor.py`)
- SQLite Helpers → SQL Safety: checks and bounds SQL (evidence: `src/sql_analyst/db.py`)
- Validator → SQL Safety: checks policy (evidence: `src/sql_analyst/agents/validator.py`)
- Orchestrator → Summarizer: requests explanation (evidence: `src/sql_analyst/orchestrator.py`)
- Orchestrator → Trace Logger: records run (evidence: `src/sql_analyst/orchestrator.py`)
- Schema Explorer → LLM Client: requests completion (evidence: `src/sql_analyst/agents/schema_explorer.py`)
- Planner → LLM Client: requests completion (evidence: `src/sql_analyst/agents/planner.py`)
- SQL Writer → LLM Client: requests completion (evidence: `src/sql_analyst/agents/writer.py`)
- Summarizer → LLM Client: requests completion (evidence: `src/sql_analyst/agents/summarizer.py`)
- LLM Client → Anthropic API: streams completions (evidence: `src/sql_analyst/llm.py`)
