# yverma-datamax/sql-rag-agent- architecture

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

- Interactive diagram: https://gitdiagram.com/yverma-datamax/sql-rag-agent-
- Repository: https://github.com/yverma-datamax/sql-rag-agent-

## Overview

This is a notebook-driven, local SQL RAG agent for querying a seeded e-commerce SQLite database in natural language. Its principal workflow retrieves schema context, generates SQL with Ollama, executes it with correction retries, then presents results; the README also documents visualization and RAG-versus-baseline evaluation. The notebook is documented as the entry point, but its source was not sampled, so its internal wiring is shown only at the capability level.

Main entry points: [`src/rag_utils.py`](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py) (SQL RAG agent), [`notebooks/sql_rag_agent.ipynb`](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb) (Agent notebook), [`src/seed_db.py`](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/seed_db.py) (Database seeder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Query workflow"]
  node_notebook["Agent notebook"]
  node_agent["SQL RAG agent<br/>[rag_utils.py]"]
  node_retriever["Schema retriever<br/>[rag_utils.py]"]
  node_generator["SQL generator<br/>[rag_utils.py]"]
  node_executor["Query executor<br/>[rag_utils.py]"]
end

subgraph group_data["Data layer"]
  node_seed["Database seeder<br/>[seed_db.py]"]
  node_sqlite[("E-commerce SQLite")]
end

subgraph group_presentation["Notebook outputs"]
  node_visualization["Charts and results"]
  node_evaluation["RAG evaluation"]
end

subgraph group_integration["Local model"]
  node_ollama["Ollama"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_notebook
node_notebook -->|"calls"| node_agent
node_agent -->|"retrieves schemas"| node_retriever
node_agent -->|"generates SQL"| node_generator
node_agent -->|"executes SQL"| node_executor
node_agent -->|"requests correction"| node_generator
node_retriever -->|"reads schema"| node_sqlite
node_retriever -->|"requests embeddings"| node_ollama
node_generator -->|"requests SQL"| node_ollama
node_executor -->|"runs query"| node_sqlite
node_seed -->|"creates and populates"| node_sqlite
node_notebook -->|"presents results"| node_visualization
node_notebook -->|"compares SQL success"| node_evaluation
node_agent -->|"returns rows and SQL"| node_notebook

click node_notebook "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb"
click node_agent "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py"
click node_retriever "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py"
click node_generator "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py"
click node_executor "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py"
click node_seed "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/seed_db.py"
click node_visualization "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb"
click node_evaluation "https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb"

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_notebook,node_agent,node_retriever,node_generator,node_executor toneBlue
class node_seed,node_sqlite toneAmber
class node_visualization,node_evaluation toneMint
class node_ollama toneRose
class node_user toneIndigo
```

## Components

### Query workflow

- [Agent notebook](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb): `notebooks/sql_rag_agent.ipynb`
- [SQL RAG agent](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py): `src/rag_utils.py`
- [Schema retriever](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py): `src/rag_utils.py`
- [SQL generator](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py): `src/rag_utils.py`
- [Query executor](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/rag_utils.py): `src/rag_utils.py`

### Data layer

- [Database seeder](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/src/seed_db.py): `src/seed_db.py`
- **E-commerce SQLite**

### Notebook outputs

- [Charts and results](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb): `notebooks/sql_rag_agent.ipynb`
- [RAG evaluation](https://github.com/yverma-datamax/sql-rag-agent-/blob/main/notebooks/sql_rag_agent.ipynb): `notebooks/sql_rag_agent.ipynb`

### Local model

- **Ollama**

### Other components

- **Questioner**

## Connections

- Questioner → Agent notebook: asks
- Agent notebook → SQL RAG agent: calls
- SQL RAG agent → Schema retriever: retrieves schemas
- SQL RAG agent → SQL generator: generates SQL
- SQL RAG agent → Query executor: executes SQL
- SQL RAG agent → SQL generator: requests correction
- Schema retriever → E-commerce SQLite: reads schema
- Schema retriever → Ollama: requests embeddings
- SQL generator → Ollama: requests SQL
- Query executor → E-commerce SQLite: runs query
- Database seeder → E-commerce SQLite: creates and populates
- Agent notebook → Charts and results: presents results
- Agent notebook → RAG evaluation: compares SQL success
- SQL RAG agent → Agent notebook: returns rows and SQL