{"id":13818868,"url":"https://github.com/fidelity/mab2rec","last_synced_at":"2026-03-09T22:30:45.665Z","repository":{"id":37718678,"uuid":"457517502","full_name":"fidelity/mab2rec","owner":"fidelity","description":"[AAAI 2024] Mab2Rec: Multi-Armed Bandits Recommender","archived":false,"fork":false,"pushed_at":"2024-10-11T17:16:11.000Z","size":3683,"stargazers_count":149,"open_issues_count":0,"forks_count":27,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-08-25T14:15:19.427Z","etag":null,"topics":["multi-armed-bandits","recommendation","recsys"],"latest_commit_sha":null,"homepage":"https://fidelity.github.io/mab2rec/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fidelity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-09T20:27:34.000Z","updated_at":"2025-08-22T21:48:00.000Z","dependencies_parsed_at":"2024-02-05T22:46:48.355Z","dependency_job_id":"9c89a313-1041-477d-9bb8-32395ddf6aec","html_url":"https://github.com/fidelity/mab2rec","commit_stats":{"total_commits":62,"total_committers":7,"mean_commits":8.857142857142858,"dds":0.4838709677419355,"last_synced_commit":"be3953a6da35c1d38f0283ca20f0325d41059578"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/fidelity/mab2rec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fmab2rec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fmab2rec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fmab2rec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fmab2rec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fidelity","download_url":"https://codeload.github.com/fidelity/mab2rec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fmab2rec/sbom","scorecard":{"id":399019,"data":{"date":"2025-08-11","repo":{"name":"github.com/fidelity/mab2rec","commit":"1cd7ebfd5fa72ed946cb1642c9d9a47d85676fb3"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":9,"reason":"Found 20/22 approved changesets -- score normalized to 9","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/fidelity/mab2rec/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/fidelity/mab2rec/ci.yml/main?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:31","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:32","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact 1.2.1 not signed: https://api.github.com/repos/fidelity/mab2rec/releases/140098354","Warn: release artifact 1.2.1 does not have provenance: https://api.github.com/repos/fidelity/mab2rec/releases/140098354"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/fidelity/.github/SECURITY.md:1","Info: Found linked content: github.com/fidelity/.github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/fidelity/.github/SECURITY.md:1","Info: Found text in security policy: github.com/fidelity/.github/SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":3,"reason":"7 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-6p56-wp2h-9hxr","Warn: Project is vulnerable to: GHSA-fpfv-jqm9-f5jm","Warn: Project is vulnerable to: PYSEC-2024-110 / GHSA-jw8x-6495-233v","Warn: Project is vulnerable to: GHSA-jxfp-4rvq-9h9m","Warn: Project is vulnerable to: PYSEC-2019-156 / GHSA-xp76-357g-9wqq","Warn: Project is vulnerable to: PYSEC-2023-102","Warn: Project is vulnerable to: PYSEC-2023-114"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":2,"reason":"SAST tool is not run on all commits -- score normalized to 2","details":["Warn: 7 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T19:42:01.363Z","repository_id":37718678,"created_at":"2025-08-18T19:42:01.363Z","updated_at":"2025-08-18T19:42:01.363Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30314626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["multi-armed-bandits","recommendation","recsys"],"created_at":"2024-08-04T08:00:33.349Z","updated_at":"2026-03-09T22:30:45.624Z","avatar_url":"https://github.com/fidelity.png","language":"Jupyter Notebook","funding_links":[],"categories":["Jupyter Notebook"],"sub_categories":[],"readme":"[![ci](https://github.com/fidelity/mab2rec/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fidelity/mab2rec/actions/workflows/ci.yml) [![PyPI version fury.io](https://badge.fury.io/py/mab2rec.svg)](https://pypi.python.org/pypi/mab2rec/) [![PyPI license](https://img.shields.io/pypi/l/mab2rec.svg)](https://pypi.python.org/pypi/mab2rec/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) [![Downloads](https://static.pepy.tech/personalized-badge/mab2rec?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=orange\u0026left_text=Downloads)](https://pepy.tech/project/mab2rec)\n\n# Mab2Rec: Multi-Armed Bandits Recommender \n\nMab2Rec ([AAAI'24](https://ojs.aaai.org/index.php/AAAI/article/view/30341)) is a Python library for building bandit-based recommendation algorithms. It supports **context-free**, **parametric** and **non-parametric** **contextual** bandit models powered by [MABWiser](https://github.com/fidelity/mabwiser) and fairness and recommenders evaluations powered by [Jurity](https://github.com/fidelity/jurity).\nThe library is designed with rapid experimentation in mind, follows the [PEP-8 standards](https://www.python.org/dev/peps/pep-0008/), and is tested heavily.\n\nMab2Rec is built on top of several other open-source software developed at the AI Center at Fidelity:\n\n* [MABWiser](https://github.com/fidelity/mabwiser) to create multi-armed bandit recommendation algorithms ([Bridge@AAAI'24](http://osullivan.ucc.ie/CPML2024/papers/06.pdf), [TMLR'22](https://openreview.net/pdf?id=sX9d3gfwtE), [IJAIT'21](https://www.worldscientific.com/doi/abs/10.1142/S0218213021500214), [ICTAI'19](https://ieeexplore.ieee.org/document/8995418)).\n* [TextWiser](https://github.com/fidelity/textwiser) to create item representations via text featurization ([AAAI'21](https://ojs.aaai.org/index.php/AAAI/article/view/17814)).\n* [Selective](https://github.com/fidelity/selective) to create user representations via feature selection ([AMAI'24](https://link.springer.com/article/10.1007/s10472-024-09941-x), [CPAIOR'21](https://link.springer.com/chapter/10.1007/978-3-030-78230-6_27), [DSO@IJCAI'21](https://arxiv.org/abs/2112.03105)).\n* [Seq2Pat](https://github.com/fidelity/seq2pat) to create user representations via sequential pattern mining ([AI Magazine'23](https://onlinelibrary.wiley.com/doi/epdf/10.1002/aaai.12081), [AAAI'22](https://ojs.aaai.org/index.php/AAAI/article/view/21542), [Bridge@AAAI'23](http://osullivan.ucc.ie/CPML2023/submissions/09.pdf), [Frontiers'22](https://www.frontiersin.org/articles/10.3389/frai.2022.868085/full), [KDF@AAAI'22](https://arxiv.org/abs/2201.09178), [CMU Blog Post](https://www.cmu.edu/tepper/news/stories/2023/may/fidelity-ai.html))\n* [Jurity](https://github.com/fidelity/jurity) to evaluate recommendations including fairness metrics ([ACM'24](https://dl.acm.org/doi/10.1145/3700145), [LION'23](https://link.springer.com/chapter/10.1007/978-3-031-44505-7_29), [CIKM'22](https://ceur-ws.org/Vol-3318/short6.pdf), [ICMLA'21](https://ieeexplore.ieee.org/abstract/document/9680169)).\n\nAn introduction to **content- and context-aware** recommender systems and an overview of the building blocks of the library is presented at [AAAI 2024](https://underline.io/lecture/91479-building-higher-order-abstractions-from-the-components-of-recommender-systems) and [All Things Open 2021](https://www.youtube.com/watch?v=54d_YUalvOA). There is a corresponding [blogpost](https://2022.allthingsopen.org/introducing-mab2rec-a-multi-armed-bandit-recommender-library/) to serve as a starting point for practioners to build and deploy bandit-based recommenders using Mab2Rec.\n\nDocumentation is available at [fidelity.github.io/mab2rec](https://fidelity.github.io/mab2rec).\n\n## Usage Patterns\n\nMab2Rec supports prototyping with a **single** bandit algorithm or benchmarking with **multiple** bandit algorithms. \nIf you are new user, the best place to start is to experiment with multiple bandits using the [tutorial notebooks](notebooks).\n\n## Quick Start\n\n### Single Recommender\n\n```python\n# Example of how to train an singler recommender to generate top-4 recommendations\n\n# Import \nfrom mab2rec import BanditRecommender, LearningPolicy\nfrom mab2rec.pipeline import train, score\n\n# LinGreedy recommender to select top-4 items with 10% random exploration \nrec = BanditRecommender(LearningPolicy.LinGreedy(epsilon=0.1), top_k=4)\n\n# Train on (user, item, response) interactions in train data using user features \ntrain(rec, data='data/data_train.csv', \n      user_features='data/features_user.csv')\n\n# Score recommendations for users in test data. The output df holds \n# user_id, item_id, score columns for every test user for top-k items \ndf = score(rec, data='data/data_test.csv', \n           user_features='data/features_user.csv')\n```\n\n### Multiple Recommenders\n\n```python\n# Example of how to benchmark multiple recommenders to generate top-4 recommendations\n\nfrom mab2rec import BanditRecommender, LearningPolicy\nfrom mab2rec.pipeline import benchmark\nfrom jurity.recommenders import BinaryRecoMetrics, RankingRecoMetrics\n\n# Recommenders (many more available)\nrecommenders = {\"Random\": BanditRecommender(LearningPolicy.Random()),\n                \"Popularity\": BanditRecommender(LearningPolicy.Popularity()),\n                \"LinGreedy\": BanditRecommender(LearningPolicy.LinGreedy(epsilon=0.1))}\n\n# Column names for the response, user, and item id columns\nmetric_params = {'click_column': 'score', 'user_id_column': 'user_id', 'item_id_column':'item_id'}\n\n# Performance metrics for benchmarking (many more available)\nmetrics = []\nfor top_k in [3, 5, 10]:\n    metrics.append(BinaryRecoMetrics.CTR(**metric_params, k=top_k))\n    metrics.append(RankingRecoMetrics.NDCG(**metric_params, k=top_k))\n\n# Benchmarking with a collection of recommenders and metrics \n# This returns two dictionaries; \n# reco_to_results: recommendations for each algorithm on cross-validation data\n# reco_to_metrics: evaluation metrics for each algorithm\nreco_to_results, reco_to_metrics = benchmark(recommenders,\n                                             metrics=metrics,\n                                             train_data=\"data/data_train.csv\",\n                                             cv=5,\n                                             user_features=\"data/features_user.csv\")\n```\n\n## Usage Examples\n\nWe provide extensive tutorials in the [notebooks](notebooks) folder with guidelines on building recommenders, performing model selection, and evaluating performance.\n\n1. [Data Overview:](https://github.com/fidelity/mab2rec/tree/master/notebooks/1_data_overview.ipynb) Overview of data required to train recommender.\n2. [Feature Engineering:](https://github.com/fidelity/mab2rec/tree/master/notebooks/2_feature_engineering.ipynb) Creating user and item features from structured, unstructured, and sequential data.\n3. [Model Selection:](https://github.com/fidelity/mab2rec/tree/master/notebooks/3_model_selection.ipynb) Model selection by benchmarking recommenders using cross-validation.\n4. [Evaluation:](https://github.com/fidelity/mab2rec/tree/master/notebooks/4_evaluation.ipynb) Benchmarking of selected recommenders and baselines on test data with detailed evaluation.\n5. [Advanced:](https://github.com/fidelity/mab2rec/tree/master/notebooks/5_advanced.ipynb) Demonstration of advanced functionality such as persistency, eligibility, item availability, and memory efficiency.\n\n## Installation\n\nMab2Rec requires **Python 3.8+** and can be installed from PyPI using ``pip install mab2rec`` or by building from source as shown in [installation instructions](https://fidelity.github.io/mab2rec/installation.html).\n\n## Citation\n\nIf you use Mab2Rec in a publication, please cite it as:\n\n```bibtex\n    @inproceedings{DBLP:conf/aaai/KadiogluK24,\n      author       = {Serdar Kadioglu and Bernard Kleynhans},\n      title        = {Building Higher-Order Abstractions from the Components of Recommender Systems},\n      booktitle    = {Thirty-Eighth {AAAI} Conference on Artificial Intelligence, {AAAI} 2024, Thirty-Sixth Conference on Innovative Applications of Artificial Intelligence, {IAAI} 2024, Fourteenth Symposium on Educational Advances in Artificial Intelligence, {EAAI} 2014, February 20-27, 2024, Vancouver, Canada},\n      pages        = {22998--23004},\n      publisher    = {{AAAI} Press},\n      year         = {2024},\n      url          = {https://doi.org/10.1609/aaai.v38i21.30341},\n      doi          = {10.1609/AAAI.V38I21.30341}\n    }\n```\n\n## Support\n\nPlease submit bug reports and feature requests as [Issues](https://github.com/fidelity/mab2rec/issues).\n\n## License\n\nMab2Rec is licensed under the [Apache License 2.0](LICENSE).\n\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidelity%2Fmab2rec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffidelity%2Fmab2rec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidelity%2Fmab2rec/lists"}