# arnabdhaliofficial/ai_sql_analyst architecture

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

- Interactive diagram: https://gitdiagram.com/arnabdhaliofficial/ai_sql_analyst
- Repository: https://github.com/arnabdhaliofficial/ai_sql_analyst

## Overview

SQL Agent is a Streamlit natural-language PostgreSQL assistant. A user submits a question in the app, which invokes the LangGraph analyst: it curates the question, gathers database schema context, generates SQL, judges its safety, executes approved queries, and turns results into a human-readable answer for display. The app also exposes a database schema browser. Model selection and PostgreSQL access are separate internal layers. The README documents the supported model providers; unsampled implementation details are not inferred beyond those documented capabilities.

Main entry points: [`app.py`](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/app.py) (Streamlit app), [`utils/llm_pick.py`](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/utils/llm_pick.py) (Model selector), [`agents/sql_analyst.py`](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py) (Agent graph), [`utils/database.py`](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/utils/database.py) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Streamlit app<br/>[app.py]"]
  node_schema_browser["Schema browser<br/>[app.py]"]
end

subgraph group_workflow["SQL agent workflow"]
  node_analyst["Agent graph<br/>[sql_analyst.py]"]
  node_curate["Question curation<br/>[sql_analyst.py]"]
  node_context["Schema context<br/>[sql_analyst.py]"]
  node_generate["SQL generation<br/>[sql_analyst.py]"]
  node_judge["SQL safety judge<br/>[sql_analyst.py]"]
  node_cancel["Unsafe query response<br/>[sql_analyst.py]"]
  node_execute["Query execution<br/>[sql_analyst.py]"]
  node_answer["Answer synthesis<br/>[sql_analyst.py]"]
end

subgraph group_services["Internal services"]
  node_state["Agent state schemas<br/>[schema.py]"]
  node_llm_picker["Model selector<br/>[llm_pick.py]"]
  node_db_util["Database access<br/>[database.py]"]
end

subgraph group_external["External systems"]
  node_postgres[("PostgreSQL")]
  node_llm_services{{"LLM providers"}}
end

node_user(("User"))

node_user -->|"asks question"| node_app
node_app -->|"invokes"| node_analyst
node_analyst -->|"returns result"| node_app
node_app -->|"renders"| node_schema_browser
node_app -->|"inspects schema"| node_postgres
node_analyst -->|"starts"| node_curate
node_curate -->|"continues"| node_context
node_context -->|"continues"| node_generate
node_generate -->|"continues"| node_judge
node_judge -->|"routes if safe"| node_execute
node_judge -->|"routes if unsafe"| node_cancel
node_execute -->|"continues"| node_answer
node_curate -->|"selects model"| node_llm_picker
node_generate -->|"selects model"| node_llm_picker
node_judge -->|"selects model"| node_llm_picker
node_answer -->|"selects model"| node_llm_picker
node_context -->|"reads schema"| node_db_util
node_execute -->|"executes query"| node_db_util
node_db_util -->|"queries"| node_postgres
node_llm_picker -->|"calls selected provider"| node_llm_services
node_analyst -->|"uses state types"| node_state

click node_app "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/app.py"
click node_schema_browser "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/app.py"
click node_analyst "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_curate "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_context "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_generate "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_judge "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_cancel "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_execute "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_answer "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py"
click node_state "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/Models/schema.py"
click node_llm_picker "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/utils/llm_pick.py"
click node_db_util "https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/utils/database.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_app,node_schema_browser,node_user toneBlue
class node_analyst,node_curate,node_context,node_generate,node_judge,node_cancel,node_execute,node_answer toneAmber
class node_state,node_llm_picker,node_db_util toneMint
class node_postgres,node_llm_services toneRose
```

## Components

### User interface

- [Streamlit app](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/app.py): `app.py`
- [Schema browser](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/app.py): `app.py`

### SQL agent workflow

- [Agent graph](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [Question curation](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [Schema context](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [SQL generation](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [SQL safety judge](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [Unsafe query response](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [Query execution](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`
- [Answer synthesis](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/agents/sql_analyst.py): `agents/sql_analyst.py`

### Internal services

- [Agent state schemas](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/Models/schema.py): `Models/schema.py`
- [Model selector](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/utils/llm_pick.py): `utils/llm_pick.py`
- [Database access](https://github.com/arnabdhaliofficial/ai_sql_analyst/blob/main/utils/database.py): `utils/database.py`

### External systems

- **PostgreSQL**
- **LLM providers**

### Other components

- **User**

## Connections

- User → Streamlit app: asks question (evidence: `app.py`)
- Streamlit app → Agent graph: invokes (evidence: `app.py`)
- Agent graph → Streamlit app: returns result (evidence: `app.py`)
- Streamlit app → Schema browser: renders (evidence: `app.py`)
- Streamlit app → PostgreSQL: inspects schema (evidence: `app.py`)
- Agent graph → Question curation: starts (evidence: `agents/sql_analyst.py`)
- Question curation → Schema context: continues (evidence: `agents/sql_analyst.py`)
- Schema context → SQL generation: continues (evidence: `agents/sql_analyst.py`)
- SQL generation → SQL safety judge: continues (evidence: `agents/sql_analyst.py`)
- SQL safety judge → Query execution: routes if safe (evidence: `agents/sql_analyst.py`)
- SQL safety judge → Unsafe query response: routes if unsafe (evidence: `agents/sql_analyst.py`)
- Query execution → Answer synthesis: continues (evidence: `agents/sql_analyst.py`)
- Question curation → Model selector: selects model (evidence: `agents/sql_analyst.py`)
- SQL generation → Model selector: selects model (evidence: `agents/sql_analyst.py`)
- SQL safety judge → Model selector: selects model (evidence: `agents/sql_analyst.py`)
- Answer synthesis → Model selector: selects model (evidence: `agents/sql_analyst.py`)
- Schema context → Database access: reads schema (evidence: `agents/sql_analyst.py`)
- Query execution → Database access: executes query (evidence: `agents/sql_analyst.py`)
- Database access → PostgreSQL: queries (evidence: `utils/database.py`)
- Model selector → LLM providers: calls selected provider (evidence: `utils/llm_pick.py`)
- Agent graph → Agent state schemas: uses state types (evidence: `agents/sql_analyst.py`)
