gobrec 0.1.0__tar.gz

gobrec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RecSys-UFSCar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gobrec-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.1
+Name: gobrec
+Version: 0.1.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# gobrec
+GOBRec: GPU Optimized Bandits Recommender

gobrec-0.1.0/README.md

@@ -0,0 +1,2 @@
+# gobrec
+GOBRec: GPU Optimized Bandits Recommender

gobrec-0.1.0/gobrec/Recommender.py

@@ -0,0 +1,29 @@
+
+from gobrec.mabs.lin_mabs.Lin import Lin
+import numpy as np
+import torch
+
+
+class Recommender:
+
+    def __init__(self, mab_algo: Lin, top_k: int):
+        self.mab_algo = mab_algo
+        self.top_k = top_k
+    
+    def fit(self, contexts: np.ndarray, items_ids: np.ndarray, rewards: np.ndarray):
+        self.mab_algo.fit(contexts, items_ids, rewards)
+    
+    def recommend(self, contexts: np.ndarray, items_ids_filter: 'list[np.ndarray, np.ndarray]' = None):
+        # ITEMS IDS FILTERS is a tuple where the first element is a list of indices (of contexts) to filter and the second element is the items_ids to filter
+
+        expectations = self.mab_algo.predict(contexts)
+
+        if items_ids_filter is not None:
+            items_ids_filter[1] = self.mab_algo.label_encoder.transform(items_ids_filter[1])
+            expectations[items_ids_filter] = -100.
+
+        topk_sorted_expectations = torch.topk(expectations, self.top_k, dim=1)
+        recommendations = self.mab_algo.label_encoder.inverse_transform(topk_sorted_expectations.indices.cpu().numpy().flatten()).reshape(contexts.shape[0], self.top_k)
+        scores = topk_sorted_expectations.values.cpu().numpy()
+        
+        return recommendations, scores

gobrec-0.1.0/gobrec/__init__.py

@@ -0,0 +1,2 @@
+
+from gobrec.Recommender import Recommender

gobrec-0.1.0/gobrec/mabs/MABAlgo.py

@@ -0,0 +1,52 @@
+
+from abc import ABC, abstractmethod
+import numpy as np
+from sklearn.preprocessing import LabelEncoder
+
+
+class MABAlgo(ABC):
+    """
+    Abstract class for Multi-Armed Bandit algorithms.
+    """
+
+    def __init__(self, seed: int = None):
+        self.seed = seed
+        self.rng = np.random.default_rng(self.seed)
+        self.label_encoder = None
+        self.num_arms = None
+        self.num_features = None
+    
+    def _update_label_encoder(self, items_ids: np.ndarray, num_features: int):
+        """
+        Update the label encoder with new item IDs.
+        """
+        if self.label_encoder is None:
+            self.label_encoder = LabelEncoder()
+            self.label_encoder.fit(items_ids)
+            self.num_arms = len(self.label_encoder.classes_)
+        else:
+            new_classes = np.setdiff1d(items_ids, self.label_encoder.classes_)
+            if len(new_classes) > 0:
+                all_classes = np.concatenate((self.label_encoder.classes_, new_classes))
+                self.label_encoder.fit(all_classes)
+            self.num_arms = len(self.label_encoder.classes_)
+        
+        if self.num_features is None:
+            self.num_features = num_features
+        
+        assert num_features == self.num_features, "Number of features has changed!"
+        
+
+    @abstractmethod
+    def fit(self, contexts: np.ndarray, items_ids: np.ndarray, rewards: np.ndarray):
+        """
+        Fit the MAB algorithm with the provided contexts, item IDs, and rewards.
+        """
+        pass
+
+    @abstractmethod
+    def predict(self, contexts: np.ndarray) -> np.ndarray:
+        """
+        Predict the expected rewards for the given contexts.
+        """
+        pass

gobrec-0.1.0/gobrec/mabs/lin_mabs/Lin.py

@@ -0,0 +1,67 @@
+
+import torch
+import numpy as np
+from sklearn.preprocessing import LabelEncoder
+from gobrec.mabs.MABAlgo import MABAlgo
+
+
+class Lin(MABAlgo):
+
+    def __init__(self, seed: int = None, l2_lambda: float = 1.0, use_gpu: bool = False, items_per_batch: int = 10_000):
+        
+        super().__init__(seed)
+
+        self.l2_lambda = l2_lambda
+        self.device = 'cuda' if use_gpu else 'cpu'
+
+        self.items_per_batch = items_per_batch
+        self.already_initialized = False
+    
+    def _update_label_encoder_and_matrices_sizes(self, items_ids: np.ndarray, num_features: int):
+
+        self._update_label_encoder(items_ids, num_features)
+
+        if not self.already_initialized:
+            self.Xty = torch.zeros((self.num_arms, self.num_features), device=self.device, dtype=torch.double)
+            self.A = torch.eye(self.num_features, device=self.device, dtype=torch.double).unsqueeze(0).repeat(self.num_arms, 1, 1) * self.l2_lambda
+            self.beta = torch.zeros((self.num_arms, self.num_features), device=self.device, dtype=torch.double)
+        elif self.num_arms != self.beta.shape[0]:
+            # the number of arms has changed, we need to update the matrices
+            Xty_new = torch.zeros((self.num_arms, self.num_features), device=self.device, dtype=torch.double)
+            Xty_new[:self.Xty.shape[0]] = self.Xty
+            self.Xty = Xty_new
+
+            A_new = torch.eye(self.num_features, device=self.device, dtype=torch.double).unsqueeze(0).repeat(self.num_arms, 1, 1) * self.l2_lambda
+            A_new[:self.A.shape[0]] = self.A
+            self.A = A_new
+
+            beta_new = torch.zeros((self.num_arms, self.num_features), device=self.device, dtype=torch.double)
+            beta_new[:self.beta.shape[0]] = self.beta
+            self.beta = beta_new
+
+
+    def fit(self, contexts: np.ndarray, items_ids: np.ndarray, rewards: np.ndarray):
+
+        self._update_label_encoder_and_matrices_sizes(items_ids, contexts.shape[1])
+
+        X_device = torch.tensor(contexts, device=self.device, dtype=torch.double)
+        y_device = torch.tensor(rewards, device=self.device, dtype=torch.double)
+        decisions_device = torch.tensor(self.label_encoder.transform(items_ids), device=self.device, dtype=torch.long)
+
+        self.A.index_add_(0, decisions_device, torch.einsum('ni,nj->nij', X_device, X_device))
+
+        self.Xty.index_add_(0, decisions_device, X_device * y_device.view(-1, 1))
+
+        for j in range(0, self.beta.shape[0], self.items_per_batch):            
+            self.beta[j:j+self.items_per_batch] = torch.linalg.solve(
+                self.A[j:j+self.items_per_batch],
+                self.Xty[j:j+self.items_per_batch]
+            )
+
+    def predict(self, contexts: np.ndarray):
+        scores = torch.empty((contexts.shape[0], self.num_arms), device=self.device, dtype=torch.double)
+        for start in range(0, self.num_arms, self.items_per_batch):
+            end = min(start + self.items_per_batch, self.num_arms)  
+            scores[:, start:end] = torch.einsum('bd,ad->ba', torch.tensor(contexts, device=self.device, dtype=torch.double), self.beta[start:end])
+        
+        return scores

gobrec-0.1.0/gobrec/mabs/lin_mabs/LinGreedy.py

@@ -0,0 +1,31 @@
+
+from gobrec.mabs.lin_mabs import Lin
+import numpy as np
+import torch
+
+
+class LinGreedy(Lin):
+
+    def __init__(self, seed: int = None, epsilon: float = 0.1, l2_lambda: float = 1.0, use_gpu: bool = False, items_per_batch: int = 10_000):
+        
+        super().__init__(seed, l2_lambda, use_gpu, items_per_batch)
+        self.epsilon = epsilon
+
+
+    def predict(self, contexts: np.ndarray):
+
+        x = torch.tensor(contexts, device=self.device, dtype=torch.double)
+
+        scores = torch.empty((contexts.shape[0], self.num_arms), device=self.device, dtype=torch.double)
+        random_mask = self.rng.random(contexts.shape[0]) < self.epsilon
+        random_indexes = random_mask.nonzero()[0]
+        not_random_indexes = (~random_mask).nonzero()[0]
+
+        scores[random_mask] = torch.tensor(self.rng.random((len(random_indexes), self.num_arms)), device=self.device, dtype=torch.double)
+
+        for start in range(0, len(not_random_indexes), self.items_per_batch):
+            end = min(start + self.items_per_batch, len(not_random_indexes))
+            batch_indexes = not_random_indexes[start:end]
+            scores[batch_indexes] = torch.einsum('bd,ad->ba', x[batch_indexes], self.beta)
+
+        return scores

gobrec-0.1.0/gobrec/mabs/lin_mabs/LinTS.py

@@ -0,0 +1,35 @@
+
+from gobrec.mabs.lin_mabs import Lin
+import numpy as np
+import torch
+
+class LinTS(Lin):
+
+    def __init__(self, seed: int = None, alpha: float = 1.0, l2_lambda: float = 1.0, use_gpu: bool = False, items_per_batch: int = 10_000):
+        
+        super().__init__(seed, l2_lambda, use_gpu, items_per_batch)
+        self.alpha = alpha
+    
+    def predict(self, contexts: np.ndarray):
+        x = torch.tensor(contexts, device=self.device, dtype=torch.double)
+
+        num_arms, num_features = self.beta.shape
+        num_contexts = contexts.shape[0]
+
+        scores = torch.empty((num_contexts, num_arms), device=self.device, dtype=torch.double)
+
+        eps = torch.from_numpy(self.rng.standard_normal(size=(num_contexts, num_features))).to(device=self.device, dtype=torch.double)
+
+        for start in range(0, num_arms, self.items_per_batch):
+            end = min(start + self.items_per_batch, num_arms)  
+
+            beta_chunk = self.beta[start:end]
+            A_chunk = self.A[start:end]
+            A_inv_chunk = torch.linalg.inv(A_chunk)
+
+            L_chunk = torch.linalg.cholesky((self.alpha ** 2) * A_inv_chunk)
+            beta_sampled = torch.einsum('bd,add->bad', eps, L_chunk) + beta_chunk
+
+            scores[:, start:end] = torch.einsum('bd,bad->ba', x, beta_sampled)
+
+        return scores

gobrec-0.1.0/gobrec/mabs/lin_mabs/LinUCB.py

@@ -0,0 +1,31 @@
+
+from gobrec.mabs.lin_mabs import Lin
+import numpy as np
+import torch
+
+
+class LinUCB(Lin):
+
+    def __init__(self, seed: int = None, alpha: float = 1.0, l2_lambda: float = 1.0, use_gpu: bool = False, items_per_batch: int = 10_000):
+        
+        super().__init__(seed, l2_lambda, use_gpu, items_per_batch)
+        self.alpha = alpha
+
+
+    def predict(self, contexts: np.ndarray):
+
+        x = torch.tensor(contexts, device=self.device, dtype=torch.double)
+
+        scores = torch.matmul(x, self.beta.T)
+
+        for j in range(0, self.beta.shape[0], self.items_per_batch):
+            x_A_inv = torch.matmul(x, torch.linalg.inv(self.A[j: j+self.items_per_batch]))
+
+            # Upper confidence bound = alpha * sqrt(x A^-1 xt). Notice that, x = xt
+            # ucb values are claculated for all the contexts in one single go. type(ucb): np.ndarray
+            ucb = self.alpha * torch.sqrt(torch.sum(x_A_inv * x, axis=2))
+
+            # Calculate linucb expectation y = x * b + ucb
+            scores[:, j: j+self.items_per_batch] += ucb.T
+        
+        return scores

gobrec-0.1.0/gobrec/mabs/lin_mabs/__init__.py

@@ -0,0 +1,5 @@
+
+from gobrec.mabs.lin_mabs.Lin import Lin
+from gobrec.mabs.lin_mabs.LinUCB import LinUCB
+from gobrec.mabs.lin_mabs.LinGreedy import LinGreedy
+from gobrec.mabs.lin_mabs.LinTS import LinTS

gobrec-0.1.0/gobrec.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.1
+Name: gobrec
+Version: 0.1.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# gobrec
+GOBRec: GPU Optimized Bandits Recommender

gobrec-0.1.0/gobrec.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+setup.py
+gobrec/Recommender.py
+gobrec/__init__.py
+gobrec.egg-info/PKG-INFO
+gobrec.egg-info/SOURCES.txt
+gobrec.egg-info/dependency_links.txt
+gobrec.egg-info/requires.txt
+gobrec.egg-info/top_level.txt
+gobrec/mabs/MABAlgo.py
+gobrec/mabs/__init__.py
+gobrec/mabs/lin_mabs/Lin.py
+gobrec/mabs/lin_mabs/LinGreedy.py
+gobrec/mabs/lin_mabs/LinTS.py
+gobrec/mabs/lin_mabs/LinUCB.py
+gobrec/mabs/lin_mabs/__init__.py

gobrec-0.1.0/gobrec.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gobrec-0.1.0/gobrec.egg-info/requires.txt

@@ -0,0 +1,3 @@
+torch
+numpy
+scikit-learn

gobrec-0.1.0/gobrec.egg-info/top_level.txt

@@ -0,0 +1 @@
+gobrec

gobrec-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gobrec-0.1.0/setup.py

@@ -0,0 +1,18 @@
+
+from setuptools import setup, find_packages
+
+with open('README.md', 'r') as f:
+    description = f.read()
+
+setup(
+    name='gobrec',
+    version='0.1.0',
+    packages=find_packages(),
+    install_requires=[
+        'torch',
+        'numpy',
+        'scikit-learn'
+    ],
+    long_description=description,
+    long_description_content_type='text/markdown'
+)