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

nextrec/models/multi_task/poso.py

@@ -46,7 +46,8 @@ from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 from nextrec.basic.layers import EmbeddingLayer, MLP, PredictionLayer
 from nextrec.basic.activation import activation_layer
 from nextrec.basic.model import BaseModel
-from nextrec.utils.model import merge_features
+
+from nextrec.utils.model import select_features
 
 
 class POSOGate(nn.Module):
@@ -295,15 +296,18 @@ class POSO(BaseModel):
 
     def __init__(
         self,
-        main_dense_features: list[DenseFeature] | None,
-        main_sparse_features: list[SparseFeature] | None,
-        main_sequence_features: list[SequenceFeature] | None,
-        pc_dense_features: list[DenseFeature] | None,
-        pc_sparse_features: list[SparseFeature] | None,
-        pc_sequence_features: list[SequenceFeature] | None,
+        dense_features: list[DenseFeature] | None,
+        sparse_features: list[SparseFeature] | None,
+        sequence_features: list[SequenceFeature] | None,
+        main_dense_features: list[str] | None,
+        main_sparse_features: list[str] | None,
+        main_sequence_features: list[str] | None,
+        pc_dense_features: list[str] | None,
+        pc_sparse_features: list[str] | None,
+        pc_sequence_features: list[str] | None,
         tower_params_list: list[dict],
         target: list[str],
-        task: str | list[str] | None = None,
+        task: str | list[str] = "binary",
         architecture: str = "mlp",
         # POSO gating defaults
         gate_hidden_dim: int = 32,
@@ -329,40 +333,32 @@ class POSO(BaseModel):
         dense_l2_reg: float = 1e-4,
         **kwargs,
     ):
-        # Keep explicit copies of main and PC features
-        self.main_dense_features = list(main_dense_features or [])
-        self.main_sparse_features = list(main_sparse_features or [])
-        self.main_sequence_features = list(main_sequence_features or [])
-        self.pc_dense_features = list(pc_dense_features or [])
-        self.pc_sparse_features = list(pc_sparse_features or [])
-        self.pc_sequence_features = list(pc_sequence_features or [])
         self.num_tasks = len(target)
 
-        if (
-            not self.pc_dense_features
-            and not self.pc_sparse_features
-            and not self.pc_sequence_features
-        ):
+        # Normalize task to match num_tasks
+        resolved_task = task
+        if resolved_task is None:
+            resolved_task = self.default_task
+        elif isinstance(resolved_task, str):
+            resolved_task = [resolved_task] * self.num_tasks
+        elif len(resolved_task) == 1 and self.num_tasks > 1:
+            resolved_task = resolved_task * self.num_tasks
+        elif len(resolved_task) != self.num_tasks:
             raise ValueError(
-                "POSO requires at least one PC feature for personalization."
+                f"Length of task ({len(resolved_task)}) must match number of targets ({self.num_tasks})."
             )
 
-        dense_features = merge_features(
-            self.main_dense_features, self.pc_dense_features
-        )
-        sparse_features = merge_features(
-            self.main_sparse_features, self.pc_sparse_features
-        )
-        sequence_features = merge_features(
-            self.main_sequence_features, self.pc_sequence_features
-        )
+        if len(tower_params_list) != self.num_tasks:
+            raise ValueError(
+                f"Number of tower params ({len(tower_params_list)}) must match number of tasks ({self.num_tasks})"
+            )
 
         super().__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
             sequence_features=sequence_features,
             target=target,
-            task=task or self.default_task,
+            task=resolved_task,
             device=device,
             embedding_l1_reg=embedding_l1_reg,
             dense_l1_reg=dense_l1_reg,
@@ -371,14 +367,42 @@ class POSO(BaseModel):
             **kwargs,
         )
 
-        self.loss = loss if loss is not None else "bce"
+        self.main_dense_feature_names = list(main_dense_features or [])
+        self.main_sparse_feature_names = list(main_sparse_features or [])
+        self.main_sequence_feature_names = list(main_sequence_features or [])
+        self.pc_dense_feature_names = list(pc_dense_features or [])
+        self.pc_sparse_feature_names = list(pc_sparse_features or [])
+        self.pc_sequence_feature_names = list(pc_sequence_features or [])
+
+        if loss is None:
+            self.loss = "bce"
+        self.loss = loss
+
         optimizer_params = optimizer_params or {}
 
-        self.num_tasks = len(target)
-        if len(tower_params_list) != self.num_tasks:
-            raise ValueError(
-                f"Number of tower params ({len(tower_params_list)}) must match number of tasks ({self.num_tasks})"
-            )
+        self.main_dense_features = select_features(
+            self.dense_features, self.main_dense_feature_names, "main_dense_features"
+        )
+        self.main_sparse_features = select_features(
+            self.sparse_features, self.main_sparse_feature_names, "main_sparse_features"
+        )
+        self.main_sequence_features = select_features(
+            self.sequence_features,
+            self.main_sequence_feature_names,
+            "main_sequence_features",
+        )
+
+        self.pc_dense_features = select_features(
+            self.dense_features, self.pc_dense_feature_names, "pc_dense_features"
+        )
+        self.pc_sparse_features = select_features(
+            self.sparse_features, self.pc_sparse_feature_names, "pc_sparse_features"
+        )
+        self.pc_sequence_features = select_features(
+            self.sequence_features,
+            self.pc_sequence_feature_names,
+            "pc_sequence_features",
+        )
 
         self.main_features = (
             self.main_dense_features
@@ -389,6 +413,13 @@ class POSO(BaseModel):
             self.pc_dense_features + self.pc_sparse_features + self.pc_sequence_features
         )
 
+        if not self.main_features:
+            raise ValueError("POSO requires at least one main feature.")
+        if not self.pc_features:
+            raise ValueError(
+                "POSO requires at least one PC feature for personalization."
+            )
+
         self.embedding = EmbeddingLayer(features=self.all_features)
         self.main_input_dim = self.embedding.get_input_dim(self.main_features)
         self.pc_input_dim = self.embedding.get_input_dim(self.pc_features)

nextrec/models/multi_task/share_bottom.py

@@ -69,7 +69,7 @@ class ShareBottom(BaseModel):
         target: list[str],
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | list[str | nn.Module] | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -80,14 +80,28 @@ class ShareBottom(BaseModel):
         **kwargs,
     ):
 
+        optimizer_params = optimizer_params or {}
+
         self.num_tasks = len(target)
 
+        resolved_task = task
+        if resolved_task is None:
+            resolved_task = self.default_task
+        elif isinstance(resolved_task, str):
+            resolved_task = [resolved_task] * self.num_tasks
+        elif len(resolved_task) == 1 and self.num_tasks > 1:
+            resolved_task = resolved_task * self.num_tasks
+        elif len(resolved_task) != self.num_tasks:
+            raise ValueError(
+                f"Length of task ({len(resolved_task)}) must match number of targets ({self.num_tasks})."
+            )
+
         super(ShareBottom, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
             sequence_features=sequence_features,
             target=target,
-            task=task or self.default_task,
+            task=resolved_task,
             device=device,
             embedding_l1_reg=embedding_l1_reg,
             dense_l1_reg=dense_l1_reg,

nextrec/models/ranking/afm.py

@@ -1,7 +1,7 @@
 """
 Date: create on 09/11/2025
-Checkpoint: edit on 06/12/2025
-Author: Yang Zhou,zyaztec@gmail.com
+Checkpoint: edit on 09/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
 Reference:
 [1] Xiao J, Ye H, He X, et al. Attentional factorization machines: Learning the weight of
 feature interactions via attention networks[C]//IJCAI. 2017: 3119-3125.
@@ -55,15 +55,15 @@ class AFM(BaseModel):
 
     def __init__(
         self,
-        dense_features: list[DenseFeature] | list = [],
-        sparse_features: list[SparseFeature] | list = [],
-        sequence_features: list[SequenceFeature] | list = [],
+        dense_features: list[DenseFeature] | None = None,
+        sparse_features: list[SparseFeature] | None = None,
+        sequence_features: list[SequenceFeature] | None = None,
         attention_dim: int = 32,
         attention_dropout: float = 0.0,
-        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",
@@ -74,6 +74,13 @@ class AFM(BaseModel):
         **kwargs,
     ):
 
+        dense_features = dense_features or []
+        sparse_features = sparse_features or []
+        sequence_features = sequence_features or []
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(AFM, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -88,13 +95,6 @@ class AFM(BaseModel):
             **kwargs,
         )
 
-        if target is None:
-            target = []
-        if optimizer_params is None:
-            optimizer_params = {}
-        if loss is None:
-            loss = "bce"
-
         self.fm_features = sparse_features + sequence_features
         if len(self.fm_features) < 2:
             raise ValueError(

nextrec/models/ranking/autoint.py

@@ -1,7 +1,7 @@
 """
 Date: create on 09/11/2025
-Checkpoint: edit on 24/11/2025
-Author: Yang Zhou,zyaztec@gmail.com
+Checkpoint: edit on 09/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
 Reference:
 [1] Song W, Shi C, Xiao Z, et al. Autoint: Automatic feature interaction learning via
 self-attentive neural networks[C]//Proceedings of the 28th ACM international conference

nextrec/models/ranking/dcn.py

@@ -1,11 +1,53 @@
 """
 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] Wang R, Fu B, Fu G, et al. Deep & cross network for ad click predictions[C]
-        //Proceedings of the ADKDD'17. 2017: 1-7.
-        (https://arxiv.org/abs/1708.05123)
+[1] Wang R, Fu B, Fu G, et al. Deep & cross network for ad click predictions[C]
+//Proceedings of the ADKDD'17. 2017: 1-7.
+(https://arxiv.org/abs/1708.05123)
+
+Deep & Cross Network (DCN) mixes explicit polynomial feature crosses with a deep
+MLP branch to capture both low-order and high-order interactions for CTR-style
+tasks. Cross Layers repeatedly apply x_{l+1} = x0 * (w_l^T x_l) + b_l + x_l,
+which expands feature crosses with linear parameter growth, while the deep branch
+learns nonlinear patterns on the same shared embeddings. The final prediction
+concatenates (or solely uses) cross outputs before a linear head, offering a
+balanced trade-off between interpretability and expressiveness.
+
+Workflow:
+  (1) Embed sparse/sequence features and concatenate with dense inputs
+  (2) Cross Network builds explicit polynomial interactions via residual crosses
+  (3) Optional MLP models implicit high-order nonlinear relationships
+  (4) Cross output (and deep output if enabled) are fused for the final logit
+  (5) Prediction layer maps logits to binary CTR scores
+
+Key Advantages:
+- Explicit, low-cost cross features with O(L * d) parameters
+- Residual cross formulation stabilizes optimization
+- Optional deep tower increases capacity without losing interpretability
+- Shared embeddings reduce redundant parameters and preprocessing
+- Strong, simple baseline for ad/recommendation ranking tasks
+
+DCN（Deep & Cross Network）通过 Cross 层显式生成多项式特征交互，同时可选 Deep
+分支学习高阶非线性关系，两者共享 embedding。Cross 层按
+x_{l+1} = x0 * (w_l^T x_l) + b_l + x_l 递推，参数线性增长且具解释性；
+Deep 分支提升表达能力；最终将 Cross（及 Deep）结果送入线性层与预测层，形成兼具
+效率与效果的 CTR/CVR 预估模型。
+
+流程：
+  (1) 对稀疏/序列特征做 embedding，并与稠密特征拼接
+  (2) Cross 层以残差形式显式构造多阶交叉特征
+  (3) 可选 MLP 学习隐式高阶非线性交互
+  (4) 将 Cross（及 Deep）输出融合后接线性头得到 logit
+  (5) 预测层输出二分类 CTR 分数
+
+主要优点：
+- 显式交叉特征、参数线性增长、易解释
+- 残差式 Cross 提升训练稳定性
+- Deep 分支可灵活增强模型容量
+- 共享 embedding，减少冗余参数与预处理
+- CTR/CVR 排序任务的简洁强基线
 """
 
 import torch
@@ -48,15 +90,15 @@ class DCN(BaseModel):
 
     def __init__(
         self,
-        dense_features: list[DenseFeature],
-        sparse_features: list[SparseFeature],
-        sequence_features: list[SequenceFeature],
+        dense_features: list[DenseFeature] | None = None,
+        sparse_features: list[SparseFeature] | None = None,
+        sequence_features: list[SequenceFeature] | None = None,
         cross_num: int = 3,
         mlp_params: dict | None = None,
-        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",
@@ -67,6 +109,13 @@ class DCN(BaseModel):
         **kwargs,
     ):
 
+        dense_features = dense_features or []
+        sparse_features = sparse_features or []
+        sequence_features = sequence_features or []
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(DCN, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -81,13 +130,6 @@ class DCN(BaseModel):
             **kwargs,
         )
 
-        self.loss = loss
-        if self.loss is None:
-            self.loss = "bce"
-
-        # All features
-        self.all_features = dense_features + sparse_features + sequence_features
-
         # Embedding layer
         self.embedding = EmbeddingLayer(features=self.all_features)
 
@@ -104,10 +146,10 @@ class DCN(BaseModel):
         )
         input_dim = emb_dim_total + dense_input_dim
 
-        # Cross Network
+        # Cross Network for explicit feature crosses
         self.cross_network = CrossNetwork(input_dim=input_dim, num_layers=cross_num)
 
-        # Deep Network (optional)
+        # Deep Network for implicit high-order interactions
         if mlp_params is not None:
             self.use_dnn = True
             self.mlp = MLP(input_dim=input_dim, **mlp_params)