# abekoki/ai_analysis_engine_sample architecture

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

- Interactive diagram: https://gitdiagram.com/abekoki/ai_analysis_engine_sample
- Repository: https://github.com/abekoki/ai_analysis_engine_sample

## Overview

##### Project Type and Purpose
- This is a Python-based AI analysis engine for anomaly detection.
- It is delivered as a CLI tool/library (`src/ai_analysis_engine`) that drives an AI agent (LangChain + OpenAI) and integrates with a Jupyter Notebook server to generate visual, beginner-friendly anomaly reports (HTML or Notebook).

##### File‐Structure Analysis
- Top‐level
- `src/ai_analysis_engine/` – core modules and CLI entry point
- `templates/` – HTML templates for report generation
- `samples/` – example CSV data, specs, sources, and expectations
- `output/` – generated reports
- Config: `pyproject.toml`, `uv.lock`
- Key Modules
- `cli.py` & `__main__.py` – parses CLI args, loads config, instantiates AI agent
- `expectation_parser.py` – converts natural-language expectations into structured constraints
- `data_analyzer.py` – ingests CSV with Pandas, identifies candidate anomalies
- `hypothesis_generator.py` – leverages LangChain/OpenAI to generate root-cause hypotheses
- `report_generator.py` – applies Jinja2 templates to produce HTML/Notebook report
- External Integrations
- Jupyter Notebook server via MultiServerMCPClient
- OpenAI API (GPT models)
- RAG-based retrieval for spec/source code search

##### Insights from README
User → AI Agent → NLP + Notebook → Anomaly Detection → Cause Analysis → Report Creation → User
- Tech stack: LangChain, OpenAI, Pandas/NumPy, Matplotlib/Seaborn, Jupyter Notebook

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    subgraph "User Interface"
        User(("User"))
        CLI["CLI (Terminal)"]:::core
        NotebookViewer["Jupyter Notebook Viewer"]:::external
    end

    %% Core Engine Modules
    subgraph "Core Engine"
        Parser["Expectation Parser"]:::core
        Analyzer["Data Analyzer"]:::core
        Hypothesis["Hypothesis Generator"]:::core
        Reporter["Report Generator"]:::core
    end

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API (GPT models)"]:::external
        JupyterServer["Jupyter Notebook Server"]:::external
    end

    %% Data Artifacts
    subgraph "Data Artifacts"
        CSV[/samples/data.csv/]:::artifact
        Expectation[/samples/expectation.txt/]:::artifact
        Source[/samples/source.py/]:::artifact
        Spec[/samples/spec.md/]:::artifact
        Templates[/templates/report_template.html/]:::artifact
        Output[/output/report.html/]:::artifact
        Config[/pyproject.toml, uv.lock/]:::artifact
    end

    %% Data Flow
    User --> CLI
    CLI --> Config
    CLI --> Parser
    Expectation --> Parser
    Parser --> Analyzer
    CSV --> Analyzer
    Analyzer --> Hypothesis
    Hypothesis -.->|RAG retrieval| Spec
    Hypothesis -.->|RAG retrieval| Source
    Hypothesis -.->|calls OpenAI| OpenAI
    Hypothesis --> Reporter
    Templates --> Reporter
    Reporter --> Output
    Reporter --> JupyterServer
    JupyterServer --> NotebookViewer
    NotebookViewer --> User

    %% Click Events
    click CLI "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/src/ai_analysis_engine/cli.py"
    click CLI "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/src/ai_analysis_engine/__main__.py"
    click Parser "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/src/ai_analysis_engine/expectation_parser.py"
    click Analyzer "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/src/ai_analysis_engine/data_analyzer.py"
    click Hypothesis "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/src/ai_analysis_engine/hypothesis_generator.py"
    click Reporter "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/src/ai_analysis_engine/report_generator.py"
    click Templates "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/templates/report_template.html"
    click CSV "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/samples/data.csv"
    click Expectation "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/samples/expectation.txt"
    click Source "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/samples/source.py"
    click Spec "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/samples/spec.md"
    click Output "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/output/report.html"
    click Config "https://github.com/abekoki/ai_analysis_engine_sample/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef artifact fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
