nextrec 0.2.1__tar.gz → 0.2.2__tar.gz

{nextrec-0.2.1 → nextrec-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.2.1
+Version: 0.2.2
 Summary: A comprehensive recommendation library with match, ranking, and multi-task learning models
 Project-URL: Homepage, https://github.com/zerolovesea/NextRec
 Project-URL: Repository, https://github.com/zerolovesea/NextRec
@@ -61,7 +61,7 @@ Description-Content-Type: text/markdown
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.2.1-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.2.2-orange.svg)
 
 English | [中文版](README_zh.md)
 

{nextrec-0.2.1 → nextrec-0.2.2}/README.md

@@ -5,7 +5,7 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.2.1-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.2.2-orange.svg)
 
 English | [中文版](README_zh.md)
 

{nextrec-0.2.1 → nextrec-0.2.2}/README_zh.md

@@ -5,7 +5,7 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.2.1-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.2.2-orange.svg)
 
 [English Version](README.md) | 中文版
 

{nextrec-0.2.1 → nextrec-0.2.2}/docs/conf.py

@@ -12,7 +12,7 @@ sys.path.insert(0, os.path.abspath('../nextrec'))
 project = "NextRec"
 copyright = "2025, Yang Zhou"
 author = "Yang Zhou"
-release = "0.2.1"
+release = "0.2.2"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

nextrec-0.2.2/docs/nextrec.loss.rst

@@ -0,0 +1,45 @@
+nextrec.loss package
+====================
+
+Submodules
+----------
+
+nextrec.loss.loss\_utils module
+-------------------------------
+
+.. automodule:: nextrec.loss.loss_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.loss.pointwise module
+-----------------------------
+
+.. automodule:: nextrec.loss.pointwise
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.loss.pairwise module
+----------------------------
+
+.. automodule:: nextrec.loss.pairwise
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.loss.listwise module
+----------------------------
+
+.. automodule:: nextrec.loss.listwise
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: nextrec.loss
+   :members:
+   :undoc-members:
+   :show-inheritance:

nextrec-0.2.2/nextrec/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

{nextrec-0.2.1 → nextrec-0.2.2}/nextrec/basic/layers.py

@@ -16,7 +16,7 @@ import torch.nn.functional as F
 
 from nextrec.basic.activation import activation_layer
 from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
-from nextrec.utils.initializer import get_initializer_fn
+from nextrec.utils.initializer import get_initializer
 
 Feature = Union[DenseFeature, SparseFeature, SequenceFeature]
 
@@ -160,7 +160,7 @@ class EmbeddingLayer(nn.Module):
                 )
                 embedding.weight.requires_grad = feature.trainable
 
-                initialization = get_initializer_fn(
+                initialization = get_initializer(
                     init_type=feature.init_type,
                     activation="linear",
                     param=feature.init_params,

{nextrec-0.2.1 → nextrec-0.2.2}/nextrec/basic/model.py

@@ -6,18 +6,15 @@ Author: Yang Zhou,zyaztec@gmail.com
 """
 
 import os
-import datetime
+import tqdm
 import logging
-import os
-from pathlib import Path
-
 import numpy as np
 import pandas as pd
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
-import tqdm
 
+from pathlib import Path
 from typing import Union, Literal
 from torch.utils.data import DataLoader, TensorDataset
 
@@ -25,11 +22,11 @@ from nextrec.basic.callback import EarlyStopper
 from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature, FeatureConfig
 from nextrec.basic.metrics import configure_metrics, evaluate_metrics
 
-from nextrec.loss import get_loss_fn
+from nextrec.loss import get_loss_fn, get_loss_kwargs
 from nextrec.data import get_column_data
 from nextrec.data.dataloader import build_tensors_from_data
 from nextrec.basic.loggers import setup_logger, colorize
-from nextrec.utils import get_optimizer_fn, get_scheduler_fn
+from nextrec.utils import get_optimizer, get_scheduler
 from nextrec.basic.session import resolve_save_path, create_session
 
 
@@ -400,7 +397,9 @@ class BaseModel(FeatureConfig, nn.Module):
                 optimizer_params: dict | None = None,
                 scheduler: str | torch.optim.lr_scheduler._LRScheduler | type[torch.optim.lr_scheduler._LRScheduler] | None = None,
                 scheduler_params: dict | None = None,
-                loss: str | nn.Module | list[str | nn.Module] | None= "bce"):
+                loss: str | nn.Module | list[str | nn.Module] | None= "bce",
+                loss_params: dict | list[dict] | None = None):
+        
         if optimizer_params is None:
             optimizer_params = {}
         
@@ -415,9 +414,10 @@ class BaseModel(FeatureConfig, nn.Module):
             self._scheduler_name = None
         self._scheduler_params = scheduler_params or {}
         self._loss_config = loss
+        self._loss_params = loss_params
         
         # set optimizer
-        self.optimizer_fn = get_optimizer_fn(
+        self.optimizer_fn = get_optimizer(
             optimizer=optimizer, 
             params=self.parameters(), 
             **optimizer_params
@@ -430,7 +430,12 @@ class BaseModel(FeatureConfig, nn.Module):
             # For ranking and multitask, use pointwise training
             training_mode = 'pointwise' if self.task_type in ['ranking', 'multitask'] else None
             # Use task_type directly, not self.task_type for single task
-            self.loss_fn = [get_loss_fn(task_type=task_type, training_mode=training_mode, loss=loss_value)]
+            self.loss_fn = [get_loss_fn(
+                task_type=task_type,
+                training_mode=training_mode,
+                loss=loss_value,
+                **get_loss_kwargs(loss_params)
+            )]
         else:
             self.loss_fn = []
             for i in range(self.nums_task):
@@ -443,10 +448,15 @@ class BaseModel(FeatureConfig, nn.Module):
                 
                 # Multitask always uses pointwise training
                 training_mode = 'pointwise'
-                self.loss_fn.append(get_loss_fn(task_type=task_type, training_mode=training_mode, loss=loss_value))
+                self.loss_fn.append(get_loss_fn(
+                    task_type=task_type,
+                    training_mode=training_mode,
+                    loss=loss_value,
+                    **get_loss_kwargs(loss_params, i)
+                ))
         
         # set scheduler
-        self.scheduler_fn = get_scheduler_fn(scheduler, self.optimizer_fn, **(scheduler_params or {})) if scheduler else None
+        self.scheduler_fn = get_scheduler(scheduler, self.optimizer_fn, **(scheduler_params or {})) if scheduler else None
 
     def compute_loss(self, y_pred, y_true):
         if y_true is None:
@@ -1130,10 +1140,13 @@ class BaseMatchModel(BaseModel):
     Base class for match (retrieval/recall) models
     Supports pointwise, pairwise, and listwise training modes
     """
-    
+    @property
+    def model_name(self) -> str:
+        raise NotImplementedError
+
     @property
     def task_type(self) -> str:
-        return 'match'
+        raise NotImplementedError
     
     @property
     def support_training_modes(self) -> list[str]:
@@ -1209,45 +1222,47 @@ class BaseMatchModel(BaseModel):
         self.num_negative_samples = num_negative_samples
         self.temperature = temperature
         self.similarity_metric = similarity_metric
-    
+
+        self.user_feature_names = [f.name for f in (
+            self.user_dense_features + self.user_sparse_features + self.user_sequence_features
+        )]
+        self.item_feature_names = [f.name for f in (
+            self.item_dense_features + self.item_sparse_features + self.item_sequence_features
+        )]
+
     def get_user_features(self, X_input: dict) -> dict:
-        user_input = {}
-        all_user_features = self.user_dense_features + self.user_sparse_features + self.user_sequence_features
-        for feature in all_user_features:
-            if feature.name in X_input:
-                user_input[feature.name] = X_input[feature.name]
-        return user_input
-    
+        return {
+            name: X_input[name]
+            for name in self.user_feature_names
+            if name in X_input
+        }
+
     def get_item_features(self, X_input: dict) -> dict:
-        item_input = {}
-        all_item_features = self.item_dense_features + self.item_sparse_features + self.item_sequence_features
-        for feature in all_item_features:
-            if feature.name in X_input:
-                item_input[feature.name] = X_input[feature.name]
-        return item_input
-    
+        return {
+            name: X_input[name]
+            for name in self.item_feature_names
+            if name in X_input
+        }
+        
     def compile(self, 
-                optimizer = "adam",
+                optimizer: str | torch.optim.Optimizer = "adam",
                 optimizer_params: dict | None = None,
                 scheduler: str | torch.optim.lr_scheduler._LRScheduler | type[torch.optim.lr_scheduler._LRScheduler] | None = None,
                 scheduler_params: dict | None = None,
-                loss: str | nn.Module | list[str | nn.Module] | None= None):
+                loss: str | nn.Module | list[str | nn.Module] | None = "bce",
+                loss_params: dict | list[dict] | None = None):
         """
         Compile match model with optimizer, scheduler, and loss function.
-        Validates that training_mode is supported by the model.
+        Mirrors BaseModel.compile while adding training_mode validation for match tasks.
         """
-        from nextrec.loss import validate_training_mode
-        
-        # Validate training mode is supported
-        validate_training_mode(
-            training_mode=self.training_mode,
-            support_training_modes=self.support_training_modes,
-            model_name=self.model_name
-        )
-        
+        if self.training_mode not in self.support_training_modes:
+            raise ValueError(
+                f"{self.model_name} does not support training_mode='{self.training_mode}'. "
+                f"Supported modes: {self.support_training_modes}"
+            )
+
         # Call parent compile with match-specific logic
-        if optimizer_params is None:
-            optimizer_params = {}
+        optimizer_params = optimizer_params or {}
         
         self._optimizer_name = optimizer if isinstance(optimizer, str) else optimizer.__class__.__name__
         self._optimizer_params = optimizer_params
@@ -1260,24 +1275,42 @@ class BaseMatchModel(BaseModel):
             self._scheduler_name = None
         self._scheduler_params = scheduler_params or {}
         self._loss_config = loss
+        self._loss_params = loss_params
         
         # set optimizer
-        self.optimizer_fn = get_optimizer_fn(
+        self.optimizer_fn = get_optimizer(
             optimizer=optimizer, 
             params=self.parameters(), 
             **optimizer_params
         )
         
         # Set loss function based on training mode
-        loss_value = loss[0] if isinstance(loss, list) else loss
+        default_losses = {
+            'pointwise': 'bce',
+            'pairwise': 'bpr',
+            'listwise': 'sampled_softmax',
+        }
+
+        if loss is None:
+            loss_value = default_losses.get(self.training_mode, "bce")
+        elif isinstance(loss, list):
+            loss_value = loss[0] if loss and loss[0] is not None else default_losses.get(self.training_mode, "bce")
+        else:
+            loss_value = loss
+
+        # Pairwise/listwise modes do not support BCE, fall back to sensible defaults
+        if self.training_mode in {"pairwise", "listwise"} and loss_value in {"bce", "binary_crossentropy"}:
+            loss_value = default_losses.get(self.training_mode, loss_value)
+
         self.loss_fn = [get_loss_fn(
             task_type='match',
             training_mode=self.training_mode,
-            loss=loss_value
+            loss=loss_value,
+            **get_loss_kwargs(loss_params, 0)
         )]
         
         # set scheduler
-        self.scheduler_fn = get_scheduler_fn(scheduler, self.optimizer_fn, **(scheduler_params or {})) if scheduler else None
+        self.scheduler_fn = get_scheduler(scheduler, self.optimizer_fn, **(scheduler_params or {})) if scheduler else None
 
     def compute_similarity(self, user_emb: torch.Tensor, item_emb: torch.Tensor) -> torch.Tensor:
         if self.similarity_metric == 'dot':

nextrec-0.2.2/nextrec/loss/__init__.py

@@ -0,0 +1,42 @@
+from nextrec.loss.listwise import (
+    ApproxNDCGLoss,
+    InfoNCELoss,
+    ListMLELoss,
+    ListNetLoss,
+    SampledSoftmaxLoss,
+)
+from nextrec.loss.pairwise import BPRLoss, HingeLoss, TripletLoss
+from nextrec.loss.pointwise import (
+    ClassBalancedFocalLoss,
+    CosineContrastiveLoss,
+    FocalLoss,
+    WeightedBCELoss,
+)
+from nextrec.loss.loss_utils import (
+    get_loss_fn,
+    get_loss_kwargs,
+    VALID_TASK_TYPES,
+)
+
+__all__ = [
+    # Pointwise
+    "CosineContrastiveLoss",
+    "WeightedBCELoss",
+    "FocalLoss",
+    "ClassBalancedFocalLoss",
+    # Pairwise
+    "BPRLoss",
+    "HingeLoss",
+    "TripletLoss",
+    # Listwise
+    "SampledSoftmaxLoss",
+    "InfoNCELoss",
+    "ListNetLoss",
+    "ListMLELoss",
+    "ApproxNDCGLoss",
+    # Utilities
+    "get_loss_fn",
+    "get_loss_kwargs",
+    "validate_training_mode",
+    "VALID_TASK_TYPES",
+]

nextrec-0.2.2/nextrec/loss/listwise.py

@@ -0,0 +1,164 @@
+"""
+Listwise loss functions for ranking and contrastive training.
+"""
+
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class SampledSoftmaxLoss(nn.Module):
+    """
+    Softmax over one positive and multiple sampled negatives.
+    """
+
+    def __init__(self, reduction: str = "mean"):
+        super().__init__()
+        self.reduction = reduction
+
+    def forward(self, pos_logits: torch.Tensor, neg_logits: torch.Tensor) -> torch.Tensor:
+        pos_logits = pos_logits.unsqueeze(1)
+        all_logits = torch.cat([pos_logits, neg_logits], dim=1)
+        targets = torch.zeros(all_logits.size(0), dtype=torch.long, device=all_logits.device)
+        loss = F.cross_entropy(all_logits, targets, reduction=self.reduction)
+        return loss
+
+
+class InfoNCELoss(nn.Module):
+    """
+    InfoNCE loss for contrastive learning with one positive and many negatives.
+    """
+
+    def __init__(self, temperature: float = 0.07, reduction: str = "mean"):
+        super().__init__()
+        self.temperature = temperature
+        self.reduction = reduction
+
+    def forward(
+        self, query: torch.Tensor, pos_key: torch.Tensor, neg_keys: torch.Tensor
+    ) -> torch.Tensor:
+        pos_sim = torch.sum(query * pos_key, dim=-1) / self.temperature
+        pos_sim = pos_sim.unsqueeze(1)
+        query_expanded = query.unsqueeze(1)
+        neg_sim = torch.sum(query_expanded * neg_keys, dim=-1) / self.temperature
+        logits = torch.cat([pos_sim, neg_sim], dim=1)
+        labels = torch.zeros(logits.size(0), dtype=torch.long, device=logits.device)
+        loss = F.cross_entropy(logits, labels, reduction=self.reduction)
+        return loss
+
+
+class ListNetLoss(nn.Module):
+    """
+    ListNet loss using top-1 probability distribution.
+    Reference: Cao et al. (ICML 2007)
+    """
+
+    def __init__(self, temperature: float = 1.0, reduction: str = "mean"):
+        super().__init__()
+        self.temperature = temperature
+        self.reduction = reduction
+
+    def forward(self, scores: torch.Tensor, labels: torch.Tensor) -> torch.Tensor:
+        pred_probs = F.softmax(scores / self.temperature, dim=1)
+        true_probs = F.softmax(labels / self.temperature, dim=1)
+        loss = -torch.sum(true_probs * torch.log(pred_probs + 1e-10), dim=1)
+
+        if self.reduction == "mean":
+            return loss.mean()
+        if self.reduction == "sum":
+            return loss.sum()
+        return loss
+
+
+class ListMLELoss(nn.Module):
+    """
+    ListMLE (Maximum Likelihood Estimation) loss.
+    Reference: Xia et al. (ICML 2008)
+    """
+
+    def __init__(self, reduction: str = "mean"):
+        super().__init__()
+        self.reduction = reduction
+
+    def forward(self, scores: torch.Tensor, labels: torch.Tensor) -> torch.Tensor:
+        sorted_labels, sorted_indices = torch.sort(labels, descending=True, dim=1)
+        batch_size, list_size = scores.shape
+        batch_indices = torch.arange(batch_size, device=scores.device).unsqueeze(1).expand(-1, list_size)
+        sorted_scores = scores[batch_indices, sorted_indices]
+
+        loss = torch.tensor(0.0, device=scores.device)
+        for i in range(list_size):
+            remaining_scores = sorted_scores[:, i:]
+            log_sum_exp = torch.logsumexp(remaining_scores, dim=1)
+            loss = loss + (log_sum_exp - sorted_scores[:, i]).sum()
+
+        if self.reduction == "mean":
+            return loss / batch_size
+        if self.reduction == "sum":
+            return loss
+        return loss / batch_size
+
+
+class ApproxNDCGLoss(nn.Module):
+    """
+    Approximate NDCG loss for learning to rank.
+    Reference: Qin et al. (2010)
+    """
+
+    def __init__(self, temperature: float = 1.0, reduction: str = "mean"):
+        super().__init__()
+        self.temperature = temperature
+        self.reduction = reduction
+
+    def _ideal_dcg(self, labels: torch.Tensor, k: Optional[int]) -> torch.Tensor:
+        # labels: [B, L]
+        sorted_labels, _ = torch.sort(labels, dim=1, descending=True)
+        if k is not None:
+            sorted_labels = sorted_labels[:, :k]
+
+        gains = torch.pow(2.0, sorted_labels) - 1.0  # [B, K]
+        positions = torch.arange(
+            1, gains.size(1) + 1, device=gains.device, dtype=torch.float32
+        )  # [K]
+        discounts = 1.0 / torch.log2(positions + 1.0)  # [K]
+        ideal_dcg = torch.sum(gains * discounts, dim=1)  # [B]
+        return ideal_dcg
+
+    def forward(
+        self, scores: torch.Tensor, labels: torch.Tensor, k: Optional[int] = None
+    ) -> torch.Tensor:
+        """
+        scores: [B, L]
+        labels: [B, L]
+        """
+        batch_size, list_size = scores.shape
+        device = scores.device
+
+        # diff[b, i, j] = (s_j - s_i) / T
+        scores_i = scores.unsqueeze(2)          # [B, L, 1]
+        scores_j = scores.unsqueeze(1)          # [B, 1, L]
+        diff = (scores_j - scores_i) / self.temperature  # [B, L, L]
+
+        P_ji = torch.sigmoid(diff)             # [B, L, L]
+        eye = torch.eye(list_size, device=device).unsqueeze(0)  # [1, L, L]
+        P_ji = P_ji * (1.0 - eye)
+
+        exp_rank = 1.0 + P_ji.sum(dim=-1)      # [B, L]
+
+        discounts = 1.0 / torch.log2(exp_rank + 1.0)  # [B, L]
+
+        gains = torch.pow(2.0, labels) - 1.0   # [B, L]
+        approx_dcg = torch.sum(gains * discounts, dim=1)  # [B]
+
+        ideal_dcg = self._ideal_dcg(labels, k)  # [B]
+
+        ndcg = approx_dcg / (ideal_dcg + 1e-10)  # [B]
+        loss = 1.0 - ndcg
+
+        if self.reduction == "mean":
+            return loss.mean()
+        if self.reduction == "sum":
+            return loss.sum()
+        return loss