# kamalesh346/data_analyst_agent architecture

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

- Interactive diagram: https://gitdiagram.com/kamalesh346/data_analyst_agent
- Repository: https://github.com/kamalesh346/data_analyst_agent

## Overview

This repository is an AI data-analysis platform that turns an uploaded CSV into verified findings and a shareable interactive report. The documented workflow profiles the dataset, plans and executes sandboxed analyses, reflects on whether more tasks are needed, verifies evidence, and generates insights and reports. FastAPI and two UIs expose the workflow. The graph and selected source excerpts support the main orchestration and upload links; several insight, chat, and frontend details are documented in the README but their implementation was not sampled.

Main entry points: [`graph.py`](https://github.com/kamalesh346/data_analyst_agent/blob/main/graph.py) (State graph), [`agents/insight/insight_node.py`](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/insight_node.py) (Insight generation), [`llm.py`](https://github.com/kamalesh346/data_analyst_agent/blob/main/llm.py) (LLM failover and cache), [`api/main.py`](https://github.com/kamalesh346/data_analyst_agent/blob/main/api/main.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["React dashboard"]
  node_streamlit["Streamlit dashboard<br/>[app.py]"]
  node_api["REST API<br/>[main.py]"]
  node_upload["Upload handling"]
end

subgraph group_orchestration["Pipeline orchestration"]
  node_graph["State graph<br/>[graph.py]"]
  node_state["Shared agent state<br/>[graph_state.py]"]
end

subgraph group_analysis["Data analysis"]
  node_profiler["CSV profiler<br/>[agent.py]"]
  node_profiletool["Sweetviz profiling<br/>[profiling_tool.py]"]
  node_planner["Analysis planner<br/>[agent.py]"]
  node_executor["Sandbox executor<br/>[agent.py]"]
  node_reflector["Plan reflector<br/>[agent.py]"]
  node_python["Python sandbox<br/>[python_executor.py]"]
end

subgraph group_insight["Evidence and reporting"]
  node_validation["Evidence validation<br/>[validation.py]"]
  node_verify["Recompute verification<br/>[verify.py]"]
  node_insight["Insight generation<br/>[insight_node.py]"]
  node_report["Report generation"]
  node_chat["Grounded chatbot<br/>[chat.py]"]
  node_artifact["Sweetviz HTML report"]
end

subgraph group_services["Shared services"]
  node_llm["LLM failover and cache<br/>[llm.py]"]
end

node_user(("Analyst"))
node_csv["CSV dataset"]
node_providers{{"LLM providers"}}
node_trace{{"LangSmith tracing"}}

node_user -->|"uploads CSV"| node_web
node_user -->|"uploads CSV"| node_streamlit
node_web -->|"uses API"| node_api
node_streamlit -->|"selects dataset"| node_upload
node_upload -->|"runs pipeline"| node_graph
node_api -->|"runs pipeline"| node_graph
node_api -->|"answers questions"| node_chat
node_graph -->|"dispatches"| node_profiler
node_graph -->|"dispatches"| node_planner
node_graph -->|"dispatches"| node_executor
node_graph -->|"routes conditionally"| node_reflector
node_graph -->|"dispatches"| node_insight
node_profiler -->|"generates profile"| node_profiletool
node_executor -->|"executes code"| node_python
node_profiler -->|"invokes model"| node_llm
node_planner -->|"plans tasks"| node_llm
node_executor -.->|"generates analysis"| node_llm
node_reflector -.->|"reviews plan"| node_llm
node_insight -->|"validates results"| node_validation
node_insight -->|"recomputes evidence"| node_verify
node_insight -->|"compiles reports"| node_report
node_report -->|"writes HTML"| node_artifact
node_chat -->|"uses verified output"| node_insight
node_llm -->|"fails over"| node_providers
node_graph -->|"shares state"| node_state
node_graph -.->|"traces runs"| node_trace

click node_web "https://github.com/kamalesh346/data_analyst_agent/tree/main/frontend/src"
click node_streamlit "https://github.com/kamalesh346/data_analyst_agent/blob/main/app.py"
click node_api "https://github.com/kamalesh346/data_analyst_agent/blob/main/api/main.py"
click node_upload "https://github.com/kamalesh346/data_analyst_agent/blob/main/ui/services/pipeline_service.py"
click node_graph "https://github.com/kamalesh346/data_analyst_agent/blob/main/graph.py"
click node_state "https://github.com/kamalesh346/data_analyst_agent/blob/main/state/graph_state.py"
click node_profiler "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/profiler/agent.py"
click node_profiletool "https://github.com/kamalesh346/data_analyst_agent/blob/main/tools/profiling_tool.py"
click node_planner "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/analysis/agent.py"
click node_executor "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/analysis/agent.py"
click node_reflector "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/analysis/agent.py"
click node_python "https://github.com/kamalesh346/data_analyst_agent/blob/main/tools/python_executor.py"
click node_validation "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/validation.py"
click node_verify "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/verify.py"
click node_insight "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/insight_node.py"
click node_report "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/report_generator.py"
click node_chat "https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/chat.py"
click node_llm "https://github.com/kamalesh346/data_analyst_agent/blob/main/llm.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_web,node_streamlit,node_api,node_upload toneBlue
class node_graph,node_state toneAmber
class node_profiler,node_profiletool,node_planner,node_executor,node_reflector,node_python toneMint
class node_validation,node_verify,node_insight,node_report,node_chat,node_artifact toneRose
class node_llm,node_user,node_csv,node_providers,node_trace toneIndigo
```

## Components

### User interfaces

- [React dashboard](https://github.com/kamalesh346/data_analyst_agent/tree/main/frontend/src): `frontend/src`
- [Streamlit dashboard](https://github.com/kamalesh346/data_analyst_agent/blob/main/app.py): `app.py`
- [REST API](https://github.com/kamalesh346/data_analyst_agent/blob/main/api/main.py): `api/main.py`
- [Upload handling](https://github.com/kamalesh346/data_analyst_agent/blob/main/ui/services/pipeline_service.py): `ui/services/pipeline_service.py`

### Pipeline orchestration

- [State graph](https://github.com/kamalesh346/data_analyst_agent/blob/main/graph.py): `graph.py`
- [Shared agent state](https://github.com/kamalesh346/data_analyst_agent/blob/main/state/graph_state.py): `state/graph_state.py`

### Data analysis

- [CSV profiler](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/profiler/agent.py): `agents/profiler/agent.py`
- [Sweetviz profiling](https://github.com/kamalesh346/data_analyst_agent/blob/main/tools/profiling_tool.py): `tools/profiling_tool.py`
- [Analysis planner](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/analysis/agent.py): `agents/analysis/agent.py`
- [Sandbox executor](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/analysis/agent.py): `agents/analysis/agent.py`
- [Plan reflector](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/analysis/agent.py): `agents/analysis/agent.py`
- [Python sandbox](https://github.com/kamalesh346/data_analyst_agent/blob/main/tools/python_executor.py): `tools/python_executor.py`

### Evidence and reporting

- [Evidence validation](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/validation.py): `agents/insight/validation.py`
- [Recompute verification](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/verify.py): `agents/insight/verify.py`
- [Insight generation](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/insight_node.py): `agents/insight/insight_node.py`
- [Report generation](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/report_generator.py): `agents/insight/report_generator.py`
- [Grounded chatbot](https://github.com/kamalesh346/data_analyst_agent/blob/main/agents/insight/chat.py): `agents/insight/chat.py`
- **Sweetviz HTML report**

### Shared services

- [LLM failover and cache](https://github.com/kamalesh346/data_analyst_agent/blob/main/llm.py): `llm.py`

### Other components

- **Analyst**
- **CSV dataset**
- **LLM providers**
- **LangSmith tracing**

## Connections

- Analyst → React dashboard: uploads CSV
- Analyst → Streamlit dashboard: uploads CSV
- React dashboard → REST API: uses API
- Streamlit dashboard → Upload handling: selects dataset
- Upload handling → State graph: runs pipeline (evidence: `ui/services/pipeline_service.py`)
- REST API → State graph: runs pipeline (evidence: `api/main.py`)
- REST API → Grounded chatbot: answers questions
- State graph → CSV profiler: dispatches (evidence: `graph.py`)
- State graph → Analysis planner: dispatches (evidence: `graph.py`)
- State graph → Sandbox executor: dispatches (evidence: `graph.py`)
- State graph → Plan reflector: routes conditionally (evidence: `graph.py`)
- State graph → Insight generation: dispatches (evidence: `graph.py`)
- CSV profiler → Sweetviz profiling: generates profile (evidence: `agents/profiler/agent.py`)
- Sandbox executor → Python sandbox: executes code (evidence: `agents/analysis/agent.py`)
- CSV profiler → LLM failover and cache: invokes model (evidence: `agents/profiler/agent.py`)
- Analysis planner → LLM failover and cache: plans tasks (evidence: `agents/analysis/agent.py`)
- Sandbox executor → LLM failover and cache: generates analysis (evidence: `agents/analysis/agent.py`)
- Plan reflector → LLM failover and cache: reviews plan (evidence: `agents/analysis/agent.py`)
- Insight generation → Evidence validation: validates results
- Insight generation → Recompute verification: recomputes evidence
- Insight generation → Report generation: compiles reports
- Report generation → Sweetviz HTML report: writes HTML
- Grounded chatbot → Insight generation: uses verified output
- LLM failover and cache → LLM providers: fails over
- State graph → Shared agent state: shares state
- State graph → LangSmith tracing: traces runs
