nextrec 0.4.22__tar.gz → 0.4.24__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.22
+Version: 0.4.24
 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
@@ -69,7 +69,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.4.22-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.24-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -182,7 +182,7 @@ sequence_features = [
     SequenceFeature(name='sequence_1', vocab_size=int(df['sequence_1'].apply(lambda x: max(x)).max() + 1), embedding_dim=16, padding_idx=0, embedding_name='sparse_0_emb'),]
 
 mlp_params = {
-    "dims": [256, 128, 64],
+    "hidden_dims": [256, 128, 64],
     "activation": "relu",
     "dropout": 0.3,
 }
@@ -191,6 +191,8 @@ model = DIN(
     dense_features=dense_features,
     sparse_features=sparse_features,
     sequence_features=sequence_features,
+    behavior_feature_name="sequence_0",
+    candidate_feature_name="item_id",
     mlp_params=mlp_params,
     attention_hidden_units=[80, 40],
     attention_activation='sigmoid',
@@ -204,7 +206,7 @@ model = DIN(
     session_id="din_tutorial",                            # 实验id，用于存放训练日志
 )
 
-# 编译模型，设置优化器和损失函数
+# 编译模型，优化器/损失/学习率调度器统一在 compile 中设置
 model.compile(
             optimizer = "adam",
             optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
@@ -247,11 +249,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.24，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.24，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

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

@@ -8,7 +8,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.4.22-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.24-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -121,7 +121,7 @@ sequence_features = [
     SequenceFeature(name='sequence_1', vocab_size=int(df['sequence_1'].apply(lambda x: max(x)).max() + 1), embedding_dim=16, padding_idx=0, embedding_name='sparse_0_emb'),]
 
 mlp_params = {
-    "dims": [256, 128, 64],
+    "hidden_dims": [256, 128, 64],
     "activation": "relu",
     "dropout": 0.3,
 }
@@ -130,6 +130,8 @@ model = DIN(
     dense_features=dense_features,
     sparse_features=sparse_features,
     sequence_features=sequence_features,
+    behavior_feature_name="sequence_0",
+    candidate_feature_name="item_id",
     mlp_params=mlp_params,
     attention_hidden_units=[80, 40],
     attention_activation='sigmoid',
@@ -143,7 +145,7 @@ model = DIN(
     session_id="din_tutorial",                            # 实验id，用于存放训练日志
 )
 
-# 编译模型，设置优化器和损失函数
+# 编译模型，优化器/损失/学习率调度器统一在 compile 中设置
 model.compile(
             optimizer = "adam",
             optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
@@ -186,11 +188,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.24，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.24，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

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

@@ -8,7 +8,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.4.22-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.24-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 English | [中文文档](README.md)
@@ -126,7 +126,7 @@ sequence_features = [
     SequenceFeature(name='sequence_1', vocab_size=int(df['sequence_1'].apply(lambda x: max(x)).max() + 1), embedding_dim=16, padding_idx=0, embedding_name='sparse_0_emb'),]
 
 mlp_params = {
-    "dims": [256, 128, 64],
+    "hidden_dims": [256, 128, 64],
     "activation": "relu",
     "dropout": 0.3,
 }
@@ -148,7 +148,7 @@ model = DIN(
     session_id="din_tutorial",                            # experiment id for logs
 )
 
-# Compile model with optimizer and loss
+# Compile model; configure optimizer/loss/scheduler via compile()
 model.compile(
             optimizer = "adam",
             optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
@@ -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.22, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.24, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-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:
+The current version is 0.4.24. 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.22 → nextrec-0.4.24}/docs/en/Getting started guide.md

@@ -49,12 +49,13 @@ train_df, valid_df = train_test_split(df, test_size=0.2, random_state=2024)
 model = DeepFM(
     dense_features=dense_features,
     sparse_features=sparse_features,
-    mlp_params={"dims": [256, 128], "activation": "relu", "dropout": 0.2},
+    mlp_params={"hidden_dims": [256, 128], "activation": "relu", "dropout": 0.2},
     target="label",
     device="cpu",
     session_id="movielens_deepfm",   # manages logs and checkpoints
 )
 
+# Optimizer/loss/scheduler are configured via compile()
 model.compile(
     optimizer="adam",
     optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},

{nextrec-0.4.22 → nextrec-0.4.24}/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.22"
+release = "0.4.24"
 
 extensions = [
     "myst_parser",

{nextrec-0.4.22 → nextrec-0.4.24}/docs/rtd/index.md

@@ -57,6 +57,7 @@ model = DeepFM(
     session_id="deepfm_demo",
 )
 
+# Configure optimizer/loss/scheduler via compile()
 model.compile(
     optimizer="adam",
     optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},

{nextrec-0.4.22 → nextrec-0.4.24}/docs/zh//345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -49,12 +49,13 @@ train_df, valid_df = train_test_split(df, test_size=0.2, random_state=2024)
 model = DeepFM(
     dense_features=dense_features,
     sparse_features=sparse_features,
-    mlp_params={"dims": [256, 128], "activation": "relu", "dropout": 0.2},
+    mlp_params={"hidden_dims": [256, 128], "activation": "relu", "dropout": 0.2},
     target="label",
     device="cpu",
     session_id="movielens_deepfm",   # 管理实验日志与检查点
 )
 
+# 优化器/损失/学习率调度器统一在 compile 中设置
 model.compile(
     optimizer="adam",
     optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},

nextrec-0.4.24/nextrec/__version__.py

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

{nextrec-0.4.22 → nextrec-0.4.24}/nextrec/basic/layers.py

@@ -20,6 +20,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.torch_utils import get_initializer
+from nextrec.utils.types import ActivationName
 
 
 class PredictionLayer(nn.Module):
@@ -590,71 +591,48 @@ class MLP(nn.Module):
     def __init__(
         self,
         input_dim: int,
-        output_layer: bool = True,
-        dims: list[int] | None = None,
+        hidden_dims: list[int] | None = None,
+        output_dim: int | None = 1,
         dropout: float = 0.0,
-        activation: Literal[
-            "dice",
-            "relu",
-            "relu6",
-            "elu",
-            "selu",
-            "leaky_relu",
-            "prelu",
-            "gelu",
-            "sigmoid",
-            "tanh",
-            "softplus",
-            "softsign",
-            "hardswish",
-            "mish",
-            "silu",
-            "swish",
-            "hardsigmoid",
-            "tanhshrink",
-            "softshrink",
-            "none",
-            "linear",
-            "identity",
-        ] = "relu",
-        use_norm: bool = True,
-        norm_type: Literal["batch_norm", "layer_norm"] = "layer_norm",
+        activation: ActivationName = "relu",
+        norm_type: Literal["batch_norm", "layer_norm", "none"] = "none",
+        output_activation: ActivationName = "none",
     ):
         """
         Multi-Layer Perceptron (MLP) module.
 
         Args:
             input_dim: Dimension of the input features.
-            output_layer: Whether to include the final output layer. If False, the MLP will output the last hidden layer, else it will output a single value.
-            dims: List of hidden layer dimensions. If None, no hidden layers are added.
+            output_dim: Output dimension of the final layer. If None, no output layer is added.
+            hidden_dims: List of hidden layer dimensions. If None, no hidden layers are added.
             dropout: Dropout rate between layers.
             activation: Activation function to use between layers.
-            use_norm: Whether to use normalization layers.
-            norm_type: Type of normalization to use ("batch_norm" or "layer_norm").
+            norm_type: Type of normalization to use ("batch_norm", "layer_norm", or "none").
+            output_activation: Activation function applied after the output layer.
         """
         super().__init__()
-        if dims is None:
-            dims = []
+        hidden_dims = hidden_dims or []
         layers = []
         current_dim = input_dim
-        for i_dim in dims:
+        for i_dim in hidden_dims:
             layers.append(nn.Linear(current_dim, i_dim))
-            if use_norm:
-                if norm_type == "batch_norm":
-                    # **IMPORTANT** be careful when using BatchNorm1d in distributed training, nextrec does not support sync batch norm now
-                    layers.append(nn.BatchNorm1d(i_dim))
-                elif norm_type == "layer_norm":
-                    layers.append(nn.LayerNorm(i_dim))
-                else:
-                    raise ValueError(f"Unsupported norm_type: {norm_type}")
+            if norm_type == "batch_norm":
+                # **IMPORTANT** be careful when using BatchNorm1d in distributed training, nextrec does not support sync batch norm now
+                layers.append(nn.BatchNorm1d(i_dim))
+            elif norm_type == "layer_norm":
+                layers.append(nn.LayerNorm(i_dim))
+            elif norm_type != "none":
+                raise ValueError(f"Unsupported norm_type: {norm_type}")
 
             layers.append(activation_layer(activation))
             layers.append(nn.Dropout(p=dropout))
             current_dim = i_dim
         # output layer
-        if output_layer:
-            layers.append(nn.Linear(current_dim, 1))
-            self.output_dim = 1
+        if output_dim is not None:
+            layers.append(nn.Linear(current_dim, output_dim))
+            if output_activation != "none":
+                layers.append(activation_layer(output_activation))
+            self.output_dim = output_dim
         else:
             self.output_dim = current_dim
         self.mlp = nn.Sequential(*layers)
@@ -663,6 +641,47 @@ class MLP(nn.Module):
         return self.mlp(x)
 
 
+class GateMLP(nn.Module):
+    """
+    Lightweight gate network: sigmoid MLP scaled by a constant factor.
+
+    Args:
+        input_dim: Dimension of the input features.
+        hidden_dim: Dimension of the hidden layer. If None, defaults to output_dim.
+        output_dim: Output dimension of the gate.
+        activation: Activation function to use in the hidden layer.
+        dropout: Dropout rate between layers.
+        use_bn: Whether to use batch normalization.
+        scale_factor: Scaling factor applied to the sigmoid output.
+    """
+
+    def __init__(
+        self,
+        input_dim: int,
+        hidden_dim: int | None,
+        output_dim: int,
+        activation: ActivationName = "relu",
+        dropout: float = 0.0,
+        use_bn: bool = False,
+        scale_factor: float = 2.0,
+    ) -> None:
+        super().__init__()
+        hidden_dim = output_dim if hidden_dim is None else hidden_dim
+        self.gate = MLP(
+            input_dim=input_dim,
+            hidden_dims=[hidden_dim],
+            output_dim=output_dim,
+            activation=activation,
+            dropout=dropout,
+            norm_type="batch_norm" if use_bn else "none",
+            output_activation="sigmoid",
+        )
+        self.scale_factor = scale_factor
+
+    def forward(self, inputs: torch.Tensor) -> torch.Tensor:
+        return self.gate(inputs) * self.scale_factor
+
+
 class FM(nn.Module):
     def __init__(self, reduce_sum: bool = True):
         super().__init__()
@@ -1007,3 +1026,34 @@ class RMSNorm(torch.nn.Module):
         variance = torch.mean(x**2, dim=-1, keepdim=True)
         x_normalized = x * torch.rsqrt(variance + self.eps)
         return self.weight * x_normalized
+
+
+class DomainBatchNorm(nn.Module):
+    """Domain-specific BatchNorm (applied per-domain with a shared interface)."""
+
+    def __init__(self, num_features: int, num_domains: int):
+        super().__init__()
+        if num_domains < 1:
+            raise ValueError("num_domains must be >= 1")
+        self.bns = nn.ModuleList(
+            [nn.BatchNorm1d(num_features) for _ in range(num_domains)]
+        )
+
+    def forward(self, x: torch.Tensor, domain_mask: torch.Tensor) -> torch.Tensor:
+        if x.dim() != 2:
+            raise ValueError("DomainBatchNorm expects 2D inputs [B, D].")
+        output = x.clone()
+        if domain_mask.dim() == 1:
+            domain_ids = domain_mask.long()
+            for idx, bn in enumerate(self.bns):
+                mask = domain_ids == idx
+                if mask.any():
+                    output[mask] = bn(x[mask])
+            return output
+        if domain_mask.dim() != 2:
+            raise ValueError("domain_mask must be 1D indices or 2D one-hot mask.")
+        for idx, bn in enumerate(self.bns):
+            mask = domain_mask[:, idx] > 0
+            if mask.any():
+                output[mask] = bn(x[mask])
+        return output