nextrec 0.4.21__tar.gz → 0.4.22__tar.gz

{nextrec-0.4.21 → nextrec-0.4.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.21
+Version: 0.4.22
 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
@@ -65,11 +65,11 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=grey&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
 ![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.4.21-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -247,11 +247,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.21，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.21，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.21 → nextrec-0.4.22}/README.md

@@ -4,11 +4,11 @@
 
 <div align="center">
 
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=grey&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
 ![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.4.21-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -186,11 +186,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.21，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.21，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.21 → nextrec-0.4.22}/README_en.md

@@ -4,11 +4,11 @@
 
 <div align="center">
 
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=grey&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
 ![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.4.21-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 English | [中文文档](README.md)
@@ -191,11 +191,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 Prediction outputs are saved under `{checkpoint_path}/predictions/{name}.{save_data_format}`.
 
-> As of version 0.4.21, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.22, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.21. All models and test code have been validated on the following platforms. If you encounter compatibility issues, please report them in the issue tracker with your system version:
+The current version is 0.4.22. All models and test code have been validated on the following platforms. If you encounter compatibility issues, please report them in the issue tracker with your system version:
 
 | Platform | Configuration | 
 |----------|---------------|

{nextrec-0.4.21 → nextrec-0.4.22}/docs/rtd/conf.py

@@ -11,7 +11,7 @@ sys.path.insert(0, str(PROJECT_ROOT / "nextrec"))
 project = "NextRec"
 copyright = "2025, Yang Zhou"
 author = "Yang Zhou"
-release = "0.4.21"
+release = "0.4.22"
 
 extensions = [
     "myst_parser",

nextrec-0.4.22/nextrec/__version__.py

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

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/basic/activation.py

@@ -9,10 +9,10 @@ Author: Yang Zhou, zyaztec@gmail.com
 import torch
 import torch.nn as nn
 
-from typing import Literal
 
 from nextrec.utils.types import ActivationName
 
+
 class Dice(nn.Module):
     """
     Dice activation function from the paper:

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/basic/heads.py

@@ -15,6 +15,7 @@ import torch.nn as nn
 import torch.nn.functional as F
 
 from nextrec.basic.layers import PredictionLayer
+from nextrec.utils.types import TaskTypeName
 
 
 class TaskHead(nn.Module):
@@ -27,9 +28,7 @@ class TaskHead(nn.Module):
 
     def __init__(
         self,
-        task_type: (
-            Literal["binary", "regression"] | list[Literal["binary", "regression"]]
-        ) = "binary",
+        task_type: TaskTypeName | list[TaskTypeName] = "binary",
         task_dims: int | list[int] | None = None,
         use_bias: bool = True,
         return_logits: bool = False,

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/basic/model.py

@@ -60,8 +60,8 @@ from nextrec.loss import (
     InfoNCELoss,
     SampledSoftmaxLoss,
     TripletLoss,
-    get_loss_fn,
 )
+from nextrec.utils.loss import get_loss_fn
 from nextrec.loss.grad_norm import get_grad_norm_shared_params
 from nextrec.utils.console import display_metrics_table, progress
 from nextrec.utils.torch_utils import (
@@ -75,7 +75,13 @@ from nextrec.utils.torch_utils import (
 )
 from nextrec.utils.config import safe_value
 from nextrec.utils.model import compute_ranking_loss
-from nextrec.utils.types import LossName, OptimizerName, SchedulerName
+from nextrec.utils.types import (
+    LossName,
+    OptimizerName,
+    SchedulerName,
+    TrainingModeName,
+    TaskTypeName,
+)
 
 
 class BaseModel(SummarySet, FeatureSet, nn.Module):
@@ -94,11 +100,8 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         sequence_features: list[SequenceFeature] | None = None,
         target: list[str] | str | None = None,
         id_columns: list[str] | str | None = None,
-        task: str | list[str] | None = None,
-        training_mode: (
-            Literal["pointwise", "pairwise", "listwise"]
-            | list[Literal["pointwise", "pairwise", "listwise"]]
-        ) = "pointwise",
+        task: TaskTypeName | list[TaskTypeName] | None = None,
+        training_mode: TrainingModeName | list[TrainingModeName] = "pointwise",
         embedding_l1_reg: float = 0.0,
         dense_l1_reg: float = 0.0,
         embedding_l2_reg: float = 0.0,
@@ -179,8 +182,7 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         else:
             training_modes = [training_mode] * self.nums_task
         if any(
-            mode not in {"pointwise", "pairwise", "listwise"}
-            for mode in training_modes
+            mode not in {"pointwise", "pairwise", "listwise"} for mode in training_modes
         ):
             raise ValueError(
                 "[BaseModel-init Error] training_mode must be one of {'pointwise', 'pairwise', 'listwise'}."
@@ -195,6 +197,7 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         self.regularization_weights = []
         self.embedding_params = []
         self.loss_weight = None
+        self.ignore_label = None
 
         self.max_gradient_norm = 1.0
         self.logger_initialized = False
@@ -407,6 +410,7 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         loss: LossName | nn.Module | list[LossName | nn.Module] | None = "bce",
         loss_params: dict | list[dict] | None = None,
         loss_weights: int | float | list[int | float] | dict | str | None = None,
+        ignore_label: int | float | None = -1,
     ):
         """
         Configure the model for training.
@@ -419,7 +423,9 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             loss_params: Loss function parameters, or list for multi-task. e.g., {'weight': tensor([0.25, 0.75])}.
             loss_weights: Weights for each task loss, int/float for single-task or list for multi-task. e.g., 1.0, or [1.0, 0.5].
                 Use "grad_norm" or {"method": "grad_norm", ...} to enable GradNorm for multi-task loss balancing.
+            ignore_label: Label value to ignore when computing loss. Use this to skip gradients for unknown labels.
         """
+        self.ignore_label = ignore_label
         default_losses = {
             "pointwise": "bce",
             "pairwise": "bpr",
@@ -540,6 +546,7 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             raise ValueError(
                 "[BaseModel-compute_loss Error] Ground truth labels (y_true) are required."
             )
+
         # single-task
         if self.nums_task == 1:
             if y_pred.dim() == 1:
@@ -547,13 +554,24 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             if y_true.dim() == 1:
                 y_true = y_true.view(-1, 1)
             if y_pred.shape != y_true.shape:
-                raise ValueError(f"Shape mismatch: {y_pred.shape} vs {y_true.shape}")
-            loss_fn = self.loss_fn[0] if getattr(self, "loss_fn", None) else None
-            if loss_fn is None:
                 raise ValueError(
-                    "[BaseModel-compute_loss Error] Loss function is not configured. Call compile() first."
+                    f"[BaseModel-compute_loss Error] Shape mismatch: {y_pred.shape} vs {y_true.shape}"
                 )
+
+            loss_fn = self.loss_fn[0]
+
+            if self.ignore_label is not None:
+                valid_mask = y_true != self.ignore_label
+                if valid_mask.dim() > 1:
+                    valid_mask = valid_mask.all(dim=1)
+                if not torch.any(valid_mask):  # if no valid labels, return zero loss
+                    return y_pred.sum() * 0.0
+
+                y_pred = y_pred[valid_mask]
+                y_true = y_true[valid_mask]
+
             mode = self.training_modes[0]
+
             task_dim = (
                 self.task_dims[0] if hasattr(self, "task_dims") else y_pred.shape[1]  # type: ignore
             )
@@ -584,7 +602,25 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         for i, (start, end) in enumerate(slices):  # type: ignore
             y_pred_i = y_pred[:, start:end]
             y_true_i = y_true[:, start:end]
+            total_count = y_true_i.shape[0]
+            # valid_count = None
+
+            # mask ignored labels
+            if self.ignore_label is not None:
+                valid_mask = y_true_i != self.ignore_label
+                if valid_mask.dim() > 1:
+                    valid_mask = valid_mask.all(dim=1)
+                if not torch.any(valid_mask):
+                    task_losses.append(y_pred_i.sum() * 0.0)
+                    continue
+                # valid_count = valid_mask.sum().to(dtype=y_true_i.dtype)
+                y_pred_i = y_pred_i[valid_mask]
+                y_true_i = y_true_i[valid_mask]
+            # else:
+            # valid_count = y_true_i.new_tensor(float(total_count))
+
             mode = self.training_modes[i]
+
             if mode in {"pairwise", "listwise"}:
                 task_loss = compute_ranking_loss(
                     training_mode=mode,
@@ -594,7 +630,11 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
                 )
             else:
                 task_loss = self.loss_fn[i](y_pred_i, y_true_i)
+            # task_loss = normalize_task_loss(
+            #     task_loss, valid_count, total_count
+            # )  # normalize by valid samples to avoid loss scale issues
             task_losses.append(task_loss)
+
         if self.grad_norm is not None:
             if self.grad_norm_shared_params is None:
                 self.grad_norm_shared_params = get_grad_norm_shared_params(
@@ -2164,7 +2204,7 @@ class BaseMatchModel(BaseModel):
             scheduler_params: Parameters for the scheduler. e.g., {'step_size': 10, 'gamma': 0.1}.
             loss: Loss function(s) to use (name, instance, or list). e.g., 'bce'.
             loss_params: Parameters for the loss function(s). e.g., {'reduction': 'mean'}.
-            loss_weights: Weights for the loss function(s). e.g., 1.0 or [0.7, 0.3]. 
+            loss_weights: Weights for the loss function(s). e.g., 1.0 or [0.7, 0.3].
         """
         if self.training_mode not in self.support_training_modes:
             raise ValueError(

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/loss/__init__.py

@@ -6,7 +6,6 @@ from nextrec.loss.listwise import (
     SampledSoftmaxLoss,
 )
 from nextrec.loss.grad_norm import GradNormLossWeighting
-from nextrec.loss.loss_utils import VALID_TASK_TYPES, get_loss_fn, get_loss_kwargs
 from nextrec.loss.pairwise import BPRLoss, HingeLoss, TripletLoss
 from nextrec.loss.pointwise import (
     ClassBalancedFocalLoss,
@@ -34,7 +33,4 @@ __all__ = [
     # Multi-task weighting
     "GradNormLossWeighting",
     # Utilities
-    "get_loss_fn",
-    "get_loss_kwargs",
-    "VALID_TASK_TYPES",
 ]

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/loss/grad_norm.py

@@ -20,9 +20,9 @@ import torch.nn.functional as F
 
 
 def get_grad_norm_shared_params(
-    model: torch.nn.Module,
-    shared_modules: Iterable[str] | None = None,
-) -> list[torch.nn.Parameter]:
+    model,
+    shared_modules=None,
+):
     if not shared_modules:
         return [p for p in model.parameters() if p.requires_grad]
     shared_params = []

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/utils/__init__.py

@@ -6,7 +6,7 @@ Last update: 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
-from . import console, data, embedding, torch_utils
+from . import console, data, embedding, loss, torch_utils
 from .config import (
     build_feature_objects,
     build_model_instance,
@@ -38,6 +38,7 @@ from .data import (
 from .embedding import get_auto_embedding_dim
 from .feature import to_list
 from .model import compute_pair_scores, get_mlp_output_dim, merge_features
+from .loss import normalize_task_loss
 from .torch_utils import (
     add_distributed_sampler,
     get_device,
@@ -81,6 +82,8 @@ __all__ = [
     "merge_features",
     "get_mlp_output_dim",
     "compute_pair_scores",
+    # Loss utilities
+    "normalize_task_loss",
     # Feature utilities
     "to_list",
     # Config utilities
@@ -101,6 +104,7 @@ __all__ = [
     "console",
     "data",
     "embedding",
+    "loss",
     "torch_utils",
     # Type aliases
     "OptimizerName",

nextrec-0.4.21/nextrec/loss/loss_utils.py → nextrec-0.4.22/nextrec/utils/loss.py

@@ -1,11 +1,13 @@
 """
 Loss utilities for NextRec.
 
-Date: create on 27/10/2025
-Checkpoint: edit on 19/12/2025
+Date: create on 28/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
+from __future__ import annotations
+
+import torch
 import torch.nn as nn
 
 from nextrec.loss.listwise import (
@@ -19,11 +21,19 @@ from nextrec.loss.pairwise import BPRLoss, HingeLoss, TripletLoss
 from nextrec.loss.pointwise import ClassBalancedFocalLoss, FocalLoss, WeightedBCELoss
 from nextrec.utils.types import LossName
 
-VALID_TASK_TYPES = [
-    "binary",
-    "multilabel",
-    "regression",
-]
+
+def normalize_task_loss(
+    task_loss,
+    valid_count,
+    total_count,
+    eps=1e-8,
+) -> torch.Tensor:
+    if not torch.is_tensor(valid_count):
+        valid_count = torch.tensor(float(valid_count), device=task_loss.device)
+    if not torch.is_tensor(total_count):
+        total_count = torch.tensor(float(total_count), device=task_loss.device)
+    scale = valid_count.to(task_loss.dtype) / (total_count.to(task_loss.dtype) + eps)
+    return task_loss * scale
 
 
 def build_cb_focal(kw):

{nextrec-0.4.21 → nextrec-0.4.22}/nextrec/utils/types.py

@@ -34,26 +34,30 @@ LossName = Literal[
 ]
 
 ActivationName = Literal[
-        "dice",
-        "relu",
-        "relu6",
-        "elu",
-        "selu",
-        "leaky_relu",
-        "prelu",
-        "gelu",
-        "sigmoid",
-        "tanh",
-        "softplus",
-        "softsign",
-        "hardswish",
-        "mish",
-        "silu",
-        "swish",
-        "hardsigmoid",
-        "tanhshrink",
-        "softshrink",
-        "none",
-        "linear",
-        "identity",
-    ] 
+    "dice",
+    "relu",
+    "relu6",
+    "elu",
+    "selu",
+    "leaky_relu",
+    "prelu",
+    "gelu",
+    "sigmoid",
+    "tanh",
+    "softplus",
+    "softsign",
+    "hardswish",
+    "mish",
+    "silu",
+    "swish",
+    "hardsigmoid",
+    "tanhshrink",
+    "softshrink",
+    "none",
+    "linear",
+    "identity",
+]
+
+TrainingModeName = Literal["pointwise", "pairwise", "listwise"]
+
+TaskTypeName = Literal["binary", "regression"]

{nextrec-0.4.21 → nextrec-0.4.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextrec"
-version = "0.4.21"
+version = "0.4.22"
 description = "A comprehensive recommendation library with match, ranking, and multi-task learning models"
 readme = "README.md"
 requires-python = ">=3.10"

{nextrec-0.4.21 → nextrec-0.4.22}/test/test_losses.py

@@ -12,8 +12,8 @@ from nextrec.loss import (
     SampledSoftmaxLoss,
     TripletLoss,
     WeightedBCELoss,
-    get_loss_fn,
 )
+from nextrec.utils.loss import get_loss_fn
 
 
 def test_focal_loss_binary_prefers_confident_logits():
@@ -126,8 +126,61 @@ class _DummyBinaryModel(BaseModel):  # type: ignore[misc]
         self.dummy = nn.Parameter(torch.zeros(1))
 
 
+class _DummyMultiTaskModel(BaseModel):  # type: ignore[misc]
+    @property
+    def model_name(self) -> str:
+        return "DummyMultiTask"
+
+    @property
+    def default_task(self) -> list[str]:
+        return ["binary", "binary"]
+
+    def forward(self, X_input):
+        return torch.zeros(1, 2)
+
+    def __init__(self):
+        super().__init__(
+            dense_features=[],
+            sparse_features=[],
+            sequence_features=[],
+            target=["y1", "y2"],
+            task=["binary", "binary"],
+        )
+        self.dummy = nn.Parameter(torch.zeros(1))
+
+
 def test_compile_acceptsloss_params():
     model = _DummyBinaryModel()
     model.compile(loss="focal", loss_params={"gamma": 1.5})
     assert isinstance(model.loss_fn[0], FocalLoss)
     assert model.loss_fn[0].gamma == 1.5
+
+
+def test_multitask_loss_ignores_negative_labels():
+    model = _DummyMultiTaskModel()
+    model.compile(loss="bce")
+
+    y_pred = torch.tensor([[0.9, 0.1], [0.2, 0.8], [0.7, 0.4]])
+    y_true = torch.tensor([[1.0, -1.0], [0.0, 1.0], [-1.0, -1.0]])
+
+    loss = model.compute_loss(y_pred, y_true)
+
+    task1_mask = y_true[:, 0] != -1
+    task2_mask = y_true[:, 1] != -1
+    task1_loss = model.loss_fn[0](y_pred[task1_mask, 0:1], y_true[task1_mask, 0:1])
+    task2_loss = model.loss_fn[1](y_pred[task2_mask, 1:2], y_true[task2_mask, 1:2])
+    expected = task1_loss + task2_loss
+    assert torch.allclose(loss, expected)
+
+
+def test_multitask_loss_skips_fully_missing_task():
+    model = _DummyMultiTaskModel()
+    model.compile(loss="bce")
+
+    y_pred = torch.tensor([[0.6, 0.3], [0.2, 0.9]])
+    y_true = torch.tensor([[1.0, -1.0], [0.0, -1.0]])
+
+    loss = model.compute_loss(y_pred, y_true)
+
+    task1_loss = model.loss_fn[0](y_pred[:, 0:1], y_true[:, 0:1])
+    assert torch.allclose(loss, task1_loss)

{nextrec-0.4.21 → nextrec-0.4.22}/test/test_ranking_models.py

@@ -1369,6 +1369,7 @@ class TestAFM:
         self, sample_sparse_features, sample_sequence_features, device
     ):
         model = AFM(
+            dense_features=[],
             sparse_features=sample_sparse_features,
             sequence_features=sample_sequence_features,
             attention_dim=16,
@@ -1386,6 +1387,7 @@ class TestAFM:
         batch_size,
     ):
         model = AFM(
+            dense_features=[],
             sparse_features=sample_sparse_features,
             sequence_features=sample_sequence_features,
             attention_dim=8,

nextrec-0.4.21/nextrec/__version__.py

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