nextrec 0.2.6__py3-none-any.whl → 0.3.1__py3-none-any.whl

nextrec/models/ranking/deepfm.py

@@ -1,9 +1,46 @@
 """
 Date: create on 27/10/2025
+Checkpoint: edit on 24/11/2025
 Author:
     Yang Zhou,zyaztec@gmail.com
 Reference:
-    [1] Guo H, Tang R, Ye Y, et al. Deepfm: a factorization-machine based neural network for ctr prediction[J]. arXiv preprint arXiv:1703.04247, 2017.(https://arxiv.org/abs/1703.04247)
+    [1] Guo H, Tang R, Ye Y, et al. DeepFM: A factorization-machine based neural network
+        for CTR prediction[J]. arXiv preprint arXiv:1703.04247, 2017.
+        (https://arxiv.org/abs/1703.04247)
+
+DeepFM combines a Factorization Machine (FM) for explicit second-order feature
+interactions with a deep MLP for high-order nonlinear patterns. Both parts share
+the same embeddings, avoiding manual feature engineering and delivering strong CTR
+performance with end-to-end training.
+
+Workflow:
+  (1) Shared embeddings encode sparse/sequence fields; dense features are concatenated
+  (2) Wide (LR) term models first-order signals
+  (3) FM term captures pairwise interactions via inner products
+  (4) Deep MLP learns higher-order interactions over concatenated embeddings
+  (5) Outputs from wide, FM, and deep parts are summed before the final prediction
+
+Key Advantages:
+- Joint explicit (FM) and implicit (MLP) interaction modeling
+- Shared embeddings remove the need for manual cross features
+- Simple to train end-to-end with minimal feature engineering
+- Strong baseline for CTR/CVR style ranking tasks
+
+DeepFM 将 FM 的显式二阶特征交互与 MLP 的高阶非线性交互结合，三部分共享
+embedding，无需手工构造交叉特征即可端到端训练，常用于 CTR/CVR 预估。
+
+流程：
+  (1) 共享 embedding 处理稀疏/序列特征，稠密特征拼接
+  (2) Wide（LR）建模一阶信号
+  (3) FM 建模二阶交互
+  (4) MLP 学习高阶非线性交互
+  (5) Wide + FM + Deep 求和后进入预测
+
+主要优点：
+- 显式与隐式交互联合建模
+- 共享 embedding，减少人工交叉特征
+- 端到端训练简单，易于落地
+- CTR/CVR 任务的常用强基线
 """
 
 import torch
@@ -59,30 +96,19 @@ class DeepFM(BaseModel):
             
         self.fm_features = sparse_features + sequence_features
         self.deep_features = dense_features + sparse_features + sequence_features
-
         self.embedding = EmbeddingLayer(features=self.deep_features)
-
         fm_emb_dim_total = sum([f.embedding_dim for f in self.fm_features])
-        deep_emb_dim_total = sum([f.embedding_dim for f in self.deep_features if not isinstance(f, DenseFeature)])
-        dense_input_dim = sum([getattr(f, "embedding_dim", 1) or 1 for f in dense_features])
-
+        # deep_emb_dim_total = sum([f.embedding_dim for f in self.deep_features if not isinstance(f, DenseFeature)])
+        # dense_input_dim = sum([getattr(f, "embedding_dim", 1) or 1 for f in dense_features])
+        mlp_input_dim = self.embedding.input_dim
         self.linear = LR(fm_emb_dim_total)
         self.fm = FM(reduce_sum=True)
-        self.mlp = MLP(input_dim=deep_emb_dim_total + dense_input_dim, **mlp_params)
+        self.mlp = MLP(input_dim=mlp_input_dim, **mlp_params)
         self.prediction_layer = PredictionLayer(task_type=self.task_type)
 
         # Register regularization weights
-        self._register_regularization_weights(
-            embedding_attr='embedding',
-            include_modules=['linear', 'mlp']
-        )
-
-        self.compile(
-            optimizer=optimizer,
-            optimizer_params=optimizer_params,
-            loss=loss,
-            loss_params=loss_params,
-        )
+        self._register_regularization_weights(embedding_attr='embedding', include_modules=['linear', 'mlp'])
+        self.compile(optimizer=optimizer, optimizer_params=optimizer_params, loss=loss, loss_params=loss_params)
 
     def forward(self, x):
         input_deep = self.embedding(x=x, features=self.deep_features, squeeze_dim=True)

nextrec/models/ranking/dien.py

@@ -10,11 +10,135 @@ Reference:
 
 import torch
 import torch.nn as nn
+import torch.nn.functional as F
 
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import EmbeddingLayer, MLP, AttentionPoolingLayer, DynamicGRU, AUGRU, PredictionLayer
+from nextrec.basic.layers import EmbeddingLayer, MLP, AttentionPoolingLayer, PredictionLayer
 from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
+class AUGRU(nn.Module):
+    """Attention-aware GRU update gate used in DIEN (Zhou et al., 2019)."""
+    """
+    Attention-based GRU for DIEN
+    Uses attention scores to weight the update of hidden states
+    """
+    
+    def __init__(self, input_size, hidden_size, bias=True):
+        super().__init__()
+        self.input_size = input_size
+        self.hidden_size = hidden_size
+        
+        self.weight_ih = nn.Parameter(torch.randn(3 * hidden_size, input_size))
+        self.weight_hh = nn.Parameter(torch.randn(3 * hidden_size, hidden_size))
+        if bias:
+            self.bias_ih = nn.Parameter(torch.randn(3 * hidden_size))
+            self.bias_hh = nn.Parameter(torch.randn(3 * hidden_size))
+        else:
+            self.register_parameter('bias_ih', None)
+            self.register_parameter('bias_hh', None)
+        
+        self.reset_parameters()
+    
+    def reset_parameters(self):
+        std = 1.0 / (self.hidden_size) ** 0.5
+        for weight in self.parameters():
+            weight.data.uniform_(-std, std)
+    
+    def forward(self, x, att_scores):
+        """
+        Args:
+            x: [batch_size, seq_len, input_size]
+            att_scores: [batch_size, seq_len, 1] - attention scores
+        Returns:
+            output: [batch_size, seq_len, hidden_size]
+            hidden: [batch_size, hidden_size] - final hidden state
+        """
+        batch_size, seq_len, _ = x.shape
+        h = torch.zeros(batch_size, self.hidden_size, device=x.device)
+        outputs = []
+        for t in range(seq_len):
+            x_t = x[:, t, :]  # [batch_size, input_size]
+            att_t = att_scores[:, t, :]  # [batch_size, 1]
+            
+            gi = F.linear(x_t, self.weight_ih, self.bias_ih)
+            gh = F.linear(h, self.weight_hh, self.bias_hh)
+            i_r, i_i, i_n = gi.chunk(3, 1)
+            h_r, h_i, h_n = gh.chunk(3, 1)
+            
+            resetgate = torch.sigmoid(i_r + h_r)
+            inputgate = torch.sigmoid(i_i + h_i)
+            newgate = torch.tanh(i_n + resetgate * h_n)
+            # Use attention score to control update
+            h = (1 - att_t) * h + att_t * newgate
+            outputs.append(h.unsqueeze(1))
+        output = torch.cat(outputs, dim=1)
+        
+        return output, h        
+
+
+class DynamicGRU(nn.Module):
+    """Dynamic GRU unit with auxiliary loss path from DIEN (Zhou et al., 2019)."""
+    """
+    GRU with dynamic routing for DIEN
+    """
+    
+    def __init__(self, input_size, hidden_size, bias=True):
+        super().__init__()
+        self.input_size = input_size
+        self.hidden_size = hidden_size
+        
+        # GRU parameters
+        self.weight_ih = nn.Parameter(torch.randn(3 * hidden_size, input_size))
+        self.weight_hh = nn.Parameter(torch.randn(3 * hidden_size, hidden_size))
+        if bias:
+            self.bias_ih = nn.Parameter(torch.randn(3 * hidden_size))
+            self.bias_hh = nn.Parameter(torch.randn(3 * hidden_size))
+        else:
+            self.register_parameter('bias_ih', None)
+            self.register_parameter('bias_hh', None)
+        
+        self.reset_parameters()
+    
+    def reset_parameters(self):
+        std = 1.0 / (self.hidden_size) ** 0.5
+        for weight in self.parameters():
+            weight.data.uniform_(-std, std)
+    
+    def forward(self, x, att_scores=None):
+        """
+        Args:
+            x: [batch_size, seq_len, input_size]
+            att_scores: [batch_size, seq_len] - attention scores for auxiliary loss
+        Returns:
+            output: [batch_size, seq_len, hidden_size]
+            hidden: [batch_size, hidden_size] - final hidden state
+        """
+        batch_size, seq_len, _ = x.shape
+        
+        # Initialize hidden state
+        h = torch.zeros(batch_size, self.hidden_size, device=x.device)
+        
+        outputs = []
+        for t in range(seq_len):
+            x_t = x[:, t, :]  # [batch_size, input_size]
+            
+            # GRU computation
+            gi = F.linear(x_t, self.weight_ih, self.bias_ih)
+            gh = F.linear(h, self.weight_hh, self.bias_hh)
+            i_r, i_i, i_n = gi.chunk(3, 1)
+            h_r, h_i, h_n = gh.chunk(3, 1)
+            
+            resetgate = torch.sigmoid(i_r + h_r)
+            inputgate = torch.sigmoid(i_i + h_i)
+            newgate = torch.tanh(i_n + resetgate * h_n)
+            h = newgate + inputgate * (h - newgate)
+            
+            outputs.append(h.unsqueeze(1))
+        
+        output = torch.cat(outputs, dim=1)  # [batch_size, seq_len, hidden_size]
+        
+        return output, h
+
 
 class DIEN(BaseModel):
     @property
@@ -76,9 +200,6 @@ class DIEN(BaseModel):
         
         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
 
         # Embedding layer
         self.embedding = EmbeddingLayer(features=self.all_features)
@@ -103,10 +224,7 @@ class DIEN(BaseModel):
         )
         
         # Interest Evolution Layer (AUGRU)
-        self.interest_evolution = AUGRU(
-            input_size=gru_hidden_size,
-            hidden_size=gru_hidden_size
-        )
+        self.interest_evolution = AUGRU(input_size=gru_hidden_size, hidden_size=gru_hidden_size)
         
         # Calculate MLP input dimension
         mlp_input_dim = 0
@@ -115,38 +233,23 @@ class DIEN(BaseModel):
         mlp_input_dim += gru_hidden_size  # final interest state
         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 for final prediction
         self.mlp = MLP(input_dim=mlp_input_dim, **mlp_params)
         self.prediction_layer = PredictionLayer(task_type=self.task_type)
-
         # Register regularization weights
-        self._register_regularization_weights(
-            embedding_attr='embedding',
-            include_modules=['interest_extractor', 'interest_evolution', 'attention_layer', 'mlp', 'candidate_proj']
-        )
-
-        self.compile(
-            optimizer=optimizer,
-            optimizer_params=optimizer_params,
-            loss=loss,
-            loss_params=loss_params,
-        )
+        self._register_regularization_weights(embedding_attr='embedding', include_modules=['interest_extractor', 'interest_evolution', 'attention_layer', 'mlp', 'candidate_proj'])
+        self.compile(optimizer=optimizer, optimizer_params=optimizer_params, loss=loss, loss_params=loss_params)
 
     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]
+            candidate_emb = self.embedding.embed_dict[self.candidate_feature.embedding_name](x[self.candidate_feature.name].long())  # [B, emb_dim]
         else:
             raise ValueError("DIEN requires a candidate item feature")
         
         # 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]
+        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:

nextrec/models/ranking/masknet.py

@@ -1,6 +1,6 @@
 """
 Date: create on 09/11/2025
-Checkpoint: edit on 24/11/2025
+Checkpoint: edit on 29/11/2025
 Author: Yang Zhou, zyaztec@gmail.com
 Reference:
 [1] Wang Z, She Q, Zhang J. MaskNet: Introducing Feature-Wise
@@ -144,7 +144,8 @@ class MaskNet(BaseModel):
 
     @property
     def task_type(self):
-        return "binary_classification"
+        # Align with PredictionLayer supported task types
+        return "binary"
 
     def __init__(
         self,
@@ -198,26 +199,19 @@ class MaskNet(BaseModel):
         self.dense_features = dense_features
         self.sparse_features = sparse_features
         self.sequence_features = sequence_features
-        self.mask_features = self.sparse_features + self.sequence_features + self.dense_features
+        self.mask_features = self.all_features  # use all features for masking
         assert len(self.mask_features) > 0, "MaskNet requires at least one feature for masking."
-
         self.embedding = EmbeddingLayer(features=self.mask_features)
-
         self.num_fields = len(self.mask_features)
-
         self.embedding_dim = getattr(self.mask_features[0], "embedding_dim", None)
         assert self.embedding_dim is not None, "MaskNet requires mask_features to have 'embedding_dim' defined."
 
         for f in self.mask_features:
             edim = getattr(f, "embedding_dim", None)
             if edim is None or edim != self.embedding_dim:
-                raise ValueError(
-                    f"MaskNet expects identical embedding_dim across all mask_features, "
-                    f"but got {edim} for feature {getattr(f, 'name', type(f))}."
-                )
+                raise ValueError(f"MaskNet expects identical embedding_dim across all mask_features, but got {edim} for feature {getattr(f, 'name', type(f))}.")
 
         self.v_emb_dim = self.num_fields * self.embedding_dim
-
         self.model_type = model_type.lower()
         assert self.model_type in ("serial", "parallel"), "model_type must be either 'serial' or 'parallel'."
 
@@ -226,68 +220,25 @@ class MaskNet(BaseModel):
         self.block_dropout = nn.Dropout(block_dropout) if block_dropout > 0 else nn.Identity()
 
         if self.model_type == "serial":
-            self.first_block = MaskBlockOnEmbedding(
-                num_fields=self.num_fields,
-                embedding_dim=self.embedding_dim,
-                mask_hidden_dim=mask_hidden_dim,
-                hidden_dim=block_hidden_dim,
-            )
-
+            self.first_block = MaskBlockOnEmbedding(num_fields=self.num_fields, embedding_dim=self.embedding_dim, mask_hidden_dim=mask_hidden_dim, hidden_dim=block_hidden_dim,)
             self.hidden_blocks = nn.ModuleList(
-                [
-                    MaskBlockOnHidden(
-                        num_fields=self.num_fields,
-                        embedding_dim=self.embedding_dim,
-                        mask_hidden_dim=mask_hidden_dim,
-                        hidden_dim=block_hidden_dim,
-                    )
-                    for _ in range(self.num_blocks - 1)
-                ]
-            )
-
+                [MaskBlockOnHidden(num_fields=self.num_fields, embedding_dim=self.embedding_dim, mask_hidden_dim=mask_hidden_dim, hidden_dim=block_hidden_dim) for _ in range(self.num_blocks - 1)])
             self.mask_blocks = nn.ModuleList([self.first_block, *self.hidden_blocks])
             self.output_layer = nn.Linear(block_hidden_dim, 1)
             self.final_mlp = None
 
         else:  # parallel
-            self.mask_blocks = nn.ModuleList(
-                [
-                    MaskBlockOnEmbedding(
-                        num_fields=self.num_fields,
-                        embedding_dim=self.embedding_dim,
-                        mask_hidden_dim=mask_hidden_dim,
-                        hidden_dim=block_hidden_dim,
-                    )
-                    for _ in range(self.num_blocks)
-                ]
-            )
-
-            self.final_mlp = MLP(
-                input_dim=self.num_blocks * block_hidden_dim,
-                **mlp_params,
-            )
+            self.mask_blocks = nn.ModuleList([MaskBlockOnEmbedding(num_fields=self.num_fields, embedding_dim=self.embedding_dim, mask_hidden_dim=mask_hidden_dim, hidden_dim=block_hidden_dim) for _ in range(self.num_blocks)])
+            self.final_mlp = MLP(input_dim=self.num_blocks * block_hidden_dim, **mlp_params)
             self.output_layer = None
-
         self.prediction_layer = PredictionLayer(task_type=self.task_type)
 
         if self.model_type == "serial":
-            self._register_regularization_weights(
-                embedding_attr="embedding",
-                include_modules=["mask_blocks", "output_layer"],
-            )
+            self._register_regularization_weights(embedding_attr="embedding", include_modules=["mask_blocks", "output_layer"],)
         # serial
         else:
-            self._register_regularization_weights(
-                embedding_attr="embedding",
-                include_modules=["mask_blocks", "final_mlp"],
-            )
-
-        self.compile(
-            optimizer=optimizer,
-            optimizer_params=optimizer_params,
-            loss=loss,
-            loss_params=loss_params,
-        )
+            self._register_regularization_weights(embedding_attr="embedding", include_modules=["mask_blocks", "final_mlp"])
+        self.compile(optimizer=optimizer, optimizer_params=optimizer_params, loss=loss, loss_params=loss_params)
 
     def forward(self, x: dict[str, torch.Tensor]) -> torch.Tensor:
         field_emb = self.embedding(x=x, features=self.mask_features, squeeze_dim=False)
@@ -300,20 +251,15 @@ class MaskNet(BaseModel):
                 h = block(field_emb, v_emb_flat)  # [B, block_hidden_dim]
                 h = self.block_dropout(h)
                 block_outputs.append(h)
-
             concat_hidden = torch.cat(block_outputs, dim=-1)
             logit = self.final_mlp(concat_hidden)  # [B, 1]
-
         # serial
         else: 
             hidden = self.first_block(field_emb, v_emb_flat)
             hidden = self.block_dropout(hidden)
-
             for block in self.hidden_blocks:
                 hidden = block(hidden, v_emb_flat)
                 hidden = self.block_dropout(hidden)
-
             logit = self.output_layer(hidden)  # [B, 1]
-
         y = self.prediction_layer(logit)
-        return y
+        return y

nextrec/models/ranking/widedeep.py

@@ -1,11 +1,42 @@
 """
 Date: create on 09/11/2025
+Checkpoint: edit on 24/11/2025
 Author:
     Yang Zhou,zyaztec@gmail.com
 Reference:
-    [1] Cheng H T, Koc L, Harmsen J, et al. Wide & deep learning for recommender systems[C]
-        //Proceedings of the 1st workshop on deep learning for recommender systems. 2016: 7-10.
+    [1] Cheng H T, Koc L, Harmsen J, et al. Wide & Deep learning for recommender systems[C]
+        //Proceedings of the 1st Workshop on Deep Learning for Recommender Systems. 2016: 7-10.
         (https://arxiv.org/abs/1606.07792)
+
+Wide & Deep blends a linear wide component (memorization of cross features) with a
+deep neural network (generalization) sharing the same feature space. The wide part
+captures co-occurrence patterns and manual crosses, while the deep part learns dense
+representations and nonlinear interactions, improving both accuracy and coverage.
+
+Workflow:
+  (1) Wide: linear/logistic model over raw or embedded features
+  (2) Deep: embeddings plus dense features feed into an MLP
+  (3) Sum wide and deep logits, then apply the final prediction layer
+
+Key Advantages:
+- Balances memorization (wide) and generalization (deep)
+- Compatible with manual crosses and automatically learned embeddings
+- Simple architecture with strong baselines for CTR/ranking
+- Shared feature space reduces duplication and engineering overhead
+
+Wide & Deep 同时使用宽线性部分（记忆共现/手工交叉）与深网络部分（泛化非线性交互），
+共享特征表示，既保留记忆能力又具备泛化能力，常用于 CTR/排序任务。
+
+流程：
+  (1) Wide：线性/逻辑回归建模原始或 embedding 后的特征
+  (2) Deep：embedding 与稠密特征输入 MLP
+  (3) 宽深输出求和后进入最终预测
+
+主要优点：
+- 兼顾记忆与泛化
+- 支持手工交叉与自动 embedding 联合
+- 结构简单，基线性能稳定
+- 共享特征空间，减少工程开销
 """
 
 import torch
@@ -63,7 +94,6 @@ class WideDeep(BaseModel):
             
         # Wide part: use all features for linear model
         self.wide_features = sparse_features + sequence_features
-        
         # Deep part: use all features
         self.deep_features = dense_features + sparse_features + sequence_features
 
@@ -75,23 +105,14 @@ class WideDeep(BaseModel):
         self.linear = LR(wide_dim)
         
         # Deep part: MLP
-        deep_emb_dim_total = sum([f.embedding_dim for f in self.deep_features if not isinstance(f, DenseFeature)])
-        dense_input_dim = sum([getattr(f, "embedding_dim", 1) or 1 for f in dense_features])
-        self.mlp = MLP(input_dim=deep_emb_dim_total + dense_input_dim, **mlp_params)
+        input_dim = self.embedding.input_dim
+        # deep_emb_dim_total = sum([f.embedding_dim for f in self.deep_features if not isinstance(f, DenseFeature)])
+        # dense_input_dim = sum([getattr(f, "embedding_dim", 1) or 1 for f in dense_features])
+        self.mlp = MLP(input_dim=input_dim, **mlp_params)
         self.prediction_layer = PredictionLayer(task_type=self.task_type)
-
         # Register regularization weights
-        self._register_regularization_weights(
-            embedding_attr='embedding',
-            include_modules=['linear', 'mlp']
-        )
-
-        self.compile(
-            optimizer=optimizer,
-            optimizer_params=optimizer_params,
-            loss=loss,
-            loss_params=loss_params,
-        )
+        self._register_regularization_weights(embedding_attr='embedding', include_modules=['linear', 'mlp'])
+        self.compile(optimizer=optimizer, optimizer_params=optimizer_params, loss=loss, loss_params=loss_params)
 
     def forward(self, x):
         # Deep part

nextrec/models/ranking/xdeepfm.py

@@ -11,12 +11,45 @@ Reference:
 
 import torch
 import torch.nn as nn
+import torch.nn.functional as F
 
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import LR, EmbeddingLayer, MLP, CIN, PredictionLayer
+from nextrec.basic.layers import LR, EmbeddingLayer, MLP, PredictionLayer
 from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
+class CIN(nn.Module):
+    """Compressed Interaction Network from xDeepFM (Lian et al., 2018)."""
 
+    def __init__(self, input_dim, cin_size, split_half=True):
+        super().__init__()
+        self.num_layers = len(cin_size)
+        self.split_half = split_half
+        self.conv_layers = torch.nn.ModuleList()
+        prev_dim, fc_input_dim = input_dim, 0
+        for i in range(self.num_layers):
+            cross_layer_size = cin_size[i]
+            self.conv_layers.append(torch.nn.Conv1d(input_dim * prev_dim, cross_layer_size, 1, stride=1, dilation=1, bias=True))
+            if self.split_half and i != self.num_layers - 1:
+                cross_layer_size //= 2
+            prev_dim = cross_layer_size
+            fc_input_dim += prev_dim
+        self.fc = torch.nn.Linear(fc_input_dim, 1)
+
+    def forward(self, x):
+        xs = list()
+        x0, h = x.unsqueeze(2), x
+        for i in range(self.num_layers):
+            x = x0 * h.unsqueeze(1)
+            batch_size, f0_dim, fin_dim, embed_dim = x.shape
+            x = x.view(batch_size, f0_dim * fin_dim, embed_dim)
+            x = F.relu(self.conv_layers[i](x))
+            if self.split_half and i != self.num_layers - 1:
+                x, h = torch.split(x, x.shape[1] // 2, dim=1)
+            else:
+                h = x
+            xs.append(x)
+        return self.fc(torch.sum(torch.cat(xs, dim=1), 2))
+    
 class xDeepFM(BaseModel):
     @property
     def model_name(self):

nextrec/utils/common.py

@@ -1,5 +1,8 @@
 import torch
 import platform
+from collections import OrderedDict
+from typing import Sequence, Union, TYPE_CHECKING
+
 
 def resolve_device() -> str:
     """Select a usable device with graceful fallback."""
@@ -13,4 +16,26 @@ def resolve_device() -> str:
             major, minor = 0, 0
         if major >= 14:
             return "mps"
-    return "cpu"
+    return "cpu"
+
+
+def merge_features(primary, secondary) -> list:
+    """
+    Merge two feature lists while preserving order and deduplicating by feature name.
+    Later duplicates are skipped.
+    """
+    merged: OrderedDict[str, object] = OrderedDict()
+    for feat in list(primary or []) + list(secondary or []):
+        merged.setdefault(feat.name, feat)
+    return list(merged.values())
+
+
+def get_mlp_output_dim(params: dict, fallback: int) -> int:
+    """
+    Get the output dimension of an MLP-like config.
+    If dims are provided, use the last dim; otherwise fall back to input dim.
+    """
+    dims = params.get("dims")
+    if dims:
+        return dims[-1]
+    return fallback