nextrec 0.4.2__py3-none-any.whl → 0.4.3__py3-none-any.whl

nextrec/models/ranking/pnn.py

@@ -3,7 +3,35 @@ Date: create on 09/11/2025
 Author:
     Yang Zhou,zyaztec@gmail.com
 Reference:
-    [1] Qu Y, Cai H, Ren K, et al. Product-based neural networks for user response prediction[C]//ICDM. 2016: 1149-1154.
+[1] Qu Y, Cai H, Ren K, et al. Product-based neural networks for user response
+prediction[C]//ICDM. 2016: 1149-1154. (https://arxiv.org/abs/1611.00144)
+
+Product-based Neural Networks (PNN) are CTR prediction models that explicitly
+encode feature interactions by combining:
+  (1) A linear signal from concatenated field embeddings
+  (2) A product signal capturing pairwise feature interactions (inner or outer)
+The product layer augments the linear input to an MLP, enabling the network to
+model both first-order and high-order feature interactions in a structured way.
+
+Computation workflow:
+  - Embed each categorical/sequence field with a shared embedding dimension
+  - Linear signal: flatten and concatenate all field embeddings
+  - Product signal:
+      * Inner product: dot products over all field pairs
+      * Outer product: project embeddings then compute element-wise products
+  - Concatenate linear and product signals; feed into MLP for prediction
+
+Key Advantages:
+- Explicit pairwise interaction modeling without heavy feature engineering
+- Flexible choice between inner/outer products to trade off capacity vs. cost
+- Combines linear context with interaction signal for stronger expressiveness
+- Simple architecture that integrates cleanly with standard MLP pipelines
+
+PNN 是一种 CTR 预估模型，通过将线性信号与乘积信号结合，显式建模特征交互：
+  - 线性信号：将各字段的 embedding 拼接，用于保留一阶信息
+  - 乘积信号：对所有字段对做内积或外积，捕捉二阶及更高阶交互
+随后将两类信号拼接送入 MLP，实现对用户响应的预测。内积版本计算量更低，
+外积版本表达力更强，可根据场景取舍。
 """
 
 import torch
@@ -15,6 +43,7 @@ from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
 
 
 class PNN(BaseModel):
+
     @property
     def model_name(self):
         return "PNN"
@@ -25,16 +54,16 @@ class PNN(BaseModel):
 
     def __init__(
         self,
-        dense_features: list[DenseFeature] | list = [],
-        sparse_features: list[SparseFeature] | list = [],
-        sequence_features: list[SequenceFeature] | list = [],
-        mlp_params: dict = {},
-        product_type: str = "inner",
+        dense_features: list[DenseFeature] | None = None,
+        sparse_features: list[SparseFeature] | None = None,
+        sequence_features: list[SequenceFeature] | None = None,
+        mlp_params: dict | None = None,
+        product_type: str = "inner",  # "inner" (IPNN), "outer" (OPNN), "both" (PNN*)
         outer_product_dim: int | None = None,
-        target: list[str] | list = [],
+        target: list[str] | str | None = None,
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -45,6 +74,16 @@ class PNN(BaseModel):
         **kwargs,
     ):
 
+        dense_features = dense_features or []
+        sparse_features = sparse_features or []
+        sequence_features = sequence_features or []
+        mlp_params = mlp_params or {}
+        if outer_product_dim is not None and outer_product_dim <= 0:
+            raise ValueError("outer_product_dim must be a positive integer.")
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(PNN, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -59,16 +98,13 @@ class PNN(BaseModel):
             **kwargs,
         )
 
-        self.loss = loss
-        if self.loss is None:
-            self.loss = "bce"
-
-        self.field_features = sparse_features + sequence_features
+        self.field_features = dense_features + sparse_features + sequence_features
         if len(self.field_features) < 2:
             raise ValueError("PNN requires at least two sparse/sequence features.")
 
         self.embedding = EmbeddingLayer(features=self.field_features)
         self.num_fields = len(self.field_features)
+
         self.embedding_dim = self.field_features[0].embedding_dim
         if any(f.embedding_dim != self.embedding_dim for f in self.field_features):
             raise ValueError(
@@ -76,24 +112,34 @@ class PNN(BaseModel):
             )
 
         self.product_type = product_type.lower()
-        if self.product_type not in {"inner", "outer"}:
-            raise ValueError("product_type must be 'inner' or 'outer'.")
+        if self.product_type not in {"inner", "outer", "both"}:
+            raise ValueError("product_type must be 'inner', 'outer', or 'both'.")
 
         self.num_pairs = self.num_fields * (self.num_fields - 1) // 2
-        if self.product_type == "outer":
-            self.outer_dim = outer_product_dim or self.embedding_dim
-            self.kernel = nn.Linear(self.embedding_dim, self.outer_dim, bias=False)
-            product_dim = self.num_pairs * self.outer_dim
+        self.outer_product_dim = outer_product_dim or self.embedding_dim
+
+        if self.product_type in {"outer", "both"}:
+            self.kernel = nn.Parameter(
+                torch.randn(self.embedding_dim, self.outer_product_dim)
+            )
+            nn.init.xavier_uniform_(self.kernel)
         else:
-            self.outer_dim = None
-            product_dim = self.num_pairs
+            self.kernel = None
 
         linear_dim = self.num_fields * self.embedding_dim
+
+        if self.product_type == "inner":
+            product_dim = self.num_pairs
+        elif self.product_type == "outer":
+            product_dim = self.num_pairs
+        else:
+            product_dim = 2 * self.num_pairs
+
         self.mlp = MLP(input_dim=linear_dim + product_dim, **mlp_params)
         self.prediction_layer = PredictionLayer(task_type=self.task)
 
         modules = ["mlp"]
-        if self.product_type == "outer":
+        if self.kernel is not None:
             modules.append("kernel")
         self.register_regularization_weights(
             embedding_attr="embedding", include_modules=modules
@@ -106,27 +152,48 @@ class PNN(BaseModel):
             loss_params=loss_params,
         )
 
+    def compute_inner_products(self, field_emb: torch.Tensor) -> torch.Tensor:
+        interactions = []
+        for i in range(self.num_fields - 1):
+            vi = field_emb[:, i, :]  # [B, D]
+            for j in range(i + 1, self.num_fields):
+                vj = field_emb[:, j, :]  # [B, D]
+                # <v_i, v_j> = sum_k v_i,k * v_j,k
+                pij = torch.sum(vi * vj, dim=1, keepdim=True)  # [B, 1]
+                interactions.append(pij)
+        return torch.cat(interactions, dim=1)  # [B, num_pairs]
+
+    def compute_outer_kernel_products(self, field_emb: torch.Tensor) -> torch.Tensor:
+        if self.kernel is None:
+            raise RuntimeError("kernel is not initialized for outer product.")
+
+        interactions = []
+        for i in range(self.num_fields - 1):
+            vi = field_emb[:, i, :]  # [B, D]
+            # Project vi with kernel -> [B, K]
+            vi_proj = torch.matmul(vi, self.kernel)  # [B, K]
+            for j in range(i + 1, self.num_fields):
+                vj = field_emb[:, j, :]  # [B, D]
+                vj_proj = torch.matmul(vj, self.kernel)  # [B, K]
+                # g(vi, vj) = (v_i^T W) * (v_j^T W) summed over projection dim
+                pij = torch.sum(vi_proj * vj_proj, dim=1, keepdim=True)  # [B, 1]
+                interactions.append(pij)
+        return torch.cat(interactions, dim=1)  # [B, num_pairs]
+
     def forward(self, x):
+        # field_emb: [B, F, D]
         field_emb = self.embedding(x=x, features=self.field_features, squeeze_dim=False)
-        linear_signal = field_emb.flatten(start_dim=1)
+        # Z = [v_1; v_2; ...; v_F]
+        linear_signal = field_emb.flatten(start_dim=1)  # [B, F*D]
 
         if self.product_type == "inner":
-            interactions = []
-            for i in range(self.num_fields - 1):
-                vi = field_emb[:, i, :]
-                for j in range(i + 1, self.num_fields):
-                    vj = field_emb[:, j, :]
-                    interactions.append(torch.sum(vi * vj, dim=1, keepdim=True))
-            product_signal = torch.cat(interactions, dim=1)
+            product_signal = self.compute_inner_products(field_emb)
+        elif self.product_type == "outer":
+            product_signal = self.compute_outer_kernel_products(field_emb)
         else:
-            transformed = self.kernel(field_emb)  # [B, F, outer_dim]
-            interactions = []
-            for i in range(self.num_fields - 1):
-                vi = transformed[:, i, :]
-                for j in range(i + 1, self.num_fields):
-                    vj = transformed[:, j, :]
-                    interactions.append(vi * vj)
-            product_signal = torch.stack(interactions, dim=1).flatten(start_dim=1)
+            inner_p = self.compute_inner_products(field_emb)
+            outer_p = self.compute_outer_kernel_products(field_emb)
+            product_signal = torch.cat([inner_p, outer_p], dim=1)
 
         deep_input = torch.cat([linear_signal, product_signal], dim=1)
         y = self.mlp(deep_input)

nextrec/models/ranking/widedeep.py

@@ -61,10 +61,10 @@ class WideDeep(BaseModel):
         sparse_features: list[SparseFeature],
         sequence_features: list[SequenceFeature],
         mlp_params: dict,
-        target: list[str] = [],
+        target: list[str] | str | None = None,
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -75,6 +75,12 @@ class WideDeep(BaseModel):
         **kwargs,
     ):
 
+        if target is None:
+            target = []
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(WideDeep, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -90,8 +96,6 @@ class WideDeep(BaseModel):
         )
 
         self.loss = loss
-        if self.loss is None:
-            self.loss = "bce"
 
         # Wide part: use all features for linear model
         self.wide_features = sparse_features + sequence_features

nextrec/models/ranking/xdeepfm.py

@@ -76,12 +76,12 @@ class xDeepFM(BaseModel):
         sparse_features: list[SparseFeature],
         sequence_features: list[SequenceFeature],
         mlp_params: dict,
-        cin_size: list[int] = [128, 128],
+        cin_size: list[int] | None = None,
         split_half: bool = True,
-        target: list[str] = [],
+        target: list[str] | str | None = None,
         task: str | list[str] | None = None,
         optimizer: str = "adam",
-        optimizer_params: dict = {},
+        optimizer_params: dict | None = None,
         loss: str | nn.Module | None = "bce",
         loss_params: dict | list[dict] | None = None,
         device: str = "cpu",
@@ -92,6 +92,13 @@ class xDeepFM(BaseModel):
         **kwargs,
     ):
 
+        cin_size = cin_size or [128, 128]
+        if target is None:
+            target = []
+        optimizer_params = optimizer_params or {}
+        if loss is None:
+            loss = "bce"
+
         super(xDeepFM, self).__init__(
             dense_features=dense_features,
             sparse_features=sparse_features,
@@ -107,8 +114,6 @@ class xDeepFM(BaseModel):
         )
 
         self.loss = loss
-        if self.loss is None:
-            self.loss = "bce"
 
         # Linear part and CIN part: use sparse and sequence features
         self.linear_features = sparse_features + sequence_features

nextrec/utils/config.py

@@ -28,9 +28,15 @@ def resolve_path(path_str: str | Path, base_dir: Path) -> Path:
     path = Path(path_str).expanduser()
     if path.is_absolute():
         return path
-    if path.exists():
-        return path.resolve()
-    return (base_dir / path).resolve()
+    # 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
 
 
 def select_features(

nextrec/utils/file.py

@@ -60,7 +60,8 @@ def read_table(path: str | Path, data_format: str | None = None) -> pd.DataFrame
     if fmt in {"parquet", ""}:
         return pd.read_parquet(data_path)
     if fmt in {"csv", "txt"}:
-        return pd.read_csv(data_path)
+        # Use low_memory=False to avoid mixed-type DtypeWarning on wide CSVs
+        return pd.read_csv(data_path, low_memory=False)
     raise ValueError(f"Unsupported data format: {data_path}")
 
 

nextrec/utils/model.py

@@ -20,3 +20,25 @@ def get_mlp_output_dim(params: dict, fallback: int) -> int:
     if dims:
         return dims[-1]
     return fallback
+
+
+def select_features(
+    available_features: list,
+    names: list[str],
+    param_name: str,
+) -> list:
+    if not names:
+        return []
+
+    if len(names) != len(set(names)):
+        raise ValueError(f"{param_name} contains duplicate feature names: {names}")
+
+    feature_map = {feat.name: feat for feat in available_features}
+    missing = [name for name in names if name not in feature_map]
+    if missing:
+        raise ValueError(
+            f"{param_name} contains unknown feature names {missing}. "
+            f"Available features: {list(feature_map)}"
+        )
+
+    return [feature_map[name] for name in names]

{nextrec-0.4.2.dist-info → nextrec-0.4.3.dist-info}/METADATA

@@ -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.dist-info → nextrec-0.4.3.dist-info}/RECORD

@@ -1,20 +1,20 @@
 nextrec/__init__.py,sha256=_M3oUqyuvQ5k8Th_3wId6hQ_caclh7M5ad51XN09m98,235
-nextrec/__version__.py,sha256=6hfVa12Q-nXyUEXr6SyKpqPEDJW6vlRHyPxlA27PfTs,22
-nextrec/cli.py,sha256=W6Zvn8YuJ3zy8QXOGkyjXchw5wO5_gD67qy0aja0frQ,18747
+nextrec/__version__.py,sha256=Nyg0pmk5ea9-SLCAFEIF96ByFx4-TJFtrqYPN-Zn6g4,22
+nextrec/cli.py,sha256=b6tv7ZO7UBRVR6IfyqVP24JEcdu9-2_vV5MlfWcQucM,18468
 nextrec/basic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextrec/basic/activation.py,sha256=uzTWfCOtBSkbu_Gk9XBNTj8__s241CaYLJk6l8nGX9I,2885
 nextrec/basic/callback.py,sha256=YPkuSmy3WV8cXj8YmLKxwNP2kULpkUlJQf8pV8CkNYQ,1037
 nextrec/basic/features.py,sha256=ZvFzH05yQzmeWpH74h5gpALz5XOqVZTibUZRzXvwdLU,4141
-nextrec/basic/layers.py,sha256=NhT73cpQgFbR70ZNYuhk6DwKHzThi1oTSw5DoTn41aU,24940
-nextrec/basic/loggers.py,sha256=FSm9OtsiAn8xRvdGtqqDeTVlFX6tQjQdxaRSu1Gfgmw,6262
-nextrec/basic/metrics.py,sha256=1QODkbWhueULfv6T6wlFDduY16T533NW0KAfhlXsDlU,23100
-nextrec/basic/model.py,sha256=PhINJiG36j8-nOPGqxXNdpCFxLd2JhyweA3i84Uhukg,97129
+nextrec/basic/layers.py,sha256=hQrxOw1XPmUKODaFG1l_K9TGJrNYHBUYcIQFirjUd7s,26004
+nextrec/basic/loggers.py,sha256=p9wNmLuRYyvHsOzP0eNOYSlV3hrTDjrt6ggrH_r4RE0,6243
+nextrec/basic/metrics.py,sha256=jr6Yqdig1gCZQP3NAWA_1fU8bTIG_7TGatrtrlzTK9E,23135
+nextrec/basic/model.py,sha256=7-9CffXDvUG9G5Yx7_yCF17EWKup4Tl87JLdbmNIjb0,97118
 nextrec/basic/session.py,sha256=UOG_-EgCOxvqZwCkiEd8sgNV2G1sm_HbzKYVQw8yYDI,4483
 nextrec/data/__init__.py,sha256=auT_PkbgU9pUCt7KQl6H2ajcUorRhSyHa8NG3wExcG8,1197
 nextrec/data/batch_utils.py,sha256=FAJiweuDyAIzX7rICVmcxMofdFs2-7RLinovwB-lAYM,2878
 nextrec/data/data_processing.py,sha256=JTjNU55vj8UV2VgXwo0Qh4MQqWfD3z5uc95uOHIC4ck,5337
 nextrec/data/data_utils.py,sha256=LaVNXATcqu0ARPV-6WESQz6JXi3g-zq4uKjcoqBFlqI,1219
-nextrec/data/dataloader.py,sha256=UYGsNSRFIG9ma43QUNvh8Yk36pKS80ITxktX-PexoHY,18787
+nextrec/data/dataloader.py,sha256=L4VBpWUZrxozFBV54nhJAAC-ZX5Hg6zFwIwpGnguJ9c,18789
 nextrec/data/preprocessor.py,sha256=BxoD6GHEre86i-TbxPi58Uwmg_G7oLkiER6f7VfmVHo,41583
 nextrec/loss/__init__.py,sha256=mO5t417BneZ8Ysa51GyjDaffjWyjzFgPXIQrrggasaQ,827
 nextrec/loss/listwise.py,sha256=UT9vJCOTOQLogVwaeTV7Z5uxIYnngGdxk-p9e97MGkU,5744
@@ -31,39 +31,39 @@ nextrec/models/match/mind.py,sha256=so7XkuCHr5k5UBhEB65GL0JavFOjLGLYeN9Nuc4eNKA,
 nextrec/models/match/sdm.py,sha256=MGEpLe1-UZ8kiHhR7-Q6zW-d9NnOm0ptHQWYVzh7m_Y,10488
 nextrec/models/match/youtube_dnn.py,sha256=DxMn-WLaLGAWRy5qhpRszUugbpPxOMUsWEuh7QEAWQw,7214
 nextrec/models/multi_task/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-nextrec/models/multi_task/esmm.py,sha256=RWdx5K4s8jsnQdYPkogHaW4RT0-QL4PRKrPEfpIj0UU,6322
-nextrec/models/multi_task/mmoe.py,sha256=82_g13252xdSFxspqZ33gSj-jTZ1Co3pHuCdbhZdKZ4,7909
-nextrec/models/multi_task/ple.py,sha256=_b6kI4XZp_v6tCcMtfq821GZFLupOCKZ9s9vQfk2jqw,12629
-nextrec/models/multi_task/poso.py,sha256=uFNoQhb8XTHqeZ7U5GNAnHnQDz7FnSRihrzqg3oV9iQ,17793
-nextrec/models/multi_task/share_bottom.py,sha256=mPlXTEW53BnuXBUlpo8aIonanwoLE1b1Sgccmo8S4dg,5934
+nextrec/models/multi_task/esmm.py,sha256=tQg_jE51VDTyc-F0auviyP8CI9uzYQ_KjybbCAXWp1s,6491
+nextrec/models/multi_task/mmoe.py,sha256=qFWKdCE_VSGpVrMgx0NOO-HtLRNGdVxCWdkMfoEgjLA,8583
+nextrec/models/multi_task/ple.py,sha256=SMTgKqz8huXzmyMwACVG8yisHvd3GFGshYl7LOpnJXs,13016
+nextrec/models/multi_task/poso.py,sha256=JkNlMcqjMuE4PTGM6HeGcJTxhbLklXpusfyY8A1BjTQ,19017
+nextrec/models/multi_task/share_bottom.py,sha256=mkWaGHimUqp-2dmPHXjb5ffxX7ixv1BF0gQXTbx9kBo,6519
 nextrec/models/ranking/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-nextrec/models/ranking/afm.py,sha256=QsL8XqQSfZk8ciUQm2K_AMeSk7t6ayyqdnByxhHARog,10027
-nextrec/models/ranking/autoint.py,sha256=6aHhunbG2chW7OlS5BCoFltMd285njw2vpWO46gzJKk,8108
-nextrec/models/ranking/dcn.py,sha256=sSfD3cA6z7J-LDwNVOnfcaaEJ29yWSYov7FXoHuMZlc,4916
-nextrec/models/ranking/dcn_v2.py,sha256=wmauPlflWojRHuPtnf8T2x6OT64EYIjbjlm_8RGdNlg,4113
-nextrec/models/ranking/deepfm.py,sha256=thuROmRVp2Ltiz_MJWili63pkdgGYzRkxtLkdyD2OPk,4967
-nextrec/models/ranking/dien.py,sha256=zKrbPpzV4L9VJmcJRbhPahy-8zc-Q2BrU70WidmidCM,12924
-nextrec/models/ranking/din.py,sha256=KoLJcSA6NOTCmV1JZY21q0IeKH4qSkWRH8bGOXB9VC8,7232
-nextrec/models/ranking/fibinet.py,sha256=OgbcUkrQmVpza_e1DZvkvtFeICFmWWNRKjdxi9rQzMs,4961
-nextrec/models/ranking/fm.py,sha256=VRlzSIlMDmhM35eBOKOgQDn8QeG4p6kI6-7uqKtZkE4,2853
-nextrec/models/ranking/masknet.py,sha256=0MWVgNN64isxj4wzUmxj785_L_Wa8rd3st4bPN9Yj7w,12351
-nextrec/models/ranking/pnn.py,sha256=zo2gmrPmD2ZBoqpTCSuKBllnrBUqHna1zjiLcvsnpNY,4831
-nextrec/models/ranking/widedeep.py,sha256=RgVICh03LFIIKkouV0VM3uUcpl3u2x5lBF4JDsGb7X0,4961
-nextrec/models/ranking/xdeepfm.py,sha256=qw3umdKlKjfBxNqG_7d4v3P594YaPxfeMAW3Tyng8uc,5771
+nextrec/models/ranking/afm.py,sha256=XaiUYm36-pVNzB31lEtMstjg42-shn94khja0LMQB3s,10125
+nextrec/models/ranking/autoint.py,sha256=CyHnYyHJiQIOiPGI-j_16nCpECDQJ3FlVZ4nq3qu-l8,8109
+nextrec/models/ranking/dcn.py,sha256=vxbrDu9RxXznXNpXVeYJR4wdxoc4Vo0ygML6fFArY18,7299
+nextrec/models/ranking/dcn_v2.py,sha256=VNMiHf6BeBOxnoommjGZfF-9t_B88niiVEgmPVcGjQM,11163
+nextrec/models/ranking/deepfm.py,sha256=D9RPM40QAhogw8_RAOfE3JD1gnGf4F3-gXR40EZq-RU,5224
+nextrec/models/ranking/dien.py,sha256=G1W_pj8XyGBPgZo_86I3LgfHzQvR-xvR-PGNJZdRdAM,18958
+nextrec/models/ranking/din.py,sha256=gcibKTxK6nQCCxYMymO9ttu3UG2MSrOWRNBPCmJgMEM,9422
+nextrec/models/ranking/fibinet.py,sha256=OuE4MoG7rHycyRRQtKOvxHbuf7C6zoJFxGFerXmmn9U,7919
+nextrec/models/ranking/fm.py,sha256=ko_Eao9UfklakEk_TVEFZSyVAojmtclo1uIMBhL4FLU,4525
+nextrec/models/ranking/masknet.py,sha256=IDp2XyGHdjuiUTIBv2JxNQlMw5ANdv12_9YJOX7tnzw,12367
+nextrec/models/ranking/pnn.py,sha256=twwixy26mfAVaI9AqNnMLdwOG-WtDga60xsNiyJrFjI,8174
+nextrec/models/ranking/widedeep.py,sha256=Xm2klmKBOoSKWCBQN7FhwLStu0BHSTOgAJ9kwLmtiFY,5077
+nextrec/models/ranking/xdeepfm.py,sha256=LI_cCHjfQCG9H2tQKFC7NfyrLkm8FAUyjjbLoTIIpzY,5930
 nextrec/utils/__init__.py,sha256=zqU9vjRUpVzJepcvdbxboik68K5jnMR40kdVjr6tpXY,2599
-nextrec/utils/config.py,sha256=Rfh75CNYRgutYvuC9q1enMLhe1XTB18mMpRQDEcWi0I,17724
+nextrec/utils/config.py,sha256=KGcKA7a592FkZ5wtbDmpvIc9Fk3uedj-BtJuRk2f4t8,18088
 nextrec/utils/device.py,sha256=DtgmrJnVJQKtgtVUbm0SW0vZ5Le0R9HU8TsvqPnRLZc,2453
 nextrec/utils/distributed.py,sha256=tIkgUjzEjR_FHOm9ckyM8KddkCfxNSogP-rdHcVGhuk,4782
 nextrec/utils/embedding.py,sha256=YSVnBeve0hVTPSfyxN4weGCK_Jd8SezRBqZgwJAR3Qw,496
 nextrec/utils/feature.py,sha256=LcXaWP98zMZhJTKL92VVHX8mqOE5Q0MyVq3hw5Z9kxs,300
-nextrec/utils/file.py,sha256=pwfp-amY1PW7JlYgJgMJHTT6-7cc_3hRJcLaY5UtPrg,2929
+nextrec/utils/file.py,sha256=s2cO1LRbU7xPeAbVoOA6XOoV6wvLrW6oy6p9fVSz9pc,3024
 nextrec/utils/initializer.py,sha256=GzxasKewn4C14ERNdSo9el2jEa8GXXEB2hTQnRcK2IA,2517
-nextrec/utils/model.py,sha256=FB7QbatO0uEvghBEfByJtRS0waaBEB1UI0YzfA_2k04,535
+nextrec/utils/model.py,sha256=dYl1XfIZt6aVjNyV2AAhcArwFRMcEAKrjG_pr8AVHs0,1163
 nextrec/utils/optimizer.py,sha256=eX8baIvWOpwDTGninbyp6pQfzdHbIL62GTi4ldpYcfM,2337
 nextrec/utils/synthetic_data.py,sha256=WSbC5cs7TbuDc57BCO74S7VJdlK0fQmnZA2KM4vUpoI,17566
 nextrec/utils/tensor.py,sha256=Z6MBpSuQpHw4kGjeKxG0cXZMpRBCM45zTKhk9WolyiM,2220
-nextrec-0.4.2.dist-info/METADATA,sha256=VKFbNQN7lnQk5K4qZJXKDL8f5JcWr9gvfgCayBY_918,16753
-nextrec-0.4.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-nextrec-0.4.2.dist-info/entry_points.txt,sha256=NN-dNSdfMRTv86bNXM7d3ZEPW2BQC6bRi7QP7i9cIps,45
-nextrec-0.4.2.dist-info/licenses/LICENSE,sha256=2fQfVKeafywkni7MYHyClC6RGGC3laLTXCNBx-ubtp0,1064
-nextrec-0.4.2.dist-info/RECORD,,
+nextrec-0.4.3.dist-info/METADATA,sha256=rD4niOz9T9rLsvQwcXakLQpU6Zn2Jj8BFZeGZDMhiyE,18952
+nextrec-0.4.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+nextrec-0.4.3.dist-info/entry_points.txt,sha256=NN-dNSdfMRTv86bNXM7d3ZEPW2BQC6bRi7QP7i9cIps,45
+nextrec-0.4.3.dist-info/licenses/LICENSE,sha256=2fQfVKeafywkni7MYHyClC6RGGC3laLTXCNBx-ubtp0,1064
+nextrec-0.4.3.dist-info/RECORD,,