# enesmanan/llmautoeda architecture

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

- Interactive diagram: https://gitdiagram.com/enesmanan/llmautoeda
- Repository: https://github.com/enesmanan/llmautoeda

## Overview

##### What this project is (type + purpose)
This is a **Python package/library** that provides **automated exploratory data analysis (EDA)**. It combines:
- **Deterministic/statistical EDA** (summaries, correlations, distributions, etc.)
- **Visualization generation**
- **LLM-powered narrative/insights** (via an OpenAI API key)
- **Report generation** (interactive HTML report)

From the README usage (`AutoEDA(...).analyze(...).save_report(...)`), the primary “product surface” is a **library API** (not a web service), with optional notebook/script examples.

##### How to read the file tree architecturally
Key directories/files:
- `llm_auto_eda/` — package root
- `llm_auto_eda/main.py` — likely CLI or entrypoint glue
- `data_loader.py` — ingestion + parsing of data sources (CSV, maybe DataFrame)
- `analyzer.py` — orchestrator / façade that coordinates the pipeline (very likely where `AutoEDA` lives or is used)
- `statistical_analyzer.py` — computes numeric summaries, correlations, missingness, etc.
- `visualizer.py` — creates plots/figures (likely matplotlib/plotly/seaborn)
- `llm_analyzer.py` — sends curated stats + context to LLM and receives insights
- `report_generator.py` — composes HTML report from stats + visuals + LLM insights
- `examples/` — consumer-side usage patterns
- `setup.py`, `MANIFEST.in` — packaging/distribution boundaries

This strongly suggests a **pipeline-style layered design**:

##### What the README implies about runtime interactions
Runtime calls look like:
##### Receives an `analysis` object exposing
- `analysis.data_summary`
- `analysis.correlations`
- `analysis.insights`
##### Optionally persists via `analysis.save_report('...html')`

- A **public API surface** (`AutoEDA`, `analysis` result model)
- A **core pipeline** in `core/*`
- An **external dependency** (OpenAI/LLM provider)
- **Artifacts** produced (plots, HTML report)

##### Public API layer
- `AutoEDA` (from `llm_auto_eda/__init__.py` and/or `core/analyzer.py`)

##### Core pipeline (llm_auto_eda/core)
- `DataLoader` (`data_loader.py`)
- `StatisticalAnalyzer` (`statistical_analyzer.py`)
- `Visualizer` (`visualizer.py`)
- `LLMAnalyzer` (`llm_analyzer.py`)
- `ReportGenerator` (`report_generator.py`)
- `Analyzer/Orchestrator` (`analyzer.py`) — this coordinates calls to the above and assembles the result

##### External systems
- **LLM Provider API** (OpenAI or compatible)
- (Optional to include if relevant) “Local file system” for reading CSV and writing HTML report

##### Inputs/outputs
- Inputs: `CSV / DataFrame / data_source`
- Outputs:
- In-memory: summaries/correlations/insights
- On-disk: `analysis_report.html` (and possibly embedded images)

- User → `AutoEDA.analyze()`
- `AutoEDA/analyzer.py` → `DataLoader` (reads CSV / returns DataFrame)
- `Analyzer` → `StatisticalAnalyzer` (returns summary tables, missingness, correlations)
- `Analyzer` → `Visualizer` (consumes DataFrame + stats → returns plots/figures)
- `Analyzer` → `LLMAnalyzer`
- Inputs to LLMAnalyzer: domain context, exclude_columns, selected stats, maybe schema/profile
- LLMAnalyzer → External “LLM API” (network call)
- External LLM API → LLMAnalyzer (insights text / structured suggestions)
- `Analyzer` → `ReportGenerator` (consumes stats + plots + LLM insights → returns HTML content)
- User / `analysis.save_report()` → File system (writes HTML)

Important: make the LLM call *explicit* as a network boundary; it matters for latency, cost, failure modes.

##### Architectural patterns/design principles used
- **Façade / Orchestrator pattern**: `AutoEDA` / `Analyzer` presents a simple API over multiple subsystems.
- **Separation of concerns**: each core module has a single responsibility.

- **Python package** distribution (`setup.py`)
- **LLM provider** (OpenAI mentioned explicitly in README)
For plotting/report tech, only label generically unless you confirm in code:
- “Plotting library (matplotlib/plotly/seaborn)” as a generic sub-label inside `Visualizer`
- “HTML templating/report composition” inside `ReportGenerator`

##### What

- Actor: “Data Scientist / Analyst”
- System: “LLM Auto EDA (Python library)”
- External system: “OpenAI API”
- External resource: “Dataset (CSV/Parquet/DF)” + “File system (report output)”
Purpose: shows boundaries and dependencies at a glance.

- AutoEDA API
- Analyzer/Orchestrator
- DataLoader
- StatisticalAnalyzer
- Visualizer
- LLMAnalyzer
- ReportGenerator
- Analysis Result Model (data summary, correlations, insights, plots, report html)

- **AutoEDA / Public API** → `llm_auto_eda/__init__.py` (+ implementation likely in `core/analyzer.py`)
- **Orchestrator** → `llm_auto_eda/core/analyzer.py`
- **Loaders** → `llm_auto_eda/core/data_loader.py`
- **Stats** → `llm_auto_eda/core/statistical_analyzer.py`
- **LLM** → `llm_auto_eda/core/llm_analyzer.py`
- **Viz** → `llm_auto_eda/core/visualizer.py`
- **Report** → `llm_auto_eda/core/report_generator.py`
- **CLI/Entry** (if used) → `llm_auto_eda/main.py`
- **Examples/Consumers** → `examples/example_usage.py`, `examples/example_notebook.ipynb`

##### Final guidance: don’t overthink, just decompose
For “best and most accurate,” prefer **more components**, not fewer:
- Separate “Stats computation” from “LLM prompt building”
- Separate “Plot creation” from “Report assembly”
- Explicitly show “Domain/exclude_columns config” flowing into analyzers and LLM prompt
- Explicitly show “Analysis object” as the aggregation point returned to the user

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram 1 — System Context (C4-style)
    %% =========================

    subgraph D1["Diagram 1 — System Context (C4-style)"]
        direction TB

        Actor["Data Scientist / Analyst"]:::actor

        subgraph SB1["System Boundary: LLM Auto EDA (Python library)"]
            direction TB
            Lib["LLM Auto EDA\n(Python package)"]:::system
            API1["Public API: AutoEDA"]:::api
            CLI1["CLI / Entrypoint Glue"]:::cli
            Lib -->|"exposes"| API1
            Lib -->|"optional_entrypoint"| CLI1
        end

        Dataset[("Dataset\nCSV / Parquet / DataFrame")]:::data
        FS[("Local File System")]:::externalStore
        OpenAI["LLM Provider API\n(OpenAI-compatible)"]:::external

        Report[("HTML Report\nanalysis_report.html")]:::artifact
        InMem["In-memory Analysis\n(summary,correlations,insights,plots)"]:::artifact

        Actor -->|"calls AutoEDA.analyze()"| API1
        Actor -->|"runs (optional)"| CLI1

        API1 -->|"reads data_source"| Dataset
        API1 -->|"loads/saves"| FS
        API1 -.->|"optional_insights(api_key)"| OpenAI

        API1 -->|"returns"| InMem
        InMem -->|"save_report()"| Report
        Report -->|"write"| FS
    end

    %% =========================
    %% Diagram 2 — Component / Pipeline (core/*)
    %% =========================

    subgraph D2["Diagram 2 — Component / Pipeline (core/*)"]
        direction TB

        User2["Client Code\n(script / notebook / app)"]:::actor
        Input2[("data_source\nCSV path / DataFrame")]:::data
        Output2[("analysis_report.html")]:::artifact
        FS2[("Local File System")]:::externalStore
        OpenAI2["LLM Provider API\n(OpenAI-compatible)"]:::external

        subgraph PKG["LLM Auto EDA Package (llm_auto_eda)"]
            direction TB
            API2["AutoEDA (Public API)"]:::api
            CoreInit["core/__init__.py\n(module exports)"]:::pkg

            subgraph PIPE["Core Pipeline (llm_auto_eda/core)"]
                direction TB
                Orchestrator["Analyzer / Orchestrator\n(façade + pipeline coordinator)"]:::core
                Loader["DataLoader\n(ingestion + parsing)"]:::core
                Stats["StatisticalAnalyzer\n(summaries,missingness,correlations)"]:::core
                Viz["Visualizer\n(plots/figures)"]:::core
                LLM["LLMAnalyzer\n(prompt build + insights)"]:::core
                ReportGen["ReportGenerator\n(HTML composition)"]:::core
            end

            Result["Analysis Result Model\n(data_summary,correlations,insights,plots,report_html)"]:::artifact
            Config["Analyze Config\n(domain,exclude_columns,api_key)"]:::config

            API2 -->|"delegates"| Orchestrator
            CoreInit -->|"exports"| Orchestrator
            Orchestrator -->|"returns"| Result
        end

        %% Main call flow (vertical pipeline)
        User2 -->|"AutoEDA(api_key)"| API2
        User2 -->|"analyze(data_source,domain,exclude_columns)"| API2
        API2 -->|"passes config"| Config
        API2 -->|"passes data_source"| Input2

        Orchestrator -->|"load()"| Loader
        Loader -->|"read (optional)"| FS2
        Input2 -->|"ingest"| Loader

        Loader -->|"DataFrame"| Orchestrator
        Config -->|"domain/exclude_columns"| Orchestrator

        Orchestrator -->|"compute_stats(df)"| Stats
        Stats -->|"tables/metrics"| Orchestrator

        Orchestrator -->|"create_plots(df,stats)"| Viz
        Viz -->|"figures/embeddables"| Orchestrator

        Orchestrator -->|"generate_insights(stats,context)"| LLM
        Config -->|"api_key (optional)"| LLM
        LLM -.->|"network_call (optional)"| OpenAI2
        OpenAI2 -.->|"insights"| LLM
        LLM -->|"narrative/insights"| Orchestrator

        Orchestrator -->|"compose_report(stats,plots,insights)"| ReportGen
        ReportGen -->|"HTML content"| Orchestrator

        %% Result aggregation + persistence
        Orchestrator -->|"assemble"| Result
        User2 <-->|"reads fields"| Result
        User2 -->|"analysis.save_report(path)"| Result
        Result -->|"write HTML"| FS2
        FS2 -->|"creates"| Output2
    end

    %% Click Events (mapped components)
    click API1 "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/__init__.py"
    click CLI1 "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/main.py"
    click Lib "https://github.com/enesmanan/llmautoeda/blob/main/setup.py"
    click Dataset "https://github.com/enesmanan/llmautoeda/blob/main/examples/example_usage.py"
    click Report "https://github.com/enesmanan/llmautoeda/blob/main/MANIFEST.in"

    click API2 "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/__init__.py"
    click CoreInit "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/__init__.py"
    click Orchestrator "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/analyzer.py"
    click Loader "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/data_loader.py"
    click Stats "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/statistical_analyzer.py"
    click Viz "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/visualizer.py"
    click LLM "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/llm_analyzer.py"
    click ReportGen "https://github.com/enesmanan/llmautoeda/blob/main/llm_auto_eda/core/report_generator.py"
    click Output2 "https://github.com/enesmanan/llmautoeda/blob/main/MANIFEST.in"
    click User2 "https://github.com/enesmanan/llmautoeda/blob/main/examples/example_notebook.ipynb"
    click Input2 "https://github.com/enesmanan/llmautoeda/blob/main/examples/example_usage.py"

    %% Styles
    classDef actor fill:#FFF2CC,stroke:#B7950B,stroke-width:1px,color:#111;
    classDef system fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px,color:#111;
    classDef api fill:#AED6F1,stroke:#1B4F72,stroke-width:1px,color:#111;
    classDef cli fill:#A9DFBF,stroke:#1E8449,stroke-width:1px,color:#111;
    classDef pkg fill:#EBF5FB,stroke:#2E86C1,stroke-width:1px,color:#111;
    classDef core fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px,color:#111;
    classDef config fill:#FADBD8,stroke:#943126,stroke-width:1px,color:#111;
    classDef external fill:#E5E7E9,stroke:#566573,stroke-width:1px,color:#111;
    classDef externalStore fill:#F2F3F4,stroke:#616A6B,stroke-width:1px,color:#111;
    classDef data fill:#D5F5E3,stroke:#1E8449,stroke-width:1px,color:#111;
    classDef artifact fill:#D1F2EB,stroke:#117A65,stroke-width:1px,color:#111;
```
