nextrec 0.4.2__tar.gz → 0.4.4__tar.gz

{nextrec-0.4.2 → nextrec-0.4.4}/.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.4}/.gitignore

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.2
+Version: 0.4.4
 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.4-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -71,59 +71,78 @@ 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 framework built on PyTorch, delivering a unified experience for modeling, training, and evaluation. Design with rich model implementations, data-processing utilities, and engineering-ready training components. NextRec focuses on large-scale industrial recommendation scenarios on Spark clusters, training on massive offline features(`parquet/csv`).
 
 ## 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.
+- **Unified feature engineering & data pipeline**: NextRec provide unified Dense/Sparse/Sequence feature definitions, 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.
+- **Developer-friendly experience**: `Stream processing/distributed 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.
 
 ## Architecture
 
-NextRec adopts a modular and low-coupling engineering design, enabling full-pipeline reusability and scalability across data processing → model construction → training & evaluation → inference & deployment. Its core components include: a Feature-Spec-driven Embedding architecture, the BaseModel abstraction, a set of independent reusable Layers, a unified DataLoader for both training and inference, and a ready-to-use Model Zoo.
+NextRec adopts a modular design, enabling full-pipeline reusability and scalability across data processing → model construction → training & evaluation → inference & deployment. Its core components include: a Feature-Spec-driven Embedding architecture, the BaseModel abstraction, a set of independent reusable Layers, a unified DataLoader for both training and inference, and a ready-to-use Model Zoo.
 
 ![NextRec Architecture](assets/nextrec_diagram_en.png)
 
-> The project borrows ideas from excellent open-source rec libraries. Early layers referenced [torch-rechub](https://github.com/datawhalechina/torch-rechub) but have been replaced with in-house implementations. torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
+> The project borrows ideas from excellent open-source rec libraries, for example: [torch-rechub](https://github.com/datawhalechina/torch-rechub). torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
 
 ---
 
 ## Installation
 
-You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required.
+You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required. If you want to run some tutorial codes, pull this project first: 
+
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec/
+pip install nextrec # or pip install -e .
+```
 
 ## Tutorials
 
 See `tutorials/` for examples covering ranking, retrieval, multi-task learning, and data processing:
 
-- [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
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM training on MovieLens 100k dataset
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN Deep Interest Network training on e-commerce dataset
+- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training on e-commerce dataset
+- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model training on MovieLens 100k dataset
 
-To dive deeper, Jupyter notebooks are available:
+- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly validate availability of all ranking models
+- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly validate availability of all multi-task models
+- [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly validate availability of all retrieval models
+
+To dive deeper into NextRec framework details, Jupyter notebooks are available:
 
 - [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)
 
-> 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.
-
 ## 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 get familiar with different features of NextRec framework. In `datasets/` you'll find an e-commerce scenario test dataset like this:
 
 | 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.
+Below is a short example showing how to train a DIN (Deep Interest Network) model. You can also run `python tutorials/example_ranking_din.py` directly to execute the training and inference code.
 
-After training, detailed logs are available under `nextrec_logs/din_tutorial`.
+After training starts, you can find detailed training logs at `nextrec_logs/din_tutorial`.
 
 ```python
 import pandas as pd
@@ -196,9 +215,26 @@ 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
+- [NextRec CLI Configuration Examples](/nextrec_cli_preset/) - CLI configuration file examples
+
+```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.4, 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.4. 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 +283,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 +305,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 consistent.
 
 ### Code Style
 

{nextrec-0.4.2 → nextrec-0.4.4}/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.4-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -15,59 +15,78 @@ 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 framework built on PyTorch, delivering a unified experience for modeling, training, and evaluation. Design with rich model implementations, data-processing utilities, and engineering-ready training components. NextRec focuses on large-scale industrial recommendation scenarios on Spark clusters, training on massive offline features(`parquet/csv`).
 
 ## 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.
+- **Unified feature engineering & data pipeline**: NextRec provide unified Dense/Sparse/Sequence feature definitions, 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.
+- **Developer-friendly experience**: `Stream processing/distributed 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.
 
 ## Architecture
 
-NextRec adopts a modular and low-coupling engineering design, enabling full-pipeline reusability and scalability across data processing → model construction → training & evaluation → inference & deployment. Its core components include: a Feature-Spec-driven Embedding architecture, the BaseModel abstraction, a set of independent reusable Layers, a unified DataLoader for both training and inference, and a ready-to-use Model Zoo.
+NextRec adopts a modular design, enabling full-pipeline reusability and scalability across data processing → model construction → training & evaluation → inference & deployment. Its core components include: a Feature-Spec-driven Embedding architecture, the BaseModel abstraction, a set of independent reusable Layers, a unified DataLoader for both training and inference, and a ready-to-use Model Zoo.
 
 ![NextRec Architecture](assets/nextrec_diagram_en.png)
 
-> The project borrows ideas from excellent open-source rec libraries. Early layers referenced [torch-rechub](https://github.com/datawhalechina/torch-rechub) but have been replaced with in-house implementations. torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
+> The project borrows ideas from excellent open-source rec libraries, for example: [torch-rechub](https://github.com/datawhalechina/torch-rechub). torch-rechub remains mature in architecture and models; the author contributed a bit there—feel free to check it out.
 
 ---
 
 ## Installation
 
-You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required.
+You can quickly install the latest NextRec via `pip install nextrec`; Python 3.10+ is required. If you want to run some tutorial codes, pull this project first: 
+
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec/
+pip install nextrec # or pip install -e .
+```
 
 ## Tutorials
 
 See `tutorials/` for examples covering ranking, retrieval, multi-task learning, and data processing:
 
-- [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
+- [movielen_ranking_deepfm.py](/tutorials/movielen_ranking_deepfm.py) — DeepFM training on MovieLens 100k dataset
+- [example_ranking_din.py](/tutorials/example_ranking_din.py) — DIN Deep Interest Network training on e-commerce dataset
+- [example_multitask.py](/tutorials/example_multitask.py) — ESMM multi-task learning training on e-commerce dataset
+- [movielen_match_dssm.py](/tutorials/example_match_dssm.py) — DSSM retrieval model training on MovieLens 100k dataset
 
-To dive deeper, Jupyter notebooks are available:
+- [run_all_ranking_models.py](/tutorials/run_all_ranking_models.py) — Quickly validate availability of all ranking models
+- [run_all_multitask_models.py](/tutorials/run_all_multitask_models.py) — Quickly validate availability of all multi-task models
+- [run_all_match_models.py](/tutorials/run_all_match_models.py) — Quickly validate availability of all retrieval models
+
+To dive deeper into NextRec framework details, Jupyter notebooks are available:
 
 - [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)
 
-> 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.
-
 ## 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 get familiar with different features of NextRec framework. In `datasets/` you'll find an e-commerce scenario test dataset like this:
 
 | 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.
+Below is a short example showing how to train a DIN (Deep Interest Network) model. You can also run `python tutorials/example_ranking_din.py` directly to execute the training and inference code.
 
-After training, detailed logs are available under `nextrec_logs/din_tutorial`.
+After training starts, you can find detailed training logs at `nextrec_logs/din_tutorial`.
 
 ```python
 import pandas as pd
@@ -140,9 +159,26 @@ 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
+- [NextRec CLI Configuration Examples](/nextrec_cli_preset/) - CLI configuration file examples
+
+```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.4, 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.4. 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 +227,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 +249,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 consistent.
 
 ### Code Style
 

{nextrec-0.4.2 → nextrec-0.4.4}/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.4-orange.svg)
 
 [English Version](README.md) | 中文文档
 
@@ -15,30 +15,48 @@
 
 </div>
 
+## 目录
+
+- [简介](#简介)
+- [安装](#安装)
+- [架构](#架构)
+- [5分钟快速上手](#5分钟快速上手)
+- [命令行工具](#命令行工具)
+- [兼容平台](#兼容平台)
+- [支持模型](#支持模型)
+- [贡献指南](#贡献指南)
+
 ## 简介
 
-NextRec 是一个基于 PyTorch 构建的现代推荐系统框架,为研究人员与工程团队提供统一的建模、训练与评估体验。框架采用模块化设计,内置丰富的模型实现、数据处理工具和工程化训练组件,可快速覆盖多种推荐场景,主要面向Spark集群下,基于大数据量parquet离线特征训练的工业推荐召回算法场景。
+NextRec是一个基于PyTorch的现代推荐系统框架，旨在为研究与工程团队提供快速的建模、训练与评估流程。框架内置丰富的模型实现、数据处理工具和工程化训练组件，覆盖多种推荐场景。此外提供了易上手的接口，命令行工具及教程，推荐算法学习者能以最快速度了解模型架构，复现学术论文并进行训练和部署。
 
 ## Why NextRec
 
-- **统一的特征工程与数据流水线**：NextRec框架提供了 Dense/Sparse/Sequence 特征定义、可持久化的 DataProcessor、批处理优化的 RecDataLoader，符合工业大数据场景下，基于离线特征的模型训练推理流程。
-- **多场景推荐能力**：同时覆盖排序（CTR/CVR）、召回、多任务学习等推荐/营销模型，并且持续扩充模型库中。
-- **友好的工程体验**：NextRec框架支持各种格式数据(csv/parquet/pathlike)的流式处理/训练/推理，并支持 GPU/MPS 加速与可视化监控。
-- **高效训练与评估**：NextRec框架的标准化训练引擎内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
+- **统一的特征工程与数据流水线**：NextRec框架提供了统一的特征定义、可持久化的数据处理、并对批处理进行了优化，符合工业大数据Spark/Hive场景下，基于离线特征的模型训练推理流程。
+- **多场景推荐能力**：覆盖排序（CTR/CVR）、召回、多任务学习、生成式召回等推荐/营销模型，持续跟进业界进展。
+- **友好的工程体验**：支持各种格式数据(`csv/parquet/pathlike`)的流式预处理/分布式训练/推理，GPU加速与可视化指标监控，方便业务算法工程师和推荐算法学习者快速复现实验。
+- **灵活的命令行工具**：支持通过命令行和配置文件，一键启动训练和推理进程，方便快速实验迭代和敏捷部署。
+- **高效训练与评估**：内置多种优化器、学习率调度、早停、模型检查点与详细的日志管理，开箱即用。
 
 ## 架构
 
-NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据处理 → 模型构建 → 训练评估 → 推理部署 全链路都具备复用性与可扩展性。其中的核心组件包括：Feature Spec驱动的Embedding架构；模型基类BaseModel；独立Layer模块；支持训练和推理的统一的DataLoader；开箱即用的模型库。
+NextRec采用模块化工程设计，核心组件包括：Feature Spec驱动的Embedding架构；模型基类BaseModel；独立Layer模块；支持训练和推理的统一的DataLoader；开箱即用的模型库等。
 
 ![NextRec架构](assets/nextrec_diagram_zh.png)
 
-> 项目的架构借鉴了一些优秀的开源推荐算法库，其中最初版的layer层借鉴了DataWhaleChina社区的[torch-rechub](https://github.com/datawhalechina/torch-rechub)，现已替换为了自有实现。torch-rechub在开发架构和模型实现上相对成熟，本人也参与了其中一小部分的维护，欢迎感兴趣的开发者前往了解。
+> 项目的架构借鉴了一些优秀的开源推荐算法库，例如DataWhaleChina社区的[torch-rechub](https://github.com/datawhalechina/torch-rechub)。torch-rechub在开发架构和模型实现上相对成熟，本人也参与了其中一小部分的维护，欢迎感兴趣的开发者前往了解。
 
 ---
 
 ## 安装
 
-你可以通过`pip install nextrec`快速安装NextRec的最新版本，环境要求为Python 3.10+。
+开发者可以通过`pip install nextrec`快速安装NextRec的最新版本，环境要求为Python 3.10+。如果需要执行示例代码，则需要先拉取仓库：
+
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec/
+pip install nextrec # or pip install -e .
+```
 
 ## 示例代码
 
@@ -49,13 +67,15 @@ NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据
 - [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/`路径下提供了一个来自电商场景的测试数据集，数据示例如下：
@@ -65,7 +85,7 @@ NextRec采用模块化、低耦合的工程设计，使得推荐系统从数据
 | 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     |
 
-接下来我们将用一个简短的示例，展示如何使用NextRec训练一个DIN模型。DIN(Deep Interest Network)来自于阿里妈妈2018年KDD最佳论文模型，用于CTR预估场景。你也可以直接执行`python tutorials/example_ranking_din.py`来执行训练推理代码。
+接下来我们将用一个简短的示例，展示如何使用NextRec训练一个DIN(Deep Interest Network)模型。您也可以直接执行`python tutorials/example_ranking_din.py`来执行训练推理代码。
 
 开始训练以后，你可以在`nextrec_logs/din_tutorial`路径下查看详细的训练日志。
 
@@ -138,9 +158,27 @@ metrics = model.evaluate(
     user_id_column='user_id'
 )
 ```
+
+## 命令行工具
+
+NextRec 提供了强大的命令行界面，支持通过 YAML 配置文件进行模型训练和预测。详细的 CLI 文档请参见：
+
+- [NextRec CLI 使用指南](/nextrec_cli_preset/NextRec-CLI_zh.md) - 完整的 CLI 使用文档
+- [NextRec CLI 配置文件示例](/nextrec_cli_preset/) - CLI 使用配置文件示例
+
+```bash
+# 训练模型
+nextrec --mode=train --train_config=path/to/train_config.yaml
+
+# 运行预测
+nextrec --mode=predict --predict_config=path/to/predict_config.yaml
+```
+
+> 截止当前版本0.4.4，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+
 ## 兼容平台
 
-当前最新版本为0.4.2，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.4，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|
@@ -187,14 +225,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 +247,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.4}/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.4"
 
 extensions = [
     "myst_parser",

nextrec-0.4.4/nextrec/__version__.py

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

{nextrec-0.4.2 → nextrec-0.4.4}/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.4}/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"