nextrec 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

nextrec/models/ranking/din.py

@@ -1,18 +1,62 @@
 """
 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
 import torch.nn as nn
 
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import EmbeddingLayer, MLP, AttentionPoolingLayer, PredictionLayer
+from nextrec.basic.layers import (
+    EmbeddingLayer,
+    MLP,
+    AttentionPoolingLayer,
+    PredictionLayer,
+)
 from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
@@ -24,28 +68,41 @@ class DIN(BaseModel):
     @property
     def default_task(self):
         return "binary"
-    
-    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',
-                 attention_use_softmax: bool = True,
-                 target: list[str] = [],
-                 task: str | list[str] | None = None,
-                 optimizer: str = "adam",
-                 optimizer_params: dict = {},
-                 loss: str | nn.Module | None = "bce",
-                 loss_params: dict | list[dict] | None = None,
-                 device: str = 'cpu',
-                 embedding_l1_reg=1e-6,
-                 dense_l1_reg=1e-5,
-                 embedding_l2_reg=1e-5,
-                 dense_l2_reg=1e-4,
-                 **kwargs):
-        
+
+    def __init__(
+        self,
+        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] | str | None = None,
+        task: str | list[str] | None = None,
+        optimizer: str = "adam",
+        optimizer_params: dict | None = None,
+        loss: str | nn.Module | None = "bce",
+        loss_params: dict | list[dict] | None = None,
+        device: str = "cpu",
+        embedding_l1_reg=1e-6,
+        dense_l1_reg=1e-5,
+        embedding_l2_reg=1e-5,
+        dense_l2_reg=1e-4,
+        **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,
@@ -57,43 +114,52 @@ class DIN(BaseModel):
             dense_l1_reg=dense_l1_reg,
             embedding_l2_reg=embedding_l2_reg,
             dense_l2_reg=dense_l2_reg,
-            **kwargs
+            **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")
-        
-        self.behavior_feature = sequence_features[0]  # User behavior sequence
-        self.candidate_feature = sparse_features[-1] if sparse_features else None  # Candidate item
-        
-        # 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
-        
-        # All features for embedding
-        self.all_features = dense_features + sparse_features + sequence_features
+            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")
+
+        if candidate_feature_name is None:
+            raise ValueError("DIN requires an explicit candidate_feature_name")
+
+        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]
+
+        # 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)
-        
+
         # Attention layer for behavior sequence
         behavior_emb_dim = self.behavior_feature.embedding_dim
         self.candidate_attention_proj = None
-        if self.candidate_feature is not None and self.candidate_feature.embedding_dim != behavior_emb_dim:
-            self.candidate_attention_proj = nn.Linear(self.candidate_feature.embedding_dim, behavior_emb_dim)
+        if (
+            self.candidate_feature is not None
+            and self.candidate_feature.embedding_dim != behavior_emb_dim
+        ):
+            self.candidate_attention_proj = nn.Linear(
+                self.candidate_feature.embedding_dim, behavior_emb_dim
+            )
         self.attention = AttentionPoolingLayer(
             embedding_dim=behavior_emb_dim,
             hidden_units=attention_hidden_units,
             activation=attention_activation,
-            use_softmax=attention_use_softmax
+            use_softmax=attention_use_softmax,
         )
-        
+
         # Calculate MLP input dimension
         # candidate + attention_pooled_behavior + other_sparse + dense
         mlp_input_dim = 0
@@ -101,16 +167,18 @@ class DIN(BaseModel):
             mlp_input_dim += self.candidate_feature.embedding_dim
         mlp_input_dim += behavior_emb_dim  # attention pooled
         mlp_input_dim += sum([f.embedding_dim for f in self.other_sparse_features])
-        mlp_input_dim += sum([getattr(f, "embedding_dim", 1) or 1 for f in dense_features])
-        
+        mlp_input_dim += sum(
+            [getattr(f, "embedding_dim", 1) or 1 for f in dense_features]
+        )
+
         # MLP for final prediction
         self.mlp = MLP(input_dim=mlp_input_dim, **mlp_params)
         self.prediction_layer = PredictionLayer(task_type=self.task)
 
         # Register regularization weights
         self.register_regularization_weights(
-            embedding_attr='embedding',
-            include_modules=['attention', 'mlp', 'candidate_attention_proj']
+            embedding_attr="embedding",
+            include_modules=["attention", "mlp", "candidate_attention_proj"],
         )
 
         self.compile(
@@ -122,62 +190,60 @@ 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]
         behavior_emb = self.embedding.embed_dict[self.behavior_feature.embedding_name](
             behavior_seq
         )  # [B, seq_len, emb_dim]
-        
+
         # Create mask for padding
         if self.behavior_feature.padding_idx is not None:
-            mask = (behavior_seq != self.behavior_feature.padding_idx).unsqueeze(-1).float()
+            mask = (
+                (behavior_seq != self.behavior_feature.padding_idx)
+                .unsqueeze(-1)
+                .float()
+            )
         else:
             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)
-        
+
         # Other sparse features
         for feat in self.other_sparse_features:
-            feat_emb = self.embedding.embed_dict[feat.embedding_name](x[feat.name].long())
+            feat_emb = self.embedding.embed_dict[feat.embedding_name](
+                x[feat.name].long()
+            )
             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]
-        
+
         # MLP prediction
         y = self.mlp(concat_input)  # [B, 1]
         return self.prediction_layer(y)

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,
@@ -30,27 +64,38 @@ class FiBiNET(BaseModel):
     @property
     def default_task(self):
         return "binary"
-    
-    def __init__(self,
-                 dense_features: list[DenseFeature] | list = [],
-                 sparse_features: list[SparseFeature] | list = [],
-                 sequence_features: list[SequenceFeature] | list = [],
-                 mlp_params: dict = {},
-                 bilinear_type: str = "field_interaction",
-                 senet_reduction: int = 3,
-                 target: list[str] | list = [],
-                 task: str | list[str] | None = None,
-                 optimizer: str = "adam",
-                 optimizer_params: dict = {},
-                 loss: str | nn.Module | None = "bce",
-                 loss_params: dict | list[dict] | None = None,
-                 device: str = 'cpu',
-                 embedding_l1_reg=1e-6,
-                 dense_l1_reg=1e-5,
-                 embedding_l2_reg=1e-5,
-                 dense_l2_reg=1e-4,
-                 **kwargs):
-        
+
+    def __init__(
+        self,
+        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] | str | None = None,
+        task: str | list[str] | None = None,
+        optimizer: str = "adam",
+        optimizer_params: dict | None = None,
+        loss: str | nn.Module | None = "bce",
+        loss_params: dict | list[dict] | None = None,
+        device: str = "cpu",
+        embedding_l1_reg=1e-6,
+        dense_l1_reg=1e-5,
+        embedding_l2_reg=1e-5,
+        dense_l2_reg=1e-4,
+        **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,
@@ -62,39 +107,61 @@ class FiBiNET(BaseModel):
             dense_l1_reg=dense_l1_reg,
             embedding_l2_reg=embedding_l2_reg,
             dense_l2_reg=dense_l2_reg,
-            **kwargs
+            **kwargs,
         )
 
         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:
-            raise ValueError("FiBiNET requires at least two sparse/sequence features for interactions.")
+            raise ValueError(
+                "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
-        if any(f.embedding_dim != self.embedding_dim for f in self.interaction_features):
-            raise ValueError("All interaction features must share the same embedding_dim in FiBiNET.")
-
-        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,
+        if any(
+            f.embedding_dim != self.embedding_dim for f in self.interaction_features
+        ):
+            raise ValueError(
+                "All interaction features must share the same embedding_dim in FiBiNET."
+            )
+
+        self.senet = SENETLayer(
+            num_fields=self.num_fields, reduction_ratio=senet_reduction
         )
 
+        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)
 
@@ -105,8 +172,14 @@ class FiBiNET(BaseModel):
 
         # Register regularization weights
         self.register_regularization_weights(
-            embedding_attr='embedding',
-            include_modules=['linear', 'senet', 'bilinear_standard', 'bilinear_senet', 'mlp']
+            embedding_attr="embedding",
+            include_modules=[
+                "linear",
+                "senet",
+                "mlp",
+                "interaction_E",
+                "interaction_V",
+            ],
         )
 
         self.compile(
@@ -117,15 +190,24 @@ class FiBiNET(BaseModel):
         )
 
     def forward(self, x):
-        input_linear = self.embedding(x=x, features=self.linear_features, squeeze_dim=True)
+        input_linear = self.embedding(
+            x=x, features=self.linear_features, squeeze_dim=True
+        )
         y_linear = self.linear(input_linear)
 
-        field_emb = self.embedding(x=x, features=self.interaction_features, squeeze_dim=False)
+        field_emb = self.embedding(
+            x=x, features=self.interaction_features, squeeze_dim=False
+        )
         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