nextrec 0.4.8__tar.gz → 0.4.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.8
+Version: 0.4.9
 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
@@ -33,6 +33,7 @@ Requires-Dist: pyarrow<15.0.0,>=12.0.0; sys_platform == 'win32'
 Requires-Dist: pyarrow>=12.0.0; sys_platform == 'darwin'
 Requires-Dist: pyarrow>=16.0.0; sys_platform == 'linux' and python_version >= '3.12'
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
 Requires-Dist: scikit-learn<2.0,>=1.2; sys_platform == 'linux' and python_version < '3.12'
 Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'darwin'
 Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'linux' and python_version >= '3.12'
@@ -43,7 +44,6 @@ 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: torch>=2.0.0
 Requires-Dist: torchvision>=0.15.0
-Requires-Dist: tqdm>=4.65.0
 Requires-Dist: transformers>=4.38.0
 Provides-Extra: dev
 Requires-Dist: jupyter>=1.0.0; extra == 'dev'
@@ -66,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.8-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.9-orange.svg)
 
 中文文档 | [English Version](README_en.md)
 
@@ -99,7 +99,7 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 
 ## NextRec近期进展
 
-- **12/12/2025** 在v0.4.8中加入了[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
+- **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)
 - **03/12/2025** NextRec获得了100颗🌟！感谢大家的支持
 - **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
@@ -241,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.8，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.9，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.8，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.9，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.8 → nextrec-0.4.9}/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.8-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.9-orange.svg)
 
 中文文档 | [English Version](README_en.md)
 
@@ -40,7 +40,7 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 
 ## NextRec近期进展
 
-- **12/12/2025** 在v0.4.8中加入了[RQ-VAE](/nextrec/models/generative/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynby)已经同步在仓库中
+- **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)
 - **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.8，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.9，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.8，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.9，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.8 → nextrec-0.4.9}/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.8-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.9-orange.svg)
 
 English | [中文文档](README.md)
 
@@ -42,7 +42,7 @@ NextRec is a modern recommendation framework built on PyTorch, delivering a unif
 
 ## NextRec Progress
 
-- **12/12/2025** Added [RQ-VAE](/nextrec/models/generative/rqvae.py), a common module for generative retrieval. Paired [dataset](/dataset/ecommerce_task.csv) and [notebook code](tutorials/notebooks/en/Build%20semantic%20ID%20with%20RQ-VAE.ipynb) are available.
+- **12/12/2025** Added [RQ-VAE](/nextrec/models/representation/rqvae.py), a common module for generative retrieval. 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).
 - **03/12/2025** NextRec reached 100 ⭐—thanks for the support!
 - **06/12/2025** Added single-machine multi-GPU DDP training in v0.4.1 with supporting [code](tutorials/distributed).
@@ -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.8, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.9, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-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:
+The current version is 0.4.9. 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.8 → nextrec-0.4.9}/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.8"
+release = "0.4.9"
 
 extensions = [
     "myst_parser",

nextrec-0.4.9/docs/rtd/nextrec.utils.rst

@@ -0,0 +1,69 @@
+nextrec.utils package
+=====================
+
+Submodules
+----------
+
+nextrec.utils.embedding module
+------------------------------
+
+.. automodule:: nextrec.utils.embedding
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.utils.console module
+----------------------------
+
+.. automodule:: nextrec.utils.console
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.utils.data module
+-------------------------
+
+.. automodule:: nextrec.utils.data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.utils.feature module
+----------------------------
+
+.. automodule:: nextrec.utils.feature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.utils.model module
+--------------------------
+
+.. automodule:: nextrec.utils.model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.utils.config module
+---------------------------
+
+.. automodule:: nextrec.utils.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+nextrec.utils.torch_utils module
+--------------------------------
+
+.. automodule:: nextrec.utils.torch_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: nextrec.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

nextrec-0.4.9/nextrec/__version__.py

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

{nextrec-0.4.8 → nextrec-0.4.9}/nextrec/basic/callback.py

@@ -2,17 +2,20 @@
 Callback System for Training Process
 
 Date: create on 27/10/2025
-Checkpoint: edit on 17/12/2025
+Checkpoint: edit on 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
 import copy
 import logging
-from typing import Optional
+import pickle
 from pathlib import Path
+from typing import Optional
+
 import torch
-import pickle
+
 from nextrec import __version__
+from nextrec.basic.loggers import colorize, format_kv
 
 
 class Callback:
@@ -209,8 +212,13 @@ class EarlyStopper(Callback):
         if self.restore_best_weights and self.best_weights is not None:
             if self.verbose > 0:
                 logging.info(
-                    f"Restoring model weights from epoch {self.best_epoch + 1} "
-                    f"with best {self.monitor}: {self.best_value:.6f}"
+                    colorize(
+                        format_kv(
+                            "Restoring model weights from epoch",
+                            f"{self.best_epoch + 1} with best {self.monitor}: {self.best_value:.6f}",
+                        ),
+                        color="bright_blue",
+                    )
                 )
             self.model.load_state_dict(self.best_weights)
 
@@ -229,7 +237,8 @@ class CheckpointSaver(Callback):
 
     def __init__(
         self,
-        save_path: str | Path,
+        best_path: str | Path,
+        checkpoint_path: str | Path,
         monitor: str = "val_auc",
         mode: str = "max",
         save_best_only: bool = False,
@@ -239,7 +248,8 @@ class CheckpointSaver(Callback):
     ):
         super().__init__()
         self.run_on_main_process_only = run_on_main_process_only
-        self.save_path = Path(save_path)
+        self.best_path = Path(best_path)
+        self.checkpoint_path = Path(checkpoint_path)
         self.monitor = monitor
         self.mode = mode
         self.save_best_only = save_best_only
@@ -260,14 +270,13 @@ class CheckpointSaver(Callback):
             self.best_value = float("inf")
         else:
             self.best_value = float("-inf")
-
-        # Create directory if it doesn't exist
-        self.save_path.parent.mkdir(parents=True, exist_ok=True)
+        self.best_path.parent.mkdir(parents=True, exist_ok=True)
+        self.checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
 
     def on_epoch_end(self, epoch: int, logs: Optional[dict] = None):
+        logging.info("")
         logs = logs or {}
 
-        # Check if we should save this epoch
         should_save = False
         if self.save_freq == "epoch":
             should_save = True
@@ -289,17 +298,23 @@ class CheckpointSaver(Callback):
         if should_save:
             if not self.save_best_only or is_best:
                 checkpoint_path = (
-                    self.save_path.parent
-                    / f"{self.save_path.stem}_epoch_{epoch + 1}{self.save_path.suffix}"
+                    self.checkpoint_path.parent
+                    / f"{self.checkpoint_path.stem}{self.checkpoint_path.suffix}"
                 )
                 self.save_checkpoint(checkpoint_path, epoch, logs)
 
                 if is_best:
                     # Use save_path directly without adding _best suffix since it may already contain it
-                    self.save_checkpoint(self.save_path, epoch, logs)
+                    self.save_checkpoint(self.best_path, epoch, logs)
                     if self.verbose > 0:
                         logging.info(
-                            f"Saved best model to {self.save_path} with {self.monitor}: {current:.6f}"
+                            colorize(
+                                format_kv(
+                                    "Saved best model to",
+                                    f"{self.best_path} with {self.monitor}: {current:.6f}",
+                                ),
+                                color="bright_blue",
+                            )
                         )
 
     def save_checkpoint(self, path: Path, epoch: int, logs: dict):

{nextrec-0.4.8 → nextrec-0.4.9}/nextrec/basic/features.py

@@ -7,6 +7,7 @@ Author: Yang Zhou, zyaztec@gmail.com
 """
 
 import torch
+
 from nextrec.utils.embedding import get_auto_embedding_dim
 from nextrec.utils.feature import normalize_to_list
 

{nextrec-0.4.8 → nextrec-0.4.9}/nextrec/basic/layers.py

@@ -2,22 +2,22 @@
 Layer implementations used across NextRec models.
 
 Date: create on 27/10/2025
-Checkpoint: edit on 29/11/2025
+Checkpoint: edit on 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
 from __future__ import annotations
 
+from collections import OrderedDict
+from itertools import combinations
+
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
 
-from itertools import combinations
-from collections import OrderedDict
-
-from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
-from nextrec.utils.initializer import get_initializer
 from nextrec.basic.activation import activation_layer
+from nextrec.basic.features import DenseFeature, SequenceFeature, SparseFeature
+from nextrec.utils.torch_utils import get_initializer
 
 
 class PredictionLayer(nn.Module):
@@ -81,8 +81,6 @@ class PredictionLayer(nn.Module):
                 outputs.append(torch.sigmoid(task_logits))
             elif task == "regression":
                 outputs.append(task_logits)
-            elif task == "multiclass":
-                outputs.append(torch.softmax(task_logits, dim=-1))
             else:
                 raise ValueError(
                     f"[PredictionLayer Error]: Unsupported task_type '{task_type}'."

{nextrec-0.4.8 → nextrec-0.4.9}/nextrec/basic/loggers.py

@@ -2,20 +2,20 @@
 NextRec Basic Loggers
 
 Date: create on 27/10/2025
-Checkpoint: edit on 03/12/2025
+Checkpoint: edit on 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
-import os
-import re
-import sys
-import json
 import copy
+import json
 import logging
 import numbers
+import os
+import re
+import sys
+from typing import Any, Mapping
 
-from typing import Mapping, Any
-from nextrec.basic.session import create_session, Session
+from nextrec.basic.session import Session, create_session
 
 ANSI_CODES = {
     "black": "\033[30m",
@@ -91,6 +91,13 @@ def colorize(text: str, color: str | None = None, bold: bool = False) -> str:
     return result
 
 
+def format_kv(label: str, value: Any, width: int = 34, indent: int = 0) -> str:
+    """Format key-value lines with consistent alignment."""
+    label_text = label if label.endswith(":") else f"{label}:"
+    prefix = " " * indent
+    return f"{prefix}{label_text:<{width}} {value}"
+
+
 def setup_logger(session_id: str | os.PathLike | None = None):
     """Set up a logger that logs to both console and a file with ANSI formatting.
     Only console output has colors; file output is stripped of ANSI codes.

{nextrec-0.4.8 → nextrec-0.4.9}/nextrec/basic/metrics.py

@@ -2,7 +2,7 @@
 Metrics computation and configuration for model evaluation.
 
 Date: create on 27/10/2025
-Checkpoint: edit on 02/12/2025
+Checkpoint: edit on 19/12/2025
 Author: Yang Zhou,zyaztec@gmail.com
 """
 
@@ -11,15 +11,15 @@ from typing import Any
 
 import numpy as np
 from sklearn.metrics import (
-    roc_auc_score,
+    accuracy_score,
+    f1_score,
     log_loss,
-    mean_squared_error,
     mean_absolute_error,
-    accuracy_score,
+    mean_squared_error,
     precision_score,
-    recall_score,
-    f1_score,
     r2_score,
+    recall_score,
+    roc_auc_score,
 )
 
 CLASSIFICATION_METRICS = {
@@ -44,11 +44,6 @@ TASK_DEFAULT_METRICS = {
     + [f"recall@{k}" for k in (5, 10, 20)]
     + [f"ndcg@{k}" for k in (5, 10, 20)]
     + [f"mrr@{k}" for k in (5, 10, 20)],
-    # generative/multiclass next-item prediction defaults
-    "multiclass": ["accuracy"]
-    + [f"hitrate@{k}" for k in (1, 5, 10)]
-    + [f"recall@{k}" for k in (1, 5, 10)]
-    + [f"mrr@{k}" for k in (1, 5, 10)],
 }
 
 
@@ -163,51 +158,6 @@ def group_indices_by_user(user_ids: np.ndarray, n_samples: int) -> list[np.ndarr
     return groups
 
 
-def normalize_multiclass_inputs(
-    y_true: np.ndarray, y_pred: np.ndarray
-) -> tuple[np.ndarray, np.ndarray]:
-    """
-    Normalize multiclass inputs to consistent shapes.
-
-    y_true: [N] of class ids
-    y_pred: [N, C] of logits/probabilities
-    """
-    labels = np.asarray(y_true).reshape(-1)
-    scores = np.asarray(y_pred)
-    if scores.ndim == 1:
-        scores = scores.reshape(scores.shape[0], -1)
-    if scores.shape[0] != labels.shape[0]:
-        raise ValueError(
-            f"[Metric Warning] y_true length {labels.shape[0]} != y_pred batch {scores.shape[0]} for multiclass metrics."
-        )
-    return labels.astype(int), scores
-
-
-def multiclass_topk_hit_rate(y_true: np.ndarray, y_pred: np.ndarray, k: int) -> float:
-    labels, scores = normalize_multiclass_inputs(y_true, y_pred)
-    if scores.shape[1] == 0:
-        return 0.0
-    k = min(k, scores.shape[1])
-    topk_idx = np.argpartition(-scores, kth=k - 1, axis=1)[:, :k]
-    hits = (topk_idx == labels[:, None]).any(axis=1)
-    return float(hits.mean()) if hits.size > 0 else 0.0
-
-
-def multiclass_mrr_at_k(y_true: np.ndarray, y_pred: np.ndarray, k: int) -> float:
-    labels, scores = normalize_multiclass_inputs(y_true, y_pred)
-    if scores.shape[1] == 0:
-        return 0.0
-    k = min(k, scores.shape[1])
-    # full sort for stable ranks
-    topk_idx = np.argsort(-scores, axis=1)[:, :k]
-    ranks = np.full(labels.shape, fill_value=k + 1, dtype=np.float32)
-    for idx in range(k):
-        match = topk_idx[:, idx] == labels
-        ranks[match] = idx + 1
-    reciprocals = np.where(ranks <= k, 1.0 / ranks, 0.0)
-    return float(reciprocals.mean()) if reciprocals.size > 0 else 0.0
-
-
 def compute_precision_at_k(
     y_true: np.ndarray, y_pred: np.ndarray, user_ids: np.ndarray, k: int
 ) -> float:
@@ -514,26 +464,6 @@ def compute_single_metric(
     """Compute a single metric given true and predicted values."""
     y_p_binary = (y_pred > 0.5).astype(int)
     metric_lower = metric.lower()
-    is_multiclass = task_type == "multiclass" and y_pred.ndim >= 2
-    if is_multiclass:
-        # Dedicated path for multiclass logits (e.g., next-item prediction)
-        labels, scores = normalize_multiclass_inputs(y_true, y_pred)
-        if metric_lower in ("accuracy", "acc"):
-            preds = scores.argmax(axis=1)
-            return float((preds == labels).mean())
-        if metric_lower.startswith("hitrate@") or metric_lower.startswith("hr@"):
-            k_str = metric_lower.split("@")[1]
-            k = int(k_str)
-            return multiclass_topk_hit_rate(labels, scores, k)
-        if metric_lower.startswith("recall@"):
-            k = int(metric_lower.split("@")[1])
-            return multiclass_topk_hit_rate(labels, scores, k)
-        if metric_lower.startswith("mrr@"):
-            k = int(metric_lower.split("@")[1])
-            return multiclass_mrr_at_k(labels, scores, k)
-        # fall back to accuracy if unsupported metric is requested
-        preds = scores.argmax(axis=1)
-        return float((preds == labels).mean())
     try:
         if metric_lower.startswith("recall@"):
             k = int(metric_lower.split("@")[1])