nextrec 0.3.4__py3-none-any.whl → 0.3.6__py3-none-any.whl

nextrec/utils/file.py

@@ -0,0 +1,70 @@
+"""
+File I/O utilities for NextRec
+
+Date: create on 03/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
+"""
+
+import pandas as pd
+import pyarrow.parquet as pq
+from pathlib import Path
+from typing import Generator
+
+
+def resolve_file_paths(path: str) -> tuple[list[str], str]:
+    """
+    Resolve file or directory path into a sorted list of files and file type.
+    
+    Args: path: Path to a file or directory
+    Returns: tuple: (list of file paths, file type)
+    """
+    path_obj = Path(path)
+
+    if path_obj.is_file():
+        file_type = path_obj.suffix.lower().lstrip(".")
+        assert file_type in ["csv", "parquet"], f"Unsupported file extension: {file_type}"
+        return [str(path_obj)], file_type
+
+    if path_obj.is_dir():
+        collected_files = [p for p in path_obj.iterdir() if p.is_file()]
+        csv_files = [str(p) for p in collected_files if p.suffix.lower() == ".csv"]
+        parquet_files = [str(p) for p in collected_files if p.suffix.lower() == ".parquet"]
+
+        if csv_files and parquet_files:
+            raise ValueError("Directory contains both CSV and Parquet files. Please keep a single format.")
+        file_paths = csv_files if csv_files else parquet_files
+        if not file_paths:
+            raise ValueError(f"No CSV or Parquet files found in directory: {path}")
+        file_paths.sort()
+        file_type = "csv" if csv_files else "parquet"
+        return file_paths, file_type
+
+    raise ValueError(f"Invalid path: {path}")
+
+
+def read_table(file_path: str, file_type: str) -> pd.DataFrame:
+    if file_type == "csv":
+        return pd.read_csv(file_path)
+    return pd.read_parquet(file_path)
+
+def load_dataframes(file_paths: list[str], file_type: str) -> list[pd.DataFrame]:
+    return [read_table(fp, file_type) for fp in file_paths]
+
+def iter_file_chunks(
+    file_path: str,
+    file_type: str,
+    chunk_size: int
+) -> Generator[pd.DataFrame, None, None]:
+    if file_type == "csv":
+        yield from pd.read_csv(file_path, chunksize=chunk_size)
+        return
+    parquet_file = pq.ParquetFile(file_path)
+    for batch in parquet_file.iter_batches(batch_size=chunk_size):
+        yield batch.to_pandas()
+
+
+def default_output_dir(path: str) -> Path:
+    path_obj = Path(path)
+    if path_obj.is_file():
+        return path_obj.parent / f"{path_obj.stem}_preprocessed"
+    return path_obj.with_name(f"{path_obj.name}_preprocessed")

nextrec/utils/initializer.py

@@ -9,14 +9,6 @@ import torch.nn as nn
 
 
 def get_initializer(init_type='normal', activation='linear', param=None):
-    """
-    Get parameter initialization function.
-        
-    Examples:
-        >>> init_fn = get_initializer('xavier_uniform', 'relu')
-        >>> init_fn(tensor)
-        >>> init_fn = get_initializer('normal', param={'mean': 0.0, 'std': 0.01})
-    """
     param = param or {}
 
     try:

nextrec/utils/model.py

@@ -0,0 +1,22 @@
+"""
+Model-related utilities for NextRec
+
+Date: create on 03/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
+"""
+
+from collections import OrderedDict
+
+
+def merge_features(primary, secondary) -> list:
+    merged: OrderedDict[str, object] = OrderedDict()
+    for feat in list(primary or []) + list(secondary or []):
+        merged.setdefault(feat.name, feat)
+    return list(merged.values())
+
+
+def get_mlp_output_dim(params: dict, fallback: int) -> int:
+    dims = params.get("dims")
+    if dims:
+        return dims[-1]
+    return fallback

nextrec/utils/optimizer.py

@@ -8,25 +8,16 @@ Author: Yang Zhou, zyaztec@gmail.com
 import torch
 from typing import Iterable
 
-
 def get_optimizer(
     optimizer: str | torch.optim.Optimizer = "adam",
     params: Iterable[torch.nn.Parameter] | None = None,
     **optimizer_params
 ):
-    """
-    Get optimizer function based on optimizer name or instance.
-        
-    Examples:
-        >>> optimizer = get_optimizer("adam", model.parameters(), lr=1e-3)
-        >>> optimizer = get_optimizer("sgd", model.parameters(), lr=0.01, momentum=0.9)
-    """
     if params is None:
         raise ValueError("params cannot be None. Please provide model parameters.")
 
     if 'lr' not in optimizer_params:
         optimizer_params['lr'] = 1e-3
-    
     if isinstance(optimizer, str):
         opt_name = optimizer.lower()
         if opt_name == "adam":
@@ -42,27 +33,17 @@ def get_optimizer(
         else:
             raise NotImplementedError(f"Unsupported optimizer: {optimizer}")
         optimizer_fn = opt_class(params=params, **optimizer_params)
-
     elif isinstance(optimizer, torch.optim.Optimizer):
         optimizer_fn = optimizer
     else:
         raise TypeError(f"Invalid optimizer type: {type(optimizer)}")
-    
     return optimizer_fn
 
-
 def get_scheduler(
     scheduler: str | torch.optim.lr_scheduler._LRScheduler | torch.optim.lr_scheduler.LRScheduler | type[torch.optim.lr_scheduler._LRScheduler] | type[torch.optim.lr_scheduler.LRScheduler] | None,
     optimizer,
     **scheduler_params
 ):
-    """
-    Get learning rate scheduler function.
-    
-    Examples:
-        >>> scheduler = get_scheduler("step", optimizer, step_size=10, gamma=0.1)
-        >>> scheduler = get_scheduler("cosine", optimizer, T_max=100)
-    """
     if isinstance(scheduler, str):
         if scheduler == "step":
             scheduler_fn = torch.optim.lr_scheduler.StepLR(optimizer, **scheduler_params)

nextrec/utils/tensor.py

@@ -0,0 +1,61 @@
+"""
+Tensor manipulation utilities for NextRec
+
+Date: create on 03/12/2025
+Author: Yang Zhou, zyaztec@gmail.com
+"""
+
+import torch
+import numpy as np
+from typing import Any
+
+
+def to_tensor(
+    value: Any,
+    dtype: torch.dtype,
+    device: torch.device | str | None = None
+) -> torch.Tensor:
+    if value is None:
+        raise ValueError("[Tensor Utils Error] Cannot convert None to tensor.")
+    tensor = value if isinstance(value, torch.Tensor) else torch.as_tensor(value)
+    if tensor.dtype != dtype:
+        tensor = tensor.to(dtype=dtype)
+    
+    if device is not None:
+        target_device = device if isinstance(device, torch.device) else torch.device(device)
+        if tensor.device != target_device:
+            tensor = tensor.to(target_device)
+    return tensor
+
+def stack_tensors(tensors: list[torch.Tensor], dim: int = 0) -> torch.Tensor:
+    if not tensors:
+        raise ValueError("[Tensor Utils Error] Cannot stack empty list of tensors.")
+    return torch.stack(tensors, dim=dim)
+
+def concat_tensors(tensors: list[torch.Tensor], dim: int = 0) -> torch.Tensor:
+    if not tensors:
+        raise ValueError("[Tensor Utils Error] Cannot concatenate empty list of tensors.")
+    return torch.cat(tensors, dim=dim)
+
+def pad_sequence_tensors(
+    tensors: list[torch.Tensor],
+    max_len: int | None = None,
+    padding_value: float = 0.0,
+    padding_side: str = 'right'
+) -> torch.Tensor:
+    if not tensors:
+        raise ValueError("[Tensor Utils Error] Cannot pad empty list of tensors.")
+    if max_len is None:
+        max_len = max(t.size(0) for t in tensors)
+    batch_size = len(tensors)
+    padded = torch.full((batch_size, max_len), padding_value, dtype=tensors[0].dtype, device=tensors[0].device)
+    
+    for i, tensor in enumerate(tensors):
+        length = min(tensor.size(0), max_len)
+        if padding_side == 'right':
+            padded[i, :length] = tensor[:length]
+        elif padding_side == 'left':
+            padded[i, -length:] = tensor[:length]
+        else:
+            raise ValueError(f"[Tensor Utils Error] padding_side must be 'right' or 'left', got {padding_side}")
+    return padded

{nextrec-0.3.4.dist-info → nextrec-0.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextrec
-Version: 0.3.4
+Version: 0.3.6
 Summary: A comprehensive recommendation library with match, ranking, and multi-task learning models
 Project-URL: Homepage, https://github.com/zerolovesea/NextRec
 Project-URL: Repository, https://github.com/zerolovesea/NextRec
@@ -63,7 +63,7 @@ Description-Content-Type: text/markdown
 ![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-1.10+-ee4c2c.svg)
 ![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)
-![Version](https://img.shields.io/badge/Version-0.3.4-orange.svg)
+![Version](https://img.shields.io/badge/Version-0.3.6-orange.svg)
 
 English | [中文文档](README_zh.md)
 
@@ -110,7 +110,7 @@ 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.4]: 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.
+> Current version [0.3.6]: 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
 

{nextrec-0.3.4.dist-info → nextrec-0.3.6.dist-info}/RECORD

@@ -1,38 +1,41 @@
-nextrec/__init__.py,sha256=CvocnY2uBp0cjNkhrT6ogw0q2bN9s1GNp754FLO-7lo,1117
-nextrec/__version__.py,sha256=oYLGMpySamd16KLiaBTfRyrAS7_oyp-TOEHmzmeumwg,22
+nextrec/__init__.py,sha256=nFRpUAjezaxyMJDTgy4g9PtpDTq28sMHleSrlg3QkVA,235
+nextrec/__version__.py,sha256=W_9dCm49nLvZulVAvvsafxLJjVBSKDBHz9K7szFZllo,22
 nextrec/basic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextrec/basic/activation.py,sha256=1qs9pq4hT3BUxIiYdYs57axMCm4-JyOBFQ6x7xkHTwM,2849
 nextrec/basic/callback.py,sha256=wwh0I2kKYyywCB-sG9eQXShlpXFJIo75qApJmnI5p6c,1036
-nextrec/basic/features.py,sha256=-RRRbEPU-SFI-GtppflW6O0bKShUsV-Hg_lTGpo3AIE,4262
+nextrec/basic/features.py,sha256=DFwYjG13GYHOujS_CMKa7Qrux9faF7MQNoaoRDF_Eks,4263
 nextrec/basic/layers.py,sha256=zzEseKYVnMVs1Tg5EGrFimugId15jI6HumgzjFyRqgw,23127
-nextrec/basic/loggers.py,sha256=hh9tRMmaCTaJ_sfRHIlbcqd6BcpK63vpZ_21TFCiKLI,6148
+nextrec/basic/loggers.py,sha256=YLmeXsnzm9M2qxtmBOLMGZRg9wOAUQYl8UNpbWFzs8s,6147
 nextrec/basic/metrics.py,sha256=8-hMZJXU5L4F8GnToxMZey5dlBrtFyRtTuI_zoQCtIo,21579
-nextrec/basic/model.py,sha256=afnvicyxXMgWdvhrIUaoNnZ7S-QYRYr7fTY5bdM1u_s,68829
-nextrec/basic/session.py,sha256=oaATn-nzbJ9A6SGbMut9xLV_NSh9_1KmVDeNauS06Ps,4767
-nextrec/data/__init__.py,sha256=6WgXZafzzXcv5kuxKNi67O8BJZVl_P_HM2IZCDIIhPA,1052
-nextrec/data/data_utils.py,sha256=aOyja3Yu7O2c8eIeL3P8MyUlUR5EerOUT9UeF4ATq8o,10574
-nextrec/data/dataloader.py,sha256=2MLe69y0E1cTZyzMNgyLUCxa6lllGd1ntvwpXzxdX10,14199
-nextrec/data/preprocessor.py,sha256=lhigpjvkEqsjTRfbBBOjgGOxoPyOifwq2LoswgyIVqc,40488
+nextrec/basic/model.py,sha256=LybJlpzK2S6zw8ez_HrR_tFc15Gzcy0t4GMD12i9sA0,69310
+nextrec/basic/session.py,sha256=kYpUE6KzN2_Jli4l-YuoeMBaghGi3kzDnGRP3E08FbQ,4430
+nextrec/data/__init__.py,sha256=OJsuESaE0NZorAkAwydWJtsWsbNBzKfmQCrDJTzA5a0,1227
+nextrec/data/batch_utils.py,sha256=6G-E85H-PqYJ20EYVLnC3MqC8xYrXzZ1XYe82MhRPck,2816
+nextrec/data/data_processing.py,sha256=N3Uk4NsUCyLeoMDV1zeLmH-dP02I-cRWDo-vvQgLqjo,5006
+nextrec/data/data_utils.py,sha256=-3xLPW3csOiGNmj0kzzpOkCxZyu09RNBgfPkwX7nDAc,1172
+nextrec/data/dataloader.py,sha256=JOudvhnMcNBYFlSKbMKi43Ndn2c1kGoyD8G9gTlW0Ps,14699
+nextrec/data/preprocessor.py,sha256=_A3eEc1MpUGDEpno1TToA-dyJ_k707Mr3GilTi_9j5I,40419
 nextrec/loss/__init__.py,sha256=mO5t417BneZ8Ysa51GyjDaffjWyjzFgPXIQrrggasaQ,827
 nextrec/loss/listwise.py,sha256=gxDbO1td5IeS28jKzdE35o1KAYBRdCYoMzyZzfNLhc0,5689
 nextrec/loss/loss_utils.py,sha256=uZ4m9ChLr-UgIc5Yxm1LjwXDDepApQ-Fas8njweZ9qg,2641
 nextrec/loss/pairwise.py,sha256=MN_3Pk6Nj8KCkmUqGT5cmyx1_nQa3TIx_kxXT_HB58c,3396
 nextrec/loss/pointwise.py,sha256=shgdRJwTV7vAnVxHSffOJU4TPQeKyrwudQ8y-R10nYM,7144
-nextrec/models/generative/__init__.py,sha256=vo8-DloD74cKc1moSH-4GYG99w8Yi8YPGPxh8XDJPoc,50
+nextrec/models/generative/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextrec/models/generative/hstu.py,sha256=CLu8Ee_L4fdnb7_DKocz0g7SZlPI1g_6o8HtyzRkI9s,16368
 nextrec/models/generative/tiger.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-nextrec/models/match/__init__.py,sha256=ASZB5abqKPhDbk8NErNNNa0DHuWpsVxvUtyEn5XMx6Y,215
+nextrec/models/match/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextrec/models/match/dssm.py,sha256=1cj1Fb3yFTKxA1kRaomh_Q8y66vBZc85ywAIXWosyL0,8230
 nextrec/models/match/dssm_v2.py,sha256=BY6m9651NlzMLjRa9oeez0dab_3NjNFVgYQ7Q39Ug74,7187
 nextrec/models/match/mind.py,sha256=0cggXKE1-XsTZ6IX4UH81a5KycdGF-_ix2Nw-eKTLpg,14886
 nextrec/models/match/sdm.py,sha256=wVRj6PWLF6hMIqqlJDUuKqxJAvCGPe-HfD3EVgd16Sw,10918
 nextrec/models/match/youtube_dnn.py,sha256=Wa5JWrlIpMuBoyXpnBrdnm1nQ8ZO_XcR517zfINh-xA,7544
+nextrec/models/multi_task/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextrec/models/multi_task/esmm.py,sha256=Ho5UN2H9H9-ZYML6eqpBYTVdTO4Ja9AoYP5SSgsgQaw,6442
 nextrec/models/multi_task/mmoe.py,sha256=zfBAUoQijHCuat962dZI0MCAy8C6PZqZ-zOd16JznF8,7803
 nextrec/models/multi_task/ple.py,sha256=zNBea0sfJska36RVH1N9O92m7rPmbaWYqoPbnGoy1RE,11949
-nextrec/models/multi_task/poso.py,sha256=_yLiCkD3NhOZEOWx-jP4MJxSEdNCu3mqeo_XRt8CWts,16652
+nextrec/models/multi_task/poso.py,sha256=_Pq-cl7HB1uQVO8HXreNeVpQso250ouxBNTsdTjyFos,16651
 nextrec/models/multi_task/share_bottom.py,sha256=kvrkXQSTDPEwwmBvXw3xryBm3gT8Uq4_Hb3TenwRj9w,5920
-nextrec/models/ranking/__init__.py,sha256=AY806x-2BtltQdlR4wu23-keL9YUe3An92OJshS4t9Y,472
+nextrec/models/ranking/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextrec/models/ranking/afm.py,sha256=uFSUIv9d6NQkCiM2epmSdMy4kxjFuCRVbrZOv3nebGE,4539
 nextrec/models/ranking/autoint.py,sha256=MN6Dv6EMK0ODsCEeX4iXBSDoxK9a_DxIdEduGAUIVEQ,7771
 nextrec/models/ranking/dcn.py,sha256=sy0v_kMQ1OfVCFuRD8FDrroQHm-RnTx4lVacfXfs2N8,4896
@@ -46,12 +49,16 @@ nextrec/models/ranking/masknet.py,sha256=9K6XKcr8f8PcVhLfgFd8l4tq78lcclAQAXZKlVE
 nextrec/models/ranking/pnn.py,sha256=eEyBnALuzaNx27iGJ0ZqNcf0u7dKN8SiO03lkcv1hiE,4956
 nextrec/models/ranking/widedeep.py,sha256=AJPkoThUTSBGPNBjD-aiWsMH2hSiSnGLjIPy_2neNhc,5034
 nextrec/models/ranking/xdeepfm.py,sha256=wn6YnX78EyBzil7IRBcqyDqsnysERVJ5-lWGuRMCpxE,5681
-nextrec/utils/__init__.py,sha256=ciw6B9SXffjSb4cwco-WXpKSE7M9D6ILpLZ2oftwj6A,457
-nextrec/utils/common.py,sha256=NYXnBVtUCtm8epT2ZxJHn_m1SIBBI_PEjZ5VpL465ls,2009
+nextrec/utils/__init__.py,sha256=lAVpHsGe_WgGf7R-K1wr0DeVLvskG0Bj1L12N6kEPwM,1810
+nextrec/utils/device.py,sha256=1QtmlpxRSHiuYfmCOQCOIk-s6bmjIpoJtzfXOcvginI,1044
 nextrec/utils/embedding.py,sha256=yxYSdFx0cJITh3Gf-K4SdhwRtKGcI0jOsyBgZ0NLa_c,465
-nextrec/utils/initializer.py,sha256=ffYOs5QuIns_d_-5e40iNtg6s1ftgREJN-ueq_NbDQE,1647
-nextrec/utils/optimizer.py,sha256=EUjAGFPeyou_Cv-_2HRvjzut8y_qpAQudc8L2T0k8zw,2706
-nextrec-0.3.4.dist-info/METADATA,sha256=X5fo5gymQdPXLgM1N03E58uFSQyuQOmdbUp8vXvKl0g,16319
-nextrec-0.3.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-nextrec-0.3.4.dist-info/licenses/LICENSE,sha256=2fQfVKeafywkni7MYHyClC6RGGC3laLTXCNBx-ubtp0,1064
-nextrec-0.3.4.dist-info/RECORD,,
+nextrec/utils/feature.py,sha256=s0eMEuvbOsotjll7eSYjb0b-1cXnvVy1mSI1Syg_7n4,299
+nextrec/utils/file.py,sha256=wxKvd1_U9ugFDP7EzLNG6-3PBInA0QhxoHzBWKfe_B8,2384
+nextrec/utils/initializer.py,sha256=BkP6-vJdsc0A-8ya-AVEs7W24dPXyxIilNnckwXgPEc,1391
+nextrec/utils/model.py,sha256=FB7QbatO0uEvghBEfByJtRS0waaBEB1UI0YzfA_2k04,535
+nextrec/utils/optimizer.py,sha256=cVkDrEkxwig17UAEhL8p9v3iVNiXI8B067Yf_6LqUp8,2198
+nextrec/utils/tensor.py,sha256=_RibR6BMPizhzRLVdnJqwUgzA0zpzkZuKfTrdSjbL60,2136
+nextrec-0.3.6.dist-info/METADATA,sha256=yq_cvYiBZzWJcZaIlBornYCW_Hc8v7p01mhRuN15jOk,16319
+nextrec-0.3.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+nextrec-0.3.6.dist-info/licenses/LICENSE,sha256=2fQfVKeafywkni7MYHyClC6RGGC3laLTXCNBx-ubtp0,1064
+nextrec-0.3.6.dist-info/RECORD,,

nextrec/utils/common.py

@@ -1,60 +0,0 @@
-import torch
-import platform
-from collections import OrderedDict
-
-
-def resolve_device() -> str:
-    """Select a usable device with graceful fallback."""
-    if torch.cuda.is_available():
-        return "cuda"
-    if torch.backends.mps.is_available():
-        mac_ver = platform.mac_ver()[0]
-        try:
-            major, minor = (int(x) for x in mac_ver.split(".")[:2])
-        except Exception:
-            major, minor = 0, 0
-        if major >= 14:
-            return "mps"
-    return "cpu"
-
-
-def normalize_to_list(value: str | list[str] | None) -> list[str]:
-    if value is None:
-        return []
-    if isinstance(value, str):
-        return [value]
-    return list(value)
-    
-
-def merge_features(primary, secondary) -> list:
-    """
-    Merge two feature lists while preserving order and deduplicating by feature name.
-    Later duplicates are skipped.
-    """
-    merged: OrderedDict[str, object] = OrderedDict()
-    for feat in list(primary or []) + list(secondary or []):
-        merged.setdefault(feat.name, feat)
-    return list(merged.values())
-
-def get_mlp_output_dim(params: dict, fallback: int) -> int:
-    """
-    Get the output dimension of an MLP-like config.
-    If dims are provided, use the last dim; otherwise fall back to input dim.
-    """
-    dims = params.get("dims")
-    if dims:
-        return dims[-1]
-    return fallback
-
-def to_tensor(value, dtype: torch.dtype, device: torch.device | str | None = None) -> torch.Tensor:
-    """Convert any value to a tensor with the desired dtype/device."""
-    if value is None:
-        raise ValueError("[Tensor Utils Error] Cannot convert None to tensor.")
-    tensor = value if isinstance(value, torch.Tensor) else torch.as_tensor(value)
-    if tensor.dtype != dtype:
-        tensor = tensor.to(dtype=dtype)
-    if device is not None:
-        target_device = device if isinstance(device, torch.device) else torch.device(device)
-        if tensor.device != target_device:
-            tensor = tensor.to(target_device)
-    return tensor