nextrec 0.4.7__tar.gz → 0.4.8__tar.gz

{nextrec-0.4.7 → nextrec-0.4.8}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.7
+Version: 0.4.8
 Summary: A comprehensive recommendation library with match, ranking, and multi-task learning models
 Project-URL: Homepage, https://github.com/zerolovesea/NextRec
 Project-URL: Repository, https://github.com/zerolovesea/NextRec
 Project-URL: Documentation, https://github.com/zerolovesea/NextRec/blob/main/README.md
 Project-URL: Issues, https://github.com/zerolovesea/NextRec/issues
-Author-email: zerolovesea <zyaztec@gmail.com>
+Author: Yang Zhou
+Author-email: zyaztec@gmail.com
 License-File: LICENSE
 Keywords: ctr,deep-learning,match,pytorch,ranking,recommendation
 Classifier: Development Status :: 3 - Alpha
@@ -65,7 +66,7 @@ Description-Content-Type: text/markdown
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.7-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.8-orange.svg)
 
 中文文档 | [English Version](README_en.md)
 
@@ -98,7 +99,7 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 
 ## NextRec近期进展
 
-- **12/12/2025** 在v0.4.7中加入了[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
+- **12/12/2025** 在v0.4.8中加入了[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
 - **07/12/2025** 发布了NextRec CLI命令行工具，它允许用户根据配置文件进行一键训练和推理，我们提供了相关的[教程](/nextrec_cli_preset/NextRec-CLI_zh.md)和[教学代码](/nextrec_cli_preset)
 - **03/12/2025** NextRec获得了100颗🌟！感谢大家的支持
 - **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
@@ -240,11 +241,11 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> 截止当前版本0.4.7，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.8，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.7，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.8，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.7 → nextrec-0.4.8}/README.md

@@ -7,7 +7,7 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.7-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.8-orange.svg)
 
 中文文档 | [English Version](README_en.md)
 
@@ -40,7 +40,7 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 
 ## NextRec近期进展
 
-- **12/12/2025** 在v0.4.7中加入了[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
+- **12/12/2025** 在v0.4.8中加入了[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
 - **07/12/2025** 发布了NextRec CLI命令行工具，它允许用户根据配置文件进行一键训练和推理，我们提供了相关的[教程](/nextrec_cli_preset/NextRec-CLI_zh.md)和[教学代码](/nextrec_cli_preset)
 - **03/12/2025** NextRec获得了100颗🌟！感谢大家的支持
 - **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
@@ -182,11 +182,11 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> 截止当前版本0.4.7，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.8，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.7，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.8，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.7 → nextrec-0.4.8}/README_en.md

@@ -7,7 +7,7 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.7-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.8-orange.svg)
 
 English | [中文文档](README.md)
 
@@ -186,11 +186,11 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> As of version 0.4.7, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.8, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.7. All models and test code have been validated on the following platforms. If you encounter compatibility issues, please report them in the issue tracker with your system version:
+The current version is 0.4.8. All models and test code have been validated on the following platforms. If you encounter compatibility issues, please report them in the issue tracker with your system version:
 
 | Platform | Configuration | 
 |----------|---------------|

{nextrec-0.4.7 → nextrec-0.4.8}/docs/rtd/conf.py

@@ -11,7 +11,7 @@ sys.path.insert(0, str(PROJECT_ROOT / "nextrec"))
 project = "NextRec"
 copyright = "2025, Yang Zhou"
 author = "Yang Zhou"
-release = "0.4.7"
+release = "0.4.8"
 
 extensions = [
     "myst_parser",

nextrec-0.4.8/nextrec/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.4.8"

{nextrec-0.4.7 → nextrec-0.4.8}/nextrec/basic/model.py

@@ -55,7 +55,6 @@ from nextrec.loss import (
     SampledSoftmaxLoss,
     TripletLoss,
     get_loss_fn,
-    get_loss_kwargs,
 )
 from nextrec.utils.tensor import to_tensor
 from nextrec.utils.device import configure_device
@@ -185,7 +184,9 @@ class BaseModel(FeatureSet, nn.Module):
         embedding_params: list[torch.Tensor] = []
         if embed_dict is not None:
             embedding_params.extend(
-                embed.weight for embed in embed_dict.values() if hasattr(embed, "weight")
+                embed.weight
+                for embed in embed_dict.values()
+                if hasattr(embed, "weight")
             )
         else:
             weight = getattr(embedding_layer, "weight", None)
@@ -739,8 +740,16 @@ class BaseModel(FeatureSet, nn.Module):
                 else:
                     train_loader = train_data
             else:
-                result = self.prepare_data_loader(train_data, batch_size=batch_size, shuffle=shuffle, num_workers=num_workers, return_dataset=True)
-                assert isinstance(result, tuple), "Expected tuple from prepare_data_loader with return_dataset=True"
+                result = self.prepare_data_loader(
+                    train_data,
+                    batch_size=batch_size,
+                    shuffle=shuffle,
+                    num_workers=num_workers,
+                    return_dataset=True,
+                )
+                assert isinstance(
+                    result, tuple
+                ), "Expected tuple from prepare_data_loader with return_dataset=True"
                 loader, dataset = result
                 if (
                     auto_distributed_sampler
@@ -845,7 +854,9 @@ class BaseModel(FeatureSet, nn.Module):
                 train_loader.sampler.set_epoch(epoch)
             # Type guard: ensure train_loader is DataLoader for train_epoch
             if not isinstance(train_loader, DataLoader):
-                raise TypeError(f"Expected DataLoader for training, got {type(train_loader)}")
+                raise TypeError(
+                    f"Expected DataLoader for training, got {type(train_loader)}"
+                )
             train_result = self.train_epoch(train_loader, is_streaming=is_streaming)
             if isinstance(train_result, tuple):  # [avg_loss, metrics_dict]
                 train_loss, train_metrics = train_result
@@ -2085,10 +2096,10 @@ class BaseMatchModel(BaseModel):
         if effective_loss is None:
             effective_loss = default_loss_by_mode[self.training_mode]
         elif isinstance(effective_loss, (str,)):
-            if (
-                self.training_mode in {"pairwise", "listwise"}
-                and effective_loss in {"bce", "binary_crossentropy"}
-            ):
+            if self.training_mode in {"pairwise", "listwise"} and effective_loss in {
+                "bce",
+                "binary_crossentropy",
+            }:
                 effective_loss = default_loss_by_mode[self.training_mode]
         elif isinstance(effective_loss, list):
             if not effective_loss:
@@ -2115,7 +2126,9 @@ class BaseMatchModel(BaseModel):
             callbacks=callbacks,
         )
 
-    def inbatch_logits(self, user_emb: torch.Tensor, item_emb: torch.Tensor) -> torch.Tensor:
+    def inbatch_logits(
+        self, user_emb: torch.Tensor, item_emb: torch.Tensor
+    ) -> torch.Tensor:
         if self.similarity_metric == "dot":
             logits = torch.matmul(user_emb, item_emb.t())
         elif self.similarity_metric == "cosine":
@@ -2216,7 +2229,9 @@ class BaseMatchModel(BaseModel):
 
             eye = torch.eye(batch_size, device=logits.device, dtype=torch.bool)
             pos_logits = logits.diag()  # [B]
-            neg_logits = logits.masked_select(~eye).view(batch_size, batch_size - 1)  # [B, B-1]
+            neg_logits = logits.masked_select(~eye).view(
+                batch_size, batch_size - 1
+            )  # [B, B-1]
 
             loss_fn = self.loss_fn[0] if getattr(self, "loss_fn", None) else None
             if isinstance(loss_fn, SampledSoftmaxLoss):

{nextrec-0.4.7 → nextrec-0.4.8}/nextrec/cli.py

@@ -14,9 +14,11 @@ Examples:
     nextrec --mode=predict --predict_config=nextrec_cli_preset/predict_config.yaml
 
 Date: create on 06/12/2025
+Checkpoint: edit on 18/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
+import sys
 import argparse
 import logging
 import pickle
@@ -44,6 +46,10 @@ from nextrec.utils.file import (
     read_yaml,
     resolve_file_paths,
 )
+from nextrec.utils.cli_utils import (
+    get_nextrec_version,
+    log_startup_info,
+)
 from nextrec.basic.loggers import setup_logger
 
 logger = logging.getLogger(__name__)
@@ -71,6 +77,9 @@ def train_model(train_config_path: str) -> None:
     artifact_root = Path(session_cfg.get("artifact_root", "nextrec_logs"))
     session_dir = artifact_root / session_id
     setup_logger(session_id=session_id)
+    logger.info(
+        f"[NextRec CLI] Training start | version={get_nextrec_version()} | session_id={session_id} | artifacts={session_dir.resolve()}"
+    )
 
     processor_path = session_dir / "processor.pkl"
     processor_path = Path(processor_path)
@@ -324,6 +333,9 @@ def predict_model(predict_config_path: str) -> None:
     artifact_root = Path(session_cfg.get("artifact_root", "nextrec_logs"))
     session_dir = Path(cfg.get("checkpoint_path") or (artifact_root / session_id))
     setup_logger(session_id=session_id)
+    logger.info(
+        f"[NextRec CLI] Predict start | version={get_nextrec_version()} | session_id={session_id} | checkpoint={session_dir.resolve()}"
+    )
 
     processor_path = Path(session_dir / "processor.pkl")
     if not processor_path.exists():
@@ -454,6 +466,13 @@ def predict_model(predict_config_path: str) -> None:
 
 def main() -> None:
     """Parse CLI arguments and dispatch to train or predict mode."""
+
+    root = logging.getLogger()
+    if not root.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        root.addHandler(handler)
+
     parser = argparse.ArgumentParser(
         description="NextRec: Training and Prediction Pipeline",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -466,25 +485,32 @@ Examples:
   nextrec --mode=predict --predict_config=configs/predict_config.yaml
         """,
     )
+
     parser.add_argument(
         "--mode",
         choices=["train", "predict"],
-        required=True,
         help="Running mode: train or predict",
     )
     parser.add_argument("--train_config", help="Training configuration file path")
     parser.add_argument("--predict_config", help="Prediction configuration file path")
     args = parser.parse_args()
 
+    logger.info(get_nextrec_version())
+
+    if not args.mode:
+        parser.error("[NextRec CLI Error] --mode is required (train|predict)")
+
     if args.mode == "train":
         config_path = args.train_config
         if not config_path:
             parser.error("[NextRec CLI Error] train mode requires --train_config")
+        log_startup_info(logger, mode="train", config_path=config_path)
         train_model(config_path)
     else:
         config_path = args.predict_config
         if not config_path:
             parser.error("[NextRec CLI Error] predict mode requires --predict_config")
+        log_startup_info(logger, mode="predict", config_path=config_path)
         predict_model(config_path)
 
 

nextrec-0.4.8/nextrec/utils/cli_utils.py

@@ -0,0 +1,58 @@
+"""
+CLI utilities for NextRec.
+
+This module provides small helpers used by command-line entrypoints, such as
+printing startup banners and resolving the installed package version.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import sys
+from datetime import datetime
+
+
+def get_nextrec_version() -> str:
+    """
+    Best-effort version resolver for NextRec.
+
+    Prefer in-repo `nextrec.__version__`, fall back to installed package metadata.
+    """
+    try:
+        from nextrec import __version__  # type: ignore
+
+        if __version__:
+            return str(__version__)
+    except Exception:
+        pass
+
+    try:
+        from importlib.metadata import version
+
+        return version("nextrec")
+    except Exception:
+        return "unknown"
+
+
+def log_startup_info(
+    logger: logging.Logger, *, mode: str, config_path: str | None
+) -> None:
+    """Log a short, user-friendly startup banner."""
+    version = get_nextrec_version()
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    lines = [
+        "NextRec CLI",
+        f"- Version: {version}",
+        f"- Time: {now}",
+        f"- Mode: {mode}",
+        f"- Config: {config_path or '(not set)'}",
+        f"- Python: {platform.python_version()} ({sys.executable})",
+        f"- Platform: {platform.system()} {platform.release()} ({platform.machine()})",
+        f"- Workdir: {os.getcwd()}",
+        f"- Command: {' '.join(sys.argv)}",
+    ]
+    for line in lines:
+        logger.info(line)

{nextrec-0.4.7 → nextrec-0.4.8}/nextrec/utils/config.py

@@ -62,7 +62,7 @@ def select_features(
 
 
 def register_processor_features(
-    processor: DataProcessor,
+    processor: "DataProcessor",
     feature_cfg: Dict[str, Any],
     dense_names: List[str],
     sparse_names: List[str],
@@ -129,6 +129,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
 
     dense_cfg = feature_cfg.get("dense", {}) or {}
     sparse_cfg = feature_cfg.get("sparse", {}) or {}
@@ -360,9 +361,9 @@ def load_model_class(model_cfg: Dict[str, Any], base_dir: Path) -> type:
 def build_model_instance(
     model_cfg: Dict[str, Any],
     model_cfg_path: Path,
-    dense_features: List[DenseFeature],
-    sparse_features: List[SparseFeature],
-    sequence_features: List[SequenceFeature],
+    dense_features: List["DenseFeature"],
+    sparse_features: List["SparseFeature"],
+    sequence_features: List["SequenceFeature"],
     target: List[str],
     device: str,
 ) -> Any:

{nextrec-0.4.7 → nextrec-0.4.8}/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "nextrec"
-version = "0.4.7"
+version = "0.4.8"
 description = "A comprehensive recommendation library with match, ranking, and multi-task learning models"
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [
-    { name = "zerolovesea", email = "zyaztec@gmail.com" }
+    { name = "Yang Zhou" },
+    { email = "zyaztec@gmail.com" }
 ]
 keywords = ["recommendation", "deep-learning", "pytorch", "ctr", "ranking", "match"]
 classifiers = [

{nextrec-0.4.7 → nextrec-0.4.8}/test/test_base_model_regularization.py

@@ -1,4 +1,3 @@
-import torch
 import torch.nn as nn
 
 from nextrec.basic.model import BaseModel

nextrec-0.4.7/nextrec/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.4.7"