nextrec 0.2.7__tar.gz → 0.3.1__tar.gz

nextrec-0.3.1/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: nextrec
+Version: 0.3.1
+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
+Project-URL: Documentation, https://github.com/zerolovesea/NextRec/blob/main/README.md
+Project-URL: Issues, https://github.com/zerolovesea/NextRec/issues
+Author-email: zerolovesea <zyaztec@gmail.com>
+License-File: LICENSE
+Keywords: ctr,deep-learning,match,pytorch,ranking,recommendation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy<2.0,>=1.21; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: numpy<3.0,>=1.26; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: numpy>=1.23.0; sys_platform == 'win32'
+Requires-Dist: numpy>=1.24.0; sys_platform == 'darwin'
+Requires-Dist: pandas<2.0,>=1.5; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: pandas<2.3.0,>=2.1.0; sys_platform == 'win32'
+Requires-Dist: pandas>=2.0.0; sys_platform == 'darwin'
+Requires-Dist: pandas>=2.1.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: pyarrow<13.0.0,>=10.0.0; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: pyarrow<15.0.0,>=12.0.0; sys_platform == 'win32'
+Requires-Dist: pyarrow>=12.0.0; sys_platform == 'darwin'
+Requires-Dist: pyarrow>=16.0.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: scikit-learn<2.0,>=1.2; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'darwin'
+Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: scikit-learn>=1.3.0; sys_platform == 'win32'
+Requires-Dist: scipy<1.12,>=1.8; sys_platform == 'linux' and python_version < '3.12'
+Requires-Dist: scipy>=1.10.0; sys_platform == 'darwin'
+Requires-Dist: scipy>=1.10.0; sys_platform == 'win32'
+Requires-Dist: scipy>=1.11.0; sys_platform == 'linux' and python_version >= '3.12'
+Requires-Dist: torch>=2.0.0
+Requires-Dist: torchvision>=0.15.0
+Requires-Dist: tqdm>=4.65.0
+Provides-Extra: dev
+Requires-Dist: jupyter>=1.0.0; extra == 'dev'
+Requires-Dist: matplotlib>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-html>=3.2.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.3.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: seaborn>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+<img align="center" src="asserts/logo.png" width="40%">
+<p>
+
+<div align="center">
+
+![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.3.1-orange.svg)
+
+English | [中文文档](README_zh.md)
+
+**A Unified, Efficient, and Scalable Recommendation System Framework**
+
+</div>
+
+## 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.
+
+### 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.
+
+> 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.
+
+---
+
+## Installation
+
+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:
+
+- [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
+
+To dive deeper, 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.3.1]: 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:
+
+| 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.
+
+After training, detailed logs are available under `nextrec_logs/din_tutorial`.
+
+```python
+import pandas as pd
+
+from nextrec.models.ranking.din import DIN
+from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+
+df = pd.read_csv('dataset/ranking_task.csv')
+
+for col in df.columns and 'sequence' in col: # csv loads lists as text; convert them back to objects
+    df[col] = df[col].apply(lambda x: eval(x) if isinstance(x, str) else x)
+
+# Define feature columns
+dense_features = [DenseFeature(name=f'dense_{i}', input_dim=1) for i in range(8)]
+
+sparse_features = [SparseFeature(name='user_id', embedding_name='user_emb', vocab_size=int(df['user_id'].max() + 1), embedding_dim=32), SparseFeature(name='item_id', embedding_name='item_emb', vocab_size=int(df['item_id'].max() + 1), embedding_dim=32),]
+
+sparse_features.extend([SparseFeature(name=f'sparse_{i}', embedding_name=f'sparse_{i}_emb', vocab_size=int(df[f'sparse_{i}'].max() + 1), embedding_dim=32) for i in range(10)])
+
+sequence_features = [
+    SequenceFeature(name='sequence_0', vocab_size=int(df['sequence_0'].apply(lambda x: max(x)).max() + 1), embedding_dim=32, padding_idx=0, embedding_name='item_emb'),
+    SequenceFeature(name='sequence_1', vocab_size=int(df['sequence_1'].apply(lambda x: max(x)).max() + 1), embedding_dim=16, padding_idx=0, embedding_name='sparse_0_emb'),]
+
+mlp_params = {
+    "dims": [256, 128, 64],
+    "activation": "relu",
+    "dropout": 0.3,
+}
+
+model = DIN(
+    dense_features=dense_features,
+    sparse_features=sparse_features,
+    sequence_features=sequence_features,
+    mlp_params=mlp_params,
+    attention_hidden_units=[80, 40],
+    attention_activation='sigmoid',
+    attention_use_softmax=True,
+    target=['label'],                                     # target variable
+    device='mps',                                         
+    embedding_l1_reg=1e-6,
+    embedding_l2_reg=1e-5,
+    dense_l1_reg=1e-5,
+    dense_l2_reg=1e-4,
+    session_id="din_tutorial",                            # experiment id for logs
+)
+
+# Compile model with optimizer and loss
+model.compile(
+            optimizer = "adam",
+            optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
+            loss = "focal",
+            loss_params={"gamma": 2.0, "alpha": 0.25},
+        )
+
+model.fit(
+    train_data=df,
+    metrics=['auc', 'gauc', 'logloss'],  # metrics to track
+    epochs=3,
+    batch_size=512,
+    shuffle=True,
+    user_id_column='user_id'             # used for GAUC
+)
+
+# Evaluate after training
+metrics = model.evaluate(
+    df,
+    metrics=['auc', 'gauc', 'logloss'],
+    batch_size=512,
+    user_id_column='user_id'
+)
+```
+
+---
+
+## Supported Models
+
+### Ranking Models
+
+| Model | Paper | Year | Status |
+|-------|-------|------|--------|
+| [FM](nextrec/models/ranking/fm.py) | Factorization Machines | ICDM 2010 | Supported |
+| [AFM](nextrec/models/ranking/afm.py) | Attentional Factorization Machines: Learning the Weight of Feature Interactions via Attention Networks | IJCAI 2017 | Supported |
+| [DeepFM](nextrec/models/ranking/deepfm.py) | DeepFM: A Factorization-Machine based Neural Network for CTR Prediction | IJCAI 2017 | Supported |
+| [Wide&Deep](nextrec/models/ranking/widedeep.py) | Wide & Deep Learning for Recommender Systems | DLRS 2016 | Supported |
+| [xDeepFM](nextrec/models/ranking/xdeepfm.py) | xDeepFM: Combining Explicit and Implicit Feature Interactions | KDD 2018 | Supported |
+| [FiBiNET](nextrec/models/ranking/fibinet.py) | FiBiNET: Combining Feature Importance and Bilinear Feature Interaction for CTR Prediction | RecSys 2019 | Supported |
+| [PNN](nextrec/models/ranking/pnn.py) | Product-based Neural Networks for User Response Prediction | ICDM 2016 | Supported |
+| [AutoInt](nextrec/models/ranking/autoint.py) | AutoInt: Automatic Feature Interaction Learning | CIKM 2019 | Supported |
+| [DCN](nextrec/models/ranking/dcn.py) | Deep & Cross Network for Ad Click Predictions | ADKDD 2017 | Supported |
+| [DCN v2](nextrec/models/ranking/dcn_v2.py) | DCN V2: Improved Deep & Cross Network and Practical Lessons for Web-scale Learning to Rank Systems | KDD 2021 | In Progress |
+| [DIN](nextrec/models/ranking/din.py) | Deep Interest Network for CTR Prediction | KDD 2018 | Supported |
+| [DIEN](nextrec/models/ranking/dien.py) | Deep Interest Evolution Network | AAAI 2019 | Supported |
+| [MaskNet](nextrec/models/ranking/masknet.py) | MaskNet: Feature-wise Gating Blocks for High-dimensional Sparse Recommendation Data | 2020 | Supported |
+
+### Retrieval Models
+
+| Model | Paper | Year | Status |
+|-------|-------|------|--------|
+| [DSSM](nextrec/models/match/dssm.py) | Learning Deep Structured Semantic Models | CIKM 2013 | Supported |
+| [DSSM v2](nextrec/models/match/dssm_v2.py) | DSSM with pairwise BPR-style optimization | - | Supported |
+| [YouTube DNN](nextrec/models/match/youtube_dnn.py) | Deep Neural Networks for YouTube Recommendations | RecSys 2016 | Supported |
+| [MIND](nextrec/models/match/mind.py) | Multi-Interest Network with Dynamic Routing | CIKM 2019 | Supported |
+| [SDM](nextrec/models/match/sdm.py) | Sequential Deep Matching Model | - | Supported |
+
+### Multi-task Models
+
+| Model | Paper | Year | Status |
+|-------|-------|------|--------|
+| [MMOE](nextrec/models/multi_task/mmoe.py) | Modeling Task Relationships in Multi-task Learning | KDD 2018 | Supported |
+| [PLE](nextrec/models/multi_task/ple.py) | Progressive Layered Extraction | RecSys 2020 | Supported |
+| [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 |
+
+---
+
+## Contributing
+
+We welcome contributions of any form!
+
+### How to Contribute
+
+1. Fork the repository  
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)  
+3. Commit your changes (`git commit -m 'Add AmazingFeature'`)  
+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.
+
+### Code Style
+
+- Follow PEP8  
+- Provide unit tests for new functionality  
+- Update documentation accordingly  
+
+### Reporting Issues
+
+When submitting issues on GitHub, please include:
+
+- Description of the problem  
+- Reproduction steps  
+- Expected behavior  
+- Actual behavior  
+- Environment info (Python version, PyTorch version, etc.)  
+
+---
+
+## License
+
+This project is licensed under the [Apache 2.0 License](./LICENSE).
+
+---
+
+## Contact
+
+- **GitHub Issues**: [Submit an issue](https://github.com/zerolovesea/NextRec/issues)  
+- **Email**: zyaztec@gmail.com  
+
+---
+
+## Acknowledgements
+
+NextRec is inspired by the following great open-source projects:
+
+- [torch-rechub](https://github.com/datawhalechina/torch-rechub) — Flexible, easy-to-extend recommendation framework  
+- [FuxiCTR](https://github.com/reczoo/FuxiCTR) — Configurable, tunable, and reproducible CTR library  
+- [RecBole](https://github.com/RUCAIBox/RecBole) — Unified, comprehensive, and efficient recommendation library  
+
+Special thanks to all open-source contributors!
+
+---
+
+<div align="center">
+
+**[Back to Top](#nextrec)**
+
+</div>

nextrec-0.3.1/README.md

@@ -0,0 +1,250 @@
+<p align="center">
+<img align="center" src="asserts/logo.png" width="40%">
+<p>
+
+<div align="center">
+
+![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.3.1-orange.svg)
+
+English | [中文文档](README_zh.md)
+
+**A Unified, Efficient, and Scalable Recommendation System Framework**
+
+</div>
+
+## 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.
+
+### 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.
+
+> 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.
+
+---
+
+## Installation
+
+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:
+
+- [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
+
+To dive deeper, 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.3.1]: 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:
+
+| 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.
+
+After training, detailed logs are available under `nextrec_logs/din_tutorial`.
+
+```python
+import pandas as pd
+
+from nextrec.models.ranking.din import DIN
+from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+
+df = pd.read_csv('dataset/ranking_task.csv')
+
+for col in df.columns and 'sequence' in col: # csv loads lists as text; convert them back to objects
+    df[col] = df[col].apply(lambda x: eval(x) if isinstance(x, str) else x)
+
+# Define feature columns
+dense_features = [DenseFeature(name=f'dense_{i}', input_dim=1) for i in range(8)]
+
+sparse_features = [SparseFeature(name='user_id', embedding_name='user_emb', vocab_size=int(df['user_id'].max() + 1), embedding_dim=32), SparseFeature(name='item_id', embedding_name='item_emb', vocab_size=int(df['item_id'].max() + 1), embedding_dim=32),]
+
+sparse_features.extend([SparseFeature(name=f'sparse_{i}', embedding_name=f'sparse_{i}_emb', vocab_size=int(df[f'sparse_{i}'].max() + 1), embedding_dim=32) for i in range(10)])
+
+sequence_features = [
+    SequenceFeature(name='sequence_0', vocab_size=int(df['sequence_0'].apply(lambda x: max(x)).max() + 1), embedding_dim=32, padding_idx=0, embedding_name='item_emb'),
+    SequenceFeature(name='sequence_1', vocab_size=int(df['sequence_1'].apply(lambda x: max(x)).max() + 1), embedding_dim=16, padding_idx=0, embedding_name='sparse_0_emb'),]
+
+mlp_params = {
+    "dims": [256, 128, 64],
+    "activation": "relu",
+    "dropout": 0.3,
+}
+
+model = DIN(
+    dense_features=dense_features,
+    sparse_features=sparse_features,
+    sequence_features=sequence_features,
+    mlp_params=mlp_params,
+    attention_hidden_units=[80, 40],
+    attention_activation='sigmoid',
+    attention_use_softmax=True,
+    target=['label'],                                     # target variable
+    device='mps',                                         
+    embedding_l1_reg=1e-6,
+    embedding_l2_reg=1e-5,
+    dense_l1_reg=1e-5,
+    dense_l2_reg=1e-4,
+    session_id="din_tutorial",                            # experiment id for logs
+)
+
+# Compile model with optimizer and loss
+model.compile(
+            optimizer = "adam",
+            optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
+            loss = "focal",
+            loss_params={"gamma": 2.0, "alpha": 0.25},
+        )
+
+model.fit(
+    train_data=df,
+    metrics=['auc', 'gauc', 'logloss'],  # metrics to track
+    epochs=3,
+    batch_size=512,
+    shuffle=True,
+    user_id_column='user_id'             # used for GAUC
+)
+
+# Evaluate after training
+metrics = model.evaluate(
+    df,
+    metrics=['auc', 'gauc', 'logloss'],
+    batch_size=512,
+    user_id_column='user_id'
+)
+```
+
+---
+
+## Supported Models
+
+### Ranking Models
+
+| Model | Paper | Year | Status |
+|-------|-------|------|--------|
+| [FM](nextrec/models/ranking/fm.py) | Factorization Machines | ICDM 2010 | Supported |
+| [AFM](nextrec/models/ranking/afm.py) | Attentional Factorization Machines: Learning the Weight of Feature Interactions via Attention Networks | IJCAI 2017 | Supported |
+| [DeepFM](nextrec/models/ranking/deepfm.py) | DeepFM: A Factorization-Machine based Neural Network for CTR Prediction | IJCAI 2017 | Supported |
+| [Wide&Deep](nextrec/models/ranking/widedeep.py) | Wide & Deep Learning for Recommender Systems | DLRS 2016 | Supported |
+| [xDeepFM](nextrec/models/ranking/xdeepfm.py) | xDeepFM: Combining Explicit and Implicit Feature Interactions | KDD 2018 | Supported |
+| [FiBiNET](nextrec/models/ranking/fibinet.py) | FiBiNET: Combining Feature Importance and Bilinear Feature Interaction for CTR Prediction | RecSys 2019 | Supported |
+| [PNN](nextrec/models/ranking/pnn.py) | Product-based Neural Networks for User Response Prediction | ICDM 2016 | Supported |
+| [AutoInt](nextrec/models/ranking/autoint.py) | AutoInt: Automatic Feature Interaction Learning | CIKM 2019 | Supported |
+| [DCN](nextrec/models/ranking/dcn.py) | Deep & Cross Network for Ad Click Predictions | ADKDD 2017 | Supported |
+| [DCN v2](nextrec/models/ranking/dcn_v2.py) | DCN V2: Improved Deep & Cross Network and Practical Lessons for Web-scale Learning to Rank Systems | KDD 2021 | In Progress |
+| [DIN](nextrec/models/ranking/din.py) | Deep Interest Network for CTR Prediction | KDD 2018 | Supported |
+| [DIEN](nextrec/models/ranking/dien.py) | Deep Interest Evolution Network | AAAI 2019 | Supported |
+| [MaskNet](nextrec/models/ranking/masknet.py) | MaskNet: Feature-wise Gating Blocks for High-dimensional Sparse Recommendation Data | 2020 | Supported |
+
+### Retrieval Models
+
+| Model | Paper | Year | Status |
+|-------|-------|------|--------|
+| [DSSM](nextrec/models/match/dssm.py) | Learning Deep Structured Semantic Models | CIKM 2013 | Supported |
+| [DSSM v2](nextrec/models/match/dssm_v2.py) | DSSM with pairwise BPR-style optimization | - | Supported |
+| [YouTube DNN](nextrec/models/match/youtube_dnn.py) | Deep Neural Networks for YouTube Recommendations | RecSys 2016 | Supported |
+| [MIND](nextrec/models/match/mind.py) | Multi-Interest Network with Dynamic Routing | CIKM 2019 | Supported |
+| [SDM](nextrec/models/match/sdm.py) | Sequential Deep Matching Model | - | Supported |
+
+### Multi-task Models
+
+| Model | Paper | Year | Status |
+|-------|-------|------|--------|
+| [MMOE](nextrec/models/multi_task/mmoe.py) | Modeling Task Relationships in Multi-task Learning | KDD 2018 | Supported |
+| [PLE](nextrec/models/multi_task/ple.py) | Progressive Layered Extraction | RecSys 2020 | Supported |
+| [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 |
+
+---
+
+## Contributing
+
+We welcome contributions of any form!
+
+### How to Contribute
+
+1. Fork the repository  
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)  
+3. Commit your changes (`git commit -m 'Add AmazingFeature'`)  
+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.
+
+### Code Style
+
+- Follow PEP8  
+- Provide unit tests for new functionality  
+- Update documentation accordingly  
+
+### Reporting Issues
+
+When submitting issues on GitHub, please include:
+
+- Description of the problem  
+- Reproduction steps  
+- Expected behavior  
+- Actual behavior  
+- Environment info (Python version, PyTorch version, etc.)  
+
+---
+
+## License
+
+This project is licensed under the [Apache 2.0 License](./LICENSE).
+
+---
+
+## Contact
+
+- **GitHub Issues**: [Submit an issue](https://github.com/zerolovesea/NextRec/issues)  
+- **Email**: zyaztec@gmail.com  
+
+---
+
+## Acknowledgements
+
+NextRec is inspired by the following great open-source projects:
+
+- [torch-rechub](https://github.com/datawhalechina/torch-rechub) — Flexible, easy-to-extend recommendation framework  
+- [FuxiCTR](https://github.com/reczoo/FuxiCTR) — Configurable, tunable, and reproducible CTR library  
+- [RecBole](https://github.com/RUCAIBox/RecBole) — Unified, comprehensive, and efficient recommendation library  
+
+Special thanks to all open-source contributors!
+
+---
+
+<div align="center">
+
+**[Back to Top](#nextrec)**
+
+</div>