# ethicalml/xai architecture

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

- Interactive diagram: https://gitdiagram.com/ethicalml/xai
- Repository: https://github.com/ethicalml/xai

## Overview

##### Project type and purpose
- This is a Python-based open-source library/toolkit (“XAI”) for eXplainable AI: a set of modules to analyze datasets, evaluate models, and monitor production metrics.
- It is *not* a full-stack web app, but rather a library consumed by data scientists (e.g. via Jupyter notebooks) and documented via Sphinx/MkDocs.

##### Main logical layers/components
a. User/Client Layer
– Jupyter Notebook or Python script (“Examples” folder)
– CLI / direct Python import (pip install xai)
b. Application Layer (XAI Core Package)
– xai.data: data loaders (e.g. load_census)
– xai.preprocessing: balancing, grouping, train‐test split
– xai.visualisation: imbalance_plot, correlations, confusion_matrix_plot, roc_plot, smile_imbalance
– xai.metrics: feature_importance, metrics_plot
c. Infrastructure / Dependencies
– External libraries: pandas, numpy, scikit-learn, TensorFlow/Keras, matplotlib, seaborn
– Data sources: built-in CSV (xai/data/census.csv) or user-supplied datasets
d. Documentation Pipeline
– Sphinx (docs_src/ + conf.py) → HTML docs (docs/)
– MkDocs (mkdocs.yml) for GitHub Pages
e. Packaging & Distribution
– setup.py / meta.yaml / env.yml / requirements.txt → PyPI distribution

##### Relationships & interactions
- The user (data scientist) writes notebook code that imports xai.* modules → invokes data loaders and analysis functions → generates DataFrame outputs and calls visualization routines → matplotlib / seaborn render charts inline.
- XAI libraries call on external dependencies for numeric computing (NumPy), data manipulation (Pandas), ML evaluation (scikit-learn), deep‐learning (TensorFlow/Keras).
- The built-in data file (census.csv) is bundled in the package under xai/data; user data can also be passed in.
- Documentation build tools read the source docs (docs_src/) and generate static assets (docs/) that get deployed to GitHub Pages.
- Packaging scripts (setup.py, MANIFEST.in, meta.yaml) read source code to package and publish to PyPI.

##### Architectural patterns or design principles
- Modular library structure: each concern (data loading, sampling, visualization, metrics) lives in its own module.
- Dependency Injection: user supplies model evaluation callback (e.g., get_avg) to feature_importance.
- Separation of concerns: visualization and data processing are decoupled—functions return DataFrames or metrics objects which are then passed to plot routines.
- Pluggable backends: supports both pure-Python computing (scikit-learn) and deep learning (TensorFlow).

##### Elements
- Notebook → xai.data → Data Source
- Notebook → xai.preprocessing → Notebook
- Notebook → xai.visualisation → matplotlib/seaborn → renders plots
- xai.metrics → scikit-learn / TensorFlow → returns metrics → xai.visualisation
- docs_src/ → Sphinx/MkDocs → docs/ → GitHub Pages
- setup.py + source code → PyPI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        NB["Jupyter Notebook / Python Script"]:::user
    end

    %% Core Modules
    subgraph "XAI Core Modules"
        Entry["xai/__init__.py"]:::core
        Data["xai.data"]:::core
        Pre["xai.preprocessing"]:::core
        Met["xai.metrics"]:::core
        Vis["xai.visualisation"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Pandas["pandas, numpy, scikit-learn, TensorFlow"]:::ext
        PlotLib["matplotlib, seaborn"]:::ext
    end

    %% Data Sources
    subgraph "Data Sources"
        BuiltInCSV[(census.csv)]:::data
        UserCSV[(user CSV)]:::data
        ExampleData[(adult.data)]:::data
    end

    %% Documentation & Packaging Pipelines
    subgraph "Documentation & Packaging & Distribution"
        DocSrc["docs_src/"]:::pipe
        Conf["conf.py"]:::pipe
        Sphinx["Sphinx/MkDocs"]:::pipe
        HTML["docs/"]:::pipe
        GH["GitHub Pages"]:::pipe
        MkCfg["mkdocs.yml"]:::pipe
        Setup["setup.py"]:::pipe
        Manifest["MANIFEST.in"]:::pipe
        Env["env.yml"]:::pipe
        Meta["meta.yaml"]:::pipe
        Req["requirements.txt"]:::pipe
        PyPI["PyPI"]:::pipe
    end

    %% Flows
    NB -->|"import + call"| Entry
    NB -->|"import + call"| Data
    NB -->|"import + call"| Pre
    NB -->|"import + call"| Met
    NB -->|"import + call"| Vis

    Data -->|"reads CSV"| BuiltInCSV
    Data -->|"reads CSV"| UserCSV
    Data -->|"reads CSV"| ExampleData

    Pre -->|"returns DataFrame"| NB
    Met -->|"returns metrics"| Vis
    Vis -->|"renders plots"| PlotLib

    Data -->|"depends on"| Pandas
    Pre -->|"depends on"| Pandas
    Met -->|"depends on"| Pandas
    Met -->|"calls ML libs"| Pandas
    Vis -->|"depends on"| PlotLib

    DocSrc -->|"uses config"| Conf
    DocSrc -->|"builds docs"| Sphinx
    Sphinx -->|"outputs"| HTML
    HTML -->|"deploys to"| GH
    MkCfg -->|"configures"| GH

    Entry -->|"packages"| Setup
    Entry -->|"packages"| Manifest
    Entry -->|"defines env"| Env
    Entry -->|"defines metadata"| Meta
    Entry -->|"lists deps"| Req
    Setup -->|"publishes package"| PyPI

    %% Click Events
    click NB "https://github.com/ethicalml/xai/blob/master/examples/XAI Tabular Data Example Usage.ipynb"
    click ExampleData "https://github.com/ethicalml/xai/blob/master/examples/data/adult.data"
    click Entry "https://github.com/ethicalml/xai/blob/master/xai/__init__.py"
    click Data "https://github.com/ethicalml/xai/blob/master/xai/data/__init__.py"
    click BuiltInCSV "https://github.com/ethicalml/xai/blob/master/xai/data/census.csv"
    click DocSrc "https://github.com/ethicalml/xai/tree/master/docs_src/source/"
    click Conf "https://github.com/ethicalml/xai/blob/master/docs_src/source/conf.py"
    click HTML "https://github.com/ethicalml/xai/tree/master/docs/"
    click MkCfg "https://github.com/ethicalml/xai/blob/master/mkdocs.yml"
    click Setup "https://github.com/ethicalml/xai/blob/master/setup.py"
    click Manifest "https://github.com/ethicalml/xai/blob/master/MANIFEST.in"
    click Env "https://github.com/ethicalml/xai/blob/master/env.yml"
    click Meta "https://github.com/ethicalml/xai/blob/master/meta.yaml"
    click Req "https://github.com/ethicalml/xai/blob/master/requirements.txt"

    %% Styles
    classDef user fill:#d0f0c0,stroke:#2d572c,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#2d5170,stroke-width:2px;
    classDef ext fill:#ffe5b4,stroke:#996515,stroke-width:2px;
    classDef data fill:#f2f2f2,stroke:#808080,stroke-width:2px,stroke-dasharray: 5 5;
    classDef pipe fill:#e0e0e0,stroke:#666666,stroke-width:2px,stroke-dasharray: 2 2;
```
