nextrec 0.4.8__py3-none-any.whl → 0.4.10__py3-none-any.whl

nextrec/models/ranking/fm.py

@@ -40,14 +40,10 @@ FM 是一种通过分解二阶特征交互矩阵、以线性复杂度建模特
 
 import torch.nn as nn
 
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.basic.layers import FM as FMInteraction
+from nextrec.basic.layers import LR, EmbeddingLayer, PredictionLayer
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import (
-    EmbeddingLayer,
-    FM as FMInteraction,
-    LR,
-    PredictionLayer,
-)
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
 class FM(BaseModel):

nextrec/models/ranking/lr.py

@@ -0,0 +1,120 @@
+"""
+Date: create on 09/11/2025
+Checkpoint: edit on 09/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
+Reference:
+[1] Hosmer D W, Lemeshow S, Sturdivant R X. Applied Logistic Regression.
+
+Logistic Regression (LR) is a classic linear baseline for CTR/ranking tasks.
+It maps each feature (dense, sparse, or sequence) into a numeric vector and
+learns a single linear logit. Despite its simplicity, LR is strong for
+high-dimensional sparse data and is commonly used as a baseline or a "wide"
+component in hybrid models.
+
+Pipeline:
+  (1) Embed sparse/sequence fields; project dense fields if configured
+  (2) Concatenate all feature vectors into a single linear input
+  (3) Apply a linear layer to produce logits
+  (4) Use the prediction layer to output task-specific probabilities
+
+Key Advantages:
+- Fast and easy to train
+- Strong baseline for sparse, high-dimensional features
+- Interpretable linear weights
+
+LR 是 CTR/排序任务中最经典的线性基线模型。它将稠密、稀疏以及序列特征
+映射为数值向量后做线性组合，输出 logit。虽然结构简单，但在稀疏高维场景
+依然具有很强的基线效果，并常作为 Wide 端与深模型组合。
+
+处理流程：
+  (1) 稀疏/序列特征做 embedding，稠密特征按需投影
+  (2) 拼接所有特征向量形成线性输入
+  (3) 线性层输出 logit
+  (4) 通过预测层输出任务概率
+
+主要优点：
+- 训练与推理速度快
+- 稀疏高维特征下表现稳定
+- 权重可解释性强
+"""
+
+import torch.nn as nn
+
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.basic.layers import EmbeddingLayer, LR as LinearLayer, PredictionLayer
+from nextrec.basic.model import BaseModel
+
+
+class LR(BaseModel):
+    @property
+    def model_name(self):
+        return "LR"
+
+    @property
+    def default_task(self):
+        return "binary"
+
+    def __init__(
+        self,
+        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 | 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 []
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
+        super(LR, self).__init__(
+            dense_features=dense_features,
+            sparse_features=sparse_features,
+            sequence_features=sequence_features,
+            target=target,
+            task=task or self.default_task,
+            device=device,
+            embedding_l1_reg=embedding_l1_reg,
+            dense_l1_reg=dense_l1_reg,
+            embedding_l2_reg=embedding_l2_reg,
+            dense_l2_reg=dense_l2_reg,
+            **kwargs,
+        )
+
+        self.loss = loss
+
+        self.embedding = EmbeddingLayer(features=self.all_features)
+        linear_input_dim = self.embedding.input_dim
+        self.linear = LinearLayer(linear_input_dim)
+        self.prediction_layer = PredictionLayer(task_type=self.task)
+
+        self.register_regularization_weights(
+            embedding_attr="embedding", include_modules=["linear"]
+        )
+
+        self.compile(
+            optimizer=optimizer,
+            optimizer_params=optimizer_params,
+            loss=loss,
+            loss_params=loss_params,
+        )
+
+    def forward(self, x):
+        input_linear = self.embedding(
+            x=x, features=self.all_features, squeeze_dim=True
+        )
+        y = self.linear(input_linear)
+        return self.prediction_layer(y)

nextrec/models/ranking/masknet.py

@@ -57,9 +57,9 @@ import torch
 import torch.nn as nn
 import torch.nn.functional as F
 
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.basic.layers import MLP, EmbeddingLayer, PredictionLayer
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import EmbeddingLayer, MLP, PredictionLayer
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
 class InstanceGuidedMask(nn.Module):

nextrec/models/ranking/pnn.py

@@ -37,9 +37,9 @@ PNN 是一种 CTR 预估模型，通过将线性信号与乘积信号结合，
 import torch
 import torch.nn as nn
 
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.basic.layers import MLP, EmbeddingLayer, PredictionLayer
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import EmbeddingLayer, MLP, PredictionLayer
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
 class PNN(BaseModel):

nextrec/models/ranking/widedeep.py

@@ -41,9 +41,9 @@ Wide & Deep 同时使用宽线性部分（记忆共现/手工交叉）与深网
 
 import torch.nn as nn
 
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.basic.layers import LR, MLP, EmbeddingLayer, PredictionLayer
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import LR, EmbeddingLayer, MLP, PredictionLayer
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
 class WideDeep(BaseModel):

nextrec/models/ranking/xdeepfm.py

@@ -55,9 +55,9 @@ import torch
 import torch.nn as nn
 import torch.nn.functional as F
 
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.basic.layers import LR, MLP, EmbeddingLayer, PredictionLayer
 from nextrec.basic.model import BaseModel
-from nextrec.basic.layers import LR, EmbeddingLayer, MLP, PredictionLayer
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
 class CIN(nn.Module):

nextrec/models/representation/__init__.py

@@ -0,0 +1,9 @@
+from nextrec.models.representation.rqvae import (
+    RQ,
+    RQVAE,
+    BalancedKmeans,
+    VQEmbedding,
+    kmeans,
+)
+
+__all__ = ["RQVAE", "RQ", "VQEmbedding", "BalancedKmeans", "kmeans"]

nextrec/models/{generative → representation}/rqvae.py

@@ -46,21 +46,21 @@ RQ-VAE 通过残差量化学习分层离散表示，将连续嵌入（如物品/
 
 from __future__ import annotations
 
+import logging
 import math
+from typing import cast
+
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
 from sklearn.cluster import KMeans
-from typing import cast
-import logging
-import tqdm
-
 from torch.utils.data import DataLoader
 
 from nextrec.basic.features import DenseFeature
+from nextrec.basic.loggers import colorize, setup_logger
 from nextrec.basic.model import BaseModel
 from nextrec.data.batch_utils import batch_to_dict
-from nextrec.basic.loggers import colorize, setup_logger
+from nextrec.utils.console import progress
 
 
 def kmeans(
@@ -729,9 +729,9 @@ class RQVAE(BaseModel):
             else:
                 tqdm_disable = not self.is_main_process
                 batch_iter = enumerate(
-                    tqdm.tqdm(
+                    progress(
                         train_loader,
-                        desc=f"Epoch {epoch + 1}/{epochs}",
+                        description=f"Epoch {epoch + 1}/{epochs}",
                         total=steps_per_epoch,
                         disable=tqdm_disable,
                     )
@@ -777,9 +777,9 @@ class RQVAE(BaseModel):
                 logging.info(colorize(train_log))
 
         if self.is_main_process:
-            logging.info(" ")
+            logging.info("")
             logging.info(colorize("Training finished.", bold=True))
-            logging.info(" ")
+            logging.info("")
         return self
 
     def predict(

nextrec/models/{match → retrieval}/dssm.py

@@ -7,13 +7,14 @@ Reference:
 //Proceedings of the 22nd ACM international conference on Information & Knowledge Management. 2013: 2333-2338.
 """
 
+from typing import Literal
+
 import torch
 import torch.nn as nn
-from typing import Literal
 
-from nextrec.basic.model import BaseMatchModel
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 from nextrec.basic.layers import MLP, EmbeddingLayer
+from nextrec.basic.model import BaseMatchModel
 
 
 class DSSM(BaseMatchModel):
@@ -28,6 +29,10 @@ class DSSM(BaseMatchModel):
     def model_name(self) -> str:
         return "DSSM"
 
+    @property
+    def support_training_modes(self) -> list[str]:
+        return ["pointwise", "pairwise", "listwise"]
+
     def __init__(
         self,
         user_dense_features: list[DenseFeature] | None = None,

nextrec/models/{match → retrieval}/dssm_v2.py

@@ -6,13 +6,14 @@ Reference:
 DSSM v2 - DSSM with pairwise training using BPR loss
 """
 
+from typing import Literal
+
 import torch
 import torch.nn as nn
-from typing import Literal
 
-from nextrec.basic.model import BaseMatchModel
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 from nextrec.basic.layers import MLP, EmbeddingLayer
+from nextrec.basic.model import BaseMatchModel
 
 
 class DSSM_v2(BaseMatchModel):
@@ -24,6 +25,10 @@ class DSSM_v2(BaseMatchModel):
     def model_name(self) -> str:
         return "DSSM_v2"
 
+    @property
+    def support_training_modes(self) -> list[str]:
+        return ["pointwise", "pairwise", "listwise"]
+
     def __init__(
         self,
         user_dense_features: list[DenseFeature] | None = None,

nextrec/models/{match → retrieval}/mind.py

@@ -7,14 +7,15 @@ Reference:
 //Proceedings of the 28th ACM international conference on information and knowledge management. 2019: 2615-2623.
 """
 
+from typing import Literal
+
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
-from typing import Literal
 
-from nextrec.basic.model import BaseMatchModel
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 from nextrec.basic.layers import MLP, EmbeddingLayer
+from nextrec.basic.model import BaseMatchModel
 
 
 class MultiInterestSA(nn.Module):

nextrec/models/{match → retrieval}/sdm.py

@@ -7,14 +7,15 @@ Reference:
 //IJCAI. 2018: 3926-3932.
 """
 
+from typing import Literal
+
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
-from typing import Literal
 
-from nextrec.basic.model import BaseMatchModel
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 from nextrec.basic.layers import MLP, EmbeddingLayer
+from nextrec.basic.model import BaseMatchModel
 
 
 class SDM(BaseMatchModel):

nextrec/models/{match → retrieval}/youtube_dnn.py

@@ -7,13 +7,14 @@ Reference:
 //Proceedings of the 10th ACM conference on recommender systems. 2016: 191-198.
 """
 
+from typing import Literal
+
 import torch
 import torch.nn as nn
-from typing import Literal
 
-from nextrec.basic.model import BaseMatchModel
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 from nextrec.basic.layers import MLP, EmbeddingLayer
+from nextrec.basic.model import BaseMatchModel
 
 
 class YoutubeDNN(BaseMatchModel):
@@ -28,6 +29,10 @@ class YoutubeDNN(BaseMatchModel):
     def model_name(self) -> str:
         return "YouTubeDNN"
 
+    @property
+    def support_training_modes(self) -> list[str]:
+        return ["pointwise", "pairwise", "listwise"]
+
     def __init__(
         self,
         user_dense_features: list[DenseFeature] | None = None,

nextrec/utils/__init__.py

@@ -1,71 +1,84 @@
 """
 Utilities package for NextRec
 
-This package provides various utility functions organized by category:
-- optimizer: Optimizer and scheduler utilities
-- initializer: Weight initialization utilities
-- embedding: Embedding dimension calculation
-- device_utils: Device management and selection
-- tensor_utils: Tensor operations and conversions
-- file_utils: File I/O operations
-- model_utils: Model-related utilities
-- feature_utils: Feature processing utilities
-- config_utils: Configuration loading and processing utilities
-
 Date: create on 13/11/2025
-Last update: 06/12/2025
+Last update: 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
-from . import optimizer, initializer, embedding
-from .optimizer import get_optimizer, get_scheduler
-from .initializer import get_initializer
-from .embedding import get_auto_embedding_dim
-from .device import resolve_device, get_device_info
-from .tensor import to_tensor, stack_tensors, concat_tensors, pad_sequence_tensors
-from .file import (
-    resolve_file_paths,
-    read_table,
-    load_dataframes,
-    iter_file_chunks,
-    default_output_dir,
-    read_yaml,
-)
-from .model import merge_features, get_mlp_output_dim
-from .feature import normalize_to_list
-from .synthetic_data import (
-    generate_match_data,
-    generate_ranking_data,
-    generate_multitask_data,
-    generate_distributed_ranking_data,
-)
+from . import console, data, embedding, torch_utils
 from .config import (
-    resolve_path,
-    select_features,
-    register_processor_features,
     build_feature_objects,
+    build_model_instance,
     extract_feature_groups,
     load_model_class,
-    build_model_instance,
+    register_processor_features,
+    resolve_path,
+    select_features,
+)
+from .console import (
+    display_metrics_table,
+    get_nextrec_version,
+    log_startup_info,
+    progress,
+)
+from .data import (
+    default_output_dir,
+    generate_distributed_ranking_data,
+    generate_match_data,
+    generate_multitask_data,
+    generate_ranking_data,
+    iter_file_chunks,
+    load_dataframes,
+    read_table,
+    read_yaml,
+    resolve_file_paths,
+)
+from .embedding import get_auto_embedding_dim
+from .feature import normalize_to_list
+from .model import get_mlp_output_dim, merge_features
+from .torch_utils import (
+    add_distributed_sampler,
+    concat_tensors,
+    configure_device,
+    gather_numpy,
+    get_device_info,
+    get_initializer,
+    get_optimizer,
+    get_scheduler,
+    init_process_group,
+    pad_sequence_tensors,
+    resolve_device,
+    stack_tensors,
+    to_tensor,
 )
 
 __all__ = [
-    # Optimizer & Scheduler
+    # Console utilities
+    "get_nextrec_version",
+    "log_startup_info",
+    "progress",
+    "display_metrics_table",
+    # Optimizer & Scheduler (torch utils)
     "get_optimizer",
     "get_scheduler",
-    # Initializer
+    # Initializer (torch utils)
     "get_initializer",
-    # Embedding
+    # Embedding utilities
     "get_auto_embedding_dim",
-    # Device utilities
+    # Device utilities (torch utils)
     "resolve_device",
     "get_device_info",
+    "configure_device",
+    "init_process_group",
+    "gather_numpy",
+    "add_distributed_sampler",
     # Tensor utilities
     "to_tensor",
     "stack_tensors",
     "concat_tensors",
     "pad_sequence_tensors",
-    # File utilities
+    # Data utilities
     "resolve_file_paths",
     "read_table",
     "read_yaml",
@@ -79,10 +92,10 @@ __all__ = [
     "normalize_to_list",
     # Config utilities
     "resolve_path",
-    "select_features",
     "register_processor_features",
     "build_feature_objects",
     "extract_feature_groups",
+    "select_features",
     "load_model_class",
     "build_model_instance",
     # Synthetic data utilities
@@ -91,7 +104,8 @@ __all__ = [
     "generate_multitask_data",
     "generate_distributed_ranking_data",
     # Module exports
-    "optimizer",
-    "initializer",
+    "console",
+    "data",
     "embedding",
+    "torch_utils",
 ]

nextrec/utils/config.py

@@ -4,7 +4,8 @@ Configuration utilities for NextRec
 This module provides utilities for loading and processing configuration files,
 including feature configuration, model configuration, and training configuration.
 
-Date: create on 06/12/2025
+Date: create on 27/10/2025
+Checkpoint: edit on 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
@@ -23,7 +24,7 @@ import torch
 from nextrec.utils.feature import normalize_to_list
 
 if TYPE_CHECKING:
-    from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+    from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
     from nextrec.data.preprocessor import DataProcessor
 
 
@@ -52,7 +53,7 @@ def select_features(
         names = [name for name in cfg.keys() if name in columns]
         missing = [name for name in cfg.keys() if name not in columns]
         if missing:
-            print(f"[feature_config] skipped missing {group} columns: {missing}")
+            print(f"[Feature Config] skipped missing {group} columns: {missing}")
         return names
 
     dense_names = pick("dense")
@@ -129,7 +130,7 @@ def build_feature_objects(
         sparse_names: List of sparse feature names
         sequence_names: List of sequence feature names
     """
-    from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+    from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
 
     dense_cfg = feature_cfg.get("dense", {}) or {}
     sparse_cfg = feature_cfg.get("sparse", {}) or {}
@@ -236,7 +237,7 @@ def extract_feature_groups(
 
         if missing_defined:
             print(
-                f"[feature_config] feature_groups.{group_name} contains features not defined in dense/sparse/sequence: {missing_defined}"
+                f"[Feature Config] feature_groups.{group_name} contains features not defined in dense/sparse/sequence: {missing_defined}"
             )
 
         for n in name_list:
@@ -249,7 +250,7 @@ def extract_feature_groups(
 
         if missing_cols:
             print(
-                f"[feature_config] feature_groups.{group_name} missing data columns: {missing_cols}"
+                f"[Feature Config] feature_groups.{group_name} missing data columns: {missing_cols}"
             )
 
         resolved[group_name] = filtered
@@ -442,7 +443,7 @@ def build_model_instance(
 
         if group_key not in feature_groups:
             print(
-                f"[feature_config] feature_bindings refers to unknown group '{group_key}', skipped"
+                f"[Feature Config] feature_bindings refers to unknown group '{group_key}', skipped"
             )
             continue