# salesforce/omnixai architecture

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

- Interactive diagram: https://gitdiagram.com/salesforce/omnixai
- Repository: https://github.com/salesforce/omnixai

## Overview

##### Project Type and Purpose
- OmniXAI is an open-source Python library for Explainable AI (XAI), not a web app.
- It also offers a Dash-based dashboard for interactive visualization and BentoML integration for serving explanation APIs.

##### High-Level File Structure
- Top-level packages:
- omnixai/data          – data abstraction classes (Tabular, Image, Text, TimeSeries)
- omnixai/preprocessing – data transforms & pipelines
- omnixai/explainers    – core explainer implementations, organized by data type and method
- omnixai/explanations  – post-processing of explainer outputs into generic Explanation objects
- omnixai/visualization – Dash app, callbacks, pages, assets for interactive dashboards
- omnixai/deployment    – BentoML save & init_service adapters
- omnixai/utils & sampler – misc helpers and sampling utilities
- Support directories:
- tutorials, docs, tests
- build/config files (setup.py, CI, mkdocs)

##### Key Components
- User Layer
- Jupyter notebooks / CLI scripts / Python code that import OmniXAI
- Data Layer
- Raw data (tabular CSV, images, text, time-series)
- Data wrappers: Tabular, Image, Text, TimeSeries
- Preprocessing Layer
- Preprocessing pipelines (base, encode, normalize, fill)
- User-provided preprocess/postprocess functions
- Model Layer (External)
- Scikit-learn models
- XGBoost, LightGBM
- PyTorch / TensorFlow deep nets
- Explainer Core
- Factory classes: TabularExplainer, VisionExplainer, NLPExplainer, TimeseriesExplainer
- Base classes & method registry (base.py)
- Plugin-style modules per method (shap, lime, mace, ig, gradcam, gpt, etc.)
- Explanation Objects
- LocalExplanation, GlobalExplanation, PredictionExplanation
- JSON (for REST) ↔ Python objects converter
- Visualization
- Dashboard (Dash)
– Layout, callbacks, pages for local/global/prediction/what-if panels
– Static assets (CSS, JS, fonts)
- Deployment
- BentoML save_model & init_service
- REST endpoints: /predict, /explain
- Multipart/form data handler
- External Services
- OpenAI GPT API (optional)
- BentoML model store
- Hosting environments (Heroku, AWS, GCP)

##### Interactions and Data Flow
- 1. User code creates Data object → applies Preprocessing → passes to Model
2. User initializes Explainer factory with Model, Data, preprocess/postprocess
3. Explainer factory invokes specific method modules → returns Explanation objects
4. Explanation objects can be:
- Plotted in‐line (IPython)
- Passed to Dashboard
5. Dashboard renders via callbacks → user interacts
6. For deployment: Explainer serialized via BentoML → Bento service exposes REST API
7. Clients send JSON/Multipart requests → service loads Explainer → returns JSON explanations

##### Important Architectural Patterns
- Modular plugin architecture for explanation methods under `omnixai/explainers`
- Factory pattern (TabularExplainer, VisionExplainer, etc.)
- Separation of concerns: data → preprocessing → explainers → visualization → deployment
- Extensibility points: adding a new explainer module and registering it in base.py
- Standard interfaces: all explainers implement .explain()/.explain_global()

##### Technologies and Frameworks
- Python 3.7–3.10
- Core ML libs: scikit-learn, XGBoost, PyTorch, TensorFlow
- Explainability: SHAP, LIME
- Visualization: Dash (Plotly)
- Deployment: BentoML
- External API: OpenAI GPT models

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        User["Jupyter notebooks / CLI / Python code"]:::user
    end

    %% Data Layer
    subgraph "Data Layer"
        RawData[(Raw Data)]:::storage
        BaseData["data/base.py"]:::core
        TabData["data/tabular.py"]:::core
        ImgData["data/image.py"]:::core
        TextData["data/text.py"]:::core
        TSData["data/timeseries.py"]:::core
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        PreBase["preprocessing/base.py"]:::core
        Pipeline["preprocessing/pipeline.py"]:::core
        Encode["preprocessing/encode.py"]:::core
        Normalize["preprocessing/normalize.py"]:::core
        Fill["preprocessing/fill.py"]:::core
        TabPre["preprocessing/tabular.py"]:::core
        TextPre["preprocessing/text.py"]:::core
        ImgPre["preprocessing/image.py"]:::core
    end

    %% Model Layer (External)
    subgraph "Model Layer" 
        SKLearn["Scikit-learn, XGBoost, LightGBM"]:::external
        DL["PyTorch / TensorFlow"]:::external
        APIModel["Black-box model APIs"]:::external
    end

    %% Explainer Core
    subgraph "Explainer Core"
        BaseExplainer["explainers/base.py"]:::core
        TabFactory["tabular/auto.py"]:::core
        VisionFactory["vision/auto.py"]:::core
        NLPFactory["nlp/auto.py"]:::core
        TSFactory["timeseries/auto.py"]:::core
        PredFactory["prediction/auto.py"]:::core
        SHAP["tabular/agnostic/shap.py"]:::core
        LIME["tabular/agnostic/lime.py"]:::core
        GPTMethod["tabular/agnostic/gpt.py"]:::core
        MACE["tabular/counterfactual/mace/mace.py"]:::core
        GradCAM["vision/specific/gradcam/gradcam.py"]:::core
        NLPShap["nlp/agnostic/shap.py"]:::core
    end

    %% Explanation Objects
    subgraph "Explanation Objects"
        ExpBase["explanations/base.py"]:::core
        TabFeat["tabular/feature_importance.py"]:::core
        ImgMask["image/mask.py"]:::core
        TxtImp["text/word_importance.py"]:::core
        TSFeat["timeseries/feature_importance.py"]:::core
        PredConf["prediction/confusion.py"]:::core
        ExpUtils["explanations/utils.py"]:::core
    end

    %% Visualization
    subgraph "Visualization (Dash Dashboard)"
        DashApp["visualization/dashboard.py"]:::core
        Layout["visualization/layout.py"]:::core
        Plot["visualization/plot.py"]:::core
        State["visualization/state.py"]:::core
        Assets[(assets/)]:::storage
        Callbacks[(callbacks/)]:::core
        Pages[(pages/)]:::core
    end

    %% Deployment
    subgraph "Deployment (BentoML)"
        BentoService["deployment/bentoml/omnixai.py"]:::core
        BentoStore[(BentoML Model Store)]:::storage
    end

    %% External Services
    subgraph "External Services"
        OpenAI((OpenAI GPT API)):::cloud
        Hosting((Heroku / AWS / GCP)):::cloud
    end

    %% Flow Arrows
    User -->|1 create Data object| RawData
    RawData -->|wrap| BaseData
    RawData -->|wrap| TabData
    RawData -->|wrap| ImgData
    RawData -->|wrap| TextData
    RawData -->|wrap| TSData

    BaseData -->|2 preprocess| PreBase
    TabData --> PreBase
    ImgData --> PreBase
    TextData --> PreBase
    TSData --> PreBase

    PreBase -->|"uses"| Pipeline
    Pipeline -->|encode| Encode
    Pipeline -->|normalize| Normalize
    Pipeline -->|fill| Fill
    Pipeline -->|type-specific| TabPre
    Pipeline -->|type-specific| TextPre
    Pipeline -->|type-specific| ImgPre

    Pipeline -->|3 pass array| SKLearn
    Pipeline --> DL
    Pipeline --> APIModel

    SKLearn -->|4 init Explainer| BaseExplainer
    DL --> BaseExplainer
    APIModel --> BaseExplainer

    BaseExplainer --> TabFactory
    BaseExplainer --> VisionFactory
    BaseExplainer --> NLPFactory
    BaseExplainer --> TSFactory
    BaseExplainer --> PredFactory

    TabFactory --> SHAP
    TabFactory --> LIME
    TabFactory --> GPTMethod
    TabFactory --> MACE
    VisionFactory --> GradCAM
    NLPFactory --> NLPShap

    SHAP --> ExpBase
    LIME --> ExpBase
    GPTMethod --> ExpBase
    MACE --> ExpBase
    GradCAM --> ExpBase
    NLPShap --> ExpBase

    ExpBase --> TabFeat
    ExpBase --> ImgMask
    ExpBase --> TxtImp
    ExpBase --> TSFeat
    ExpBase --> PredConf
    ExpBase --> ExpUtils

    ExpBase -->|5 inline plot| DashApp
    DashApp --> Layout
    DashApp --> Plot
    DashApp --> State
    DashApp --> Assets
    DashApp --> Callbacks
    DashApp --> Pages

    ExpBase -->|6 serialize| BentoService
    BentoService -->|expose REST| BentoStore
    BentoService -->|7 REST requests| Hosting

    Hosting --> OpenAI
    Hosting --> BentoStore

    %% Click Events
    click BaseData "https://github.com/salesforce/omnixai/blob/main/omnixai/data/base.py"
    click TabData "https://github.com/salesforce/omnixai/blob/main/omnixai/data/tabular.py"
    click ImgData "https://github.com/salesforce/omnixai/blob/main/omnixai/data/image.py"
    click TextData "https://github.com/salesforce/omnixai/blob/main/omnixai/data/text.py"
    click TSData "https://github.com/salesforce/omnixai/blob/main/omnixai/data/timeseries.py"
    click PreBase "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/base.py"
    click Pipeline "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/pipeline.py"
    click Encode "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/encode.py"
    click Normalize "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/normalize.py"
    click Fill "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/fill.py"
    click TabPre "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/tabular.py"
    click TextPre "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/text.py"
    click ImgPre "https://github.com/salesforce/omnixai/blob/main/omnixai/preprocessing/image.py"
    click BaseExplainer "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/base.py"
    click TabFactory "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/tabular/auto.py"
    click VisionFactory "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/vision/auto.py"
    click NLPFactory "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/nlp/auto.py"
    click TSFactory "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/timeseries/auto.py"
    click PredFactory "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/prediction/auto.py"
    click SHAP "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/tabular/agnostic/shap.py"
    click LIME "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/tabular/agnostic/lime.py"
    click GPTMethod "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/tabular/agnostic/gpt.py"
    click MACE "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/tabular/counterfactual/mace/mace.py"
    click GradCAM "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/vision/specific/gradcam/gradcam.py"
    click NLPShap "https://github.com/salesforce/omnixai/blob/main/omnixai/explainers/nlp/agnostic/shap.py"
    click ExpBase "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/base.py"
    click TabFeat "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/tabular/feature_importance.py"
    click ImgMask "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/image/mask.py"
    click TxtImp "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/text/word_importance.py"
    click TSFeat "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/timeseries/feature_importance.py"
    click PredConf "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/prediction/confusion.py"
    click ExpUtils "https://github.com/salesforce/omnixai/blob/main/omnixai/explanations/utils.py"
    click DashApp "https://github.com/salesforce/omnixai/blob/main/omnixai/visualization/dashboard.py"
    click Layout "https://github.com/salesforce/omnixai/blob/main/omnixai/visualization/layout.py"
    click Plot "https://github.com/salesforce/omnixai/blob/main/omnixai/visualization/plot.py"
    click State "https://github.com/salesforce/omnixai/blob/main/omnixai/visualization/state.py"
    click Assets "https://github.com/salesforce/omnixai/tree/main/omnixai/visualization/assets/"
    click Callbacks "https://github.com/salesforce/omnixai/tree/main/omnixai/visualization/callbacks/"
    click Pages "https://github.com/salesforce/omnixai/tree/main/omnixai/visualization/pages/"
    click BentoService "https://github.com/salesforce/omnixai/blob/main/omnixai/deployment/bentoml/omnixai.py"
    click BentoStore "https://github.com/salesforce/omnixai/tree/main/BentoML Model Store"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef user fill:#FFA500,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef cloud fill:#E0FFFF,stroke:#333,stroke-width:1px
```
