nextrec 0.4.20__tar.gz → 0.4.22__tar.gz

{nextrec-0.4.20 → nextrec-0.4.22}/.gitignore

@@ -72,6 +72,7 @@ uv.lock
 logs/
 *.log
 nextrec_logs/
+swanlog/
 
 # Checkpoints
 checkpoints/

{nextrec-0.4.20 → nextrec-0.4.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.20
+Version: 0.4.22
 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
@@ -42,9 +42,11 @@ Requires-Dist: scipy<1.12,>=1.8; sys_platform == 'linux' and python_version < '3
 Requires-Dist: scipy>=1.10.0; sys_platform == 'darwin'
 Requires-Dist: scipy>=1.10.0; sys_platform == 'win32'
 Requires-Dist: scipy>=1.11.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: swanlab>=0.7.2
 Requires-Dist: torch>=2.0.0
 Requires-Dist: torchvision>=0.15.0
 Requires-Dist: transformers>=4.38.0
+Requires-Dist: wandb>=0.23.1
 Provides-Extra: dev
 Requires-Dist: jupyter>=1.0.0; extra == 'dev'
 Requires-Dist: matplotlib>=3.7.0; extra == 'dev'
@@ -63,11 +65,11 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=grey&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
 ![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.20-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -100,7 +102,7 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 - **高效训练与评估**：内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
 
 ## NextRec近期进展
-
+- **28/12/2025** 在v0.4.21中加入了对SwanLab和Wandb的支持，通过model的`fit`方法进行配置：`use_swanlab=True, swanlab_kwargs={"project": "NextRec","name":"tutorial_movielens_deepfm"},`
 - **21/12/2025** 在v0.4.16中加入了对[GradNorm](/nextrec/loss/grad_norm.py)的支持，通过compile的`loss_weight='grad_norm'`进行配置
 - **12/12/2025** 在v0.4.9中加入了[RQ-VAE](/nextrec/models/representation/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynb)已经同步在仓库中
 - **07/12/2025** 发布了NextRec CLI命令行工具，它允许用户根据配置文件进行一键训练和推理，我们提供了相关的[教程](/nextrec_cli_preset/NextRec-CLI_zh.md)和[教学代码](/nextrec_cli_preset)
@@ -245,11 +247,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.20，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.20，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.20 → nextrec-0.4.22}/README.md

@@ -4,11 +4,11 @@
 
 <div align="center">
 
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=grey&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
 ![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.20-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -41,7 +41,7 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 - **高效训练与评估**：内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
 
 ## NextRec近期进展
-
+- **28/12/2025** 在v0.4.21中加入了对SwanLab和Wandb的支持，通过model的`fit`方法进行配置：`use_swanlab=True, swanlab_kwargs={"project": "NextRec","name":"tutorial_movielens_deepfm"},`
 - **21/12/2025** 在v0.4.16中加入了对[GradNorm](/nextrec/loss/grad_norm.py)的支持，通过compile的`loss_weight='grad_norm'`进行配置
 - **12/12/2025** 在v0.4.9中加入了[RQ-VAE](/nextrec/models/representation/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynb)已经同步在仓库中
 - **07/12/2025** 发布了NextRec CLI命令行工具，它允许用户根据配置文件进行一键训练和推理，我们提供了相关的[教程](/nextrec_cli_preset/NextRec-CLI_zh.md)和[教学代码](/nextrec_cli_preset)
@@ -186,11 +186,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.20，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.20，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.20 → nextrec-0.4.22}/README_en.md

@@ -4,11 +4,11 @@
 
 <div align="center">
 
-[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=BLACK&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/nextrec?period=total&units=NONE&left_color=grey&right_color=GREEN&left_text=PyPI-downloads)](https://pypistats.org/packages/nextrec)
 ![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.20-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 English | [中文文档](README.md)
@@ -44,6 +44,7 @@ NextRec is a modern recommendation framework built on PyTorch, delivering a unif
 
 ## NextRec Progress
 
+- **28/12/2025** Added support for SwanLab and Weights & Biases in v0.4.21, configurable via the model `fit` method: `use_swanlab=True, swanlab_kwargs={"project": "NextRec","name":"tutorial_movielens_deepfm"},`
 - **21/12/2025** Added support for [GradNorm](/nextrec/loss/grad_norm.py) in v0.4.16, configurable via `loss_weight='grad_norm'` in the compile method
 - **12/12/2025** Added [RQ-VAE](/nextrec/models/representation/rqvae.py), a common module for generative retrieval in v0.4.9. Paired [dataset](/dataset/ecommerce_task.csv) and [notebook code](tutorials/notebooks/en/Build%20semantic%20ID%20with%20RQ-VAE.ipynb) are available.
 - **07/12/2025** Released the NextRec CLI tool to run training/inference from configs. See the [guide](/nextrec_cli_preset/NextRec-CLI.md) and [reference code](/nextrec_cli_preset).
@@ -190,11 +191,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 Prediction outputs are saved under `{checkpoint_path}/predictions/{name}.{save_data_format}`.
 
-> As of version 0.4.20, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.22, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.20. 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.22. 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.20 → nextrec-0.4.22}/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.20"
+release = "0.4.22"
 
 extensions = [
     "myst_parser",

{nextrec-0.4.20 → nextrec-0.4.22}/docs/rtd/index.md

@@ -70,7 +70,7 @@ model.fit(
     batch_size=512,
     shuffle=True,
     verbose=1,
-    validation_split=0.1,
+    valid_split=0.1,
 )
 
 preds = model.predict(df)
@@ -121,7 +121,7 @@ model.fit(
     batch_size=256,
     shuffle=True,
     verbose=1,
-    validation_split=0.1,                      # auto split when valid_data is None
+    valid_split=0.1,                      # auto split when valid_data is None
 )
 
 scores = model.evaluate(valid_df_or_loader)    # returns metric dict

nextrec-0.4.22/nextrec/__version__.py

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

{nextrec-0.4.20 → nextrec-0.4.22}/nextrec/basic/activation.py

@@ -1,8 +1,8 @@
 """
-Activation function definitions
+Activation function definitions for NextRec models.
 
 Date: create on 27/10/2025
-Checkpoint: edit on 29/11/2025
+Checkpoint: edit on 28/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
@@ -10,6 +10,9 @@ import torch
 import torch.nn as nn
 
 
+from nextrec.utils.types import ActivationName
+
+
 class Dice(nn.Module):
     """
     Dice activation function from the paper:
@@ -41,9 +44,11 @@ class Dice(nn.Module):
         return output
 
 
-def activation_layer(activation: str, emb_size: int | None = None):
+def activation_layer(
+    activation: ActivationName = "none",
+    emb_size: int | None = None,
+):
     """Create an activation layer based on the given activation name."""
-    activation = activation.lower()
     if activation == "dice":
         if emb_size is None:
             raise ValueError(

{nextrec-0.4.20 → nextrec-0.4.22}/nextrec/basic/callback.py

@@ -2,7 +2,7 @@
 Callback System for Training Process
 
 Date: create on 27/10/2025
-Checkpoint: edit on 19/12/2025
+Checkpoint: edit on 27/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
@@ -61,16 +61,16 @@ class Callback:
         self.params = params
 
     def should_run(self) -> bool:
-        if not getattr(self, "run_on_main_process_only", False):
+        if not self.run_on_main_process_only:
             return True
-        model = getattr(self, "model", None)
-        if model is None:
-            return True
-        return bool(getattr(model, "is_main_process", True))
+        model = self.model
+        return bool(model.is_main_process)
 
 
 class CallbackList:
-    """Generates a list of callbacks"""
+    """
+    Generates a list of callbacks
+    """
 
     def __init__(self, callbacks: Optional[list[Callback]] = None):
         self.callbacks = callbacks or []
@@ -85,7 +85,8 @@ class CallbackList:
             getattr(callback, fn_name)(*args, **kwargs)
 
     def set_model(self, model):
-        self.call("set_model", model)
+        for callback in self.callbacks:
+            callback.set_model(model)
 
     def set_params(self, params: dict):
         self.call("set_params", params)
@@ -194,9 +195,8 @@ class EarlyStopper(Callback):
             self.wait += 1
             if self.wait >= self.patience:
                 self.stopped_epoch = epoch
-                if hasattr(self.model, "stop_training"):
-                    self.model.stop_training = True
-                if self.verbose > 0:
+                self.model.stop_training = True
+                if self.verbose == 1:
                     logging.info(
                         f"Early stopping triggered at epoch {epoch + 1}. "
                         f"Best {self.monitor}: {self.best_value:.6f} at epoch {self.best_epoch + 1}"
@@ -218,14 +218,15 @@ class EarlyStopper(Callback):
 
 
 class CheckpointSaver(Callback):
-    """Callback to save model checkpoints during training.
+    """
+    Callback to save model checkpoints during training.
 
     Args:
         save_path: Path to save checkpoints.
         monitor: Metric name to monitor for saving best model.
         mode: One of {'min', 'max'}.
         save_best_only: If True, only save when the model is considered the "best".
-        save_freq: Frequency of checkpoint saving ('epoch' or integer for every N epochs).
+        save_freq: Frequency of checkpoint saving (integer for every N epochs).
         verbose: Verbosity mode.
         run_on_main_process_only: Whether to run this callback only on the main process in DDP.
     """
@@ -237,7 +238,7 @@ class CheckpointSaver(Callback):
         monitor: str = "val_auc",
         mode: str = "max",
         save_best_only: bool = False,
-        save_freq: str | int = "epoch",
+        save_freq: int = 1,
         verbose: int = 1,
         run_on_main_process_only: bool = True,
     ):
@@ -272,7 +273,7 @@ class CheckpointSaver(Callback):
         logs = logs or {}
 
         should_save = False
-        if self.save_freq == "epoch":
+        if self.save_freq == 1:
             should_save = True
         elif isinstance(self.save_freq, int) and (epoch + 1) % self.save_freq == 0:
             should_save = True
@@ -306,12 +307,10 @@ class CheckpointSaver(Callback):
 
     def save_checkpoint(self, path: Path, epoch: int, logs: dict):
 
-        # Get the actual model (unwrap DDP if needed)
-        model_to_save = (
-            self.model.ddp_model.module
-            if getattr(self.model, "ddp_model", None) is not None
-            else self.model
-        )
+        if hasattr(self.model, "ddp_model") and self.model.ddp_model is not None:
+            model_to_save = self.model.ddp_model.module
+        else:
+            model_to_save = self.model
 
         # Save only state_dict to match BaseModel.save_model() format
         torch.save(model_to_save.state_dict(), path)
@@ -328,12 +327,13 @@ class CheckpointSaver(Callback):
             with open(config_path, "wb") as f:
                 pickle.dump(features_config, f)
 
-        if self.verbose > 1:
+        if self.verbose == 1:
             logging.info(f"Saved checkpoint to {path}")
 
 
 class LearningRateScheduler(Callback):
-    """Callback for learning rate scheduling.
+    """
+    Callback for learning rate scheduling.
 
     Args:
         scheduler: Learning rate scheduler instance or name.
@@ -346,73 +346,25 @@ class LearningRateScheduler(Callback):
         self.verbose = verbose
 
     def on_train_begin(self, logs: Optional[dict] = None):
-        if self.scheduler is None and hasattr(self.model, "scheduler_fn"):
+        if self.scheduler is None:
             self.scheduler = self.model.scheduler_fn
 
     def on_epoch_end(self, epoch: int, logs: Optional[dict] = None):
         if self.scheduler is not None:
-            # Get current lr before step
-            if hasattr(self.model, "optimizer_fn"):
-                old_lr = self.model.optimizer_fn.param_groups[0]["lr"]
-
-            # Step the scheduler
-            if hasattr(self.scheduler, "step"):
-                # Some schedulers need metrics
-                if logs is None:
-                    logs = {}
-                if "val_loss" in logs and hasattr(self.scheduler, "mode"):
-                    self.scheduler.step(logs["val_loss"])
-                else:
-                    self.scheduler.step()
+            old_lr = self.model.optimizer_fn.param_groups[0]["lr"]
+            if logs is None:
+                logs = {}
 
-            # Log new lr
-            if self.verbose > 0 and hasattr(self.model, "optimizer_fn"):
-                if getattr(self.model, "is_main_process", True):
-                    new_lr = self.model.optimizer_fn.param_groups[0]["lr"]
-                    if new_lr != old_lr:
-                        logging.info(
-                            f"Learning rate changed from {old_lr:.6e} to {new_lr:.6e}"
-                        )
+            # step for ReduceLROnPlateau
+            if "val_loss" in logs and hasattr(self.scheduler, "mode"):
+                self.scheduler.step(logs["val_loss"])
+            else:
+                self.scheduler.step()
 
-
-class MetricsLogger(Callback):
-    """Callback for logging training metrics.
-
-    Args:
-        log_freq: Frequency of logging ('epoch', 'batch', or integer for every N epochs/batches).
-        verbose: Verbosity mode.
-    """
-
-    def __init__(self, log_freq: str | int = "epoch", verbose: int = 1):
-        super().__init__()
-        self.run_on_main_process_only = True
-        self.log_freq = log_freq
-        self.verbose = verbose
-
-    def on_epoch_end(self, epoch: int, logs: Optional[dict] = None):
-        if self.verbose > 0 and (
-            self.log_freq == "epoch"
-            or (isinstance(self.log_freq, int) and (epoch + 1) % self.log_freq == 0)
-        ):
-            logs = logs or {}
-            metrics_str = " - ".join(
-                [
-                    f"{k}: {v:.6f}" if isinstance(v, float) else f"{k}: {v}"
-                    for k, v in logs.items()
-                ]
-            )
-            logging.info(f"Epoch {epoch + 1}: {metrics_str}")
-
-    def on_batch_end(self, batch: int, logs: Optional[dict] = None):
-        if self.verbose > 1 and (
-            self.log_freq == "batch"
-            or (isinstance(self.log_freq, int) and (batch + 1) % self.log_freq == 0)
-        ):
-            logs = logs or {}
-            metrics_str = " - ".join(
-                [
-                    f"{k}: {v:.6f}" if isinstance(v, float) else f"{k}: {v}"
-                    for k, v in logs.items()
-                ]
-            )
-            logging.info(f"Batch {batch}: {metrics_str}")
+            # Log new lr
+            if self.verbose == 1:
+                new_lr = self.model.optimizer_fn.param_groups[0]["lr"]
+                if new_lr != old_lr:
+                    logging.info(
+                        f"Learning rate changed from {old_lr:.6e} to {new_lr:.6e}"
+                    )