nextrec 0.4.2__py3-none-any.whl → 0.4.4__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

@@ -1,12 +1,54 @@
 """
 Date: create on 09/11/2025
 Author:
-    Yang Zhou,zyaztec@gmail.com
+Yang Zhou,zyaztec@gmail.com
 Reference:
-    [1] Lian J, Zhou X, Zhang F, et al. xdeepfm: Combining explicit and implicit feature interactions
-        for recommender systems[C]//Proceedings of the 24th ACM SIGKDD international conference on
-        knowledge discovery & data mining. 2018: 1754-1763.
-        (https://arxiv.org/abs/1803.05170)
+[1] Lian J, Zhou X, Zhang F, et al. xdeepfm: Combining explicit and implicit feature interactions
+for recommender systems[C]//Proceedings of the 24th ACM SIGKDD international conference on
+knowledge discovery & data mining. 2018: 1754-1763.
+(https://arxiv.org/abs/1803.05170)
+
+xDeepFM is a CTR prediction model that unifies explicit and implicit
+feature interaction learning. It extends DeepFM by adding the
+Compressed Interaction Network (CIN) to explicitly model high-order
+interactions at the vector-wise level, while an MLP captures implicit
+non-linear crosses. A linear term retains first-order signals, and all
+three parts are learned jointly end-to-end.
+
+In the forward pass:
+  (1) Embedding Layer: transforms sparse/sequence fields into dense vectors
+  (2) Linear Part: captures first-order contributions of sparse/sequence fields
+  (3) CIN: explicitly builds higher-order feature crosses via convolution over
+      outer products of field embeddings, with optional split-half connections
+  (4) Deep Part (MLP): models implicit, non-linear interactions across all fields
+  (5) Combination: sums outputs from linear, CIN, and deep branches before the
+      task-specific prediction layer
+
+Key Advantages:
+- Jointly learns first-order, explicit high-order, and implicit interactions
+- CIN offers interpretable vector-wise crosses with controlled complexity
+- Deep branch enhances representation power for non-linear patterns
+- End-to-end optimization eliminates heavy manual feature engineering
+- Flexible design supports both sparse and sequence features
+
+xDeepFM 是一个 CTR 预估模型，将显式与隐式的特征交互学习统一到同一框架。
+在 DeepFM 的基础上，额外引入了 CIN（Compressed Interaction Network）
+显式建模高阶向量级交互，同时 MLP 负责隐式非线性交互，线性部分保留一阶信号，
+三者联合训练。
+
+前向流程：
+  (1) 嵌入层：将稀疏/序列特征映射为稠密向量
+  (2) 线性部分：建模稀疏/序列特征的一阶贡献
+  (3) CIN：通过对字段嵌入做外积并卷积，显式捕获高阶交叉，可选 split-half 以控参
+  (4) 深层部分（MLP）：对所有特征进行隐式非线性交互建模
+  (5) 融合：线性、CIN、MLP 输出求和后进入任务预测层
+
+主要优点：
+- 同时学习一阶、显式高阶、隐式交互
+- CIN 提供可解释的向量级交叉并可控复杂度
+- 深层分支提升非线性表达能力
+- 端到端训练降低人工特征工程需求
+- 兼容稀疏与序列特征的建模
 """
 
 import torch
@@ -76,12 +118,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 +134,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 +156,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(
@@ -154,8 +160,11 @@ def build_feature_objects(
             SparseFeature(
                 name=name,
                 vocab_size=int(vocab_size),
+                embedding_name=embed_cfg.get("embedding_name", name),
                 embedding_dim=embed_cfg.get("embedding_dim"),
                 padding_idx=embed_cfg.get("padding_idx"),
+                init_type=embed_cfg.get("init_type", "xavier_uniform"),
+                init_params=embed_cfg.get("init_params"),
                 l1_reg=embed_cfg.get("l1_reg", 0.0),
                 l2_reg=embed_cfg.get("l2_reg", 1e-5),
                 trainable=embed_cfg.get("trainable", True),
@@ -178,9 +187,12 @@ def build_feature_objects(
                 name=name,
                 vocab_size=int(vocab_size),
                 max_len=embed_cfg.get("max_len") or proc_cfg.get("max_len", 50),
+                embedding_name=embed_cfg.get("embedding_name", name),
                 embedding_dim=embed_cfg.get("embedding_dim"),
                 padding_idx=embed_cfg.get("padding_idx"),
                 combiner=embed_cfg.get("combiner", "mean"),
+                init_type=embed_cfg.get("init_type", "xavier_uniform"),
+                init_params=embed_cfg.get("init_params"),
                 l1_reg=embed_cfg.get("l1_reg", 0.0),
                 l2_reg=embed_cfg.get("l2_reg", 1e-5),
                 trainable=embed_cfg.get("trainable", True),

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/initializer.py

@@ -5,10 +5,9 @@ Date: create on 13/11/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
-from typing import Any, Dict, Set, cast
+from typing import Any, Dict, Set, 
 
 import torch.nn as nn
-from torch.nn.init import _NonlinearityType
 
 KNOWN_NONLINEARITIES: Set[str] = {
     "linear",
@@ -27,28 +26,25 @@ KNOWN_NONLINEARITIES: Set[str] = {
 }
 
 
-def resolve_nonlinearity(activation: str | _NonlinearityType) -> _NonlinearityType:
-    if isinstance(activation, str):
-        if activation in KNOWN_NONLINEARITIES:
-            return cast(_NonlinearityType, activation)
-        # Fall back to linear for custom activations (gain handled separately).
-        return "linear"
-    return activation
+def resolve_nonlinearity(activation: str):
+    if activation in KNOWN_NONLINEARITIES:
+        return activation
+    return "linear"
 
 
-def resolve_gain(activation: str | _NonlinearityType, param: Dict[str, Any]) -> float:
+def resolve_gain(activation: str, param: Dict[str, Any]) -> float:
     if "gain" in param:
         return param["gain"]
     nonlinearity = resolve_nonlinearity(activation)
     try:
-        return nn.init.calculate_gain(nonlinearity, param.get("param"))
+        return nn.init.calculate_gain(nonlinearity, param.get("param")) # type: ignore
     except ValueError:
-        return 1.0  # custom activation with no gain estimate available
+        return 1.0
 
 
 def get_initializer(
     init_type: str = "normal",
-    activation: str | _NonlinearityType = "linear",
+    activation: str = "linear",
     param: Dict[str, Any] | None = None,
 ):
     param = param or {}
@@ -62,11 +58,11 @@ def get_initializer(
             nn.init.xavier_normal_(tensor, gain=gain)
         elif init_type == "kaiming_uniform":
             nn.init.kaiming_uniform_(
-                tensor, a=param.get("a", 0), nonlinearity=nonlinearity
+                tensor, a=param.get("a", 0), nonlinearity=nonlinearity # type: ignore
             )
         elif init_type == "kaiming_normal":
             nn.init.kaiming_normal_(
-                tensor, a=param.get("a", 0), nonlinearity=nonlinearity
+                tensor, a=param.get("a", 0), nonlinearity=nonlinearity # type: ignore
             )
         elif init_type == "orthogonal":
             nn.init.orthogonal_(tensor, gain=gain)
@@ -80,4 +76,4 @@ def get_initializer(
             raise ValueError(f"Unknown init_type: {init_type}")
         return tensor
 
-    return initializer_fn
+    return initializer_fn

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.4.dist-info}/METADATA

@@ -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