Explainable Multi-Agent System for Automated Data Analysis

EMAS-ADA transforms raw datasets into comprehensive, insightful reports with explainable visualizations using a team of specialized AI agents.

Why this project exists

Modern AI systems fail silently.

Small changes in prompts, models, preprocessing, or data distributions can cause:

• subtle quality regressions
• inconsistent outputs across runs
• explanations that no longer match behavior
• decisions that are difficult to audit or trust

This project was built to address that problem.

EMAS-ADA is not a dashboard-first analytics tool — it is an evaluation and decision-support pipeline. Its primary goal is to turn raw, messy inputs into reproducible signals that help teams answer:

• What changed?
• Why did it change?
• Can we trust this output?
• Would we catch this regression again if it happened tomorrow?

To do this, the system enforces:

• Deterministic, ordered execution (no ad-hoc notebooks)
• Explicit failure surfaces at each stage of the pipeline
• Auditable transformations with before/after comparisons
• Explainability as a first-class output, not an afterthought

While the implementation uses an EDA workflow as the substrate, the design principles map directly to AI evaluation infrastructure — where correctness, traceability, and regression detection matter more than speed or visual polish.

Architecture Diagram

flowchart LR
    User[User] -->|Upload Dataset| Frontend[Next.js Frontend]
    Frontend -->|REST API| Backend[FastAPI Backend]
    Backend -->|Orchestrate| Crew[CrewAI EDACrew]
  
    subgraph Agents[Specialized Agents]
        direction TB
        A1[Profiler] --> A2[Cleaner]
        A2 --> A3[Statistician]
        A3 --> A4[Visualizer]
        A4 --> A5[XAI Agent]
        A5 --> A6[Reporter]
    end
  
    Crew --> Agents
    Agents -->|Generate| Output[Reports and Charts]
    Output -->|Display| Frontend

_{Detailed Architecture Diagram (for nerds)}

flowchart TB
    subgraph UserInterface["User Interface Layer"]
        User["User"]
        subgraph NextJS["Next.js Frontend"]
            FileUploader["FileUploader"]
            ProgressBar["ProgressBar"]
            Dashboard["Dashboard Page"]
            ReportViewer["ReportViewer"]
            ChartGallery["ChartGallery"]
            ModelViewer["ModelViewer"]
            BeforeAfter["BeforeAfterPanel"]
        end
    end

    subgraph APILayer["API Layer"]
        subgraph FastAPI["FastAPI Backend"]
            Upload["/api/upload"]
            RunEDA["/api/eda/run"]
            Status["/api/eda/status"]
            Report["/api/report"]
            Charts["/api/charts"]
            Model["/api/model"]
            SHAP["/api/shap"]
        end
        ProgressTracker["ProgressTracker"]
    end

    subgraph OrchestrationLayer["Orchestration Layer"]
        EDACrew["EDACrew Orchestrator"]
        LLM["LLM Provider via OpenRouter"]
        TaskQueue["Task Sequencing"]
        Callbacks["Step and Task Callbacks"]
    end

    subgraph AgentLayer["Agent Layer"]
        direction LR
        Profiler["Data Profiler Agent"]
        Cleaner["Data Cleaner Agent"]
        Statistician["Statistician Agent"]
        Visualizer["Data Visualizer Agent"]
        ModelRec["Model Recommender Agent"]
        XAIAgent["XAI Agent"]
        Reporter["Technical Report Writer"]
    end

    subgraph ToolsLayer["Tools Layer"]
        subgraph DataTools["Data Tools"]
            ProfileDataset["ProfileDatasetTool"]
            DetectOutliers["DetectOutliersTool"]
            CleanMissing["CleanMissingValuesTool"]
            GetColumnInfo["GetColumnInfoTool"]
            GetDataSummary["GetDataSummaryTool"]
        end
        subgraph StatsTools["Statistics Tools"]
            DescriptiveStats["DescriptiveStatsTool"]
            CorrelationAnalysis["CorrelationAnalysisTool"]
            CategoricalAnalysis["CategoricalAnalysisTool"]
            DetectPatterns["DetectPatternsTool"]
            NormalityTest["NormalityTestTool"]
        end
        subgraph VizTools["Visualization Tools"]
            DistributionPlots["DistributionPlotsTool"]
            CorrelationHeatmap["CorrelationHeatmapTool"]
            CategoricalCharts["CategoricalChartsTool"]
            BoxPlots["BoxPlotsTool"]
            CleaningImpact["CleaningImpactPlotTool"]
            DataQualitySummary["DataQualitySummaryTool"]
        end
        subgraph MLTools["ML Tools"]
            SuggestModels["SuggestModelsBasedOnDataTool"]
            TrainModel["TrainSimpleModelTool"]
        end
        subgraph XAITools["XAI Tools"]
            SHAPSummary["GenerateSHAPSummaryTool"]
            LIMEExplanation["GenerateLIMEExplanationTool"]
            FeatureImportance["CompareFeatureImportanceTool"]
        end
    end

    subgraph DataLayer["Data Layer"]
        DataStore["DataStore Singleton"]
        OriginalDF["Original DataFrame"]
        CleanedDF["Cleaned DataFrame"]
        Changelog["Changelog"]
        Metadata["Metadata"]
    end

    subgraph OutputLayer["Output Layer"]
        OutputDir["output/"]
        ChartsDir["output/charts/"]
        ModelsDir["output/models/"]
        ReportMD["report.md + Model Summary"]
        ReportHTML["report.html + Model Summary"]
        CleanedCSV["cleaned_data.csv"]
        PNGCharts["*.png Charts"]
        ModelPKL["trained_model.pkl"]
    end

    User -->|"Upload CSV/Excel"| FileUploader
    FileUploader -->|"POST /api/upload"| Upload
    Dashboard -->|"POST /api/eda/run"| RunEDA
    ProgressBar -->|"GET /api/eda/status"| Status
    ReportViewer -->|"GET /api/report"| Report
    ChartGallery -->|"GET /api/charts"| Charts
    ModelViewer -->|"GET /api/model"| Model

    Upload -->|"Store File"| DataStore
    RunEDA -->|"Trigger Background Task"| EDACrew
    Status -->|"Query Status"| ProgressTracker

    EDACrew -->|"Create LLM"| LLM
    EDACrew -->|"Sequence Tasks"| TaskQueue
    EDACrew -->|"Track Progress"| Callbacks
    Callbacks -->|"Update"| ProgressTracker

    TaskQueue -->|"1. Profile"| Profiler
    TaskQueue -->|"2. Clean"| Cleaner
    TaskQueue -->|"3. Analyze"| Statistician
    TaskQueue -->|"4. Visualize"| Visualizer
    TaskQueue -->|"5. Recommend"| ModelRec
    TaskQueue -->|"6. Explain"| XAIAgent
    TaskQueue -->|"7. Report"| Reporter

    Profiler --> DataTools
    Cleaner --> DataTools
    Statistician --> StatsTools
    Visualizer --> VizTools
    ModelRec --> MLTools
    XAIAgent --> XAITools

    DataTools --> DataStore
    StatsTools --> DataStore
    VizTools --> DataStore
    MLTools --> DataStore
    XAITools --> DataStore

    DataStore --> OriginalDF
    DataStore --> CleanedDF
    DataStore --> Changelog
    DataStore --> Metadata

    VizTools -->ChartsDir
    MLTools --> ModelsDir
    MLTools -->|"Append Model Summary"| ReportMD
    MLTools -->|"Append Model Summary"| ReportHTML
    Reporter --> ReportMD
    Reporter --> ReportHTML
    DataTools --> CleanedCSV

    ChartsDir --> PNGCharts
    ModelsDir --> ModelPKL

Architecture Explanation

• Data Ingestion Module: src/api/main.py handles file uploads via FastAPI, validating formats (.csv, .xlsx) and storing them safely.
• Agent Orchestrator: src/crew/eda_crew.py utilizes CrewAI to manage the lifecycle of agents, ensuring tasks are executed in the correct sequential order.
• Specialized Agents (7 total):
  • Profiler: Audits data quality, structure, and identifies issues.
  • Cleaner: Handles missing values and outlier detection using Pandas.
  • Statistician: Performs statistical analysis (correlations, normality tests, pattern detection).
  • Visualizer: Generates charts using Matplotlib/Seaborn (distributions, heatmaps, box plots).
  • Model Recommender: Suggests and trains ML models using Scikit-learn, capturing detailed training metadata.
  • XAI Agent: Computes SHAP values and LIME explanations for model interpretability.
  • Reporter: Compiles all findings into structured Markdown/HTML reports.
• Model Summary Integration: After training, detailed model metrics are automatically appended to the report.
• Frontend UI: A Next.js application that provides a real-time dashboard for monitoring progress, viewing interactive reports, and exploring model training details (confusion matrix, hyperparameters, feature importance).

Key Features

• Multi-Agent Collaboration: Specialized roles ensure depth in every aspect of analysis (cleaning, stats, viz).
• Explainable AI (XAI): Integrated SHAP and LIME for transparent model interpretation.
• Automated Data Cleaning: Intelligent handling of missing values and outliers with audit logs.
• Interactive Dashboard: Modern UI for easy upload, monitoring, and report consumption.
• Dual-Format Reporting: Generates both Markdown (for devs) and HTML (for business) reports.
• Enhanced Model Viewer: Displays training configuration, data split, performance metrics, confusion matrix with interpretation, and hyperparameters.
• Unified Model Report: Model training summary is automatically appended to the EDA report after training.

Screenshots

<div align="center"> <table> <tr> <th>_Upload</th> <th>_Charts</th> <th>_Report</th> </tr> <tr> <td><img src="screenshots/upload.png" width="350"/></td> <td><img src="screenshots/charts.png" width="350"/></td> <td rowspan="3" align="center"><img src="screenshots/report.png" width="350"/></td> </tr> <tr> <th>_Dashboard</th> <th>_Model</th> </tr> <tr> <td><img src="screenshots/dashboard.png" width="350"/></td> <td><img src="screenshots/model.png" width="350"/></td> </tr> </table> </div>

Tech Stack (With Purpose)

• Python 3.10+: The core runtime for backend logic and data science libraries.
• CrewAI: Orchestrates the multi-agent workflow and task delegation.
• FastAPI: Provides a high-performance, async REST API for the frontend.
• Next.js 14: Powers the responsive, server-side rendered user interface.
• Pandas & NumPy: High-performance data manipulation and analysis.
• Scikit-learn: Machine learning utilities for predictive modeling and clustering.
• SHAP & LIME: Explainable AI libraries for model transparency.

System Workflow (Chronological Processing Steps)

1. Upload: User uploads a dataset via the Web UI.
2. Profiling: The Profiler agent scans the file for schema, types, and quality issues.
3. Cleaning: The Cleaner agent executes transformations to fix identified issues.
4. Statistical Analysis: The Statistician agent computes descriptive stats, correlations, and pattern detection.
5. Visualization: The Visualizer agent generates distribution plots, heatmaps, and box plots.
6. Model Training: The Model Recommender agent suggests and trains an appropriate ML model, capturing detailed metrics (accuracy, precision, recall, F1, confusion matrix).
7. Explanation: The XAI Agent computes SHAP/LIME explanations for model interpretability.
8. Reporting: The Reporter agent compiles all artifacts into a cohesive narrative.
9. Model Summary: Training results are automatically appended to the report (training config, data split, performance metrics, hyperparameters).
10. Review: User views the final report, charts, and model details on the Dashboard.

Input Format

• Data: .csv, .xlsx, or .xls.
• Requirements: Tabular data with headers.

Output Format

• Interactive Report: Displayed directly in the UI with live model metrics.
• Files:
  • report.md: Comprehensive Markdown report (includes Model Training Summary section).
  • report.html: HTML-formatted report for business stakeholders.
  • cleaned_data.csv: The processed dataset.
  • charts/*.png: Generated visualizations (distributions, correlations, SHAP, LIME).
  • models/trained_model.pkl: Trained ML model with encoders and metadata.

Installation Instructions

1. Clone the Repository:

   git clone https://github.com/siddharth-narigra/crewai-eda-pipeline.git
   cd crewai-eda-pipeline
   

2. Backend Setup:

   python -m venv venv
   .\venv\Scripts\activate       # Windows
   # source venv/bin/activate    # Linux/Mac
   pip install -r requirements.txt
   

3. Frontend Setup:

   cd frontend
   npm install
   

4. Configuration:

   • Copy .env.example to .env.
   • Add your API Key (e.g., OPENROUTER_API_KEY=sk-...).

How to Run

1. Start Backend:

   # From root directory
   uvicorn src.api.main:app --reload
   

2. Start Frontend:

   # From frontend directory
   npm run dev
   

3. Access App: Open http://localhost:3000.

Folder Structure

crewai-eda-pipeline/
├── src/
│   ├── agents/              # Agent definitions (Profiler, Cleaner, Statistician, etc.)
│   ├── api/                 # FastAPI endpoints and progress tracking
│   ├── crew/                # CrewAI orchestration (eda_crew.py)
│   ├── tools/               # Custom tools (data, stats, viz, ml, xai)
│   └── utils/               # Utility functions (file handling)
├── frontend/                # Next.js Web Application
│   └── src/components/      # React components (FileUploader, ReportViewer, etc.)
├── output/                  # Generated artifacts (Reports, Charts, Models)
├── uploads/                 # Temporary storage for uploaded files
├── sample_data/             # Sample datasets for testing
├── requirements.txt         # Backend Python dependencies
└── README.md                # This document

Limitations

• LLM Dependency: Requires an active internet connection and API key for the LLM provider.
• Processing Time: Large datasets may take longer to process due to LLM latency.
• Token Costs: Extensive analysis of very large files may consume significant API tokens.

License

MIT License