# eliask93/langchain-sql-agent-for-dynamic-data-visualization architecture

> Architecture diagram of the GitHub repository eliask93/langchain-sql-agent-for-dynamic-data-visualization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization
- Repository: https://github.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization

## Overview

##### Project Type and Purpose
- This is a Python-based demonstration application (“LangChain SQL Agent for dynamic data visualization”) that combines an LLM (OpenAI GPT-4o mini) with a local SQL database and Plotly visualization tools.

##### File Structure Analysis
- README.md: Describes purpose, datasets, tools, and requirements.
- config.py: Holds configuration (database URI, OpenAI API key, other settings).
- agent_tools.py: Defines three visualization functions (table, bar plot, time-series plot) using Plotly.
- run_sql_agent.py: Main entry point that loads data into SQL, instantiates the LangChain agent, processes user prompts, and dispatches tool calls.
- imgs/: Contains example output images for README.

##### Key Components
a. User Interface
- A CLI or notebook interface where the user types questions.
b. Orchestrator (run_sql_agent.py)
- Loads data into local SQL database (initial ingestion).
- Reads config.py for DB connection and API keys.
- Instantiates the LangChain SQL agent.
- Feeds user prompts to the agent in up to 15 iterations.
c. SQL Database (Local)
- A SQLite (or other) database containing the four Eurostat tables.
- Accessed via SQLAlchemy.
d. LLM Agent (LangChain + OpenAI)
- Implements the SQLDatabaseChain (or custom Chain) that:
– Generates SQL queries based on user input and past context.
– Sends queries to the local database.
– Receives results, reasons about next steps or tool choice.
- Communicates with the OpenAI API for each reasoning step.
e. Tool Functions (agent_tools.py)
- output_table() → Plotly table.
- output_bar_plot() → Bar chart.
- output_time_series_plot() → Line/time-series chart.
- Invoked by the LLM agent to render results.
f. External Services
- OpenAI API (LLM inference).
- Eurostat API (used offline for initial data ingestion).

##### Relationships and Data Flow
1. User prompt → Orchestrator
2. Orchestrator → LLM Agent (via LangChain)
3. LLM Agent → OpenAI API → receives reasoning and SQL
4. LLM Agent → SQLAlchemy → executes SQL on local DB → returns result set
5. LLM Agent → decides on visualization → calls appropriate agent_tools function
6. agent_tools → Plotly → renders figure
7. Orchestrator → presents figure to user
8. (Repeat iterations up to 15)

##### Architectural Patterns and Principles
- Separation of concerns:
- config.py for settings
- agent_tools.py for visualization
- run_sql_agent.py for orchestration
- Tool-based LLM architecture: Uses LangChain’s tool invocation pattern.
- Data pipeline: initial ingestion → query → visualization.
- Modular design: easy to swap in new tools or data sources.

##### Technologies and Frameworks
- Python 3.10+
- LangChain, langchain-community, langchain-openai
- SQLAlchemy (database access)
- Pydantic (config validation)
- Pandas (data frames, optional)
- Plotly (visualization)
- SQLite (or other local SQL)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Setup / Ingestion Phase
    subgraph "Setup / Ingestion Phase"
        DataIngestion["Data Ingestion"]:::orchestration
        Eurostat["Eurostat API"]:::external
        DB["Local SQL Database"]:::db
        DataIngestion -->|"fetch data"| Eurostat
        DataIngestion -->|"load into DB"| DB
    end

    %% Query / Visualization Phase
    subgraph "Query / Visualization Phase"
        UI["User Interface\n(CLI/Notebook)"]:::ui
        Orch["Orchestrator"]:::orchestration
        Conf["Config Module"]:::config
        Agent["LLM Agent\n(LangChain SQL Agent)"]:::agent
        OpenAI["OpenAI API"]:::external
        SQLA["SQLAlchemy"]:::module
        Tools["Visualization Tools"]:::tool
        Plotly["Plotly Library"]:::external

        UI -->|"user prompt"| Orch
        Orch -->|"reads config"| Conf
        Orch -->|"invoke agent"| Agent

        Agent -->|"LLM request"| OpenAI
        OpenAI -->|"LLM response"| Agent

        Agent -->|"generate SQL"| SQLA
        SQLA -->|"execute query"| DB
        DB -->|"query results"| SQLA
        SQLA -->|"results"| Agent

        Agent -->|"invoke tool"| Tools
        Tools -->|"render chart"| Plotly
        Plotly -->|"figure output"| Orch

        Orch -->|"display figure"| UI

        Agent -.->|"iterate up to 15 times"| Agent
    end

    %% Standalone Config and Docs
    README["Project Documentation"]:::doc
    Imgs["Example Output Images"]:::doc

    %% Dependencies
    Orch --> README
    DataIngestion --> Imgs

    %% Click Events
    click Orch "https://github.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization/blob/master/run_sql_agent.py"
    click Conf "https://github.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization/blob/master/config.py"
    click Tools "https://github.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization/blob/master/agent_tools.py"
    click README "https://github.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization/blob/master/README.md"
    click Imgs "https://github.com/eliask93/langchain-sql-agent-for-dynamic-data-visualization/tree/master/imgs/"

    %% Styles
    classDef ui fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,stroke-width:2px;
    classDef orchestration fill:#FFF3E0,stroke:#FB8C00,color:#E65100,stroke-width:2px;
    classDef agent fill:#E8F5E9,stroke:#43A047,color:#1B5E20,stroke-width:2px;
    classDef db fill:#EFEBE9,stroke:#8D6E63,color:#4E342E,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#F3E5F5,stroke:#9C27B0,color:#4A148C,stroke-width:2px,stroke-dasharray: 2 2;
    classDef module fill:#E0F7FA,stroke:#00ACC1,color:#006064,stroke-width:2px;
    classDef tool fill:#FFFDE7,stroke:#FDD835,color:#F57F17,stroke-width:2px;
    classDef config fill:#ECEFF1,stroke:#546E7A,color:#263238,stroke-width:2px;
    classDef doc fill:#FAFAFA,stroke:#BDBDBD,color:#424242,stroke-width:1px,stroke-dasharray: 2 2;
```
