# geliang0114/nvagent architecture

> Architecture diagram of the GitHub repository geliang0114/nvagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geliang0114/nvagent
- Repository: https://github.com/geliang0114/nvagent

## Overview

##### Project Type & Purpose
- nvAgent is a full-stack AI workflow for Natural-Language-to-Visualization (NL2Vis).
- It comprises three collaborative agents (processor, composer, validator), a web UI for live demos, and an evaluation framework (VisEval) for benchmarking.

##### File Structure
- Top level:
- core/ – orchestration of agents, LLM config, prompts, utilities
- web_vis/ – Flask‐based web interface (app.py, templates)
- viseval/ – evaluation code and checks (evaluate.py, check/*)
- run_evaluate.py – entry point for automated benchmarking
- Observations:
- MVC pattern in web_vis (app.py controllers + templates views)
- Agent workflow in core (chat_manager orchestrates multiple LLM calls)
- visEval as a separate evaluation micro-service

##### Extract Architectural Insights from README
- Three Agents:
a. ProcessorAgent – filters/queries tabular data
b. ComposerAgent – plans visualization (chart type, axes, encodings)
c. ValidatorAgent – translates plan into code + verifies output
- Interactive demo: Flask UI where users upload CSVs and type requests
- Evaluation: uses Selenium + GPT-4o-mini (vision model) as a judge

##### Main Components & Their Interactions
A. Frontend (Web UI)
- Flask app (web_vis/app.py)
- Jinja2 templates (web_vis/templates/index.html)
- Static/demo assets for user upload & text input
B. Backend Core (Agent Workflow)
- ChatManager (core/chat_manager.py) orchestrates:
- ProcessorAgent (core/agents.py)
- ComposerAgent (core/agents.py)
- ValidatorAgent (core/agents.py)
- LLM Interface (core/llm.py) via Azure OpenAI / OpenAI API
- Prompt Templates (core/const.py), Config (core/api_config.py), Utilities
C. Data Layer
- User‐uploaded CSV files (runtime)
- VisEval Dataset (visEval_dataset.zip) for evaluation
D. Visualization Engine
- Matplotlib / Seaborn code generated by agents
- Output images / chart objects returned to UI
E. Evaluation Framework (visEval)
- Dataset loader (viseval/dataset.py)
- Evaluation runner (viseval/evaluate.py + run_evaluate.py)
- Check modules (viseval/check/*.py) for layout, readability, etc.
- Vision-language judge (GPT-4o-mini via Langchain) + Selenium

##### Relationships & Data Flow
- User → Frontend UI → Backend API endpoint (Flask)
- Backend → ChatManager → ProcessorAgent → (reads CSV) → calls LLM
- ProcessorAgent → ComposerAgent → LLM → returns visualization plan
- ComposerAgent → ValidatorAgent → LLM → returns executable Python code
- ValidatorAgent → executes code → generates chart → returns image URL/data
- Backend → responds to UI with rendered chart
- For batch evaluation: run_evaluate.py → loads visEval dataset → ChatManager → generates & saves charts → Selenium captures screenshots → Vision LLM judges → evaluation scores

##### Architectural Patterns / Principles
- Agent-based micro-workflow: clear separation of responsibilities among agents
- MVC for web interface: Controllers (app.py) ↔ Views (templates)
- Layered design: Presentation (web_vis) → Application (core) → Data (files, datasets) → External (LLM APIs)
- Modular evaluation service decoupled from main inference pipeline

##### Technologies & Frameworks to Call Out
- Python 3.9+, Flask, Jinja2
- Langchain for LLM orchestration
- Azure OpenAI / OpenAI API for code generation & vision judging
- Matplotlib / Seaborn for charting
- Selenium (chromedriver) for screenshot‐based evaluation
- GPT-4o-mini as MLLM-as-Judge

## Diagram (Mermaid)

```mermaid
graph TB
    %% External User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend (Web UI)"
        direction TB
        FrontendApp["Flask App"]:::frontend
        Templates["Jinja2 Templates"]:::frontend
        StaticAssets["Static Assets"]:::frontend
    end

    %% Backend Core Layer
    subgraph "Backend Core (Agent Workflow)"
        direction TB
        ChatManager["ChatManager"]:::core
        ProcessorAgent["ProcessorAgent"]:::core
        ComposerAgent["ComposerAgent"]:::core
        ValidatorAgent["ValidatorAgent"]:::core
        LLMInterface["LLM Interface"]:::core
        APIConfig["API Configuration"]:::core
        PromptTemplates["Prompt Templates"]:::core
        Utilities["Utilities"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        CSVStore["User-uploaded CSV"]:::data
        EvalDataset["visEval Dataset"]:::data
        Archive["visEval Dataset Archive"]:::data
    end

    %% Visualization Engine
    subgraph "Visualization Engine"
        direction TB
        ChartLib["Matplotlib/Seaborn"]:::core
    end

    %% Evaluation Framework
    subgraph "Evaluation Framework (visEval)"
        direction TB
        DatasetLoader["Dataset Loader"]:::eval
        EvalRunner["Evaluation Runner"]:::eval
        EvalChecks["Evaluation Checks"]:::eval
        EntryPoint["Batch Entry Point"]:::eval
        VisionJudge["Vision LLM Judge"]:::external
        Selenium["Selenium"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMAPI["LLM API"]:::external
    end

    %% Connections
    User -->|"uploads CSV & request"| FrontendApp
    FrontendApp -->|"renders views"| Templates
    FrontendApp -->|"serves assets"| StaticAssets
    FrontendApp -->|"calls API"| ChatManager

    ChatManager -->|"calls"| ProcessorAgent
    ProcessorAgent -->|"reads CSV"| CSVStore
    ProcessorAgent -->|"queries"| LLMInterface
    ProcessorAgent -->|"sends to"| LLMAPI

    ChatManager -->|"calls"| ComposerAgent
    ComposerAgent -->|"uses prompts"| PromptTemplates
    ComposerAgent -->|"config via"| APIConfig
    ComposerAgent -->|"calls"| LLMInterface
    ComposerAgent -->|"sends to"| LLMAPI

    ChatManager -->|"calls"| ValidatorAgent
    ValidatorAgent -->|"executes code via"| Utilities
    ValidatorAgent -->|"generates chart"| ChartLib
    ValidatorAgent -->|"returns image"| FrontendApp

    EvalRunner -->|"loads dataset"| DatasetLoader
    EvalRunner -->|"uses checks"| EvalChecks
    EvalRunner -->|"invokes ChatManager"| ChatManager
    EvalRunner -->|"launches"| Selenium
    Selenium -->|"captures screenshots"| VisionJudge
    VisionJudge -->|"judges via"| LLMAPI
    EvalRunner -->|"outputs scores"| EvalDataset

    %% Data flows
    CSVStore -.->|runtime CSV| ProcessorAgent
    EvalDataset -.->|benchmark data| DatasetLoader
    Archive -.->|source archive| DatasetLoader

    %% Click Events
    click FrontendApp "https://github.com/geliang0114/nvagent/blob/main/web_vis/app.py"
    click Templates "https://github.com/geliang0114/nvagent/blob/main/web_vis/templates/index.html"
    click StaticAssets "https://github.com/geliang0114/nvagent/tree/main/assets/"
    click ChatManager "https://github.com/geliang0114/nvagent/blob/main/core/chat_manager.py"
    click ProcessorAgent "https://github.com/geliang0114/nvagent/blob/main/core/agents.py"
    click ComposerAgent "https://github.com/geliang0114/nvagent/blob/main/core/agents.py"
    click ValidatorAgent "https://github.com/geliang0114/nvagent/blob/main/core/agents.py"
    click LLMInterface "https://github.com/geliang0114/nvagent/blob/main/core/llm.py"
    click APIConfig "https://github.com/geliang0114/nvagent/blob/main/core/api_config.py"
    click PromptTemplates "https://github.com/geliang0114/nvagent/blob/main/core/const.py"
    click Utilities "https://github.com/geliang0114/nvagent/blob/main/core/utils.py"
    click DatasetLoader "https://github.com/geliang0114/nvagent/blob/main/viseval/dataset.py"
    click EvalRunner "https://github.com/geliang0114/nvagent/blob/main/viseval/evaluate.py"
    click EvalChecks "https://github.com/geliang0114/nvagent/tree/main/viseval/check/"
    click EntryPoint "https://github.com/geliang0114/nvagent/blob/main/run_evaluate.py"
    click Archive "https://github.com/geliang0114/nvagent/blob/main/visEval_dataset.zip"

    %% Styles
    classDef frontend fill:#ccffcc,stroke:#000
    classDef core fill:#cce5ff,stroke:#000
    classDef eval fill:#ffe5cc,stroke:#000
    classDef external fill:#f0f0f0,stroke:#000
    classDef data fill:#e5ffcc,stroke:#000
```
