# ibm/infairness architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/infairness
- Repository: https://github.com/ibm/infairness

## Overview

##### Main Components
- Core Library (inFairness Package): Divide it into its major submodules:
- Auditor Module: Contains the implementations for “auditing”, e.g., modules like auditor.py, sensei_auditor.py, sensr_auditor.py, senstir_auditor.py. This component is responsible for evaluating whether a given ML model meets individual fairness criteria.
- Distances Module: Implements various distance metrics (files like euclidean_dists.py, mahalanobis_distance.py, sensitive_subspace_dist.py, logistic_sensitive_subspace.py, wasserstein_distance.py). This module measures similarity between inputs and outputs.
- Fair Algorithms Module (fairalgo): Holds the fair learning algorithms (such as SenSeI in SenSeI.py) which are used to train models under fairness constraints.
- Postprocessing Module: Contains the post‑processing methods to adjust the outcomes of models for fairness purposes.
- Utility Module: Provides helper functions and utilities (datautils, ndcg, plackett_luce, etc.) that support data handling, metrics calculation, and parameter validation.

##### External Components
- ML Model and Data Pipeline: Highlight that the package is typically used alongside a PyTorch model and data loaders. Illustrate how training workflows incorporate distance metric fitting and fairness training.
- Examples and Tutorials: Indicate the presence of the “examples” directory where various demos (e.g., sentiment analysis, synthetic data generation, adult income prediction) show typical usage patterns.
- Testing and CI Pipeline: Mention the tests directory for unit testing and configuration files such as .travis.yml that indicate continuous integration processes.

##### Relationships and Data Flow
- Data is processed by the Distances Module to compute dₓ and dᵧ.
- The computed distances and input data are passed to the Fair Algorithms module (for instance, using algorithms like SenSeI) which enforces fairness during training.
- The Auditor module can then evaluate the fairness of the trained model by comparing predictions and input similarities.
- If necessary, the Postprocessing module further adjusts model outputs.
- The Utility module serves throughout these processes to support computations and validations.

##### Architectural Patterns and Design Principles
- Modularity: Each subcomponent (auditor, distances, fairalgo, postprocessing) is encapsulated and independently testable.
- Separation of Concerns: Fairness auditing, fair learning, and metric computations are separated into their own modules.
- Extensibility: The clear interfaces between modules (e.g., datainterface in both auditor and postprocessing) promote integration and additional feature development.
- Testability: Presence of the tests directory ensures that each component is validated independently.

a. Auditor Module (with subnodes for each auditor type)
b. Distances Module (with subnodes for different distance computations)
c. Fair Algorithms Module (depicting SenSeI)
d. Postprocessing Module
e. Utilities Module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    MLModel["ML Model & Data Pipeline"]:::external
    Examples["Examples & Tutorials"]:::external
    Testing["Testing & CI Pipeline"]:::test

    %% inFairness Package Subgraphs
    subgraph "inFairness Package"
        %% Auditor Module
        subgraph "Auditor Module"
            A1["auditor.py"]
            A2["sensei_auditor.py"]
            A3["sensr_auditor.py"]
            A4["senstir_auditor.py"]
            A5["datainterface.py"]
        end

        %% Distances Module
        subgraph "Distances Module"
            D1["euclidean_dists.py"]
            D2["mahalanobis_distance.py"]
            D3["sensitive_subspace_dist.py"]
            D4["logistic_sensitive_subspace.py"]
            D5["wasserstein_distance.py"]
            D6["distance.py"]
            D7["explore_distance.py"]
        end

        %% Fair Algorithms Module
        subgraph "Fair Algorithms Module"
            F1["sensei.py"]
            F2["sensr.py"]
            F3["senstir.py"]
            F4["datainterfaces.py"]
        end

        %% Postprocessing Module
        subgraph "Postprocessing Module"
            P1["base_postprocessing.py"]
            P2["data_ds.py"]
            P3["datainterfaces.py"]
            P4["distance_ds.py"]
            P5["glif.py"]
            P6["utils/postprocessing.py"]
        end

        %% Utility Module
        subgraph "Utility Module"
            U1["datautils.py"]
            U2["ndcg.py"]
            U3["plackett_luce.py"]
            U4["misc.py"]
            U5["params.py"]
            U6["postprocessing.py"]
            U7["validationutils.py"]
        end
    end

    %% Data Flow Connections
    MLModel -->|"computeDistances"| D1
    D1 -->|"applyFairAlgo"| F1
    F1 -->|"auditFairness"| A1
    A1 -->|"postProcess"| P1

    %% Utility Module supporting connections (dashed arrows)
    U1 ---|"support"| D1
    U1 ---|"support"| F1
    U1 ---|"support"| A1
    U1 ---|"support"| P1

    %% Additional External Connections
    P1 -->|"validatedByTests"| Testing
    Testing -->|"demoUsage"| Examples

    %% Click Events
    click A1 "https://github.com/ibm/infairness/tree/main/inFairness/auditor/"
    click D1 "https://github.com/ibm/infairness/tree/main/inFairness/distances/"
    click F1 "https://github.com/ibm/infairness/tree/main/inFairness/fairalgo/"
    click P1 "https://github.com/ibm/infairness/tree/main/inFairness/postprocessing/"
    click U1 "https://github.com/ibm/infairness/tree/main/inFairness/utils/"
    click Examples "https://github.com/ibm/infairness/tree/main/examples/"
    click Testing "https://github.com/ibm/infairness/tree/main/tests/"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:2px
    classDef external fill:#90ee90,stroke:#000,stroke-width:2px
    classDef test fill:#ffcccb,stroke:#000,stroke-width:2px
    classDef support fill:#f9d6a5,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5

    %% Assign classes to core module nodes (using representative nodes)
    class A1,D1,F1,P1,U1 core
    class MLModel,Examples external
    class Testing test
```
