# samithila/nl-db-agent architecture

> Architecture diagram of the GitHub repository samithila/nl-db-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/samithila/nl-db-agent
- Repository: https://github.com/samithila/nl-db-agent

## Overview

nl-db-agent answers business questions by routing them to SQL, industry-document retrieval, or both, then returning a grounded natural-language response with citations and route details. The documented flow starts with clarification and routing; SQL work uses schema inspection, generation, validation, guardrails, and execution, while RAG retrieves document context. The API exposes the agent and feedback capabilities; evaluation and tracing support quality analysis. Several implementation details are unsampled, so the graph omits unverified connections rather than inferring a pipeline from module names.

Main entry points: [`agent/graph.py`](https://github.com/samithila/nl-db-agent/blob/main/agent/graph.py) (Agent Graph), [`api/main.py`](https://github.com/samithila/nl-db-agent/blob/main/api/main.py) (REST API), [`db_connector.py`](https://github.com/samithila/nl-db-agent/blob/main/db_connector.py) (DB Connector), [`tools/schema_inspector.py`](https://github.com/samithila/nl-db-agent/blob/main/tools/schema_inspector.py) (Schema Inspector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interface"]
  node_ui["Query UI<br/>[app.py]"]
  node_api["REST API<br/>[main.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_state["Run State<br/>[state.py]"]
  node_clarify["Clarifier<br/>[clarifier.py]"]
  node_router["Route Classifier<br/>[router.py]"]
  node_graph["Agent Graph<br/>[graph.py]"]
  node_formatter["Answer Formatter<br/>[formatter.py]"]
end

subgraph group_data["Data Access"]
  node_schema["Schema Inspector"]
  node_generator["SQL Generator<br/>[sql_generator.py]"]
  node_validator["SQL Validator<br/>[validator.py]"]
  node_executor["Query Executor<br/>[executor.py]"]
  node_connector["DB Connector<br/>[db_connector.py]"]
  node_database[("User Database")]
  node_rag["Document Retriever<br/>[retriever.py]"]
  node_ingestion["Document Ingestion<br/>[ingestion.py]"]
  node_vectorstore[("Pinecone Index")]
end

subgraph group_safeguards["Safety Controls"]
  node_permissions["Access Permissions<br/>[permissions.py]"]
  node_limits["Rate and Query Limits<br/>[limits.py]"]
  node_safety["Injection Safety<br/>[safety.py]"]
end

subgraph group_insight["Quality and Observability"]
  node_tracer["Run Tracer<br/>[tracer.py]"]
  node_metrics["Benchmark Metrics<br/>[metrics.py]"]
  node_judge["LLM Judge<br/>[llm_judge.py]"]
end

node_user(("Analyst"))
node_llm{{"OpenAI Models"}}

node_user -->|"asks question"| node_ui
node_ui -->|"submits query"| node_api
node_api -->|"runs query"| node_graph
node_graph -->|"updates state"| node_state
node_graph -->|"checks ambiguity"| node_clarify
node_graph -->|"routes query"| node_router
node_graph -->|"retrieves schema"| node_schema
node_graph -->|"generates SQL"| node_generator
node_graph -->|"validates SQL"| node_validator
node_graph -->|"executes query"| node_executor
node_graph -->|"checks access"| node_permissions
node_graph -->|"checks limits"| node_limits
node_graph -->|"checks safety"| node_safety
node_graph -->|"retrieves context"| node_rag
node_graph -->|"formats answer"| node_formatter
node_schema -->|"inspects database"| node_connector
node_generator -->|"uses schema"| node_schema
node_validator -->|"checks database"| node_connector
node_executor -->|"runs read-only SQL"| node_connector
node_connector -->|"connects to"| node_database
node_permissions -->|"reads schema"| node_connector
node_router -->|"checks connected schema"| node_schema
node_rag -->|"searches vectors"| node_vectorstore
node_ingestion -.->|"indexes chunks"| node_vectorstore
node_rag -->|"embeds query"| node_llm
node_router -->|"classifies question"| node_llm
node_formatter -->|"synthesizes answer"| node_llm
node_api -.->|"records runs"| node_tracer
node_metrics -->|"benchmarks runs"| node_graph
node_metrics -->|"scores answers"| node_judge
node_judge -.->|"evaluates answers"| node_llm
node_api -->|"returns answer"| node_user
node_user -.->|"rates answer"| node_api

click node_ui "https://github.com/samithila/nl-db-agent/blob/main/ui/app.py"
click node_api "https://github.com/samithila/nl-db-agent/blob/main/api/main.py"
click node_state "https://github.com/samithila/nl-db-agent/blob/main/agent/state.py"
click node_clarify "https://github.com/samithila/nl-db-agent/blob/main/tools/clarifier.py"
click node_router "https://github.com/samithila/nl-db-agent/blob/main/agent/router.py"
click node_graph "https://github.com/samithila/nl-db-agent/blob/main/agent/graph.py"
click node_formatter "https://github.com/samithila/nl-db-agent/blob/main/tools/formatter.py"
click node_schema "https://github.com/samithila/nl-db-agent/blob/main/tools/schema_inspector.py"
click node_generator "https://github.com/samithila/nl-db-agent/blob/main/tools/sql_generator.py"
click node_validator "https://github.com/samithila/nl-db-agent/blob/main/tools/validator.py"
click node_executor "https://github.com/samithila/nl-db-agent/blob/main/tools/executor.py"
click node_connector "https://github.com/samithila/nl-db-agent/blob/main/db_connector.py"
click node_rag "https://github.com/samithila/nl-db-agent/blob/main/rag/retriever.py"
click node_ingestion "https://github.com/samithila/nl-db-agent/blob/main/rag/ingestion.py"
click node_permissions "https://github.com/samithila/nl-db-agent/blob/main/guardrails/permissions.py"
click node_limits "https://github.com/samithila/nl-db-agent/blob/main/guardrails/limits.py"
click node_safety "https://github.com/samithila/nl-db-agent/blob/main/guardrails/safety.py"
click node_tracer "https://github.com/samithila/nl-db-agent/blob/main/observability/tracer.py"
click node_metrics "https://github.com/samithila/nl-db-agent/blob/main/evaluation/metrics.py"
click node_judge "https://github.com/samithila/nl-db-agent/blob/main/evaluation/llm_judge.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_ui,node_api toneBlue
class node_state,node_clarify,node_router,node_graph,node_formatter toneAmber
class node_schema,node_generator,node_validator,node_executor,node_connector,node_database,node_rag,node_ingestion,node_vectorstore toneMint
class node_permissions,node_limits,node_safety toneRose
class node_tracer,node_metrics,node_judge,node_user,node_llm toneIndigo
```

## Components

### User Interface

- [Query UI](https://github.com/samithila/nl-db-agent/blob/main/ui/app.py): `ui/app.py`
- [REST API](https://github.com/samithila/nl-db-agent/blob/main/api/main.py): `api/main.py`

### Agent Workflow

- [Run State](https://github.com/samithila/nl-db-agent/blob/main/agent/state.py): `agent/state.py`
- [Clarifier](https://github.com/samithila/nl-db-agent/blob/main/tools/clarifier.py): `tools/clarifier.py`
- [Route Classifier](https://github.com/samithila/nl-db-agent/blob/main/agent/router.py): `agent/router.py`
- [Agent Graph](https://github.com/samithila/nl-db-agent/blob/main/agent/graph.py): `agent/graph.py`
- [Answer Formatter](https://github.com/samithila/nl-db-agent/blob/main/tools/formatter.py): `tools/formatter.py`

### Data Access

- [Schema Inspector](https://github.com/samithila/nl-db-agent/blob/main/tools/schema_inspector.py): `tools/schema_inspector.py`
- [SQL Generator](https://github.com/samithila/nl-db-agent/blob/main/tools/sql_generator.py): `tools/sql_generator.py`
- [SQL Validator](https://github.com/samithila/nl-db-agent/blob/main/tools/validator.py): `tools/validator.py`
- [Query Executor](https://github.com/samithila/nl-db-agent/blob/main/tools/executor.py): `tools/executor.py`
- [DB Connector](https://github.com/samithila/nl-db-agent/blob/main/db_connector.py): `db_connector.py`
- **User Database**
- [Document Retriever](https://github.com/samithila/nl-db-agent/blob/main/rag/retriever.py): `rag/retriever.py`
- [Document Ingestion](https://github.com/samithila/nl-db-agent/blob/main/rag/ingestion.py): `rag/ingestion.py`
- **Pinecone Index**

### Safety Controls

- [Access Permissions](https://github.com/samithila/nl-db-agent/blob/main/guardrails/permissions.py): `guardrails/permissions.py`
- [Rate and Query Limits](https://github.com/samithila/nl-db-agent/blob/main/guardrails/limits.py): `guardrails/limits.py`
- [Injection Safety](https://github.com/samithila/nl-db-agent/blob/main/guardrails/safety.py): `guardrails/safety.py`

### Quality and Observability

- [Run Tracer](https://github.com/samithila/nl-db-agent/blob/main/observability/tracer.py): `observability/tracer.py`
- [Benchmark Metrics](https://github.com/samithila/nl-db-agent/blob/main/evaluation/metrics.py): `evaluation/metrics.py`
- [LLM Judge](https://github.com/samithila/nl-db-agent/blob/main/evaluation/llm_judge.py): `evaluation/llm_judge.py`

### Other components

- **Analyst**
- **OpenAI Models**

## Connections

- Analyst → Query UI: asks question (evidence: `README.md`)
- Query UI → REST API: submits query (evidence: `README.md`)
- REST API → Agent Graph: runs query (evidence: `api/main.py`)
- Agent Graph → Run State: updates state (evidence: `agent/graph.py`)
- Agent Graph → Clarifier: checks ambiguity (evidence: `agent/graph.py`)
- Agent Graph → Route Classifier: routes query (evidence: `agent/graph.py`)
- Agent Graph → Schema Inspector: retrieves schema (evidence: `agent/graph.py`)
- Agent Graph → SQL Generator: generates SQL (evidence: `agent/graph.py`)
- Agent Graph → SQL Validator: validates SQL (evidence: `agent/graph.py`)
- Agent Graph → Query Executor: executes query (evidence: `agent/graph.py`)
- Agent Graph → Access Permissions: checks access (evidence: `agent/graph.py`)
- Agent Graph → Rate and Query Limits: checks limits (evidence: `agent/graph.py`)
- Agent Graph → Injection Safety: checks safety (evidence: `agent/graph.py`)
- Agent Graph → Document Retriever: retrieves context (evidence: `agent/graph.py`)
- Agent Graph → Answer Formatter: formats answer (evidence: `agent/graph.py`)
- Schema Inspector → DB Connector: inspects database (evidence: `tools/schema_inspector.py`)
- SQL Generator → Schema Inspector: uses schema (evidence: `tools/sql_generator.py`)
- SQL Validator → DB Connector: checks database (evidence: `tools/validator.py`)
- Query Executor → DB Connector: runs read-only SQL (evidence: `tools/executor.py`)
- DB Connector → User Database: connects to (evidence: `db_connector.py`)
- Access Permissions → DB Connector: reads schema (evidence: `guardrails/permissions.py`)
- Route Classifier → Schema Inspector: checks connected schema (evidence: `agent/router.py`)
- Document Retriever → Pinecone Index: searches vectors (evidence: `rag/retriever.py`)
- Document Ingestion → Pinecone Index: indexes chunks
- Document Retriever → OpenAI Models: embeds query (evidence: `rag/retriever.py`)
- Route Classifier → OpenAI Models: classifies question (evidence: `agent/router.py`)
- Answer Formatter → OpenAI Models: synthesizes answer (evidence: `tools/formatter.py`)
- REST API → Run Tracer: records runs (evidence: `api/main.py`)
- Benchmark Metrics → Agent Graph: benchmarks runs (evidence: `evaluation/metrics.py`)
- Benchmark Metrics → LLM Judge: scores answers (evidence: `evaluation/metrics.py`)
- LLM Judge → OpenAI Models: evaluates answers
- REST API → Analyst: returns answer (evidence: `api/main.py`)
- Analyst → REST API: rates answer (evidence: `README.md`)
