nextrec 0.4.22__tar.gz → 0.4.23__tar.gz

{nextrec-0.4.22 → nextrec-0.4.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.4.22
+Version: 0.4.23
 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
@@ -69,7 +69,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.22-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.23-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -191,6 +191,8 @@ model = DIN(
     dense_features=dense_features,
     sparse_features=sparse_features,
     sequence_features=sequence_features,
+    behavior_feature_name="sequence_0",
+    candidate_feature_name="item_id",
     mlp_params=mlp_params,
     attention_hidden_units=[80, 40],
     attention_activation='sigmoid',
@@ -204,7 +206,7 @@ model = DIN(
     session_id="din_tutorial",                            # 实验id，用于存放训练日志
 )
 
-# 编译模型，设置优化器和损失函数
+# 编译模型，优化器/损失/学习率调度器统一在 compile 中设置
 model.compile(
             optimizer = "adam",
             optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
@@ -247,11 +249,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.23，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.23，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.22 → nextrec-0.4.23}/README.md

@@ -8,7 +8,7 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.23-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 中文文档 | [English Version](README_en.md)
@@ -130,6 +130,8 @@ model = DIN(
     dense_features=dense_features,
     sparse_features=sparse_features,
     sequence_features=sequence_features,
+    behavior_feature_name="sequence_0",
+    candidate_feature_name="item_id",
     mlp_params=mlp_params,
     attention_hidden_units=[80, 40],
     attention_activation='sigmoid',
@@ -143,7 +145,7 @@ model = DIN(
     session_id="din_tutorial",                            # 实验id，用于存放训练日志
 )
 
-# 编译模型，设置优化器和损失函数
+# 编译模型，优化器/损失/学习率调度器统一在 compile 中设置
 model.compile(
             optimizer = "adam",
             optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
@@ -186,11 +188,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 预测结果固定保存到 `{checkpoint_path}/predictions/{name}.{save_data_format}`。
 
-> 截止当前版本0.4.22，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
+> 截止当前版本0.4.23，NextRec CLI支持单机训练，分布式训练相关功能尚在开发中。
 
 ## 兼容平台
 
-当前最新版本为0.4.22，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
+当前最新版本为0.4.23，所有模型和测试代码均已在以下平台通过验证，如果开发者在使用中遇到兼容问题，请在issue区提出错误报告及系统版本：
 
 | 平台 | 配置 | 
 |------|------|

{nextrec-0.4.22 → nextrec-0.4.23}/README_en.md

@@ -8,7 +8,7 @@
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.4.22-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.4.23-orange.svg)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zerolovesea/NextRec)
 
 English | [中文文档](README.md)
@@ -148,7 +148,7 @@ model = DIN(
     session_id="din_tutorial",                            # experiment id for logs
 )
 
-# Compile model with optimizer and loss
+# Compile model; configure optimizer/loss/scheduler via compile()
 model.compile(
             optimizer = "adam",
             optimizer_params = {"lr": 1e-3, "weight_decay": 1e-5},
@@ -191,11 +191,11 @@ nextrec --mode=predict --predict_config=path/to/predict_config.yaml
 
 Prediction outputs are saved under `{checkpoint_path}/predictions/{name}.{save_data_format}`.
 
-> As of version 0.4.22, NextRec CLI supports single-machine training; distributed training features are currently under development.
+> As of version 0.4.23, NextRec CLI supports single-machine training; distributed training features are currently under development.
 
 ## Platform Compatibility
 
-The current version is 0.4.22. 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.23. 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 | 
 |----------|---------------|

{nextrec-0.4.22 → nextrec-0.4.23}/docs/en/Getting started guide.md

@@ -55,6 +55,7 @@ model = DeepFM(
     session_id="movielens_deepfm",   # manages logs and checkpoints
 )
 
+# Optimizer/loss/scheduler are configured via compile()
 model.compile(
     optimizer="adam",
     optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},

{nextrec-0.4.22 → nextrec-0.4.23}/docs/rtd/conf.py

@@ -11,7 +11,7 @@ sys.path.insert(0, str(PROJECT_ROOT / "nextrec"))
 project = "NextRec"
 copyright = "2025, Yang Zhou"
 author = "Yang Zhou"
-release = "0.4.22"
+release = "0.4.23"
 
 extensions = [
     "myst_parser",

{nextrec-0.4.22 → nextrec-0.4.23}/docs/rtd/index.md

@@ -57,6 +57,7 @@ model = DeepFM(
     session_id="deepfm_demo",
 )
 
+# Configure optimizer/loss/scheduler via compile()
 model.compile(
     optimizer="adam",
     optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},

{nextrec-0.4.22 → nextrec-0.4.23}/docs/zh//345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -55,6 +55,7 @@ model = DeepFM(
     session_id="movielens_deepfm",   # 管理实验日志与检查点
 )
 
+# 优化器/损失/学习率调度器统一在 compile 中设置
 model.compile(
     optimizer="adam",
     optimizer_params={"lr": 1e-3, "weight_decay": 1e-5},

nextrec-0.4.23/nextrec/__version__.py

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

{nextrec-0.4.22 → nextrec-0.4.23}/nextrec/basic/metrics.py

@@ -2,7 +2,7 @@
 Metrics computation and configuration for model evaluation.
 
 Date: create on 27/10/2025
-Checkpoint: edit on 20/12/2025
+Checkpoint: edit on 29/12/2025
 Author: Yang Zhou,zyaztec@gmail.com
 """
 
@@ -39,7 +39,6 @@ REGRESSION_METRICS = {"mse", "mae", "rmse", "r2", "mape", "msle"}
 TASK_DEFAULT_METRICS = {
     "binary": ["auc", "gauc", "ks", "logloss", "accuracy", "precision", "recall", "f1"],
     "regression": ["mse", "mae", "rmse", "r2", "mape"],
-    "multilabel": ["auc", "hamming_loss", "subset_accuracy", "micro_f1", "macro_f1"],
     "matching": ["auc", "gauc", "precision@10", "hitrate@10", "map@10", "cosine"]
     + [f"recall@{k}" for k in (5, 10, 20)]
     + [f"ndcg@{k}" for k in (5, 10, 20)]

{nextrec-0.4.22 → nextrec-0.4.23}/nextrec/basic/model.py

@@ -2,13 +2,14 @@
 Base Model & Base Match Model Class
 
 Date: create on 27/10/2025
-Checkpoint: edit on 28/12/2025
+Checkpoint: edit on 29/12/2025
 Author: Yang Zhou,zyaztec@gmail.com
 """
 
 import getpass
 import logging
 import os
+import sys
 import pickle
 import socket
 from pathlib import Path
@@ -16,6 +17,16 @@ from typing import Any, Literal
 
 import numpy as np
 import pandas as pd
+
+try:
+    import swanlab  # type: ignore
+except ModuleNotFoundError:
+    swanlab = None
+try:
+    import wandb  # type: ignore
+except ModuleNotFoundError:
+    wandb = None
+
 import torch
 import torch.distributed as dist
 import torch.nn as nn
@@ -74,13 +85,19 @@ from nextrec.utils.torch_utils import (
     to_tensor,
 )
 from nextrec.utils.config import safe_value
-from nextrec.utils.model import compute_ranking_loss
+from nextrec.utils.model import (
+    compute_ranking_loss,
+    get_loss_list,
+    resolve_loss_weights,
+    get_training_modes,
+)
 from nextrec.utils.types import (
     LossName,
     OptimizerName,
     SchedulerName,
     TrainingModeName,
     TaskTypeName,
+    MetricsName,
 )
 
 
@@ -90,7 +107,7 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         raise NotImplementedError
 
     @property
-    def default_task(self) -> str | list[str]:
+    def default_task(self) -> TaskTypeName | list[TaskTypeName]:
         raise NotImplementedError
 
     def __init__(
@@ -139,6 +156,9 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             world_size: Number of processes (defaults to env WORLD_SIZE).
             local_rank: Local rank for selecting CUDA device (defaults to env LOCAL_RANK).
             ddp_find_unused_parameters: Default False, set it True only when exist unused parameters in ddp model, in most cases should be False.
+
+        Note:
+            Optimizer, scheduler, and loss are configured via compile().
         """
         super(BaseModel, self).__init__()
 
@@ -171,24 +191,12 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             dense_features, sparse_features, sequence_features, target, id_columns
         )
 
-        self.task = self.default_task if task is None else task
+        self.task = task or self.default_task
         self.nums_task = len(self.task) if isinstance(self.task, list) else 1
-        if isinstance(training_mode, list):
-            training_modes = list(training_mode)
-            if len(training_modes) != self.nums_task:
-                raise ValueError(
-                    "[BaseModel-init Error] training_mode list length must match number of tasks."
-                )
-        else:
-            training_modes = [training_mode] * self.nums_task
-        if any(
-            mode not in {"pointwise", "pairwise", "listwise"} for mode in training_modes
-        ):
-            raise ValueError(
-                "[BaseModel-init Error] training_mode must be one of {'pointwise', 'pairwise', 'listwise'}."
-            )
-        self.training_modes = training_modes
-        self.training_mode = training_modes if self.nums_task > 1 else training_modes[0]
+        self.training_modes = get_training_modes(training_mode, self.nums_task)
+        self.training_mode = (
+            self.training_modes if self.nums_task > 1 else self.training_modes[0]
+        )
 
         self.embedding_l1_reg = embedding_l1_reg
         self.dense_l1_reg = dense_l1_reg
@@ -196,8 +204,9 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         self.dense_l2_reg = dense_l2_reg
         self.regularization_weights = []
         self.embedding_params = []
-        self.loss_weight = None
+
         self.ignore_label = None
+        self.compiled = False
 
         self.max_gradient_norm = 1.0
         self.logger_initialized = False
@@ -431,28 +440,9 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             "pairwise": "bpr",
             "listwise": "listnet",
         }
-        effective_loss = loss
-        if effective_loss is None:
-            loss_list = [default_losses[mode] for mode in self.training_modes]
-        elif isinstance(effective_loss, list):
-            if not effective_loss:
-                loss_list = [default_losses[mode] for mode in self.training_modes]
-            else:
-                if len(effective_loss) != self.nums_task:
-                    raise ValueError(
-                        f"[BaseModel-compile Error] Number of loss functions ({len(effective_loss)}) must match number of tasks ({self.nums_task})."
-                    )
-                loss_list = list(effective_loss)
-        else:
-            loss_list = [effective_loss] * self.nums_task
-
-        for idx, mode in enumerate(self.training_modes):
-            if isinstance(loss_list[idx], str) and loss_list[idx] in {
-                "bce",
-                "binary_crossentropy",
-            }:
-                if mode in {"pairwise", "listwise"}:
-                    loss_list[idx] = default_losses[mode]
+        loss_list = get_loss_list(
+            loss, self.training_modes, self.nums_task, default_losses
+        )
         self.loss_params = loss_params or {}
         optimizer_params = optimizer_params or {}
         self.optimizer_name = (
@@ -516,30 +506,9 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
                 nums_task=self.nums_task, device=self.device, **grad_norm_params
             )
             self.loss_weights = None
-        elif loss_weights is None:
-            self.loss_weights = None
-        elif self.nums_task == 1:
-            if isinstance(loss_weights, (list, tuple)):
-                if len(loss_weights) != 1:
-                    raise ValueError(
-                        "[BaseModel-compile Error] loss_weights list must have exactly one element for single-task setup."
-                    )
-                loss_weights = loss_weights[0]
-            self.loss_weights = [float(loss_weights)]  # type: ignore
         else:
-            if isinstance(loss_weights, (int, float)):
-                weights = [float(loss_weights)] * self.nums_task
-            elif isinstance(loss_weights, (list, tuple)):
-                weights = [float(w) for w in loss_weights]
-                if len(weights) != self.nums_task:
-                    raise ValueError(
-                        f"[BaseModel-compile Error] Number of loss_weights ({len(weights)}) must match number of tasks ({self.nums_task})."
-                    )
-            else:
-                raise TypeError(
-                    f"[BaseModel-compile Error] loss_weights must be int, float, list or tuple, got {type(loss_weights)}"
-                )
-            self.loss_weights = weights
+            self.loss_weights = resolve_loss_weights(loss_weights, self.nums_task)
+        self.compiled = True
 
     def compute_loss(self, y_pred, y_true):
         if y_true is None:
@@ -602,9 +571,6 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         for i, (start, end) in enumerate(slices):  # type: ignore
             y_pred_i = y_pred[:, start:end]
             y_true_i = y_true[:, start:end]
-            total_count = y_true_i.shape[0]
-            # valid_count = None
-
             # mask ignored labels
             if self.ignore_label is not None:
                 valid_mask = y_true_i != self.ignore_label
@@ -613,11 +579,8 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
                 if not torch.any(valid_mask):
                     task_losses.append(y_pred_i.sum() * 0.0)
                     continue
-                # valid_count = valid_mask.sum().to(dtype=y_true_i.dtype)
                 y_pred_i = y_pred_i[valid_mask]
                 y_true_i = y_true_i[valid_mask]
-            # else:
-            # valid_count = y_true_i.new_tensor(float(total_count))
 
             mode = self.training_modes[i]
 
@@ -691,7 +654,7 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         train_data=None,
         valid_data=None,
         metrics: (
-            list[str] | dict[str, list[str]] | None
+            list[MetricsName] | dict[str, list[MetricsName]] | None
         ) = None,  # ['auc', 'logloss'] or {'target1': ['auc', 'logloss'], 'target2': ['mse']}
         epochs: int = 1,
         shuffle: bool = True,
@@ -705,6 +668,8 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         use_tensorboard: bool = True,
         use_wandb: bool = False,
         use_swanlab: bool = False,
+        wandb_api: str | None = None,
+        swanlab_api: str | None = None,
         wandb_kwargs: dict | None = None,
         swanlab_kwargs: dict | None = None,
         auto_ddp_sampler: bool = True,
@@ -734,6 +699,8 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             use_tensorboard: Enable tensorboard logging.
             use_wandb: Enable Weights & Biases logging.
             use_swanlab: Enable SwanLab logging.
+            wandb_api: W&B API key for non-tty login.
+            swanlab_api: SwanLab API key for non-tty login.
             wandb_kwargs: Optional kwargs for wandb.init(...).
             swanlab_kwargs: Optional kwargs for swanlab.init(...).
             auto_ddp_sampler: Attach DistributedSampler automatically when distributed, set False to when data is already sharded per rank.
@@ -751,6 +718,16 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
         )
         self.to(self.device)
 
+        if not self.compiled:
+            self.compile(
+                optimizer="adam",
+                optimizer_params={},
+                scheduler=None,
+                scheduler_params={},
+                loss=None,
+                loss_params={},
+            )
+
         if (
             self.distributed
             and dist.is_available()
@@ -825,6 +802,24 @@ class BaseModel(SummarySet, FeatureSet, nn.Module):
             }
             training_config: dict = safe_value(training_config)  # type: ignore
 
+        if self.is_main_process:
+            is_tty = sys.stdin.isatty() and sys.stdout.isatty()
+            if not is_tty:
+                if use_wandb and wandb_api:
+                    if wandb is None:
+                        logging.warning(
+                            "[BaseModel-fit] wandb not installed, skip wandb login."
+                        )
+                    else:
+                        wandb.login(key=wandb_api)
+                if use_swanlab and swanlab_api:
+                    if swanlab is None:
+                        logging.warning(
+                            "[BaseModel-fit] swanlab not installed, skip swanlab login."
+                        )
+                    else:
+                        swanlab.login(api_key=swanlab_api)
+
         self.training_logger = (
             TrainingLogger(
                 session=self.session,

{nextrec-0.4.22 → nextrec-0.4.23}/nextrec/basic/summary.py

@@ -1,5 +1,9 @@
 """
 Summary utilities for BaseModel.
+
+Date: create on 03/12/2025
+Checkpoint: edit on 29/12/2025
+Author: Yang Zhou,zyaztec@gmail.com
 """
 
 from __future__ import annotations
@@ -12,9 +16,39 @@ from torch.utils.data import DataLoader
 
 from nextrec.basic.loggers import colorize, format_kv
 from nextrec.data.data_processing import extract_label_arrays, get_data_length
+from nextrec.utils.types import TaskTypeName
 
 
 class SummarySet:
+    model_name: str
+    dense_features: list[Any]
+    sparse_features: list[Any]
+    sequence_features: list[Any]
+    task: TaskTypeName | list[TaskTypeName]
+    target_columns: list[str]
+    nums_task: int
+    metrics: Any
+    device: Any
+    optimizer_name: str
+    optimizer_params: dict[str, Any]
+    scheduler_name: str | None
+    scheduler_params: dict[str, Any]
+    loss_config: Any
+    loss_weights: Any
+    grad_norm: Any
+    embedding_l1_reg: float
+    embedding_l2_reg: float
+    dense_l1_reg: float
+    dense_l2_reg: float
+    early_stop_patience: int
+    max_gradient_norm: float | None
+    metrics_sample_limit: int | None
+    session_id: str | None
+    features_config_path: str
+    checkpoint_path: str
+    train_data_summary: dict[str, Any] | None
+    valid_data_summary: dict[str, Any] | None
+
     def build_data_summary(
         self, data: Any, data_loader: DataLoader | None, sample_key: str
     ):
@@ -305,7 +339,7 @@ class SummarySet:
                         lines = details.get("lines", [])
                         logger.info(f"{target_name}:")
                         for label, value in lines:
-                            logger.info(format_kv(label, value))
+                            logger.info(f"  {format_kv(label, value)}")
 
             if self.valid_data_summary:
                 if self.train_data_summary:
@@ -320,4 +354,4 @@ class SummarySet:
                         lines = details.get("lines", [])
                         logger.info(f"{target_name}:")
                         for label, value in lines:
-                            logger.info(format_kv(label, value))
+                            logger.info(f"  {format_kv(label, value)}")