nextrec 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

nextrec/models/ranking/din.py

@@ -1,11 +1,50 @@
 """
 Date: create on 09/11/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Checkpoint: edit on 09/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
 Reference:
-    [1] Zhou G, Zhu X, Song C, et al. Deep interest network for click-through rate prediction[C]
-        //Proceedings of the 24th ACM SIGKDD international conference on knowledge discovery & data mining. 2018: 1059-1068.
-        (https://arxiv.org/abs/1706.06978)
+[1] Zhou G, Zhu X, Song C, et al. Deep interest network for click-through rate
+prediction[C] //Proceedings of the 24th ACM SIGKDD international conference on
+knowledge discovery & data mining. 2018: 1059-1068.
+(https://arxiv.org/abs/1706.06978)
+
+Deep Interest Network (DIN) is a CTR model that builds a target-aware user
+representation by attending over the historical behavior sequence. Instead of
+compressing all behaviors into one static vector, DIN highlights the behaviors
+most relevant to the current candidate item, enabling adaptive interest
+modeling for each request.
+
+Pipeline:
+  (1) Embed candidate item, user behavior sequence, and other sparse/dense fields
+  (2) Use a small attention MLP to score each historical behavior against the
+      candidate embedding
+  (3) Apply masked weighted pooling to obtain a target-specific interest vector
+  (4) Concatenate candidate, interest vector, other sparse embeddings, and dense
+      features
+  (5) Feed the combined representation into an MLP for final prediction
+
+Key Advantages:
+- Target-aware attention captures fine-grained interests per candidate item
+- Adaptive pooling handles diverse behavior patterns without heavy feature crafting
+- Masked weighting reduces noise from padded sequence positions
+- Easily incorporates additional sparse/dense context features alongside behavior
+
+DIN 是一个 CTR 预估模型，通过对用户历史行为序列进行目标感知的注意力加权，
+构建针对当前候选物品的兴趣表示。它不是将全部行为压缩为固定向量，而是突出
+与候选物品最相关的行为，实现请求级的自适应兴趣建模。
+
+处理流程：
+  (1) 对候选物品、用户行为序列及其他稀疏/稠密特征做 embedding
+  (2) 使用小型注意力 MLP 计算每个历史行为与候选 embedding 的相关性
+  (3) 通过掩码加权池化得到目标特定的兴趣向量
+  (4) 拼接候选、兴趣向量、其他稀疏 embedding 与稠密特征
+  (5) 输入 MLP 完成最终点击率预测
+
+主要优点：
+- 目标感知注意力捕捉候选级的细粒度兴趣
+- 自适应池化应对多样化行为模式，减少手工特征工程
+- 掩码加权降低序列填充位置的噪声
+- 便捷融合行为与额外稀疏/稠密上下文信息
 """
 
 import torch
@@ -32,17 +71,19 @@ class DIN(BaseModel):
 
     def __init__(
         self,
-        dense_features: list[DenseFeature],
-        sparse_features: list[SparseFeature],
-        sequence_features: list[SequenceFeature],
-        mlp_params: dict,
-        attention_hidden_units: list[int] = [80, 40],
-        attention_activation: str = "sigmoid",
+        dense_features: list[DenseFeature] | None = None,
+        sparse_features: list[SparseFeature] | None = None,
+        sequence_features: list[SequenceFeature] | None = None,
+        behavior_feature_name: str | None = None,
+        candidate_feature_name: str | None = None,
+        mlp_params: dict | None = None,
+        attention_hidden_units: list[int] | None = None,
+        attention_activation: str = "dice",
         attention_use_softmax: bool = True,
-        target: list[str] = [],
+        target: list[str] | str | None = None,
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -53,6 +94,15 @@ class DIN(BaseModel):
         **kwargs,
     ):
 
+        dense_features = dense_features or []
+        sparse_features = sparse_features or []
+        sequence_features = sequence_features or []
+        mlp_params = mlp_params or {}
+        attention_hidden_units = attention_hidden_units or [80, 40]
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(DIN, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -67,30 +117,28 @@ class DIN(BaseModel):
             **kwargs,
         )
 
-        self.loss = loss
-        if self.loss is None:
-            self.loss = "bce"
-
-        # Features classification
-        # DIN requires: candidate item + user behavior sequence + other features
+        # DIN requires: user behavior sequence + candidate item + other features
         if len(sequence_features) == 0:
             raise ValueError(
                 "DIN requires at least one sequence feature for user behavior history"
             )
+        if behavior_feature_name is None:
+            raise ValueError("DIN requires an explicit behavior_feature_name")
 
-        self.behavior_feature = sequence_features[0]  # User behavior sequence
-        self.candidate_feature = (
-            sparse_features[-1] if sparse_features else None
-        )  # Candidate item
+        if candidate_feature_name is None:
+            raise ValueError("DIN requires an explicit candidate_feature_name")
 
-        # Other features (excluding behavior sequence in final concatenation)
-        self.other_sparse_features = (
-            sparse_features[:-1] if self.candidate_feature else sparse_features
-        )
-        self.dense_features_list = dense_features
+        self.behavior_feature = [
+            f for f in sequence_features if f.name == behavior_feature_name
+        ][0]
+        self.candidate_feature = [
+            f for f in sparse_features if f.name == candidate_feature_name
+        ][0]
 
-        # All features for embedding
-        self.all_features = dense_features + sparse_features + sequence_features
+        # Other sparse features
+        self.other_sparse_features = [
+            f for f in sparse_features if f.name != self.candidate_feature.name
+        ]
 
         # Embedding layer
         self.embedding = EmbeddingLayer(features=self.all_features)
@@ -142,14 +190,13 @@ class DIN(BaseModel):
 
     def forward(self, x):
         # Get candidate item embedding
-        if self.candidate_feature:
-            candidate_emb = self.embedding.embed_dict[
-                self.candidate_feature.embedding_name
-            ](
-                x[self.candidate_feature.name].long()
-            )  # [B, emb_dim]
-        else:
-            candidate_emb = None
+        if self.candidate_feature is None:
+            raise ValueError("DIN requires a candidate item feature")
+        candidate_emb = self.embedding.embed_dict[
+            self.candidate_feature.embedding_name
+        ](
+            x[self.candidate_feature.name].long()
+        )  # [B, emb_dim]
 
         # Get behavior sequence embedding
         behavior_seq = x[self.behavior_feature.name].long()  # [B, seq_len]
@@ -168,24 +215,17 @@ class DIN(BaseModel):
             mask = (behavior_seq != 0).unsqueeze(-1).float()
 
         # Apply attention pooling
-        if candidate_emb is not None:
-            candidate_query = candidate_emb
-            if self.candidate_attention_proj is not None:
-                candidate_query = self.candidate_attention_proj(candidate_query)
-            pooled_behavior = self.attention(
-                query=candidate_query, keys=behavior_emb, mask=mask
-            )  # [B, emb_dim]
-        else:
-            # If no candidate, use mean pooling
-            pooled_behavior = torch.sum(behavior_emb * mask, dim=1) / (
-                mask.sum(dim=1) + 1e-9
-            )
+        candidate_query = candidate_emb
+        if self.candidate_attention_proj is not None:
+            candidate_query = self.candidate_attention_proj(candidate_query)
+        pooled_behavior = self.attention(
+            query=candidate_query, keys=behavior_emb, mask=mask
+        )  # [B, emb_dim]
 
         # Get other features
         other_embeddings = []
 
-        if candidate_emb is not None:
-            other_embeddings.append(candidate_emb)
+        other_embeddings.append(candidate_emb)
 
         other_embeddings.append(pooled_behavior)
 
@@ -197,11 +237,9 @@ class DIN(BaseModel):
             other_embeddings.append(feat_emb)
 
         # Dense features
-        for feat in self.dense_features_list:
-            val = x[feat.name].float()
-            if val.dim() == 1:
-                val = val.unsqueeze(1)
-            other_embeddings.append(val)
+        for feat in self.dense_features:
+            dense_val = self.embedding.project_dense(feat, x)
+            other_embeddings.append(dense_val)
 
         # Concatenate all features
         concat_input = torch.cat(other_embeddings, dim=-1)  # [B, total_dim]

nextrec/models/ranking/fibinet.py

@@ -1,10 +1,43 @@
 """
 Date: create on 09/11/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Checkpoint: edit on 09/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
 Reference:
-    [1] Huang T, Zhang Z, Zhang B, et al. FiBiNET: Combining feature importance and bilinear feature interaction
-        for click-through rate prediction[C]//RecSys. 2019: 169-177.
+[1] Huang T, Zhang Z, Zhang B, et al. FiBiNET: Combining feature importance and bilinear
+feature interaction for click-through rate prediction[C]//RecSys. 2019: 169-177.
+(https://arxiv.org/abs/1905.09433)
+
+FiBiNET (Feature Importance and Bilinear Interaction Network) is a CTR model that
+jointly learns which fields matter most and how they interact. It first uses SENET
+to produce field-wise importance weights and recalibrate embeddings, then applies a
+bilinear interaction layer to capture pairwise feature relationships with enhanced
+expressiveness.
+
+Pipeline:
+  (1) Embed sparse and sequence features that share a common embedding dimension
+  (2) SENET squeezes and excites across fields to generate importance scores
+  (3) Reweight embeddings with SENET scores to highlight informative fields
+  (4) Compute bilinear interactions on both the original and SENET-reweighted
+      embeddings to model pairwise relations
+  (5) Concatenate interaction outputs and feed them into an MLP alongside a linear
+      term for final prediction
+
+Key Advantages:
+- SENET recalibration emphasizes the most informative feature fields
+- Bilinear interactions explicitly model pairwise relationships beyond simple dot
+  products
+- Dual-path (standard + SENET-reweighted) interactions enrich representation power
+- Combines linear and deep components for both memorization and generalization
+
+FiBiNET 是一个 CTR 预估模型，通过 SENET 重新分配特征字段的重要性，再用双线性
+交互层捕捉成对特征关系。模型先对稀疏/序列特征做 embedding，SENET 生成字段权重并
+重标定 embedding，随后在原始和重标定的 embedding 上分别计算双线性交互，最后将
+交互结果与线性部分一起输入 MLP 得到预测。
+主要优点：
+- SENET 让模型聚焦最重要的特征字段
+- 双线性交互显式建模特征对关系，表达力强于简单点积
+- 标准与重标定两路交互结合，丰富特征表示
+- 线性与深层结构并行，兼顾记忆与泛化
 """
 
 import torch
@@ -13,6 +46,7 @@ import torch.nn as nn
 from nextrec.basic.model import BaseModel
 from nextrec.basic.layers import (
     BiLinearInteractionLayer,
+    HadamardInteractionLayer,
     EmbeddingLayer,
     LR,
     MLP,
@@ -33,16 +67,17 @@ class FiBiNET(BaseModel):
 
     def __init__(
         self,
-        dense_features: list[DenseFeature] | list = [],
-        sparse_features: list[SparseFeature] | list = [],
-        sequence_features: list[SequenceFeature] | list = [],
-        mlp_params: dict = {},
+        dense_features: list[DenseFeature] | None = None,
+        sparse_features: list[SparseFeature] | None = None,
+        sequence_features: list[SequenceFeature] | None = None,
+        mlp_params: dict | None = None,
+        interaction_combo: str = "11",  # "0": Hadamard, "1": Bilinear
         bilinear_type: str = "field_interaction",
         senet_reduction: int = 3,
-        target: list[str] | list = [],
+        target: list[str] | str | None = None,
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -53,6 +88,14 @@ class FiBiNET(BaseModel):
         **kwargs,
     ):
 
+        dense_features = dense_features or []
+        sparse_features = sparse_features or []
+        sequence_features = sequence_features or []
+        mlp_params = mlp_params or {}
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(FiBiNET, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -68,11 +111,7 @@ class FiBiNET(BaseModel):
         )
 
         self.loss = loss
-        if self.loss is None:
-            self.loss = "bce"
-
         self.linear_features = sparse_features + sequence_features
-        self.deep_features = dense_features + sparse_features + sequence_features
         self.interaction_features = sparse_features + sequence_features
 
         if len(self.interaction_features) < 2:
@@ -80,7 +119,7 @@ class FiBiNET(BaseModel):
                 "FiBiNET requires at least two sparse/sequence features for interactions."
             )
 
-        self.embedding = EmbeddingLayer(features=self.deep_features)
+        self.embedding = EmbeddingLayer(features=self.all_features)
 
         self.num_fields = len(self.interaction_features)
         self.embedding_dim = self.interaction_features[0].embedding_dim
@@ -94,16 +133,34 @@ class FiBiNET(BaseModel):
         self.senet = SENETLayer(
             num_fields=self.num_fields, reduction_ratio=senet_reduction
         )
-        self.bilinear_standard = BiLinearInteractionLayer(
-            input_dim=self.embedding_dim,
-            num_fields=self.num_fields,
-            bilinear_type=bilinear_type,
-        )
-        self.bilinear_senet = BiLinearInteractionLayer(
-            input_dim=self.embedding_dim,
-            num_fields=self.num_fields,
-            bilinear_type=bilinear_type,
-        )
+
+        self.interaction_combo = interaction_combo
+
+        # E interaction layers: original embeddings
+        if interaction_combo[0] == "0":  # Hadamard
+            self.interaction_E = HadamardInteractionLayer(
+                num_fields=self.num_fields
+            )  # [B, num_pairs, D]
+        elif interaction_combo[0] == "1":  # Bilinear
+            self.interaction_E = BiLinearInteractionLayer(
+                input_dim=self.embedding_dim,
+                num_fields=self.num_fields,
+                bilinear_type=bilinear_type,
+            )  # [B, num_pairs, D]
+        else:
+            raise ValueError("interaction_combo must be '01' or '11'")
+
+        # V interaction layers: SENET reweighted embeddings
+        if interaction_combo[1] == "0":
+            self.interaction_V = HadamardInteractionLayer(num_fields=self.num_fields)
+        elif interaction_combo[1] == "1":
+            self.interaction_V = BiLinearInteractionLayer(
+                input_dim=self.embedding_dim,
+                num_fields=self.num_fields,
+                bilinear_type=bilinear_type,
+            )
+        else:
+            raise ValueError("Deep-FiBiNET SENET side must be '01' or '11'")
 
         linear_dim = sum([f.embedding_dim for f in self.linear_features])
         self.linear = LR(linear_dim)
@@ -119,9 +176,9 @@ class FiBiNET(BaseModel):
             include_modules=[
                 "linear",
                 "senet",
-                "bilinear_standard",
-                "bilinear_senet",
                 "mlp",
+                "interaction_E",
+                "interaction_V",
             ],
         )
 
@@ -143,9 +200,14 @@ class FiBiNET(BaseModel):
         )
         senet_emb = self.senet(field_emb)
 
-        bilinear_standard = self.bilinear_standard(field_emb).flatten(start_dim=1)
-        bilinear_senet = self.bilinear_senet(senet_emb).flatten(start_dim=1)
-        deep_input = torch.cat([bilinear_standard, bilinear_senet], dim=1)
+        out_E = self.interaction_E(field_emb)  # [B, num_pairs, D]
+
+        out_V = self.interaction_V(senet_emb)  # [B, num_pairs, D]
+
+        deep_input = torch.cat(
+            [out_E.flatten(start_dim=1), out_V.flatten(start_dim=1)], dim=1
+        )
+
         y_deep = self.mlp(deep_input)
 
         y = y_linear + y_deep

nextrec/models/ranking/fm.py

@@ -1,9 +1,41 @@
 """
 Date: create on 09/11/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Checkpoint: edit on 09/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
 Reference:
-    [1] Rendle S. Factorization machines[C]//ICDM. 2010: 995-1000.
+[1] Rendle S. Factorization machines[C]//ICDM. 2010: 995-1000.
+
+Factorization Machines (FM) capture second-order feature interactions with
+linear complexity by factorizing the pairwise interaction matrix. Each field
+is embedded into a latent vector; FM models the dot product of every pair of
+embeddings and sums them along with a linear term, enabling strong performance
+with sparse high-dimensional data and minimal feature engineering.
+
+Pipeline:
+  (1) Embed sparse and sequence fields into low-dimensional vectors
+  (2) Compute linear logit over concatenated embeddings
+  (3) Compute pairwise interaction logit via factorized dot products
+  (4) Sum linear + interaction terms and apply prediction layer
+
+Key Advantages:
+- Models pairwise interactions efficiently (O(nk) vs. O(n^2))
+- Works well on sparse inputs without handcrafted crosses
+- Simple architecture with strong baseline performance
+
+FM 是一种通过分解二阶特征交互矩阵、以线性复杂度建模特征对的 CTR 模型。
+每个特征映射为低维向量，FM 对任意特征对进行内积求和并叠加线性项，
+无需复杂特征工程即可在稀疏高维场景取得稳健效果。
+
+处理流程：
+  (1) 对稀疏/序列特征做 embedding
+  (2) 计算线性部分的 logit
+  (3) 计算嵌入对之间的二阶交互 logit
+  (4) 线性项与交互项求和，再通过预测层输出
+
+主要优点：
+- 线性复杂度建模二阶交互，效率高
+- 对稀疏特征友好，减少人工特征交叉
+- 结构简单、表现强健，常作 CTR 基线
 """
 
 import torch.nn as nn
@@ -29,13 +61,13 @@ class FM(BaseModel):
 
     def __init__(
         self,
-        dense_features: list[DenseFeature] | list = [],
-        sparse_features: list[SparseFeature] | list = [],
-        sequence_features: list[SequenceFeature] | list = [],
-        target: list[str] | list = [],
+        dense_features: list[DenseFeature] | None = None,
+        sparse_features: list[SparseFeature] | None = None,
+        sequence_features: list[SequenceFeature] | None = None,
+        target: list[str] | str | None = None,
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -46,6 +78,10 @@ class FM(BaseModel):
         **kwargs,
     ):
 
+        dense_features = dense_features or []
+        sparse_features = sparse_features or []
+        sequence_features = sequence_features or []
+
         super(FM, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,

nextrec/models/ranking/masknet.py

@@ -166,7 +166,7 @@ class MaskNet(BaseModel):
         dense_features: list[DenseFeature] | None = None,
         sparse_features: list[SparseFeature] | None = None,
         sequence_features: list[SequenceFeature] | None = None,
-        model_type: str = "parallel",  # "serial" or "parallel"
+        architecture: str = "parallel",  # "serial" or "parallel"
         num_blocks: int = 3,
         mask_hidden_dim: int = 64,
         block_hidden_dim: int = 256,
@@ -232,11 +232,11 @@ class MaskNet(BaseModel):
                 )
 
         self.v_emb_dim = self.num_fields * self.embedding_dim
-        self.model_type = model_type.lower()
-        assert self.model_type in (
+        self.architecture = architecture.lower()
+        assert self.architecture in (
             "serial",
             "parallel",
-        ), "model_type must be either 'serial' or 'parallel'."
+        ), "architecture must be either 'serial' or 'parallel'."
 
         self.num_blocks = max(1, num_blocks)
         self.block_hidden_dim = block_hidden_dim
@@ -244,7 +244,7 @@ class MaskNet(BaseModel):
             nn.Dropout(block_dropout) if block_dropout > 0 else nn.Identity()
         )
 
-        if self.model_type == "serial":
+        if self.architecture == "serial":
             self.first_block = MaskBlockOnEmbedding(
                 num_fields=self.num_fields,
                 embedding_dim=self.embedding_dim,
@@ -284,7 +284,7 @@ class MaskNet(BaseModel):
             self.output_layer = None
         self.prediction_layer = PredictionLayer(task_type=self.task)
 
-        if self.model_type == "serial":
+        if self.architecture == "serial":
             self.register_regularization_weights(
                 embedding_attr="embedding",
                 include_modules=["mask_blocks", "output_layer"],
@@ -306,7 +306,7 @@ class MaskNet(BaseModel):
         B = field_emb.size(0)
         v_emb_flat = field_emb.view(B, -1)  # flattened embeddings
 
-        if self.model_type == "parallel":
+        if self.architecture == "parallel":
             block_outputs = []
             for block in self.mask_blocks:
                 h = block(field_emb, v_emb_flat)  # [B, block_hidden_dim]