# holistic-ai/holisticai architecture

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

- Interactive diagram: https://gitdiagram.com/holistic-ai/holisticai
- Repository: https://github.com/holistic-ai/holisticai

## Overview

##### Project Type and Purpose
- This is not a typical full-stack web application but rather a Python library (with bundles for bias, explainability, etc.) that is used as a toolkit by data scientists and ML engineers.
- The README emphasizes that the library is dedicated to measuring key attributes like bias, fairness, and security and includes both metric computation and mitigation strategies. The library also provides visualizations and tutorials for users.
- The extensive file tree (with src, docs, tutorials, tests, configuration, and CI/CD workflows) indicates a mature open-source project with a strong emphasis on modularity, testing, and ease-of-use/documentation.

##### Interpretation of the File Structure
- Top-Level Directories:
- docs: Contains documentation sources, assets, and build files for generating project documentation.
- src: Holds the main library code under the “holisticai” package. This includes submodules for “bias,” “explainability,” “robustness,” “security,” “efficacy,” and others.
- tests: Contains unit tests that mirror most of the high-level functionalities provided by the library.
- tutorials: Provides example notebooks and demonstration scripts that show how to use the library.
- .github (and various CI/CD workflow files): Show that continuous integration and automated releases are in place.
- Within the src/holisticai folder, note the further breakdown into many submodules. For instance:
- The “bias” module splits into metrics, mitigation (including inprocessing, postprocessing, and preprocessing), and plotting.
- Other modules like “explainability,” “datasets,” “robustness,” “security,” and “pipeline” likewise have their own dedicated subdirectories and helper utilities.
- The division of modules and the naming conventions suggest a plug-and-play, composable system design where different functionalities are clearly isolated.

##### Key Components
a. Core Library Modules:
- API Entry Point (holisticai/__init__.py) which provides the public interface.
- Bias: Further divided into metrics (e.g., classification, clustering, multiclass, recommender, regression), mitigation strategies (inprocessing, preprocessing, postprocessing), and plotting.
- Explainability: Metrics and visualization components.
- Robustness: Includes modules for attackers, metrics, and plotting.
- Security: Contains modules for metrics, common utilities (e.g., data minimization, anonymization), and mitigation approaches.
- Efficacy: Provides performance metrics for evaluating AI models.
- Datasets: Functions for loading and processing datasets.
- Pipeline and Inspection: Modules for orchestrating model training, transformation, and explanatory analysis.
- Utils: Support modules for optimization, plotting, surrogate models, etc.

b. External Interfaces and Dependencies:
- Integration with popular ML frameworks (e.g., scikit-learn as seen in the quick-start example).
- Dependencies such as plotting libraries, datasets utilities, and even external libraries for mathematical optimization.
- CI/CD workflows (.github/workflows directory) that automate testing, release, and documentation (e.g., ReadTheDocs build from .readthedocs.yaml).

c. Relationships and Interactions:
- Public functions from the API layer call into the core modules, such as metric computation and bias mitigation algorithms.
- Visualization components in the “plots” submodules rely on underlying metrics and data from the respective modules.
- The testing suite in the tests folder should be drawn as interacting with each of these components to ensure correctness.
- Tutorials and documentation components (in docs and tutorials) illustrate usage scenarios and hence interact with the core library modules.

##### Architectural Patterns and Design Principles
- Modularity: The decomposition into submodules (bias, explainability, robustness, etc.) indicates a design where functionality is segregated. This might be driven by “separation of concerns.”
- Plug-and-Play: Each mitigation and metric module appears as independent plugins that can potentially be composed or replaced.
- Consistent Namespace: All components are housed under the “holisticai” package, enabling clear import paths and integration.
- Documentation-Driven: Extensive documentation and tutorials are provided, pointing to a design where learnability and transparency are prioritized.

##### Graphical Representations
▸ API (holisticai/__init__.py)
▸ Bias Module:
– Metrics (classification, clustering, multiclass, etc.)
– Mitigation (inprocessing, preprocessing, postprocessing along with commons and helper components)
– Plots
▸ Explainability Module (metrics, plots, surrogate, tree, etc.)
▸ Robustness Module (attackers, metrics, plots)
▸ Security Module (metrics, mitigation, commons)
▸ Efficacy Module (metrics and evaluation)
▸ Datasets, Pipeline, Utils, and Inspection Modules.
- Auxiliary components:
▸ Tutorials and Docs demonstrating use cases.
▸ Testing framework as an overlay ensuring code quality.
▸ CI/CD pipelines (GitHub workflows) for deployment.
- From the API entry point to core modules.
- From the core modules to visualization (plots) and utility helpers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public Interface
    subgraph "Public Interface"
        API["API Entry Point"]:::interface
        Docs["Documentation"]:::interface
        Tutorials["Tutorials"]:::interface
    end

    %% Core Library
    subgraph "Core Library"
        %% Bias Module
        subgraph "Bias Module"
            biasMetrics["Bias - Metrics"]:::core
            biasMitInproc["Bias - Mitigation - Inprocessing"]:::core
            biasMitPreproc["Bias - Mitigation - Preprocessing"]:::core
            biasMitPostproc["Bias - Mitigation - Postprocessing"]:::core
            biasPlots["Bias - Plots"]:::core
        end

        %% Explainability Module
        subgraph "Explainability Module"
            explMetrics["Explainability - Metrics"]:::core
            explSurrogate["Explainability - Surrogate"]:::core
            explPlots["Explainability - Plots"]:::core
        end

        %% Robustness Module
        subgraph "Robustness Module"
            robustAttack["Robustness - Attackers"]:::core
            robustMetrics["Robustness - Metrics"]:::core
            robustPlots["Robustness - Plots"]:::core
        end

        %% Security Module
        subgraph "Security Module"
            secMetrics["Security - Metrics"]:::core
            secMitig["Security - Mitigation"]:::core
            secCommons["Security - Commons"]:::core
        end

        efficacy["Efficacy - Metrics"]:::core
        datasets["Datasets"]:::core
        pipeline["Pipeline"]:::core
        inspection["Inspection"]:::core
        utils["Utils"]:::core
    end

    %% Support & Integration
    subgraph "Support & Integration"
        tests["Tests"]:::support
        cicd["CI/CD Workflows"]:::support
        extLib["External Libraries (scikit-learn)"]:::support
    end

    %% Connections from Public Interface to Core Library
    API -->|"calls"| biasMetrics
    API -->|"calls"| explMetrics
    API -->|"calls"| robustAttack
    API -->|"calls"| secMetrics
    API -->|"calls"| efficacy
    API -->|"calls"| datasets
    API -->|"calls"| pipeline
    API -->|"calls"| inspection
    API -->|"calls"| utils

    %% Internal connections within Bias Module
    biasMetrics -->|"dataFeeds"| biasPlots
    biasMetrics -->|"triggers"| biasMitInproc
    biasMetrics -->|"triggers"| biasMitPreproc
    biasMetrics -->|"triggers"| biasMitPostproc

    %% Internal connections within Explainability Module
    explMetrics -->|"informs"| explPlots
    explMetrics -->|"supports"| explSurrogate

    %% Internal connections within Robustness Module
    robustMetrics -->|"informs"| robustPlots

    %% Internal connections within Security Module
    secMetrics -->|"triggers"| secMitig
    secMetrics -->|"triggers"| secCommons

    %% Data flow from Datasets to Pipeline to Inspection
    datasets -->|"feeds"| pipeline
    pipeline -->|"orchestrates"| inspection

    %% Utils support for Pipeline
    utils -->|"assists"| pipeline

    %% Support & Integration interactions
    tests -->|"verifies"| API
    cicd -->|"automates"| tests
    extLib -->|"integrates"| API
    Tutorials -->|"demonstrates"| API
    Docs -->|"explains"| API

    %% Class Definitions for styling
    classDef interface fill:#AEDFF7,stroke:#1A91DA,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef support fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;

    %% Click Events
    click API "https://github.com/holistic-ai/holisticai/blob/main/src/holisticai/__init__.py"
    click biasMetrics "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/bias/metrics"
    click biasMitInproc "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/bias/mitigation/inprocessing"
    click biasMitPreproc "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/bias/mitigation/preprocessing"
    click biasMitPostproc "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/bias/mitigation/postprocessing"
    click biasPlots "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/bias/plots"
    click explMetrics "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/explainability/metrics"
    click explSurrogate "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/explainability/metrics/surrogate"
    click explPlots "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/explainability/plots"
    click robustAttack "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/robustness/attackers"
    click robustMetrics "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/robustness/metrics"
    click robustPlots "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/robustness/plots"
    click secMetrics "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/security/metrics"
    click secMitig "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/security/mitigation"
    click secCommons "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/security/commons"
    click efficacy "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/efficacy/metrics"
    click datasets "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/datasets"
    click pipeline "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/pipeline"
    click inspection "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/inspection"
    click utils "https://github.com/holistic-ai/holisticai/tree/main/src/holisticai/utils"
    click cicd "https://github.com/holistic-ai/holisticai/tree/main/.github/workflows"
    click Tutorials "https://github.com/holistic-ai/holisticai/tree/main/tutorials"
    click Docs "https://github.com/holistic-ai/holisticai/tree/main/docs"
```
