nextrec 0.2.2__tar.gz → 0.2.4__tar.gz

{nextrec-0.2.2 → nextrec-0.2.4}/.github/workflows/publish.yml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  # dev 分支 -> TestPyPI
+  # dev -> TestPyPI
   publish-to-testpypi:
     if: github.ref == 'refs/heads/dev'
     runs-on: ubuntu-latest
@@ -36,7 +36,7 @@ jobs:
         run: |
           twine upload --verbose --repository testpypi dist/*
 
-  # main 分支 -> 正式 PyPI
+  # main -> PyPI
   publish-to-pypi:
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest

{nextrec-0.2.2 → nextrec-0.2.4}/.gitignore

@@ -127,4 +127,4 @@ session/
 pypirc.template
 
 # Sphinx build
-docs/_build/
+docs/rtd/_build/

{nextrec-0.2.2 → nextrec-0.2.4}/.readthedocs.yaml

@@ -12,12 +12,12 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+   configuration: docs/rtd/conf.py
   
 # Optionally, but recommended,
 # declare the Python requirements required to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
    install:
-   - requirements: docs/requirements.txt
-        
+   - requirements: docs/rtd/requirements.txt
+        

{nextrec-0.2.2 → nextrec-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.2.2
+Version: 0.2.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
@@ -61,7 +61,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.2.2-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.2.4-orange.svg)
 
 English | [中文版](README_zh.md)
 

{nextrec-0.2.2 → nextrec-0.2.4}/README.md

@@ -5,7 +5,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.2.2-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.2.4-orange.svg)
 
 English | [中文版](README_zh.md)
 

{nextrec-0.2.2 → nextrec-0.2.4}/README_zh.md

@@ -5,7 +5,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.2.2-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.2.4-orange.svg)
 
 [English Version](README.md) | 中文版
 

nextrec-0.2.4/docs/rtd/conf.py

@@ -0,0 +1,39 @@
+"""Sphinx configuration for building docs on Read the Docs."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(PROJECT_ROOT / "nextrec"))
+
+project = "NextRec"
+copyright = "2025, Yang Zhou"
+author = "Yang Zhou"
+release = "0.2.4"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "special-members": "__init__, __iter__",
+    "private-members": True,
+}

nextrec-0.2.4/docs/rtd/index.md

@@ -0,0 +1,157 @@
+# NextRec Documentation
+
+NextRec is a unified recommendation framework built on PyTorch. It offers modular feature definitions, a reproducible data processing pipeline, and a standard training engine that already powers ranking, retrieval, multi-task, and emerging generative recommendation models.
+
+## What you get
+- Unified interface for ranking, retrieval, multi-task, and early generative recommenders (TIGER, HSTU in progress).
+- Ready-to-use feature abstractions: `DenseFeature`, `SparseFeature`, `SequenceFeature`.
+- End-to-end training loop with `compile`, `fit`, `evaluate`, `predict`, checkpoints, metrics, and early stopping.
+- DataProcessor for repeatable numeric/sparse/sequence/target handling with save/load support.
+- GPU/MPS ready; tutorials and runnable scripts under `tutorials/`.
+
+## Installation
+Using uv (recommended):
+
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec
+pip install uv
+uv sync
+source .venv/bin/activate
+uv pip install -e .
+```
+
+Using pip:
+
+```bash
+git clone https://github.com/zerolovesea/NextRec.git
+cd NextRec
+pip install -r requirements.txt
+pip install -r test_requirements.txt
+pip install -e .
+```
+
+## 5-minute quick start (DeepFM)
+Train and predict on MovieLens-style data:
+
+```python
+import pandas as pd
+from nextrec.models.ranking.deepfm import DeepFM
+from nextrec.basic.features import DenseFeature, SparseFeature
+
+df = pd.read_csv("dataset/movielens_100k.csv")
+
+dense_features = [DenseFeature("age")]
+sparse_features = [
+    SparseFeature("user_id", vocab_size=df["user_id"].max() + 1, embedding_dim=4),
+    SparseFeature("item_id", vocab_size=df["item_id"].max() + 1, embedding_dim=4),
+    SparseFeature("gender", vocab_size=df["gender"].max() + 1, embedding_dim=4),
+    SparseFeature("occupation", vocab_size=df["occupation"].max() + 1, embedding_dim=4),
+]
+
+model = DeepFM(
+    dense_features=dense_features,
+    sparse_features=sparse_features,
+    target="label",
+    device="cpu",
+    session_id="deepfm_demo",
+)
+
+model.compile(
+    optimizer="adam",
+    optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},
+    loss="bce",
+)
+
+model.fit(
+    train_data=df,
+    metrics=["auc", "recall", "precision"],
+    epochs=5,
+    batch_size=512,
+    shuffle=True,
+    verbose=1,
+    validation_split=0.1,
+)
+
+preds = model.predict(df)
+print(preds[:5])
+```
+
+## Core API guide
+Feature definitions (`nextrec.basic.features`):
+
+- `DenseFeature(name, embedding_dim=1)` for continuous values.
+- `SparseFeature(name, vocab_size, embedding_dim=auto, padding_idx=None, l1_reg=0.0, l2_reg=1e-5, trainable=True)` for categorical ids.
+- `SequenceFeature(name, vocab_size, max_len=20, combiner="mean", padding_idx=None, l1_reg=0.0, l2_reg=1e-5, trainable=True)` for histories with pooling.
+
+Data processing (`nextrec.data.preprocessor.DataProcessor`):
+
+```python
+from nextrec.data.preprocessor import DataProcessor
+
+processor = DataProcessor()
+processor.add_numeric_feature("age", scaler="standard")
+processor.add_sparse_feature("user_id", encode_method="label")
+processor.add_sequence_feature("item_history", encode_method="hash", hash_size=5000, max_len=50, pad_value=0)
+processor.add_target("label", target_type="binary")
+
+processor.fit(train_df)                       # learns scalers/encoders
+train_arr = processor.transform(train_df)     # dict -> numpy arrays
+vocab_sizes = processor.get_vocab_sizes()     # useful for embedding dims
+processor.save("processor.pkl")               # persist for serving
+processor = DataProcessor.load("processor.pkl")
+```
+
+## Training workflow (`nextrec.basic.model.BaseModel` interface)
+
+```python
+model.compile(
+    optimizer="adam",                          # str, class, or instance
+    optimizer_params={"lr": 1e-3},
+    scheduler="steplr",                        # optional torch scheduler name/class/instance
+    scheduler_params={"step_size": 3, "gamma": 0.5},
+    loss="bce",                                # per-task loss or list
+)
+
+model.fit(
+    train_data=train_df_or_loader,             # dict, DataFrame, or DataLoader
+    valid_data=valid_df_or_loader,             # optional validation split
+    metrics=["auc", "logloss"],                # or {"label": ["auc", "logloss"]}
+    epochs=10,
+    batch_size=256,
+    shuffle=True,
+    verbose=1,
+    validation_split=0.1,                      # auto split when valid_data is None
+)
+
+scores = model.evaluate(valid_df_or_loader)    # returns metric dict
+preds = model.predict(test_df_or_loader)       # numpy array or dict
+model.save_weights("checkpoint.model")
+model.load_weights("checkpoint.model", map_location="cpu")
+```
+
+## Model zoo (`nextrec.models`)
+- Ranking: FM, AFM, DeepFM, Wide&Deep, xDeepFM, FiBiNET, PNN, AutoInt, DCN, DIN, DIEN, MaskNet.
+- Retrieval: DSSM, DSSM v2 (pairwise), YouTube DNN, MIND, SDM.
+- Multi-task: MMOE, PLE, ESMM, ShareBottom.
+- Generative (in progress): TIGER, HSTU.
+
+## Tutorials and scripts
+- Ready-to-run examples live in `tutorials/` (e.g., `movielen_ranking_deepfm.py`, `example_multitask.py`).
+- Datasets used in samples live in `dataset/`. Check `README.md` and `README_zh.md` for dataset prep and more examples.
+
+## Contents
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+modules
+```
+
+## API reference stub
+
+```{automodule} nextrec
+:members:
+:noindex:
+```

nextrec-0.2.4/docs/rtd/requirements.txt

@@ -0,0 +1,3 @@
+sphinx-autodoc-typehints
+sphinx_rtd_theme
+myst-parser

nextrec-0.2.4/docs/zh//345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -0,0 +1,97 @@
+> 本文演示如何用 NextRec 从零到一训练并构建一个可上线的推荐模型。示例基于仓库自带的 `dataset/movielens_100k.csv`和`dataset/match_task.csv`实现。
+
+## 1. 环境与数据准备
+
+- 依赖：Python 3.10+、PyTorch 1.10+。
+- 安装：`pip install nextrec`（或仓库根目录 `pip install -e .` 以开发模式安装）。
+- 数据格式：CSV 或 Parquet 均可，通常包含用户特征、物品特征、行为序列及监督标签（如 `label`、`click`）。
+
+## 2. 关于特征
+
+在上手之前，先介绍一些推荐系统的概念。在推荐系统中，通常会处理多种类型的输入信号，在经过一系列的变换之后转化为向量输入网络：
+
+- 稠密特征（数值型）：连续或可序数化的数值，如年龄、价格、时长、打分；常见做法是标准化/归一化或对数变换。
+- 稀疏特征（类别/ID）：高基数离散字段，如用户 ID、物品 ID、性别、职业、设备类型；通常需要索引化后，在一个embedding lookup matrix中进行嵌入。
+- 序列特征（行为序列）：可变长的历史行为，如用户的浏览/点击/购买列表。这类特征表征了用户的行为和兴趣变化，通常我们需要截断、padding，嵌入后通过不同聚合方式（如 mean/sum/attention）将其变为定长向量。
+- 上下文特征：时间、地理、曝光位置等环境信息，可是稠密也可能是稀疏，常与主特征交互。
+- 多模态特征：文本、图片、视频等经过预训练模型得到的向量，可直接作为稠密输入，或与 ID 交互建模。
+
+通常一个标准的训练数据格式如下所示：
+
+```text
+user_id,item_id,gender,age,occupation,history_seq,label
+1024,501,1,28,3,"[12,45,18,77]",1
+2048,777,0,35,5,"[8,99]",0
+```
+
+## 3. 训练一个排序模型（DeepFM）
+
+接下来，我们通过一个简单的模型，指导大家如何使用NextRec在movielens数据集上训练一个DeepFM模型。首先，需要将不同的特征进行定义。
+
+对于稀疏特征，我们需要定义词表大小`vocab_size`和嵌入层大小`embedding_dim`，嵌入层id`embedding_name`，对于稠密特征，需要定义是否需要线性变换及变换后的维度。
+
+```python
+import pandas as pd
+from sklearn.model_selection import train_test_split
+
+from nextrec.basic.features import DenseFeature, SparseFeature
+from nextrec.models.ranking.deepfm import DeepFM
+
+df = pd.read_csv("dataset/movielens_100k.csv")
+
+dense_features = [DenseFeature('age')]
+sparse_features = [
+    SparseFeature('user_id', vocab_size=df['user_id'].max() + 1, embedding_dim=16),
+    SparseFeature('item_id', vocab_size=df['item_id'].max() + 1, embedding_dim=16),
+    SparseFeature('gender', vocab_size=df['gender'].max() + 1, embedding_dim=4),
+    SparseFeature('occupation', vocab_size=df['occupation'].max() + 1, embedding_dim=8),
+]
+
+train_df, valid_df = train_test_split(df, test_size=0.2, random_state=2024)
+```
+
+在定义特征后，我只需要实例化需要的模型，随后为模型配置所需要的训练参数。在训练时，模型内部会组装dataloader并进行训练，并可以输出需要的训练指标。
+
+```python
+model = DeepFM(
+    dense_features=dense_features,
+    sparse_features=sparse_features,
+    mlp_params={"dims": [256, 128], "activation": "relu", "dropout": 0.2},
+    target='label',
+    device='cpu',
+    session_id="movielens_deepfm" # 通过设置session id，来管理不同实验的日志
+)
+
+model.compile(
+    optimizer="adam",
+    optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},
+    loss='binary_crossentropy',
+)
+
+model.fit(
+    train_data=train_df,
+    valid_data=test_df,
+    metrics=['auc', 'recall','precision'],
+    epochs=1,  
+    batch_size=512,
+    shuffle=True
+)
+```
+
+- `metrics` 支持 `auc`/`logloss`/`accuracy`/`gauc` 等，使用 GAUC 时传入 `user_id_column='user_id'`。
+- 训练会自动早停，并在 `session_id` 对应目录下保存最佳权重。
+
+## 5. 推理与评估
+
+训练完成后，用户可以进行批量预测。NextRec支持不同的推理数据格式，包括csv，parquet，路径，字典，dataframe，以及符合要求dataloader，。
+
+```python
+# 批量预测
+preds = model.predict(valid_df, batch_size=512)
+```
+
+- 保存预测：`model.predict(..., save_path="outputs/preds", save_format="csv")`。
+- 评估接口：`model.evaluate(valid_df, metrics=['auc', 'gauc'], user_id_column='user_id')`。
+
+
+现在你已完成从数据预处理到训练、评估、保存与加载的全流程，可以替换为自己的数据和模型配置，快速构建可上线的推荐系统。

nextrec-0.2.4/nextrec/__version__.py

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

{nextrec-0.2.2 → nextrec-0.2.4}/nextrec/basic/features.py

@@ -83,7 +83,7 @@ class DenseFeature(BaseFeature):
         self.embedding_dim = embedding_dim
 
 
-class FeatureConfig:
+class FeatureSpecMixin:
     """
     Mixin that normalizes dense/sparse/sequence feature lists and target/id columns.
     """
@@ -116,3 +116,4 @@ class FeatureConfig:
         if isinstance(value, str):
             return [value]
         return list(value)
+

{nextrec-0.2.2 → nextrec-0.2.4}/nextrec/basic/model.py

@@ -19,7 +19,7 @@ from typing import Union, Literal
 from torch.utils.data import DataLoader, TensorDataset
 
 from nextrec.basic.callback import EarlyStopper
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature, FeatureConfig
+from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature, FeatureSpecMixin
 from nextrec.basic.metrics import configure_metrics, evaluate_metrics
 
 from nextrec.loss import get_loss_fn, get_loss_kwargs
@@ -30,7 +30,7 @@ from nextrec.utils import get_optimizer, get_scheduler
 from nextrec.basic.session import resolve_save_path, create_session
 
 
-class BaseModel(FeatureConfig, nn.Module):
+class BaseModel(FeatureSpecMixin, nn.Module):
     @property
     def model_name(self) -> str:
         raise NotImplementedError

{nextrec-0.2.2 → nextrec-0.2.4}/nextrec/data/__init__.py

@@ -18,9 +18,7 @@ from nextrec.data.data_utils import (
     read_table,
     load_dataframes,
 )
-from nextrec.basic.features import FeatureConfig
-
-# For backward compatibility, keep utils accessible
+from nextrec.basic.features import FeatureSpecMixin
 from nextrec.data import data_utils
 
 __all__ = [
@@ -33,6 +31,6 @@ __all__ = [
     'iter_file_chunks',
     'read_table',
     'load_dataframes',
-    'FeatureConfig',
+    'FeatureSpecMixin',
     'data_utils',
 ]

{nextrec-0.2.2 → nextrec-0.2.4}/nextrec/data/dataloader.py

@@ -17,7 +17,7 @@ from typing import Iterator, Literal, Union, Optional
 
 from torch.utils.data import DataLoader, TensorDataset, IterableDataset
 from nextrec.data.preprocessor import DataProcessor
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature, FeatureConfig
+from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature, FeatureSpecMixin
 
 from nextrec.basic.loggers import colorize
 from nextrec.data import (
@@ -28,7 +28,7 @@ from nextrec.data import (
 )
 
 
-class FileDataset(FeatureConfig, IterableDataset):
+class FileDataset(FeatureSpecMixin, IterableDataset):
     """
     Iterable dataset that streams CSV/Parquet files in chunks and yields tensor tuples.
 
@@ -164,7 +164,7 @@ class FileDataset(FeatureConfig, IterableDataset):
         )
 
 
-class RecDataLoader(FeatureConfig):
+class RecDataLoader(FeatureSpecMixin):
     """
     Convenience wrapper for building PyTorch ``DataLoader`` objects for recommendation models.
 

{nextrec-0.2.2 → nextrec-0.2.4}/nextrec/data/preprocessor.py

@@ -31,9 +31,9 @@ from nextrec.data.data_utils import (
     default_output_dir,
 )
 from nextrec.basic.session import create_session, resolve_save_path
-from nextrec.basic.features import FeatureConfig
+from nextrec.basic.features import FeatureSpecMixin
 
-class DataProcessor(FeatureConfig):
+class DataProcessor(FeatureSpecMixin):
     """DataProcessor for data preprocessing including numeric, sparse, sequence features and target processing.
     
     Examples:

{nextrec-0.2.2 → nextrec-0.2.4}/nextrec/models/ranking/autoint.py

@@ -1,12 +1,57 @@
 """
 Date: create on 09/11/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Checkpoint: edit on 24/11/2025
+Author: Yang Zhou,zyaztec@gmail.com
 Reference:
-    [1] Song W, Shi C, Xiao Z, et al. Autoint: Automatic feature interaction learning via 
-        self-attentive neural networks[C]//Proceedings of the 28th ACM international conference 
-        on information and knowledge management. 2019: 1161-1170.
-        (https://arxiv.org/abs/1810.11921)
+[1] Song W, Shi C, Xiao Z, et al. Autoint: Automatic feature interaction learning via 
+self-attentive neural networks[C]//Proceedings of the 28th ACM international conference 
+on information and knowledge management. 2019: 1161-1170.
+(https://arxiv.org/abs/1810.11921)
+
+AutoInt is a CTR prediction model that leverages multi-head self-attention
+to automatically learn high-order feature interactions in an explicit and
+interpretable way. Instead of relying on manual feature engineering or
+implicit MLP-based transformations, AutoInt models feature dependencies
+by attending over all embedded fields and capturing their contextual
+relationships.
+
+In each Interacting Layer:
+  (1) Each field embedding is projected into multiple attention heads
+  (2) Scaled dot-product attention computes feature-to-feature interactions
+  (3) Outputs are aggregated and passed through residual connections
+  (4) Layer Normalization ensures stable optimization
+
+By stacking multiple Interacting Layers, AutoInt progressively discovers
+higher-order feature interactions, while maintaining transparency since
+attention weights explicitly show which features interact.
+
+Key Advantages:
+- Explicit modeling of high-order feature interactions
+- Multi-head attention enhances representation diversity
+- Residual structure facilitates deep interaction learning
+- Attention weights provide interpretability of feature relations
+- Eliminates heavy manual feature engineering
+
+AutoInt 是一个 CTR 预估模型，通过多头自注意力机制显式学习高阶特征交互，
+并具有良好的可解释性。不同于依赖人工特征工程或 MLP 隐式建模的方法，
+AutoInt 通过对所有特征 embedding 进行注意力计算，捕捉特征之间的上下文依赖关系。
+
+在每个 Interacting Layer（交互层）中：
+  (1) 每个特征 embedding 通过投影分成多个注意力头
+  (2) 使用缩放点积注意力计算特征间交互权重
+  (3) 将多头输出进行聚合，并使用残差连接
+  (4) Layer Normalization 确保训练稳定性
+
+通过堆叠多个交互层，AutoInt 能逐步学习更高阶的特征交互；
+同时由于注意力权重可视化，模型具有明确的可解释能力，
+能展示哪些特征之间的关系最重要。
+
+主要优点：
+- 显式建模高阶特征交互
+- 多头机制增强表示能力
+- 残差结构支持深层交互学习
+- 注意力权重天然具备可解释性
+- 减少繁重的人工特征工程工作
 """
 
 import torch
@@ -80,7 +125,6 @@ class AutoInt(BaseModel):
         
         # Project embeddings to attention embedding dimension
         num_fields = len(self.interaction_features)
-        total_embedding_dim = sum([f.embedding_dim for f in self.interaction_features])
         
         # If embeddings have different dimensions, project them to att_embedding_dim
         self.need_projection = not all(f.embedding_dim == att_embedding_dim for f in self.interaction_features)