# fidelity/mab2rec architecture

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

- Interactive diagram: https://gitdiagram.com/fidelity/mab2rec
- Repository: https://github.com/fidelity/mab2rec

## Overview

The Mab2Rec project is a Python library designed to build multi-armed bandit recommendation algorithms. Its purpose, as described in both the README and the file structure, is to provide a flexible framework for rapid experimentation with bandit-based methods in recommender systems. It supports various bandit models (context-free, parametric, and non-parametric contextual) and integrates with other in-house tools such as MABWiser, TextWiser, Selective, Seq2Pat, and Jurity for model building and evaluation.

##### Components Identification
- Core Library Module:
- The primary logic is implemented in the “mab2rec” directory, which contains modules like pipeline.py (orchestrating training and scoring), rec.py (for recommendations), utils.py, visualization.py, and an __init__.py.
- The BanditRecommender class and LearningPolicy configurations represent the central abstraction for the recommendation algorithms.
- Data Layer:
- The “data” directory holds training and testing data (CSV files including features for users and items) which are the input to the training pipeline.
- The “data/extended” subdirectory contains additional datasets and metadata such as eligibility data and JSON files specifying data types.
- Preprocessing and Scripting:
- The “scripts” directory provides shell scripts to preprocess data; these help clean, merge, and prepare datasets before they feed into the system.
- Notable scripts include those for concatenating files, inserting headers, or sorting data.
- Experimentation and Prototyping:
- The “notebooks” directory contains Jupyter notebooks that act as tutorials/demos. They illustrate how to train a single recommender and how to benchmark multiple recommenders.
- Testing & CI:
- The “tests” directory contains unit and integration tests ensuring the correctness of the implementation.
- GitHub Actions workflows (in .github/workflows) provide CI/CD processes confirming code quality.
- Documentation:
- The “docs” and “docsrc” directories house the documentation source and built HTML pages, making it easy to understand the system’s components and usage.
- External Dependencies:

##### Relationships and Data/Control Flow
- Core Algorithm Components: Illustrate components such as BanditRecommender (with further branching for different LearningPolicy strategies) and how they interact with functions in rec.py for recommendation generation.
- Evaluation and Benchmarking: Outline connections from the pipeline to evaluation modules (i.e., integration with Jurity) when benchmarking multiple recommenders. Represent how performance metrics (e.g., CTR, NDCG) are computed using external evaluators.

##### Architectural Patterns and Design Principles
- Data Ingestion & Preprocessing (data and scripts)
- Core Recommendation Engine (mab2rec modules)
- API/Pipeline Layer (functions such as train, score, benchmark)
- Evaluation & Reporting (integration with Jurity and visualizations)
- Separation of Concerns: Each module (data processing, algorithm, evaluation) is distinct, making it easier to swap components or update functionalities.
- Extensibility: Mark the entry points for plugging in new bandit algorithms and evaluation metrics, highlighting the flexibility of the pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing Layer
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        subgraph "Data Layer"
            direction TB
            DT("Train Data (CSV)"):::data
            DS("Test Data (CSV)"):::data
            DF("Features Data (CSV)"):::data
            DE("Extended Data (JSON/CSV)"):::data
        end
        PS("Preprocessing Scripts"):::preproc
    end

    %% Core Recommendation Engine
    subgraph "Core Recommendation Engine"
        direction TB
        PL("Pipeline Module"):::core
        REC("Recommendation Module"):::core
        UT("Utilities Module"):::core
        VIS("Visualization Module"):::core
        INIT("Init Module"):::core
    end

    %% Evaluation & External Libraries
    subgraph "Evaluation & External Libraries"
        direction TB
        EXM("MABWiser"):::external
        EXJ("Jurity"):::external
        EXT("TextWiser"):::external
        EXS("Selective"):::external
        EXP("Seq2Pat"):::external
    end

    %% Supporting Components (Experimentation, Testing, Documentation)
    subgraph "Supporting Components"
        direction TB
        NB("Experimentation Notebooks"):::support
        TST("Tests Suite"):::support
        CI("CI Workflows"):::support
        DOC("Documentation"):::support
        DOCSRC("DocSrc"):::support
    end

    %% Data flow connections
    DT -->|"CSV_Data"| PS
    DS -->|"CSV_Data"| PS
    DF -->|"CSV_Data"| PS
    DE -->|"Additional_Metadata"| PS

    PS -->|"Processed_Data"| PL

    %% Core interactions
    PL -->|"Triggers_Training"| REC
    PL -->|"Calls_Utilities"| UT
    PL -->|"Generates_Visuals"| VIS
    REC -->|"Implements_BanditRecommender"| PL

    %% External library integrations
    PL -->|"Evaluates_with"| EXJ
    REC -->|"Integrates_with"| EXM
    REC -->|"Extracts_Features_using"| EXT
    REC -->|"Selects_Actions_via"| EXS
    REC -->|"Sequential_Patterns_by"| EXP

    %% Supporting components connections
    NB -->|"Demonstrates_Usage"| PL
    TST -->|"Validates_Pipeline"| PL
    TST -->|"Validates_Recommendation"| REC
    CI -->|"Automates_Testing"| TST
    DOC -->|"Documents_System"| PL
    DOCSRC -->|"Source_for_Docs"| DOC

    %% Click Events for Component Mapping
    click DT "https://github.com/fidelity/mab2rec/blob/main/data/data_train.csv"
    click DS "https://github.com/fidelity/mab2rec/blob/main/data/data_test.csv"
    click DF "https://github.com/fidelity/mab2rec/blob/main/data/features_item.csv"
    click DE "https://github.com/fidelity/mab2rec/blob/main/data/extended/data_eligibility.csv"
    click PS "https://github.com/fidelity/mab2rec/tree/main/scripts/data_prep/"
    click PL "https://github.com/fidelity/mab2rec/blob/main/mab2rec/pipeline.py"
    click REC "https://github.com/fidelity/mab2rec/blob/main/mab2rec/rec.py"
    click UT "https://github.com/fidelity/mab2rec/blob/main/mab2rec/utils.py"
    click VIS "https://github.com/fidelity/mab2rec/blob/main/mab2rec/visualization.py"
    click INIT "https://github.com/fidelity/mab2rec/blob/main/mab2rec/__init__.py"
    click NB "https://github.com/fidelity/mab2rec/tree/main/notebooks/"
    click TST "https://github.com/fidelity/mab2rec/tree/main/tests/"
    click CI "https://github.com/fidelity/mab2rec/blob/main/.github/workflows/ci.yml"
    click DOC "https://github.com/fidelity/mab2rec/tree/main/docs/"
    click DOCSRC "https://github.com/fidelity/mab2rec/tree/main/docsrc/"

    %% Styles for different layers
    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef preproc fill:#FAD7A0,stroke:#7D6608,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef support fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
```
