nextrec 0.4.2__tar.gz → 0.4.3__tar.gz

{nextrec-0.4.2 → nextrec-0.4.3}/.github/workflows/tests.yml

@@ -45,7 +45,23 @@ jobs:
       run: |
         python -c "import torch; print(f'PyTorch version: {torch.__version__}')"
         python -c "import nextrec; print('NextRec imported successfully')"
+
+    - name: Format codebase
+      run: |
+        python scripts/format_code.py
+                
+    - name: Run tutorial multi-task models
+      run: |
+        python tutorials/run_all_multitask_models.py
         
+    - name: Run tutorial ranking models
+      run: |
+        python tutorials/run_all_ranking_models.py
+        
+    - name: Run tutorial match models
+      run: |
+        python tutorials/run_all_match_models.py
+
     - name: Run match model tests
       run: |
         pytest test/test_match_models.py -v --cov=nextrec/models/match --cov-report=xml

{nextrec-0.4.2 → nextrec-0.4.3}/.gitignore

@@ -94,6 +94,7 @@ criteo/
 # Test coverage
 .coverage
 .coverage.*
+coverage.xml
 htmlcov/
 .tox/
 .hypothesis/

{nextrec-0.4.2 → nextrec-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.2
+Version: 0.4.3
 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,7 +63,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.2-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.3-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -71,16 +71,28 @@ English | [中文文档](README_zh.md)
 
 </div>
 
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [5-Minute Quick Start](#5-minute-quick-start)
+- [CLI Usage](#cli-usage)
+- [Platform Compatibility](#platform-compatibility)
+- [Supported Models](#supported-models)
+- [Contributing](#contributing)
+
 ## Introduction
 
-NextRec is a modern recommendation framework built on PyTorch, delivering a unified experience for modeling, training, and evaluation. It follows a modular design with rich model implementations, data-processing utilities, and engineering-ready training components. NextRec focuses on large-scale industrial recall scenarios on Spark clusters, training on massive offline parquet features.
+NextRec is a modern recommendation system framework built on PyTorch, providing researchers and engineering teams with a fast modeling, training, and evaluation experience. The framework adopts a modular design with rich built-in model implementations, data processing tools, and engineering-ready training components, covering various recommendation scenarios. NextRec provides easy-to-use interfaces, command-line tools, and tutorials, enabling recommendation algorithm learners to quickly understand model architectures and train and infer models at the fastest speed.
 
 ## Why NextRec
 
-- **Unified feature engineering & data pipeline**: Dense/Sparse/Sequence feature definitions, persistent DataProcessor, and batch-optimized RecDataLoader, matching offline feature training/inference in industrial big-data settings.
-- **Multi-scenario coverage**: Ranking (CTR/CVR), retrieval, multi-task learning, and more marketing/rec models, with a continuously expanding model zoo.
-- **Developer-friendly experience**: Stream processing/training/inference for csv/parquet/pathlike data, plus GPU/MPS acceleration and visualization support.
-- **Efficient training & evaluation**: Standardized engine with optimizers, LR schedulers, early stopping, checkpoints, and detailed logging out of the box.
+- **Unified feature engineering & data pipeline**: NextRec provides Dense/Sparse/Sequence feature definitions, persistent DataProcessor, and batch-optimized RecDataLoader, matching the model training and inference process based on offline `parquet/csv` features in industrial big-data Spark/Hive scenarios.
+- **Multi-scenario recommendation capabilities**: Covers ranking (CTR/CVR), retrieval, multi-task learning and other recommendation/marketing models, with a continuously expanding model zoo.
+- **Developer-friendly experience**: Supports stream preprocessing/distributed training/inference for various data formats (`csv/parquet/pathlike`), GPU acceleration and visual metric monitoring, facilitating experiments for business algorithm engineers and recommendation algorithm learners.
+- **Flexible command-line tool**: Through configuring training and inference config files, start training and inference processes with one command `nextrec --mode=train --train_config=train_config.yaml`, facilitating rapid experiment iteration and agile deployment.
+- **Efficient training & evaluation**: NextRec's standardized training engine comes with various optimizers, learning rate schedulers, early stopping, model checkpoints, and detailed log management built-in, ready to use out of the box.
 
 ## Architecture
 
@@ -96,34 +108,36 @@ NextRec adopts a modular and low-coupling engineering design, enabling full-pipe
 
 You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required.
 
-## Tutorials
 
-See `tutorials/` for examples covering ranking, retrieval, multi-task learning, and data processing:
+## Tutorials
 
-- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM training on MovieLens 100k
-- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN training on the e-commerce dataset
-- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task training on the e-commerce dataset
-- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval on MovieLens 100k
+We provide multiple examples in the `tutorials/` directory, covering ranking, retrieval, multi-task, and data processing scenarios:
 
-To dive deeper, Jupyter notebooks are available:
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM model training example on MovieLens 100k dataset
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN deep interest network training example on e-commerce dataset
+- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training example on e-commerce dataset
+- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model example trained on MovieLens 100k dataset
+- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly verify the availability of all ranking models
+- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly verify the availability of all multi-task models
+- [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly verify the availability of all retrieval models
 
-- [Hands on the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
-- [Using the data processor for preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
+If you want to learn more details about the NextRec framework, we also provide Jupyter notebooks to help you understand:
 
-> Current version [0.4.2]: the matching module is not fully polished yet and may have compatibility issues or unexpected errors. Please raise an issue if you run into problems.
+- [How to get started with the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
+- [How to use the data processor for data preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
 
 ## 5-Minute Quick Start
 
-We provide a detailed quick start and paired datasets to help you learn the framework. In `datasets/` you’ll find an e-commerce sample dataset like this:
+We provide a detailed quick start guide and paired datasets to help you become familiar with different features of the NextRec framework. We provide a test dataset from an e-commerce scenario in the `datasets/` path, with data examples as follows:
 
 | user_id | item_id | dense_0     | dense_1     | dense_2     | dense_3    | dense_4     | dense_5     | dense_6     | dense_7     | sparse_0 | sparse_1 | sparse_2 | sparse_3 | sparse_4 | sparse_5 | sparse_6 | sparse_7 | sparse_8 | sparse_9 | sequence_0                                               | sequence_1                                                | label |
 |--------|---------|-------------|-------------|-------------|------------|-------------|-------------|-------------|-------------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|-----------------------------------------------------------|-----------------------------------------------------------|-------|
 | 1      | 7817    | 0.14704075  | 0.31020382  | 0.77780896  | 0.944897   | 0.62315375  | 0.57124174  | 0.77009535  | 0.3211029   | 315      | 260      | 379      | 146      | 168      | 161      | 138      | 88       | 5        | 312      | [170,175,97,338,105,353,272,546,175,545,463,128,0,0,0]   | [368,414,820,405,548,63,327,0,0,0,0,0,0,0,0]              | 0     |
 | 1      | 3579    | 0.77811223  | 0.80359334  | 0.5185201   | 0.91091245 | 0.043562356 | 0.82142705  | 0.8803686   | 0.33748195 | 149      | 229      | 442      | 6        | 167      | 252      | 25       | 402      | 7        | 168      | [179,48,61,551,284,165,344,151,0,0,0,0,0,0,0]            | [814,0,0,0,0,0,0,0,0,0,0,0,0,0,0]                          | 1     |
 
-Below is a short example showing how to train a DIN model. DIN (Deep Interest Network) won Best Paper at KDD 2018 for CTR prediction. You can also run `python tutorials/example_ranking_din.py` directly.
+Next, we'll use a short example to show you how to train a DIN model using NextRec. DIN (Deep Interest Network) is from Alibaba's 2018 KDD Best Paper, used for CTR prediction scenarios. You can also directly execute `python tutorials/example_ranking_din.py` to run the training and inference code.
 
-After training, detailed logs are available under `nextrec_logs/din_tutorial`.
+After starting training, you can view detailed training logs in the `nextrec_logs/din_tutorial` path.
 
 ```python
 import pandas as pd
@@ -196,9 +210,25 @@ metrics = model.evaluate(
 )
 ```
 
+## CLI Usage
+
+NextRec provides a powerful command-line interface for model training and prediction using YAML configuration files. For detailed CLI documentation, see:
+
+- [NextRec CLI User Guide](/nextrec_cli_preset/NextRec-CLI.md) - Complete guide for using the CLI
+
+```bash
+# Train a model
+nextrec --mode=train --train_config=path/to/train_config.yaml
+
+# Run prediction
+nextrec --mode=predict --predict_config=path/to/predict_config.yaml
+```
+
+> As of version 0.4.3, NextRec CLI supports single-machine training; distributed training features are currently under development.
+
 ## Platform Compatibility
 
-The current version is 0.4.2. 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.3. 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 | 
 |----------|---------------|
@@ -247,14 +277,13 @@ The current version is 0.4.2. All models and test code have been validated on th
 | [ESMM](nextrec/models/multi_task/esmm.py) | Entire Space Multi-task Model | SIGIR 2018 | Supported |
 | [ShareBottom](nextrec/models/multi_task/share_bottom.py) | Multitask Learning | - | Supported |
 | [POSO](nextrec/models/multi_task/poso.py) | POSO: Personalized Cold-start Modules for Large-scale Recommender Systems | 2021 | Supported |
-| [POSO-IFLYTEK](nextrec/models/multi_task/poso_iflytek.py) | POSO with PLE-style gating for sequential marketing tasks | - | Supported |
 
 ### Generative Models
 
 | Model | Paper | Year | Status |
 |-------|-------|------|--------|
 | [TIGER](nextrec/models/generative/tiger.py) | Recommender Systems with Generative Retrieval | NeurIPS 2023 | In Progress |
-| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | In Progress |
+| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | Supported |
 
 ---
 
@@ -270,7 +299,7 @@ We welcome contributions of any form!
 4. Push your branch (`git push origin feature/AmazingFeature`)  
 5. Open a Pull Request  
 
-> Before submitting a PR, please run tests using `pytest test/ -v` or `python -m pytest` to ensure everything passes.
+> Before submitting a PR, please run `python test/run_tests.py` and `python scripts/format_code.py` to ensure all tests pass and code style is unified.
 
 ### Code Style
 

{nextrec-0.4.2 → nextrec-0.4.3}/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.2-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.3-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -15,16 +15,28 @@ English | [中文文档](README_zh.md)
 
 </div>
 
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [5-Minute Quick Start](#5-minute-quick-start)
+- [CLI Usage](#cli-usage)
+- [Platform Compatibility](#platform-compatibility)
+- [Supported Models](#supported-models)
+- [Contributing](#contributing)
+
 ## Introduction
 
-NextRec is a modern recommendation framework built on PyTorch, delivering a unified experience for modeling, training, and evaluation. It follows a modular design with rich model implementations, data-processing utilities, and engineering-ready training components. NextRec focuses on large-scale industrial recall scenarios on Spark clusters, training on massive offline parquet features.
+NextRec is a modern recommendation system framework built on PyTorch, providing researchers and engineering teams with a fast modeling, training, and evaluation experience. The framework adopts a modular design with rich built-in model implementations, data processing tools, and engineering-ready training components, covering various recommendation scenarios. NextRec provides easy-to-use interfaces, command-line tools, and tutorials, enabling recommendation algorithm learners to quickly understand model architectures and train and infer models at the fastest speed.
 
 ## Why NextRec
 
-- **Unified feature engineering & data pipeline**: Dense/Sparse/Sequence feature definitions, persistent DataProcessor, and batch-optimized RecDataLoader, matching offline feature training/inference in industrial big-data settings.
-- **Multi-scenario coverage**: Ranking (CTR/CVR), retrieval, multi-task learning, and more marketing/rec models, with a continuously expanding model zoo.
-- **Developer-friendly experience**: Stream processing/training/inference for csv/parquet/pathlike data, plus GPU/MPS acceleration and visualization support.
-- **Efficient training & evaluation**: Standardized engine with optimizers, LR schedulers, early stopping, checkpoints, and detailed logging out of the box.
+- **Unified feature engineering & data pipeline**: NextRec provides Dense/Sparse/Sequence feature definitions, persistent DataProcessor, and batch-optimized RecDataLoader, matching the model training and inference process based on offline `parquet/csv` features in industrial big-data Spark/Hive scenarios.
+- **Multi-scenario recommendation capabilities**: Covers ranking (CTR/CVR), retrieval, multi-task learning and other recommendation/marketing models, with a continuously expanding model zoo.
+- **Developer-friendly experience**: Supports stream preprocessing/distributed training/inference for various data formats (`csv/parquet/pathlike`), GPU acceleration and visual metric monitoring, facilitating experiments for business algorithm engineers and recommendation algorithm learners.
+- **Flexible command-line tool**: Through configuring training and inference config files, start training and inference processes with one command `nextrec --mode=train --train_config=train_config.yaml`, facilitating rapid experiment iteration and agile deployment.
+- **Efficient training & evaluation**: NextRec's standardized training engine comes with various optimizers, learning rate schedulers, early stopping, model checkpoints, and detailed log management built-in, ready to use out of the box.
 
 ## Architecture
 
@@ -40,34 +52,36 @@ NextRec adopts a modular and low-coupling engineering design, enabling full-pipe
 
 You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required.
 
-## Tutorials
 
-See `tutorials/` for examples covering ranking, retrieval, multi-task learning, and data processing:
+## Tutorials
 
-- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM training on MovieLens 100k
-- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN training on the e-commerce dataset
-- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task training on the e-commerce dataset
-- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval on MovieLens 100k
+We provide multiple examples in the `tutorials/` directory, covering ranking, retrieval, multi-task, and data processing scenarios:
 
-To dive deeper, Jupyter notebooks are available:
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM model training example on MovieLens 100k dataset
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN deep interest network training example on e-commerce dataset
+- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training example on e-commerce dataset
+- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model example trained on MovieLens 100k dataset
+- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly verify the availability of all ranking models
+- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly verify the availability of all multi-task models
+- [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly verify the availability of all retrieval models
 
-- [Hands on the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
-- [Using the data processor for preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
+If you want to learn more details about the NextRec framework, we also provide Jupyter notebooks to help you understand:
 
-> Current version [0.4.2]: the matching module is not fully polished yet and may have compatibility issues or unexpected errors. Please raise an issue if you run into problems.
+- [How to get started with the NextRec framework](/tutorials/notebooks/en/Hands%20on%20nextrec.ipynb)
+- [How to use the data processor for data preprocessing](/tutorials/notebooks/en/Hands%20on%20dataprocessor.ipynb)
 
 ## 5-Minute Quick Start
 
-We provide a detailed quick start and paired datasets to help you learn the framework. In `datasets/` you’ll find an e-commerce sample dataset like this:
+We provide a detailed quick start guide and paired datasets to help you become familiar with different features of the NextRec framework. We provide a test dataset from an e-commerce scenario in the `datasets/` path, with data examples as follows:
 
 | user_id | item_id | dense_0     | dense_1     | dense_2     | dense_3    | dense_4     | dense_5     | dense_6     | dense_7     | sparse_0 | sparse_1 | sparse_2 | sparse_3 | sparse_4 | sparse_5 | sparse_6 | sparse_7 | sparse_8 | sparse_9 | sequence_0                                               | sequence_1                                                | label |
 |--------|---------|-------------|-------------|-------------|------------|-------------|-------------|-------------|-------------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|-----------------------------------------------------------|-----------------------------------------------------------|-------|
 | 1      | 7817    | 0.14704075  | 0.31020382  | 0.77780896  | 0.944897   | 0.62315375  | 0.57124174  | 0.77009535  | 0.3211029   | 315      | 260      | 379      | 146      | 168      | 161      | 138      | 88       | 5        | 312      | [170,175,97,338,105,353,272,546,175,545,463,128,0,0,0]   | [368,414,820,405,548,63,327,0,0,0,0,0,0,0,0]              | 0     |
 | 1      | 3579    | 0.77811223  | 0.80359334  | 0.5185201   | 0.91091245 | 0.043562356 | 0.82142705  | 0.8803686   | 0.33748195 | 149      | 229      | 442      | 6        | 167      | 252      | 25       | 402      | 7        | 168      | [179,48,61,551,284,165,344,151,0,0,0,0,0,0,0]            | [814,0,0,0,0,0,0,0,0,0,0,0,0,0,0]                          | 1     |
 
-Below is a short example showing how to train a DIN model. DIN (Deep Interest Network) won Best Paper at KDD 2018 for CTR prediction. You can also run `python tutorials/example_ranking_din.py` directly.
+Next, we'll use a short example to show you how to train a DIN model using NextRec. DIN (Deep Interest Network) is from Alibaba's 2018 KDD Best Paper, used for CTR prediction scenarios. You can also directly execute `python tutorials/example_ranking_din.py` to run the training and inference code.
 
-After training, detailed logs are available under `nextrec_logs/din_tutorial`.
+After starting training, you can view detailed training logs in the `nextrec_logs/din_tutorial` path.
 
 ```python
 import pandas as pd
@@ -140,9 +154,25 @@ metrics = model.evaluate(
 )
 ```
 
+## CLI Usage
+
+NextRec provides a powerful command-line interface for model training and prediction using YAML configuration files. For detailed CLI documentation, see:
+
+- [NextRec CLI User Guide](/nextrec_cli_preset/NextRec-CLI.md) - Complete guide for using the CLI
+
+```bash
+# Train a model
+nextrec --mode=train --train_config=path/to/train_config.yaml
+
+# Run prediction
+nextrec --mode=predict --predict_config=path/to/predict_config.yaml
+```
+
+> As of version 0.4.3, NextRec CLI supports single-machine training; distributed training features are currently under development.
+
 ## Platform Compatibility
 
-The current version is 0.4.2. 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.3. 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 | 
 |----------|---------------|
@@ -191,14 +221,13 @@ The current version is 0.4.2. All models and test code have been validated on th
 | [ESMM](nextrec/models/multi_task/esmm.py) | Entire Space Multi-task Model | SIGIR 2018 | Supported |
 | [ShareBottom](nextrec/models/multi_task/share_bottom.py) | Multitask Learning | - | Supported |
 | [POSO](nextrec/models/multi_task/poso.py) | POSO: Personalized Cold-start Modules for Large-scale Recommender Systems | 2021 | Supported |
-| [POSO-IFLYTEK](nextrec/models/multi_task/poso_iflytek.py) | POSO with PLE-style gating for sequential marketing tasks | - | Supported |
 
 ### Generative Models
 
 | Model | Paper | Year | Status |
 |-------|-------|------|--------|
 | [TIGER](nextrec/models/generative/tiger.py) | Recommender Systems with Generative Retrieval | NeurIPS 2023 | In Progress |
-| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | In Progress |
+| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | Supported |
 
 ---
 
@@ -214,7 +243,7 @@ We welcome contributions of any form!
 4. Push your branch (`git push origin feature/AmazingFeature`)  
 5. Open a Pull Request  
 
-> Before submitting a PR, please run tests using `pytest test/ -v` or `python -m pytest` to ensure everything passes.
+> Before submitting a PR, please run `python test/run_tests.py` and `python scripts/format_code.py` to ensure all tests pass and code style is unified.
 
 ### Code Style
 

{nextrec-0.4.2 → nextrec-0.4.3}/README_zh.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.2-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.3-orange.svg)
 
 [English Version](README.md) | 中文文档
 
@@ -15,15 +15,27 @@
 
 </div>
 
+## 目录
+
+- [简介](#简介)
+- [安装](#安装)
+- [架构](#架构)
+- [5分钟快速上手](#5分钟快速上手)
+- [命令行工具](#命令行工具)
+- [兼容平台](#兼容平台)
+- [支持模型](#支持模型)
+- [贡献指南](#贡献指南)
+
 ## 简介
 
-NextRec 是一个基于 PyTorch 构建的现代推荐系统框架,为研究人员与工程团队提供统一的建模、训练与评估体验。框架采用模块化设计,内置丰富的模型实现、数据处理工具和工程化训练组件,可快速覆盖多种推荐场景,主要面向Spark集群下,基于大数据量parquet离线特征训练的工业推荐召回算法场景。
+NextRec是一个基于 PyTorch 构建的现代推荐系统框架，为研究人员与工程团队提供快速的建模、训练与评估体验。框架采用模块化设计，内置丰富的模型实现、数据处理工具和工程化训练组件，覆盖多种推荐场景。NextRec提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构并训练和推理模型。
 
 ## Why NextRec
 
-- **统一的特征工程与数据流水线**：NextRec框架提供了 Dense/Sparse/Sequence 特征定义、可持久化的 DataProcessor、批处理优化的 RecDataLoader，符合工业大数据场景下，基于离线特征的模型训练推理流程。
+- **统一的特征工程与数据流水线**：NextRec框架提供了 Dense/Sparse/Sequence 特征定义、可持久化的 DataProcessor、批处理优化的 RecDataLoader，符合工业大数据Spark/Hive场景下，基于离线`parquet/csv`特征的模型训练推理流程。
 - **多场景推荐能力**：同时覆盖排序（CTR/CVR）、召回、多任务学习等推荐/营销模型，并且持续扩充模型库中。
-- **友好的工程体验**：NextRec框架支持各种格式数据(csv/parquet/pathlike)的流式处理/训练/推理，并支持 GPU/MPS 加速与可视化监控。
+- **友好的工程体验**：支持各种格式数据(`csv/parquet/pathlike`)的流式预处理/分布式训练/推理，GPU加速与可视化指标监控，方便业务算法工程师和推荐算法学习者进行实验。
+- **灵活的命令行工具**：通过配置训练配置文件和推理配置文件，通过`nextrec --mode=train --train_config=train_config.yaml` 一键启动训练和推理进程，方便快速实验迭代和敏捷部署。
 - **高效训练与评估**：NextRec框架的标准化训练引擎内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
 
 ## 架构
@@ -48,14 +60,15 @@ NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据
 - [example_ranking_din.py](/tutorials/example_ranking_din.py) - 电商数据集上的DIN 深度兴趣网络训练示例
 - [example_multitask.py](/tutorials/example_multitask.py) - 电商数据集上的ESMM多任务学习训练示例
 - [movielen_match_dssm.py](/tutorials/example_match_dssm.py) - 基于movielen 100k数据集训练的 DSSM 召回模型示例
+- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) - 快速校验所有排序模型的可用性
+- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) - 快速校验所有多任务模型的可用性
+- [run_all_match_models.py](/tutorials/run_all_match_models.py) - 快速校验所有召回模型的可用性
 
 如果想了解更多NextRec框架的细节，我们还提供了Jupyter notebook来帮助你了解：
 
 - [如何上手NextRec框架](/tutorials/notebooks/zh/Hands%20on%20nextrec.ipynb)
 - [如何使用数据处理器进行数据预处理](/tutorials/notebooks/zh/Hands%20on%20dataprocessor.ipynb)
 
-> 当前版本[0.4.2]，召回模型模块尚不完善，可能存在一些兼容性问题或意外报错，如果遇到问题，欢迎开发者在Issue区提出问题。
-
 ## 5分钟快速上手
 
 我们提供了详细的上手指南和配套数据集，帮助您熟悉NextRec框架的不同功能。我们在`datasets/`路径下提供了一个来自电商场景的测试数据集，数据示例如下：
@@ -138,9 +151,26 @@ metrics = model.evaluate(
     user_id_column='user_id'
 )
 ```
+
+## 命令行工具
+
+NextRec 提供了强大的命令行界面，支持通过 YAML 配置文件进行模型训练和预测。详细的 CLI 文档请参见：
+
+- [NextRec CLI 使用指南](/nextrec_cli_preset/NextRec-CLI_zh.md) - 完整的 CLI 使用文档
+
+```bash
+# 训练模型
+nextrec --mode=train --train_config=path/to/train_config.yaml
+
+# 运行预测
+nextrec --mode=predict --predict_config=path/to/predict_config.yaml
+```
+
+> 截止当前版本0.4.3，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+
 ## 兼容平台
 
-当前最新版本为0.4.2，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.3，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|
@@ -187,14 +217,13 @@ metrics = model.evaluate(
 | [ESMM](nextrec/models/multi_task/esmm.py) | Entire Space Multi-Task Model | SIGIR 2018 | 已支持 |
 | [ShareBottom](nextrec/models/multi_task/share_bottom.py) | Multitask Learning | - | 已支持 |
 | [POSO](nextrec/models/multi_task/poso.py) | POSO: Personalized Cold-start Modules for Large-scale Recommender Systems | 2021 | 已支持 |
-| [POSO-IFLYTEK](nextrec/models/multi_task/poso_iflytek.py) | POSO with PLE-style gating for sequential marketing tasks | - | 已支持 |
 
 ### 生成式模型
 
 | 模型 | 论文 | 年份 | 状态 |
 |------|------|------|------|
 | [TIGER](nextrec/models/generative/tiger.py) | Recommender Systems with Generative Retrieval | NeurIPS 2023 | 开发中 |
-| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | 开发中 |
+| [HSTU](nextrec/models/generative/hstu.py) | Hierarchical Sequential Transduction Units | - | 已支持 |
 
 ---
 
@@ -210,7 +239,7 @@ metrics = model.evaluate(
 4. 推送到分支 (`git push origin feature/AmazingFeature`)
 5. 创建 Pull Request
 
-> 在提交 PR 之前，请运行 `python test/run_tests.py` 确保所有测试通过。
+> 在提交 PR 之前，请运行 `python test/run_tests.py` 和 `python scripts/format_code.py` 确保所有测试通过并统一代码风格。
 
 ### 代码规范
 

{nextrec-0.4.2 → nextrec-0.4.3}/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.2"
+release = "0.4.3"
 
 extensions = [
     "myst_parser",

nextrec-0.4.3/nextrec/__version__.py

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

{nextrec-0.4.2 → nextrec-0.4.3}/nextrec/basic/layers.py

@@ -51,11 +51,11 @@ class PredictionLayer(nn.Module):
 
         # slice offsets per task
         start = 0
-        self._task_slices: list[tuple[int, int]] = []
+        self.task_slices: list[tuple[int, int]] = []
         for dim in self.task_dims:
             if dim < 1:
                 raise ValueError("Each task dimension must be >= 1.")
-            self._task_slices.append((start, start + dim))
+            self.task_slices.append((start, start + dim))
             start += dim
         if use_bias:
             self.bias = nn.Parameter(torch.zeros(self.total_dim))
@@ -71,7 +71,7 @@ class PredictionLayer(nn.Module):
             )
         logits = x if self.bias is None else x + self.bias
         outputs = []
-        for task_type, (start, end) in zip(self.task_types, self._task_slices):
+        for task_type, (start, end) in zip(self.task_types, self.task_slices):
             task_logits = logits[..., start:end]  # logits for the current task
             if self.return_logits:
                 outputs.append(task_logits)
@@ -367,20 +367,29 @@ class MLP(nn.Module):
         dims: list[int] | None = None,
         dropout: float = 0.0,
         activation: str = "relu",
+        use_norm: bool = True,
+        norm_type: str = "layer_norm",
     ):
         super().__init__()
         if dims is None:
             dims = []
         layers = []
         current_dim = input_dim
-
         for i_dim in dims:
             layers.append(nn.Linear(current_dim, i_dim))
-            layers.append(nn.BatchNorm1d(i_dim))
+            if use_norm:
+                if norm_type == "batch_norm":
+                    # **IMPORTANT** be careful when using BatchNorm1d in distributed training, nextrec does not support sync batch norm now
+                    layers.append(nn.BatchNorm1d(i_dim))
+                elif norm_type == "layer_norm":
+                    layers.append(nn.LayerNorm(i_dim))
+                else:
+                    raise ValueError(f"Unsupported norm_type: {norm_type}")
+
             layers.append(activation_layer(activation))
             layers.append(nn.Dropout(p=dropout))
             current_dim = i_dim
-
+        # output layer
         if output_layer:
             layers.append(nn.Linear(current_dim, 1))
             self.output_dim = 1
@@ -471,6 +480,21 @@ class BiLinearInteractionLayer(nn.Module):
         return torch.cat(bilinear_list, dim=1)
 
 
+class HadamardInteractionLayer(nn.Module):
+    """Hadamard interaction layer for Deep-FiBiNET (0 case in 01/11)."""
+
+    def __init__(self, num_fields: int):
+        super().__init__()
+        self.num_fields = num_fields
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        # x: [B, F, D]
+        feature_emb = torch.split(x, 1, dim=1)  # list of F tensors [B,1,D]
+
+        hadamard_list = [v_i * v_j for (v_i, v_j) in combinations(feature_emb, 2)]
+        return torch.cat(hadamard_list, dim=1)  # [B, num_pairs, D]
+
+
 class MultiHeadSelfAttention(nn.Module):
     def __init__(
         self,
@@ -542,7 +566,7 @@ class AttentionPoolingLayer(nn.Module):
         embedding_dim: int,
         hidden_units: list = [80, 40],
         activation: str = "sigmoid",
-        use_softmax: bool = True,
+        use_softmax: bool = False,
     ):
         super().__init__()
         self.embedding_dim = embedding_dim
@@ -553,7 +577,7 @@ class AttentionPoolingLayer(nn.Module):
         layers = []
         for hidden_unit in hidden_units:
             layers.append(nn.Linear(input_dim, hidden_unit))
-            layers.append(activation_layer(activation))
+            layers.append(activation_layer(activation, emb_size=hidden_unit))
             input_dim = hidden_unit
         layers.append(nn.Linear(input_dim, 1))
         self.attention_net = nn.Sequential(*layers)

{nextrec-0.4.2 → nextrec-0.4.3}/nextrec/basic/loggers.py

@@ -103,7 +103,7 @@ def setup_logger(session_id: str | os.PathLike | None = None):
     session = create_session(str(session_id) if session_id is not None else None)
     log_dir = session.logs_dir
     log_dir.mkdir(parents=True, exist_ok=True)
-    log_file = log_dir / f"{session.log_basename}.log"
+    log_file = log_dir / "runs.log"
 
     console_format = "%(message)s"
     file_format = "%(asctime)s - %(levelname)s - %(message)s"

{nextrec-0.4.2 → nextrec-0.4.3}/nextrec/basic/metrics.py

@@ -260,7 +260,7 @@ def compute_mrr_at_k(
         order = np.argsort(scores)[::-1]
         k_user = min(k, idx.size)
         topk = order[:k_user]
-        ranked_labels = labels[order]
+        ranked_labels = labels[topk]
         rr = 0.0
         for rank, lab in enumerate(ranked_labels[:k_user], start=1):
             if lab > 0:
@@ -612,6 +612,7 @@ def evaluate_metrics(
                     if task_type in ["binary", "multilabel"]:
                         should_compute = metric_lower in {
                             "auc",
+                            "gauc",
                             "ks",
                             "logloss",
                             "accuracy",

{nextrec-0.4.2 → nextrec-0.4.3}/nextrec/basic/model.py

@@ -455,7 +455,7 @@ class BaseModel(FeatureSet, nn.Module):
         if hasattr(
             self, "prediction_layer"
         ):  # we need to use registered task_slices for multi-task and multi-class
-            slices = self.prediction_layer._task_slices  # type: ignore
+            slices = self.prediction_layer.task_slices  # type: ignore
         else:
             slices = [(i, i + 1) for i in range(self.nums_task)]
         task_losses = []
@@ -1369,7 +1369,7 @@ class BaseModel(FeatureSet, nn.Module):
         pred_columns: list[str] = []
         if self.target_columns:
             for name in self.target_columns[:num_outputs]:
-                pred_columns.append(f"{name}_pred")
+                pred_columns.append(f"{name}")
         while len(pred_columns) < num_outputs:
             pred_columns.append(f"pred_{len(pred_columns)}")
         if include_ids and predict_id_columns:
@@ -1496,7 +1496,7 @@ class BaseModel(FeatureSet, nn.Module):
                     pred_columns = []
                     if self.target_columns:
                         for name in self.target_columns[:num_outputs]:
-                            pred_columns.append(f"{name}_pred")
+                            pred_columns.append(f"{name}")
                     while len(pred_columns) < num_outputs:
                         pred_columns.append(f"pred_{len(pred_columns)}")