# fidelity/mabwiser architecture

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

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

## Overview

##### Project Type & Purpose
- MABWiser is a Python library intended for rapidly prototyping multi-armed bandit algorithms. It is used in contexts such as recommender systems and combinatorial optimization.
- The library implements a number of learning policies (e.g., UCB1, Thompson Sampling, Epsilon Greedy, etc.) as well as neighborhood policies (e.g., Clusters, LSH Nearest) with built-in parallelization support for both training and testing.
- Its scikit-learn style interface makes it seamless to integrate into other projects like Mab2Rec (for recommender systems) or Adaptive Large-Neighborhood Search (ALNS) for optimization problems.

##### Analyzing the File Structure
- Key Directories:
- The "mabwiser" directory holds the core library code including modules such as base_mab.py, greedy.py, linear.py, mab.py, simulator.py, ucb.py, and additional algorithm implementations.
- The "tests" directory contains unit tests that check various algorithm implementations and integration points.
- The "docs" and "docsrc" directories include Sphinx documentation with source texts, static assets, and build configuration files, which help define the external API and usage examples.
- The "examples" directory offers real-world usage examples (e.g., context-free, contextual, parallel, parametric bandit examples) that illustrate how to interact with the library and its simulation utilities.
- Other files like setup.py, requirements.txt, and CI/CD YAML workflows show that the project is packaged, continuously integrated, and expected to follow modern Python packaging standards.

##### Key Components
a. Core Components:
- Library Core (mabwiser module): This is the heart of the system. Show a central block labeled “MABWiser Core” that encapsulates various submodules:
- Base classes (e.g., Base MAB, utilities)
- Multiple Learning Policies (e.g., UCB1, Thompson Sampling, Epsilon Greedy, LinTS, etc.)
- Neighborhood Policies (e.g., Clusters, K-Nearest, LSH Nearest)
- Simulator/Training & Prediction Interfaces – the components that handle fitting on data and decision-making.

b. Supporting Components:
- Testing Suite: A block representing "Tests" that interacts with the MABWiser Core to ensure correctness of algorithms.
- CI/CD Pipeline: Denote a “CI/CD” block (with .github workflows) that automatically runs tests and integration processes, ensuring stable builds.
- External Integrations: Optionally include integrations with dependent systems like scikit-learn (for the interface) and external packages used for parallelization.

##### Relationships and Data Flow
- Internecine interactions within the core:
- How the main MAB class delegates to the specific learning or neighborhood policy modules.
- How the Simulator interacts with the core to run parallelized training and testing.
- A feedback loop where simulations or predictions might inform hyperparameter tuning or further algorithm selection.

##### Architectural Patterns and Design Principles
- The project follows a modular design where each learning and neighborhood policy is implemented as a separate module. Emphasize the plug-and-play nature of algorithm components (fostering extensibility and ease of adding new policies).
- It adopts a “scikit-learn style” API, so the design is influenced by standardized model–fit/predict patterns.

##### Final Details
- Avoid over-complicating by focusing only on key relationships. Emphasize the separation of concerns—the interface, core functionality (with policy modules), simulation utilities, and integration components.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        E1["Examples & Simulation Utility"]:::client
        SE["Simulator (Example)"]:::simulator
    end

    %% Core Layer
    subgraph "Core Layer"
        C["MABWiser Core"]:::core
        subgraph "Learning Policies"
            G1["Greedy"]:::policies
            G2["Thompson Sampling"]:::policies
            G3["UCB1"]:::policies
            G4["Softmax"]:::policies
            G5["Linear"]:::policies
            G6["Random"]:::policies
        end
        subgraph "Neighborhood Policies"
            N1["Clusters"]:::policies
            N2["Neighbors"]:::policies
        end
        SC["Simulator (Core)"]:::simulator
    end

    %% Support Layer
    subgraph "Support Layer"
        T["Testing Suite"]:::tests
        D["Documentation"]:::docs
        CI["CI/CD Pipeline"]:::cicd
    end

    %% External Integration
    EI["External Integrations"]:::integration

    %% Relationships
    E1 -->|"calls"| C
    SE -->|"calls"| C
    C -->|"delegatesTo"| G1
    C -->|"delegatesTo"| G2
    C -->|"delegatesTo"| G3
    C -->|"delegatesTo"| G4
    C -->|"delegatesTo"| G5
    C -->|"delegatesTo"| G6
    C -->|"delegatesTo"| N1
    C -->|"delegatesTo"| N2
    C -->|"exposes"| SC
    EI -->|"integrates"| C
    T -->|"validates"| C
    CI -->|"runsTests"| T
    C -->|"docs"| D
    E1 -->|"docs"| D

    %% Click Events
    click C "https://github.com/fidelity/mabwiser/tree/master/mabwiser/"
    click G1 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/greedy.py"
    click G2 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/thompson.py"
    click G3 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/ucb.py"
    click G4 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/softmax.py"
    click G5 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/linear.py"
    click G6 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/rand.py"
    click N1 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/clusters.py"
    click N2 "https://github.com/fidelity/mabwiser/blob/master/mabwiser/neighbors.py"
    click SC "https://github.com/fidelity/mabwiser/blob/master/mabwiser/simulator.py"
    click SE "https://github.com/fidelity/mabwiser/blob/master/examples/simulator.py"
    click E1 "https://github.com/fidelity/mabwiser/tree/master/examples/"
    click T "https://github.com/fidelity/mabwiser/tree/master/tests/"
    click D "https://github.com/fidelity/mabwiser/tree/master/docs/"
    click CI "https://github.com/fidelity/mabwiser/tree/master/.github/workflows/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef policies fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef simulator fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef client fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef tests fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef docs fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef cicd fill:#F0B27A,stroke:#D35400,stroke-width:2px;
    classDef integration fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
