nextrec 0.4.20__py3-none-any.whl → 0.4.21__py3-none-any.whl

nextrec/basic/session.py

@@ -12,7 +12,7 @@ from pathlib import Path
 
 __all__ = [
     "Session",
-    "resolve_save_path",
+    "get_save_path",
     "create_session",
 ]
 
@@ -89,7 +89,7 @@ def create_session(experiment_id: str | Path | None = None) -> Session:
     return Session(experiment_id=exp_id, root=root, log_basename=log_basename)
 
 
-def resolve_save_path(
+def get_save_path(
     path: str | os.PathLike | Path | None,
     default_dir: str | Path,
     default_name: str,

nextrec/basic/summary.py

@@ -0,0 +1,323 @@
+"""
+Summary utilities for BaseModel.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Literal
+
+import numpy as np
+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
+
+
+class SummarySet:
+    def build_data_summary(
+        self, data: Any, data_loader: DataLoader | None, sample_key: str
+    ):
+        dataset = data_loader.dataset if data_loader else None
+
+        train_size = get_data_length(dataset)
+        if train_size is None:
+            train_size = get_data_length(data)
+
+        labels = extract_label_arrays(dataset, self.target_columns)
+        if labels is None:
+            labels = extract_label_arrays(data, self.target_columns)
+
+        summary = {}
+        if train_size is not None:
+            summary[sample_key] = int(train_size)
+
+        if labels:
+            task_types = list(self.task) if isinstance(self.task, list) else [self.task]
+            if len(task_types) != len(self.target_columns):
+                task_types = [task_types[0]] * len(self.target_columns)
+
+            label_distributions = {}
+            for target_name, task_type in zip(self.target_columns, task_types):
+                values = labels.get(target_name)
+                if values is None:
+                    continue
+                values = np.asarray(values).reshape(-1)
+                if values.size == 0:
+                    continue
+                if task_type == "regression":
+                    values = values.astype(float)
+                    stats = {
+                        "mean": np.nanmean(values),
+                        "std": np.nanstd(values),
+                        "min": np.nanmin(values),
+                        "p25": np.nanpercentile(values, 25),
+                        "p50": np.nanpercentile(values, 50),
+                        "p75": np.nanpercentile(values, 75),
+                        "max": np.nanmax(values),
+                    }
+                    stat_text = ", ".join(
+                        f"{key}={value:.6g}" for key, value in stats.items()
+                    )
+                    label_distributions[target_name] = {
+                        "task": task_type,
+                        "lines": [("stats", stat_text)],
+                    }
+                else:
+                    uniques, counts = np.unique(values, return_counts=True)
+                    total = counts.sum()
+                    if total == 0:
+                        continue
+                    label_parts = []
+                    for label_value, count in zip(uniques, counts):
+                        if isinstance(label_value, (int, np.integer)):
+                            label_str = f"{int(label_value)}"
+                        elif isinstance(
+                            label_value, (float, np.floating)
+                        ) and np.isclose(label_value, int(label_value)):
+                            label_str = f"{int(label_value)}"
+                        else:
+                            label_str = f"{label_value}"
+                        ratio = count / total
+                        label_parts.append((label_str, f"{count} ({ratio:.2%})"))
+                    label_distributions[target_name] = {
+                        "task": task_type,
+                        "lines": label_parts,
+                    }
+
+            if label_distributions:
+                summary["label_distributions"] = label_distributions
+
+        return summary or None
+
+    def build_train_data_summary(
+        self, train_data: Any, train_loader: DataLoader | None
+    ):
+        return self.build_data_summary(
+            data=train_data,
+            data_loader=train_loader,
+            sample_key="train_samples",
+        )
+
+    def build_valid_data_summary(
+        self, valid_data: Any, valid_loader: DataLoader | None
+    ):
+        return self.build_data_summary(
+            data=valid_data,
+            data_loader=valid_loader,
+            sample_key="valid_samples",
+        )
+
+    def summary(
+        self,
+        sections: list[Literal["feature", "model", "train", "data"]] | None = None,
+    ):
+        logger = logging.getLogger()
+        allowed_sections = {
+            "feature": "Feature Configuration",
+            "model": "Model Parameters",
+            "train": "Training Configuration",
+            "data": "Data Summary",
+        }
+        if sections is None:
+            selected_sections = set(allowed_sections.values())
+        else:
+            selected_sections = set()
+            invalid_sections = []
+            for section in sections:
+                key = str(section).strip().lower()
+                if key in allowed_sections:
+                    selected_sections.add(allowed_sections[key])
+                else:
+                    invalid_sections.append(section)
+            if invalid_sections:
+                raise ValueError(
+                    "[BaseModel-summary Error] Unknown summary section(s): "
+                    f"{invalid_sections}. Allowed: {list(allowed_sections.keys())}"
+                )
+
+        logger.info("")
+        logger.info(
+            colorize(
+                f"Model Summary: {self.model_name.upper()}",
+                color="bright_blue",
+                bold=True,
+            )
+        )
+        logger.info("")
+
+        if "Feature Configuration" in selected_sections:
+            logger.info("")
+            logger.info(colorize("Feature Configuration", color="cyan", bold=True))
+            logger.info(colorize("-" * 80, color="cyan"))
+
+            if self.dense_features:
+                logger.info(f"Dense Features ({len(self.dense_features)}):")
+                for i, feat in enumerate(self.dense_features, 1):
+                    embed_dim = (
+                        feat.embedding_dim if hasattr(feat, "embedding_dim") else 1
+                    )
+                    logger.info(f"  {i}. {feat.name:20s}")
+
+            if self.sparse_features:
+                logger.info(f"\nSparse Features ({len(self.sparse_features)}):")
+
+                max_name_len = max(len(feat.name) for feat in self.sparse_features)
+                max_embed_name_len = max(
+                    len(feat.embedding_name) for feat in self.sparse_features
+                )
+                name_width = max(max_name_len, 10) + 2
+                embed_name_width = max(max_embed_name_len, 15) + 2
+
+                logger.info(
+                    f"  {'#':<4} {'Name':<{name_width}} {'Vocab Size':>12} {'Embed Name':>{embed_name_width}} {'Embed Dim':>10}"
+                )
+                logger.info(
+                    f"  {'-'*4} {'-'*name_width} {'-'*12} {'-'*embed_name_width} {'-'*10}"
+                )
+                for i, feat in enumerate(self.sparse_features, 1):
+                    vocab_size = (
+                        feat.vocab_size if hasattr(feat, "vocab_size") else "N/A"
+                    )
+                    embed_dim = (
+                        feat.embedding_dim if hasattr(feat, "embedding_dim") else "N/A"
+                    )
+                    logger.info(
+                        f"  {i:<4} {feat.name:<{name_width}} {str(vocab_size):>12} {feat.embedding_name:>{embed_name_width}} {str(embed_dim):>10}"
+                    )
+
+            if self.sequence_features:
+                logger.info(f"\nSequence Features ({len(self.sequence_features)}):")
+
+                max_name_len = max(len(feat.name) for feat in self.sequence_features)
+                max_embed_name_len = max(
+                    len(feat.embedding_name) for feat in self.sequence_features
+                )
+                name_width = max(max_name_len, 10) + 2
+                embed_name_width = max(max_embed_name_len, 15) + 2
+
+                logger.info(
+                    f"  {'#':<4} {'Name':<{name_width}} {'Vocab Size':>12} {'Embed Name':>{embed_name_width}} {'Embed Dim':>10} {'Max Len':>10}"
+                )
+                logger.info(
+                    f"  {'-'*4} {'-'*name_width} {'-'*12} {'-'*embed_name_width} {'-'*10} {'-'*10}"
+                )
+                for i, feat in enumerate(self.sequence_features, 1):
+                    vocab_size = (
+                        feat.vocab_size if hasattr(feat, "vocab_size") else "N/A"
+                    )
+                    embed_dim = (
+                        feat.embedding_dim if hasattr(feat, "embedding_dim") else "N/A"
+                    )
+                    max_len = feat.max_len if hasattr(feat, "max_len") else "N/A"
+                    logger.info(
+                        f"  {i:<4} {feat.name:<{name_width}} {str(vocab_size):>12} {feat.embedding_name:>{embed_name_width}} {str(embed_dim):>10} {str(max_len):>10}"
+                    )
+
+        if "Model Parameters" in selected_sections:
+            logger.info("")
+            logger.info(colorize("Model Parameters", color="cyan", bold=True))
+            logger.info(colorize("-" * 80, color="cyan"))
+
+            # Model Architecture
+            logger.info("Model Architecture:")
+            logger.info(str(self))
+            logger.info("")
+
+            total_params = sum(p.numel() for p in self.parameters())
+            trainable_params = sum(
+                p.numel() for p in self.parameters() if p.requires_grad
+            )
+            non_trainable_params = total_params - trainable_params
+
+            logger.info(f"Total Parameters:        {total_params:,}")
+            logger.info(f"Trainable Parameters:    {trainable_params:,}")
+            logger.info(f"Non-trainable Parameters: {non_trainable_params:,}")
+
+            logger.info("Layer-wise Parameters:")
+            for name, module in self.named_children():
+                layer_params = sum(p.numel() for p in module.parameters())
+                if layer_params > 0:
+                    logger.info(f"  {name:30s}: {layer_params:,}")
+
+        if "Training Configuration" in selected_sections:
+            logger.info("")
+            logger.info(colorize("Training Configuration", color="cyan", bold=True))
+            logger.info(colorize("-" * 80, color="cyan"))
+
+            logger.info(f"Task Type:               {self.task}")
+            logger.info(f"Number of Tasks:         {self.nums_task}")
+            logger.info(f"Metrics:                 {self.metrics}")
+            logger.info(f"Target Columns:          {self.target_columns}")
+            logger.info(f"Device:                  {self.device}")
+
+            if hasattr(self, "optimizer_name"):
+                logger.info(f"Optimizer:               {self.optimizer_name}")
+                if self.optimizer_params:
+                    for key, value in self.optimizer_params.items():
+                        logger.info(f"  {key:25s}: {value}")
+
+            if hasattr(self, "scheduler_name") and self.scheduler_name:
+                logger.info(f"Scheduler:               {self.scheduler_name}")
+                if self.scheduler_params:
+                    for key, value in self.scheduler_params.items():
+                        logger.info(f"  {key:25s}: {value}")
+
+            if hasattr(self, "loss_config"):
+                logger.info(f"Loss Function:           {self.loss_config}")
+            if hasattr(self, "loss_weights"):
+                logger.info(f"Loss Weights:            {self.loss_weights}")
+            if hasattr(self, "grad_norm"):
+                logger.info(f"GradNorm Enabled:        {self.grad_norm is not None}")
+                if self.grad_norm is not None:
+                    grad_lr = self.grad_norm.optimizer.param_groups[0].get("lr")
+                    logger.info(f"  GradNorm alpha:        {self.grad_norm.alpha}")
+                    logger.info(f"  GradNorm lr:           {grad_lr}")
+
+            logger.info("Regularization:")
+            logger.info(f"  Embedding L1:          {self.embedding_l1_reg}")
+            logger.info(f"  Embedding L2:          {self.embedding_l2_reg}")
+            logger.info(f"  Dense L1:              {self.dense_l1_reg}")
+            logger.info(f"  Dense L2:              {self.dense_l2_reg}")
+
+            logger.info("Other Settings:")
+            logger.info(f"  Early Stop Patience:   {self.early_stop_patience}")
+            logger.info(f"  Max Gradient Norm:     {self.max_gradient_norm}")
+            logger.info(f"  Max Metrics Samples:   {self.metrics_sample_limit}")
+            logger.info(f"  Session ID:            {self.session_id}")
+            logger.info(f"  Features Config Path:  {self.features_config_path}")
+            logger.info(f"  Latest Checkpoint:     {self.checkpoint_path}")
+
+        if "Data Summary" in selected_sections and (
+            self.train_data_summary or self.valid_data_summary
+        ):
+            logger.info("")
+            logger.info(colorize("Data Summary", color="cyan", bold=True))
+            logger.info(colorize("-" * 80, color="cyan"))
+            if self.train_data_summary:
+                train_samples = self.train_data_summary.get("train_samples")
+                if train_samples is not None:
+                    logger.info(format_kv("Train Samples", f"{train_samples:,}"))
+
+                label_distributions = self.train_data_summary.get("label_distributions")
+                if isinstance(label_distributions, dict):
+                    for target_name, details in label_distributions.items():
+                        lines = details.get("lines", [])
+                        logger.info(f"{target_name}:")
+                        for label, value in lines:
+                            logger.info(format_kv(label, value))
+
+            if self.valid_data_summary:
+                if self.train_data_summary:
+                    logger.info("")
+                valid_samples = self.valid_data_summary.get("valid_samples")
+                if valid_samples is not None:
+                    logger.info(format_kv("Valid Samples", f"{valid_samples:,}"))
+
+                label_distributions = self.valid_data_summary.get("label_distributions")
+                if isinstance(label_distributions, dict):
+                    for target_name, details in label_distributions.items():
+                        lines = details.get("lines", [])
+                        logger.info(f"{target_name}:")
+                        for label, value in lines:
+                            logger.info(format_kv(label, value))

nextrec/cli.py

@@ -48,7 +48,7 @@ from nextrec.utils.data import (
     read_yaml,
     resolve_file_paths,
 )
-from nextrec.utils.feature import normalize_to_list
+from nextrec.utils.feature import to_list
 
 logger = logging.getLogger(__name__)
 
@@ -111,7 +111,7 @@ def train_model(train_config_path: str) -> None:
 
     # train data
     data_path = resolve_path(data_cfg["path"], config_dir)
-    target = normalize_to_list(data_cfg["target"])
+    target = to_list(data_cfg["target"])
     file_paths: List[str] = []
     file_type: str | None = None
     streaming_train_files: List[str] | None = None
@@ -507,7 +507,7 @@ def predict_model(predict_config_path: str) -> None:
         or model_cfg.get("params", {}).get("target")
     )
     if target_override:
-        target_cols = normalize_to_list(target_override)
+        target_cols = to_list(target_override)
 
     model = build_model_instance(
         model_cfg=model_cfg,

nextrec/data/data_processing.py

@@ -2,7 +2,7 @@
 Data processing utilities for NextRec
 
 Date: create on 03/12/2025
-Checkpoint: edit on 19/12/2025
+Checkpoint: edit on 25/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
@@ -28,6 +28,50 @@ def get_column_data(data: dict | pd.DataFrame, name: str):
         raise KeyError(f"Unsupported data type for extracting column {name}")
 
 
+def to_numpy(values: Any) -> np.ndarray:
+    if isinstance(values, torch.Tensor):
+        return values.detach().cpu().numpy()
+    return np.asarray(values)
+
+
+def get_data_length(data: Any) -> int | None:
+    if data is None:
+        return None
+    if isinstance(data, pd.DataFrame):
+        return len(data)
+    if isinstance(data, dict):
+        if not data:
+            return None
+        sample_key = next(iter(data))
+        return len(data[sample_key])
+    try:
+        return len(data)
+    except TypeError:
+        return None
+
+
+def extract_label_arrays(
+    data: Any, target_columns: list[str]
+) -> dict[str, np.ndarray] | None:
+    if not target_columns or data is None:
+        return None
+
+    if isinstance(data, (dict, pd.DataFrame)):
+        label_source = data
+    elif hasattr(data, "labels"):
+        label_source = data.labels
+    else:
+        return None
+
+    labels: dict[str, np.ndarray] = {}
+    for name in target_columns:
+        column = get_column_data(label_source, name)
+        if column is None:
+            continue
+        labels[name] = to_numpy(column)
+    return labels or None
+
+
 def split_dict_random(data_dict, test_size=0.2, random_state=None):
 
     lengths = [len(v) for v in data_dict.values()]

nextrec/data/dataloader.py

@@ -424,10 +424,10 @@ def normalize_sequence_column(column, feature: SequenceFeature) -> np.ndarray:
                 sequences.append(np.asarray(seq, dtype=np.int64))
             else:
                 sequences.append(np.asarray([seq], dtype=np.int64))
-        max_len = getattr(feature, "max_len", 0)
+        max_len = feature.max_len if feature.max_len is not None else 0
         if max_len <= 0:
             max_len = max((len(seq) for seq in sequences), default=1)
-        pad_value = getattr(feature, "padding_idx", 0)
+        pad_value = feature.padding_idx if feature.padding_idx is not None else 0
         padded = [
             (
                 seq[:max_len]

nextrec/data/preprocessor.py

@@ -30,7 +30,7 @@ from sklearn.preprocessing import (
 from nextrec.__version__ import __version__
 from nextrec.basic.features import FeatureSet
 from nextrec.basic.loggers import colorize
-from nextrec.basic.session import resolve_save_path
+from nextrec.basic.session import get_save_path
 from nextrec.data.data_processing import hash_md5_mod
 from nextrec.utils.console import progress
 from nextrec.utils.data import (
@@ -957,7 +957,7 @@ class DataProcessor(FeatureSet):
         save_path = Path(save_path)
         if not self.is_fitted:
             logger.warning("Saving unfitted DataProcessor")
-        target_path = resolve_save_path(
+        target_path = get_save_path(
             path=save_path,
             default_dir=Path(os.getcwd()),
             default_name="fitted_processor",

nextrec/loss/loss_utils.py

@@ -6,8 +6,6 @@ Checkpoint: edit on 19/12/2025
 Author: Yang Zhou, zyaztec@gmail.com
 """
 
-from typing import Literal
-
 import torch.nn as nn
 
 from nextrec.loss.listwise import (
@@ -19,6 +17,7 @@ from nextrec.loss.listwise import (
 )
 from nextrec.loss.pairwise import BPRLoss, HingeLoss, TripletLoss
 from nextrec.loss.pointwise import ClassBalancedFocalLoss, FocalLoss, WeightedBCELoss
+from nextrec.utils.types import LossName
 
 VALID_TASK_TYPES = [
     "binary",
@@ -26,33 +25,6 @@ VALID_TASK_TYPES = [
     "regression",
 ]
 
-# Define all supported loss types
-LossType = Literal[
-    # Pointwise losses
-    "bce",
-    "binary_crossentropy",
-    "weighted_bce",
-    "focal",
-    "focal_loss",
-    "cb_focal",
-    "class_balanced_focal",
-    "crossentropy",
-    "ce",
-    "mse",
-    "mae",
-    # Pairwise ranking losses
-    "bpr",
-    "hinge",
-    "triplet",
-    # Listwise ranking losses
-    "sampled_softmax",
-    "softmax",
-    "infonce",
-    "listnet",
-    "listmle",
-    "approx_ndcg",
-]
-
 
 def build_cb_focal(kw):
     if "class_counts" not in kw:
@@ -60,7 +32,10 @@ def build_cb_focal(kw):
     return ClassBalancedFocalLoss(**kw)
 
 
-def get_loss_fn(loss=None, **kw) -> nn.Module:
+def get_loss_fn(
+    loss: LossName | None | nn.Module = None,
+    **kw,
+) -> nn.Module:
     """
     Get loss function by name or return the provided loss module.
 

nextrec/models/multi_task/esmm.py

@@ -83,11 +83,10 @@ class ESMM(BaseModel):
         optimizer_params: dict | None = None,
         loss: str | nn.Module | list[str | nn.Module] | None = "bce",
         loss_params: dict | list[dict] | None = None,
-        device: str = "cpu",
-        embedding_l1_reg=1e-6,
-        dense_l1_reg=1e-5,
-        embedding_l2_reg=1e-5,
-        dense_l2_reg=1e-4,
+        embedding_l1_reg=0.0,
+        dense_l1_reg=0.0,
+        embedding_l2_reg=0.0,
+        dense_l2_reg=0.0,
         **kwargs,
     ):
 
@@ -121,7 +120,6 @@ class ESMM(BaseModel):
             sequence_features=sequence_features,
             target=target,
             task=resolved_task,  # Both CTR and CTCVR are binary classification
-            device=device,
             embedding_l1_reg=embedding_l1_reg,
             dense_l1_reg=dense_l1_reg,
             embedding_l2_reg=embedding_l2_reg,

nextrec/models/multi_task/mmoe.py

@@ -86,11 +86,10 @@ class MMOE(BaseModel):
         optimizer_params: dict | None = None,
         loss: str | nn.Module | list[str | nn.Module] | None = "bce",
         loss_params: dict | list[dict] | None = None,
-        device: str = "cpu",
-        embedding_l1_reg=1e-6,
-        dense_l1_reg=1e-5,
-        embedding_l2_reg=1e-5,
-        dense_l2_reg=1e-4,
+        embedding_l1_reg=0.0,
+        dense_l1_reg=0.0,
+        embedding_l2_reg=0.0,
+        dense_l2_reg=0.0,
         **kwargs,
     ):
 
@@ -127,7 +126,6 @@ class MMOE(BaseModel):
             sequence_features=sequence_features,
             target=target,
             task=resolved_task,
-            device=device,
             embedding_l1_reg=embedding_l1_reg,
             dense_l1_reg=dense_l1_reg,
             embedding_l2_reg=embedding_l2_reg,

nextrec/models/multi_task/ple.py

@@ -195,7 +195,7 @@ class PLE(BaseModel):
 
     @property
     def default_task(self):
-        nums_task = getattr(self, "nums_task", None)
+        nums_task = self.nums_task if hasattr(self, "nums_task") else None
         if nums_task is not None and nums_task > 0:
             return ["binary"] * nums_task
         return ["binary"]
@@ -217,11 +217,10 @@ class PLE(BaseModel):
         optimizer_params: dict | None = None,
         loss: str | nn.Module | list[str | nn.Module] | None = "bce",
         loss_params: dict | list[dict] | None = None,
-        device: str = "cpu",
-        embedding_l1_reg=1e-6,
-        dense_l1_reg=1e-5,
-        embedding_l2_reg=1e-5,
-        dense_l2_reg=1e-4,
+        embedding_l1_reg=0.0,
+        dense_l1_reg=0.0,
+        embedding_l2_reg=0.0,
+        dense_l2_reg=0.0,
         **kwargs,
     ):
 
@@ -245,7 +244,6 @@ class PLE(BaseModel):
             sequence_features=sequence_features,
             target=target,
             task=resolved_task,
-            device=device,
             embedding_l1_reg=embedding_l1_reg,
             dense_l1_reg=dense_l1_reg,
             embedding_l2_reg=embedding_l2_reg,
@@ -273,7 +271,7 @@ class PLE(BaseModel):
         # Calculate input dimension
         input_dim = self.embedding.input_dim
         # emb_dim_total = sum([f.embedding_dim for f in self.all_features if not isinstance(f, DenseFeature)])
-        # dense_input_dim = sum([getattr(f, "embedding_dim", 1) or 1 for f in dense_features])
+        # dense_input_dim = sum([(f.embedding_dim or 1) for f in dense_features])
         # input_dim = emb_dim_total + dense_input_dim
 
         # Get expert output dimension

nextrec/models/multi_task/poso.py

@@ -290,7 +290,7 @@ class POSO(BaseModel):
 
     @property
     def default_task(self) -> list[str]:
-        nums_task = getattr(self, "nums_task", None)
+        nums_task = self.nums_task if hasattr(self, "nums_task") else None
         if nums_task is not None and nums_task > 0:
             return ["binary"] * nums_task
         return ["binary"]
@@ -327,11 +327,10 @@ class POSO(BaseModel):
         optimizer_params: dict | None = None,
         loss: str | nn.Module | list[str | nn.Module] | None = "bce",
         loss_params: dict | list[dict] | None = None,
-        device: str = "cpu",
-        embedding_l1_reg: float = 1e-6,
-        dense_l1_reg: float = 1e-5,
-        embedding_l2_reg: float = 1e-5,
-        dense_l2_reg: float = 1e-4,
+        embedding_l1_reg=0.0,
+        dense_l1_reg=0.0,
+        embedding_l2_reg=0.0,
+        dense_l2_reg=0.0,
         **kwargs,
     ):
         self.nums_task = len(target)
@@ -360,7 +359,6 @@ class POSO(BaseModel):
             sequence_features=sequence_features,
             target=target,
             task=resolved_task,
-            device=device,
             embedding_l1_reg=embedding_l1_reg,
             dense_l1_reg=dense_l1_reg,
             embedding_l2_reg=embedding_l2_reg,