gobrec 1.0.5

No project description provided

GOBRec: GPU Optimized Bandits Recommender

GOBRec is a Python library with an optimized implementation of contextual multi-armed bandits (CMABs) for recommender systems. The library features a simple API that enables the use of CMAB algorithms to generate item (arms) expectations, allowing for tasks beyond recommendations. You can also use any of the implemented CMABs inside the Recommender to efficiently generate top-K recommendations.

The main contribution of GOBRec is its efficient implementation. With the vectorized code, using only CPU, our implementation was up to 150 times faster than other libraries. Using GPU optimization, our library achieved a speed gain of 700 times. More details about these comparisons can be found in the "performance comparison" section. For more detailed information, please visit the GOBRec documentation.

Library design

The library leverages vectorized operations and optional GPU acceleration to enable efficient training and inference in large-scale settings. The library is structured around two core components: (i) the MAB algorithm and (ii) the Recommender, explained further in detail. Together, these components support incremental learning and the generation of top-K recommendations in an online setting.

• MAB Algorithm: This module is responsible for incremental model updates and executing exploration strategies. It provides optimized implementations of widely used linear CMAB methods, including LinUCB [1], LinTS [2], and LinGreedy [3]. All supported linear algorithms share a common ridge regression formulation for parameter estimation, which is encapsulated in a reusable base implementation to promote extensibility. In addition, GOBRec provides a MABAlgo interface that specifies the required methods and parameters for implementing new bandit algorithms that can be integrated into the recommendation pipeline.

• Recommender: It is responsible for efficiently ranking the item scores produced by an MAB algorithm and generating a top-K list of recommended items. It also handles the exclusion of previously consumed items from the recommendation set, ensuring that only eligible items are considered. The recommender operates independently of the underlying bandit implementation and can therefore be used with any algorithm conforming to the MABAlgo interface, facilitating the integration of new methods within the GOBRec framework.

The usage pipeline consists of feeding the recommender with context vectors, observed decisions (i.e., consumed item identifiers), and rewards (i.e., ratings or implicit feedback). These interactions are then used to update the underlying CMAB model incrementally. At inference time, new contexts are passed to the recommender, which invokes the MAB algorithm to score candidate items, filters previously consumed items, and returns a top-K recommendation list.

Installation

GOBRec is available on PyPI and can be installed by the command below:

pip install gobrec

The recommended Python version to use is 3.8.20 (but newer versions should work too). For using GPU optimization, it is important to install PyTorch with CUDA implementation. More details on installing PyTorch with CUDA can be found in the PyTorch documentation. The recommended PyTorch version to use is 2.4.1.

More installation options can be found in the documentation.

Usage

This section shows two examples of how to use GOBRec. You can also use the available Jupyter notebook to reproduce the examples and verify the generated output.

Using an MAB Algorithm individually to generate arm scores

It is possible to generate item (arm) expectations by using an MAB Algorithm alone. That way, it is possible to use these algorithms for tasks other than recommendation.

import numpy as np
# Import LinUCB as an example, it could be also LinTS or LinGreedy
from gobrec.mabs.lin_mabs import LinUCB

# A batch of contexts for training
contexts = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
# Corresponding decisions (items) taken, it can be str or int
decisions = np.array(['a', 1, 2])
# Corresponding rewards (ratings) received                     
rewards = np.array([1, 0, 1])

# Initialize the bandit. A seed is set for reproducibility and GPU usage can be switched
bandit = LinUCB(seed=42, use_gpu=True)

# Fit the model with the training data
bandit.fit(contexts, decisions, rewards)

# Predict scores for each arm (item) given a batch of contexts
bandit.predict(np.array([[1, 1, 0], [0, 1, 1]]))

Using an MAB Algorithm to generate recommendations

It is possible to use an MAB Algorithm with the Recommender class to efficiently generate top-K recommendations.

import numpy as np
import gobrec
# Import LinUCB as an example, it could be also LinTS or LinGreedy
from gobrec.mabs.lin_mabs import LinUCB

# A batch of contexts for training.
contexts = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]])
# Corresponding decisions (items) taken, it can be str or int
decisions = np.array(['a', 1, 2])
# Corresponding rewards (ratings) received
rewards = np.array([1, 0, 1])

recommender = gobrec.Recommender(
    # The recommender can use any implementation following the MABAlgo interface
    mab_algo=LinUCB(seed=42, use_gpu=True),
    # Number of items to recommend
    top_k=2
)

# Fit the model with the training data
recommender.fit(contexts, decisions, rewards)

# Recommend top_k items given a batch of contexts
recommender.recommend(np.array([[1, 1, 0], [0, 1, 1]]))

Performance comparison

To evaluate the computational efficiency of GOBRec, we compared its execution time against Mab2Rec and iRec recommendation libraries on three MovieLens datasets of increasing scale.

Experiments were conducted in an incremental offline setting. The first 50% of interactions were used to warm up the models, while the remaining data were divided into ten equally sized windows. In each window, recommendations were generated, and the underlying models were incrementally updated using the observed decisions. Each experiment was repeated five times, with the average elapsed execution time and the speed-up achieved by GOBRec reported in the Table bellow.

		LinGreedy			LinUCB			LinTS
			Mab2Rec	iRec		Mab2Rec	iRec		Mab2Rec	iRec
GOBRec	MovieLens-100k
		Time	0.8	0.5	Time	1.1	0.9	Time	1.9	1.4
	CPU	0.01	106.7×	66.7×	0.07	15.6×	13.5×	0.07	29.0×	21.4×
	GPU	0.00	192.1×	120.6×	0.01	102.5×	88.5×	0.00	379.1×	279.3×
	MovieLens-1M
		Time	18.0	15.7	Time	23.9	19.2	Time	41.4	33.5
	CPU	0.11	168.6×	147.1×	1.32	18.0×	14.5×	1.26	32.8×	26.5×
	GPU	0.06	322.4×	281.2×	0.20	117.4×	94.3×	0.07	576.6×	466.6×
	MovieLens-10M
		Time	406.5	332.6	Time	526.1	441.4	Time	941.3	780.8
	CPU	2.05	198.1×	162.1×	28.21	18.7×	15.7×	27.70	34.0×	28.2×
	GPU	0.85	476.3×	389.7×	4.13	127.4×	106.9×	1.21	778.9×	646.1×

The results highlight the computational efficiency of GOBRec, particularly for the LinGreedy and LinTS models, for which the GPU-enabled implementation achieves speed-ups of more than 400× and 700×, respectively, compared to Mab2Rec. Similar trends are observed in comparisons with iRec, where GOBRec consistently outperforms the baseline library across all evaluated CMAB models and datasets.

Scalability analysis reveals that GOBRec maintains near-linear time complexity relative to interaction volume; a 100× increase in data resulted in only a 121× increase in execution time for LinTS. In contrast, baselines exhibited super-linear growth (up to 558×), demonstrating GOBRec’s suitability for production-scale interaction matrices. Results show that even in scenarios with limited GPU availability, the optimized CPU implementation of GOBRec can substantially outperform competing libraries, achieving speed-ups of more than 100× for the LinGreedy model in all MovieLens datasets.

The conducted experiments can be reproduced using the code available in the experiments folder of this repository.

Available algorithms

Available linear CMABs:

• Lin (only exploitation)
• LinUCB [1]
• LinTS [2]
• LinGreedy [3]

Available baselines:

• Random

Contributing

Details on how to contribute to the GOBRec development can be viewed in the contributing documentation.

License

GOBRec is licensed under the MIT License.

References

[1] Lihong Li, Wei Chu, John Langford, and Robert E. Schapire. A contextual-bandit approach to personalized news article recommendation. In Proceedings of the 19th International Conference on World Wide Web, WWW'09, pages 661-670, New York, NY, USA, 2010. Association for Computing Machinery. doi: 10.1145/1772690.1772758.

[2] Shipra Agrawal and Navin Goyal. Thompson sampling for contextual bandits with linear payoffs. In Proceedings of the 30th International Conference on Machine Learning, ICML'13, pages 1220-1228, New York, NY, USA, 2013. JMLR.org. doi: 10.48550/arXiv.1209.3352.

[3] John Langford and Tong Zhang. The epoch-greedy algorithm for contextual multi-armed bandits. In Proceedings of the 20th International Conference on Neural Information Processing Systems, NIPS'07, pages 817-824, Red Hook, NY, USA, 2007. Curran Associates Inc. doi: 10.5555/2981562.2981665.