nextrec 0.4.13__tar.gz → 0.4.15__tar.gz

nextrec-0.4.15/.github/workflows/publish.yml

@@ -0,0 +1,107 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  workflow_dispatch:
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.version.outputs.changed }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Compare project version
+        id: version
+        run: |
+          before="${{ github.event.before }}"
+          after="${{ github.sha }}"
+          zero_sha="0000000000000000000000000000000000000000"
+
+          if [ -z "$before" ] || [ "$before" = "$zero_sha" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          get_version() {
+            git show "$1:pyproject.toml" | grep -m 1 '^version[[:space:]]*=' | sed -E 's/.*"([^"]+)".*/\1/'
+          }
+
+          before_version="$(get_version "$before" || true)"
+          after_version="$(get_version "$after" || true)"
+
+          if [ -z "$before_version" ] || [ -z "$after_version" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ "$before_version" = "$after_version" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  # dev -> TestPyPI
+  publish-to-testpypi:
+    needs: check-version
+    if: needs.check-version.outputs.changed == 'true' && github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install build tools
+        run: |
+          pip install build twine
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Publish to TestPyPI
+        env:
+          TWINE_USERNAME: ${{ secrets.TEST_PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_PASSWORD }}
+        run: |
+          twine upload --verbose --repository testpypi dist/*
+
+  # main -> PyPI
+  publish-to-pypi:
+    needs: check-version
+    if: needs.check-version.outputs.changed == 'true' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install build tools
+        run: |
+          pip install build twine
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          twine upload --verbose dist/*

{nextrec-0.4.13 → nextrec-0.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.13
+Version: 0.4.15
 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
@@ -63,10 +63,13 @@ 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://pepy.tech/projects/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.13-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.15-orange.svg)
+
 
 中文文档 | [English Version](README_en.md)
 
@@ -99,7 +102,8 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 
 ## NextRec近期进展
 
-- **12/12/2025** 在v0.4.13中加入了[RQ-VAE](/nextrec/models/representation/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynb)已经同步在仓库中
+- **21/12/2025** 在v0.4.15中加入了对[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)
 - **03/12/2025** NextRec获得了100颗🌟！感谢大家的支持
 - **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
@@ -240,11 +244,11 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> 截止当前版本0.4.13，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.15，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.13，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.15，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.13 → nextrec-0.4.15}/README.md

@@ -4,10 +4,13 @@
 
 <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://pepy.tech/projects/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.13-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.15-orange.svg)
+
 
 中文文档 | [English Version](README_en.md)
 
@@ -40,7 +43,8 @@ NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究工程
 
 ## NextRec近期进展
 
-- **12/12/2025** 在v0.4.13中加入了[RQ-VAE](/nextrec/models/representation/rqvae.py)模块。配套的[数据集](/dataset/ecommerce_task.csv)和[代码](tutorials/notebooks/zh/使用RQ-VAE构建语义ID.ipynb)已经同步在仓库中
+- **21/12/2025** 在v0.4.15中加入了对[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)
 - **03/12/2025** NextRec获得了100颗🌟！感谢大家的支持
 - **06/12/2025** 在v0.4.1中支持了单机多卡的分布式DDP训练，并且提供了配套的[代码](tutorials/distributed)
@@ -181,11 +185,11 @@ nextrec --mode=train --train_config=path/to/train_config.yaml
 nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 ```
 
-> 截止当前版本0.4.13，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.15，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.13，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.15，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.13 → nextrec-0.4.15}/README_en.md

@@ -4,10 +4,12 @@
 
 <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://pepy.tech/projects/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.13-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.15-orange.svg)
 
 English | [中文文档](README.md)
 
@@ -42,7 +44,8 @@ NextRec is a modern recommendation framework built on PyTorch, delivering a unif
 
 ## NextRec Progress
 
-- **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.
+- **21/12/2025** Added support for [GradNorm](/nextrec/loss/grad_norm.py) in v0.4.15, 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).
 - **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).
@@ -185,11 +188,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.13, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.15, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.13. 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.15. 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.13 → nextrec-0.4.15}/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.13"
+release = "0.4.15"
 
 extensions = [
     "myst_parser",

nextrec-0.4.15/nextrec/__version__.py

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

{nextrec-0.4.13 → nextrec-0.4.15}/nextrec/basic/model.py

@@ -341,7 +341,7 @@ class BaseModel(FeatureSet, nn.Module):
                     )
         else:
             raise TypeError(
-                f"[BaseModel-validation Error] train_data must be a pandas DataFrame or a dict, got {type(train_data)}"
+                f"[BaseModel-validation Error] If you want to use validation_split, train_data must be a pandas DataFrame or a dict instead of {type(train_data)}"
             )
         rng = np.random.default_rng(42)
         indices = rng.permutation(total_length)
@@ -481,7 +481,7 @@ class BaseModel(FeatureSet, nn.Module):
                         "[BaseModel-compile Error] loss_weights list must have exactly one element for single-task setup."
                     )
                 loss_weights = loss_weights[0]
-            self.loss_weights = [float(loss_weights)]
+            self.loss_weights = [float(loss_weights)] # type: ignore
         else:
             if isinstance(loss_weights, (int, float)):
                 weights = [float(loss_weights)] * self.nums_task
@@ -555,13 +555,13 @@ class BaseModel(FeatureSet, nn.Module):
 
     def prepare_data_loader(
         self,
-        data: dict | pd.DataFrame | DataLoader,
+        data,
         batch_size: int = 32,
         shuffle: bool = True,
         num_workers: int = 0,
         sampler=None,
         return_dataset: bool = False,
-    ) -> DataLoader | tuple[DataLoader, TensorDictDataset | None]:
+    ):
         """
         Prepare a DataLoader from input data. Only used when input data is not a DataLoader.
         """
@@ -591,8 +591,8 @@ class BaseModel(FeatureSet, nn.Module):
 
     def fit(
         self,
-        train_data: dict | pd.DataFrame | DataLoader,
-        valid_data: dict | pd.DataFrame | DataLoader | None = None,
+        train_data = None,
+        valid_data = None,
         metrics: (
             list[str] | dict[str, list[str]] | None
         ) = None,  # ['auc', 'logloss'] or {'target1': ['auc', 'logloss'], 'target2': ['mse']}
@@ -1420,6 +1420,11 @@ class BaseModel(FeatureSet, nn.Module):
         # Create DataLoader based on data type
         if isinstance(data, DataLoader):
             data_loader = data
+            if num_workers != 0:
+                logging.warning(
+                    "[Predict Warning] num_workers parameter is ignored when data is already a DataLoader. "
+                    "The DataLoader's existing num_workers configuration will be used."
+                )
         elif isinstance(data, (str, os.PathLike)):
             rec_loader = RecDataLoader(
                 dense_features=self.dense_features,
@@ -1578,6 +1583,14 @@ class BaseModel(FeatureSet, nn.Module):
         else:
             data_loader = data
 
+            if hasattr(data_loader, 'num_workers') and data_loader.num_workers > 0:
+                if hasattr(data_loader.dataset, '__class__') and 'Streaming' in data_loader.dataset.__class__.__name__:
+                    logging.warning(
+                        f"[Predict Streaming Warning] Detected DataLoader with num_workers={data_loader.num_workers} "
+                        "and streaming dataset. This may cause data duplication! "
+                        "When using streaming mode, set num_workers=0 to avoid reading data multiple times."
+                    )
+
         suffix = ".csv" if save_format == "csv" else ".parquet"
         target_path = resolve_save_path(
             path=save_path,
@@ -1943,6 +1956,12 @@ class BaseModel(FeatureSet, nn.Module):
             logger.info(f"Loss Function:           {self.loss_config}")
         if hasattr(self, "loss_weights"):
             logger.info(f"Loss Weights:            {self.loss_weights}")
+        if hasattr(self, "grad_norm"):
+            logger.info(f"GradNorm Enabled:        {self.grad_norm is not None}")
+            if self.grad_norm is not None:
+                grad_lr = self.grad_norm.optimizer.param_groups[0].get("lr")
+                logger.info(f"  GradNorm alpha:        {self.grad_norm.alpha}")
+                logger.info(f"  GradNorm lr:           {grad_lr}")
 
         logger.info("Regularization:")
         logger.info(f"  Embedding L1:          {self.embedding_l1_reg}")

{nextrec-0.4.13 → nextrec-0.4.15}/nextrec/cli.py

@@ -21,6 +21,7 @@ Author: Yang Zhou, zyaztec@gmail.com
 import argparse
 import logging
 import pickle
+import resource
 import sys
 import time
 from pathlib import Path
@@ -625,6 +626,17 @@ def predict_model(predict_config_path: str) -> None:
 def main() -> None:
     """Parse CLI arguments and dispatch to train or predict mode."""
 
+    # Increase file descriptor limit to avoid "Too many open files" error
+    # when using DataLoader with multiple workers
+    try:
+        soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)
+        target_limit = 65535
+        if soft < target_limit:
+            resource.setrlimit(resource.RLIMIT_NOFILE, (min(target_limit, hard), hard))
+    except (ValueError, OSError):
+        # If we can't set the limit, continue anyway
+        pass
+
     root = logging.getLogger()
     if not root.handlers:
         handler = logging.StreamHandler(sys.stdout)

{nextrec-0.4.13 → nextrec-0.4.15}/nextrec/data/dataloader.py

@@ -186,6 +186,7 @@ class RecDataLoader(FeatureSet):
             | list[str]
             | list[os.PathLike]
             | DataLoader
+            | None
         ),
         batch_size: int = 32,
         shuffle: bool = True,
@@ -209,6 +210,15 @@ class RecDataLoader(FeatureSet):
             DataLoader instance.
         """
 
+        # Enforce num_workers=0 for streaming mode to prevent data duplication
+        if streaming and num_workers > 0:
+            logging.warning(
+                f"[RecDataLoader Warning] num_workers={num_workers} is not compatible with streaming=True. "
+                "Each worker would create its own data stream, causing data duplication. "
+                "Forcing num_workers=0."
+            )
+            num_workers = 0
+
         if isinstance(data, DataLoader):
             return data
         elif isinstance(data, (str, os.PathLike)):
@@ -362,6 +372,13 @@ class RecDataLoader(FeatureSet):
             logging.info(
                 "[RecDataLoader Info] Streaming mode enforces batch_size=1; tune chunk_size to control memory/throughput."
             )
+        if num_workers > 0:
+            logging.warning(
+                f"[RecDataLoader Warning] num_workers={num_workers} is not compatible with streaming mode. "
+                "Each worker would create its own data stream, causing data duplication. "
+                "Forcing num_workers=0."
+            )
+            num_workers = 0
         dataset = FileDataset(
             file_paths=file_paths,
             dense_features=self.dense_features,

{nextrec-0.4.13 → nextrec-0.4.15}/nextrec/utils/config.py

@@ -28,19 +28,19 @@ if TYPE_CHECKING:
     from nextrec.data.preprocessor import DataProcessor
 
 
-def resolve_path(path_str: str | Path, base_dir: Path) -> Path:
+def resolve_path(path_str: str | Path | None = None, base_dir: Path | None = None) -> Path:
+    if path_str is None:
+        return Path.cwd()
     path = Path(path_str).expanduser()
     if path.is_absolute():
         return path
     # Prefer resolving relative to current working directory when the path (or its parent)
     # already exists there; otherwise fall back to the config file's directory.
-    cwd_path = (Path.cwd() / path).resolve()
-    if cwd_path.exists() or cwd_path.parent.exists():
-        return cwd_path
-    base_dir_path = (base_dir / path).resolve()
-    if base_dir_path.exists() or base_dir_path.parent.exists():
-        return base_dir_path
-    return cwd_path
+    candidates = ((Path.cwd() / path).resolve(), ((base_dir or Path.cwd()) / path).resolve())
+    return next(
+        (candidate for candidate in candidates if candidate.exists() or candidate.parent.exists()),
+        candidates[0],
+    )
 
 
 def select_features(

{nextrec-0.4.13 → nextrec-0.4.15}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextrec"
-version = "0.4.13"
+version = "0.4.15"
 description = "A comprehensive recommendation library with match, ranking, and multi-task learning models"
 readme = "README.md"
 requires-python = ">=3.10"

nextrec-0.4.13/.github/workflows/publish.yml

@@ -1,65 +0,0 @@
-name: Publish to PyPI
-
-on:
-  push:
-    branches:
-      - main
-      - dev
-  workflow_dispatch:
-
-jobs:
-  # dev -> TestPyPI
-  publish-to-testpypi:
-    if: github.ref == 'refs/heads/dev'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-
-      - name: Install build tools
-        run: |
-          pip install build twine
-
-      - name: Build package
-        run: |
-          python -m build
-
-      - name: Publish to TestPyPI
-        env:
-          TWINE_USERNAME: ${{ secrets.TEST_PYPI_USERNAME }}
-          TWINE_PASSWORD: ${{ secrets.TEST_PYPI_PASSWORD }}
-        run: |
-          twine upload --verbose --repository testpypi dist/*
-
-  # main -> PyPI
-  publish-to-pypi:
-    if: github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-
-      - name: Install build tools
-        run: |
-          pip install build twine
-
-      - name: Build package
-        run: |
-          python -m build
-
-      - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
-          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: |
-          twine upload --verbose dist/*

nextrec-0.4.13/nextrec/__version__.py

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