How fidelity/mab2rec works
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.