nextrec 0.1.11__py3-none-any.whl → 0.2.1__py3-none-any.whl

nextrec/__version__.py

@@ -1 +1 @@
-__version__ = "0.1.11"
+__version__ = "0.2.1"

nextrec/basic/activation.py

@@ -2,8 +2,7 @@
 Activation function definitions
 
 Date: create on 27/10/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
 
 import torch

nextrec/basic/callback.py

@@ -2,8 +2,7 @@
 EarlyStopper definitions
 
 Date: create on 27/10/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
 
 import copy

nextrec/basic/features.py

@@ -2,12 +2,11 @@
 Feature definitions
 
 Date: create on 27/10/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
-
-from typing import Optional
-from nextrec.utils import get_auto_embedding_dim
+from __future__ import annotations
+from typing import List, Sequence, Optional    
+from nextrec.utils.embedding import get_auto_embedding_dim
 
 class BaseFeature(object):
     def __repr__(self):
@@ -26,9 +25,9 @@ class SequenceFeature(BaseFeature):
         vocab_size: int,
         max_len: int = 20,
         embedding_name: str = '',
-        embedding_dim: Optional[int] = 4,
+        embedding_dim: int | None = 4,
         combiner: str = "mean",
-        padding_idx: Optional[int] = None,
+        padding_idx: int | None = None,
         init_type: str='normal',
         init_params: dict|None = None,
         l1_reg: float = 0.0,
@@ -55,7 +54,7 @@ class SparseFeature(BaseFeature):
                  name: str, 
                  vocab_size: int, 
                  embedding_name: str = '', 
-                 embedding_dim: int = 4, 
+                 embedding_dim: int | None  = 4, 
                  padding_idx: int | None = None,
                  init_type: str='normal',
                  init_params: dict|None = None,
@@ -84,4 +83,36 @@ class DenseFeature(BaseFeature):
         self.embedding_dim = embedding_dim
 
 
+class FeatureConfig:
+    """
+    Mixin that normalizes dense/sparse/sequence feature lists and target/id columns.
+    """
+
+    def _set_feature_config(
+        self,
+        dense_features: Sequence[DenseFeature] | None = None,
+        sparse_features: Sequence[SparseFeature] | None = None,
+        sequence_features: Sequence[SequenceFeature] | None = None,
+    ) -> None:
+        self.dense_features: List[DenseFeature] = list(dense_features) if dense_features else []
+        self.sparse_features: List[SparseFeature] = list(sparse_features) if sparse_features else []
+        self.sequence_features: List[SequenceFeature] = list(sequence_features) if sequence_features else []
+
+        self.all_features = self.dense_features + self.sparse_features + self.sequence_features
+        self.feature_names = [feat.name for feat in self.all_features]
+
+    def _set_target_config(
+        self,
+        target: str | Sequence[str] | None = None,
+        id_columns: str | Sequence[str] | None = None,
+    ) -> None:
+        self.target_columns = self._normalize_to_list(target)
+        self.id_columns = self._normalize_to_list(id_columns)
 
+    @staticmethod
+    def _normalize_to_list(value: str | Sequence[str] | None) -> list[str]:
+        if value is None:
+            return []
+        if isinstance(value, str):
+            return [value]
+        return list(value)

nextrec/basic/layers.py

@@ -2,8 +2,7 @@
 Layer implementations used across NextRec models.
 
 Date: create on 27/10/2025, update on 19/11/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
 
 from __future__ import annotations

nextrec/basic/loggers.py

@@ -2,16 +2,18 @@
 NextRec Basic Loggers
 
 Date: create on 27/10/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
 
+
 import os
 import re
 import sys
 import copy
 import datetime
 import logging
+from pathlib import Path
+from nextrec.basic.session import resolve_save_path, create_session
 
 ANSI_CODES = {
     'black': '\033[30m',
@@ -89,16 +91,19 @@ def colorize(text: str, color: str | None = None, bold: bool = False) -> str:
 
     return result
 
-def setup_logger(log_dir: str | None = None):
+def setup_logger(session_id: str | os.PathLike | None = None):
     """Set up a logger that logs to both console and a file with ANSI formatting.
-       Only console output has colors; file output is stripped of ANSI codes.    
+       Only console output has colors; file output is stripped of ANSI codes.
+       Logs are stored under ``log/<experiment_id>/logs`` by default. A stable
+       log file is used per experiment so multiple components (e.g. data
+       processor and model training) append to the same file instead of creating
+       separate timestamped files.
     """
-    if log_dir is None:
-        project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-        log_dir = os.path.join(project_root, "..", "logs")
-    
-    os.makedirs(log_dir, exist_ok=True)
-    log_file = os.path.join(log_dir, f"nextrec_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.log")
+
+    session = create_session(str(session_id) if session_id is not None else None)
+    log_dir = session.logs_dir
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / f"{session.experiment_id}.log"
 
     console_format = '%(message)s'
     file_format = '%(asctime)s - %(levelname)s - %(message)s'

nextrec/basic/metrics.py

@@ -2,8 +2,7 @@
 Metrics computation and configuration for model evaluation.
 
 Date: create on 27/10/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
 import logging
 import numpy as np

nextrec/basic/model.py

@@ -2,34 +2,38 @@
 Base Model & Base Match Model Class
 
 Date: create on 27/10/2025
-Author:
-    Yang Zhou,zyaztec@gmail.com
+Author: Yang Zhou,zyaztec@gmail.com
 """
 
 import os
-import tqdm
-import torch
-import logging
 import datetime
+import logging
+import os
+from pathlib import Path
+
 import numpy as np
 import pandas as pd
+import torch
 import torch.nn as nn
 import torch.nn.functional as F
+import tqdm
 
 from typing import Union, Literal
 from torch.utils.data import DataLoader, TensorDataset
 
 from nextrec.basic.callback import EarlyStopper
-from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature
+from nextrec.basic.features import DenseFeature, SparseFeature, SequenceFeature, FeatureConfig
 from nextrec.basic.metrics import configure_metrics, evaluate_metrics
 
+from nextrec.loss import get_loss_fn
 from nextrec.data import get_column_data
+from nextrec.data.dataloader import build_tensors_from_data
 from nextrec.basic.loggers import setup_logger, colorize
 from nextrec.utils import get_optimizer_fn, get_scheduler_fn
-from nextrec.loss import get_loss_fn
+from nextrec.basic.session import resolve_save_path, create_session
 
 
-class BaseModel(nn.Module):
+class BaseModel(FeatureConfig, nn.Module):
     @property
     def model_name(self) -> str:
         raise NotImplementedError
@@ -43,6 +47,7 @@ class BaseModel(nn.Module):
                  sparse_features: list[SparseFeature] | None = None, 
                  sequence_features: list[SequenceFeature] | None = None,
                  target: list[str] | str | None = None,
+                 id_columns: list[str] | str | None = None,
                  task: str|list[str] = 'binary',
                  device: str = 'cpu',
                  embedding_l1_reg: float = 0.0,
@@ -50,26 +55,40 @@ class BaseModel(nn.Module):
                  embedding_l2_reg: float = 0.0, 
                  dense_l2_reg: float = 0.0,
                  early_stop_patience: int = 20, 
-                 model_path: str = './',
-                 model_id: str = 'baseline'): 
+                 session_id: str | None = None,): 
         
         super(BaseModel, self).__init__()
 
         try:
             self.device = torch.device(device)
         except Exception as e:
-            logging.warning(colorize("Invalid device , defaulting to CPU.", color='yellow'))
+            logging.warning("Invalid device , defaulting to CPU.")
             self.device = torch.device('cpu')
 
-        self.dense_features = list(dense_features) if dense_features is not None else []
-        self.sparse_features = list(sparse_features) if sparse_features is not None else []
-        self.sequence_features = list(sequence_features) if sequence_features is not None else []
-        
-        if isinstance(target, str):
-            self.target = [target]
-        else:
-            self.target = list(target) if target is not None else []
-        
+        self.session_id = session_id
+        self.session = create_session(session_id)
+        self.session_path = Path(self.session.logs_dir)
+        checkpoint_dir = self.session.checkpoints_dir / self.model_name
+
+        self.checkpoint = resolve_save_path(
+            path=None,
+            default_dir=checkpoint_dir,
+            default_name=self.model_name,
+            suffix=".model",
+            add_timestamp=True,
+        )
+
+        self.best = resolve_save_path(
+            path="best.model",
+            default_dir=checkpoint_dir,
+            default_name="best",
+            suffix=".model",
+        )
+
+        self._set_feature_config(dense_features, sparse_features, sequence_features)
+        self._set_target_config(target, id_columns)
+
+        self.target = self.target_columns
         self.target_index = {target_name: idx for idx, target_name in enumerate(self.target)}
 
         self.task = task
@@ -86,14 +105,6 @@ class BaseModel(nn.Module):
         self.early_stop_patience = early_stop_patience
         self._max_gradient_norm = 1.0   # Maximum gradient norm for gradient clipping
 
-        self.model_id = model_id
-
-        model_path = os.path.abspath(os.getcwd() if model_path in [None, './'] else model_path)
-        checkpoint_dir = os.path.join(model_path, "checkpoints", self.model_id)
-        os.makedirs(checkpoint_dir, exist_ok=True)
-        self.checkpoint = os.path.join(checkpoint_dir, f"{self.model_name}_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.model")
-        self.best = os.path.join(checkpoint_dir, f"{self.model_name}_{self.model_id}_best.model")
-
         self._logger_initialized = False
         self._verbose = 1
 
@@ -456,54 +467,15 @@ class BaseModel(nn.Module):
     def _prepare_data_loader(self, data: dict|pd.DataFrame|DataLoader, batch_size: int = 32, shuffle: bool = True):
         if isinstance(data, DataLoader):
             return data
-        tensors = []
-        all_features = self.dense_features + self.sparse_features + self.sequence_features
-        
-        for feature in all_features:
-            column = get_column_data(data, feature.name)
-            if column is None:
-                raise KeyError(f"Feature {feature.name} not found in provided data.")
-            
-            if isinstance(feature, SequenceFeature):
-                if isinstance(column, pd.Series):
-                    column = column.values
-                if isinstance(column, np.ndarray) and column.dtype == object:
-                    column = np.array([np.array(seq, dtype=np.int64) if not isinstance(seq, np.ndarray) else seq for seq in column])
-                if isinstance(column, np.ndarray) and column.ndim == 1 and column.dtype == object:
-                    column = np.vstack([c if isinstance(c, np.ndarray) else np.array(c) for c in column])  # type: ignore
-                tensor = torch.from_numpy(np.asarray(column, dtype=np.int64)).to('cpu')
-            else:
-                dtype = torch.float32 if isinstance(feature, DenseFeature) else torch.long
-                tensor = self._to_tensor(column, dtype=dtype, device='cpu')
-            
-            tensors.append(tensor)
-        
-        label_tensors = []
-        for target_name in self.target:
-            column = get_column_data(data, target_name)
-            if column is None:
-                continue
-            label_tensor = self._to_tensor(column, dtype=torch.float32, device='cpu')
-            
-            if label_tensor.dim() == 1:
-                # 1D tensor: (N,) -> (N, 1)
-                label_tensor = label_tensor.view(-1, 1)
-            elif label_tensor.dim() == 2:
-                if label_tensor.shape[0] == 1 and label_tensor.shape[1] > 1:
-                    label_tensor = label_tensor.t()
-            
-            label_tensors.append(label_tensor)
-        
-        if label_tensors:
-            if len(label_tensors) == 1 and label_tensors[0].shape[1] > 1:
-                y_tensor = label_tensors[0]
-            else:
-                y_tensor = torch.cat(label_tensors, dim=1)
-
-            if y_tensor.shape[1] == 1:
-                y_tensor = y_tensor.squeeze(1)
-            tensors.append(y_tensor)
-        
+        tensors = build_tensors_from_data(
+            data=data,
+            raw_data=data,
+            features=self.all_features,
+            target_columns=self.target,
+            id_columns=getattr(self, "id_columns", []),
+            on_missing_feature="raise",
+        )
+        assert tensors is not None, "No tensors were created from provided data."
         dataset = TensorDataset(*tensors)
         return DataLoader(dataset, batch_size=batch_size, shuffle=shuffle)
 
@@ -549,7 +521,7 @@ class BaseModel(nn.Module):
 
         self.to(self.device)
         if not self._logger_initialized:
-            setup_logger()
+            setup_logger(session_id=self.session_id)
             self._logger_initialized = True
         self._verbose = verbose
         self._set_metrics(metrics) # add self.metrics, self.task_specific_metrics, self.best_metrics_mode, self.early_stopper
@@ -976,7 +948,11 @@ class BaseModel(nn.Module):
         )
 
 
-    def predict(self, data: str|dict|pd.DataFrame|DataLoader, batch_size: int = 32) -> np.ndarray:
+    def predict(self, 
+                data: str|dict|pd.DataFrame|DataLoader, 
+                batch_size: int = 32,
+                save_path: str | os.PathLike | None = None,
+                save_format: Literal["npy", "csv"] = "npy") -> np.ndarray:
         self.eval()
         # todo: handle file path input later
         if isinstance(data, (str, os.PathLike)):
@@ -999,12 +975,38 @@ class BaseModel(nn.Module):
 
         if len(y_pred_list) > 0:
             y_pred_all = np.concatenate(y_pred_list, axis=0)
-            return y_pred_all
         else:
-            return np.array([])
+            y_pred_all = np.array([])
+
+        if save_path is not None:
+            suffix = ".npy" if save_format == "npy" else ".csv"
+            target_path = resolve_save_path(
+                path=save_path,
+                default_dir=self.session.predictions_dir,
+                default_name="predictions",
+                suffix=suffix,
+                add_timestamp=True if save_path is None else False,
+            )
+
+            if save_format == "npy":
+                np.save(target_path, y_pred_all)
+            else:
+                pd.DataFrame(y_pred_all).to_csv(target_path, index=False)
+
+            if self._verbose:
+                logging.info(colorize(f"Predictions saved to: {target_path}", color="green"))
+
+        return y_pred_all
     
-    def save_weights(self, model_path: str):
-        torch.save(self.state_dict(), model_path)
+    def save_weights(self, model_path: str | os.PathLike | None):
+        target_path = resolve_save_path(
+            path=model_path,
+            default_dir=self.session.checkpoints_dir / self.model_name,
+            default_name=self.model_name,
+            suffix=".model",
+            add_timestamp=model_path is None,
+        )
+        torch.save(self.state_dict(), target_path)
     
     def load_weights(self, checkpoint):
         self.to(self.device)
@@ -1116,7 +1118,7 @@ class BaseModel(nn.Module):
         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"  Model ID:              {self.model_id}")
+        logger.info(f"  Session ID:            {self.session_id}")
         logger.info(f"  Checkpoint Path:       {self.checkpoint}")
         
         logger.info("")
@@ -1161,7 +1163,7 @@ class BaseMatchModel(BaseModel):
                  embedding_l2_reg: float = 0.0,
                  dense_l2_reg: float = 0.0,
                  early_stop_patience: int = 20,
-                 model_id: str = 'baseline'):
+                 **kwargs):
         
         all_dense_features = []
         all_sparse_features = []
@@ -1192,7 +1194,7 @@ class BaseMatchModel(BaseModel):
             embedding_l2_reg=embedding_l2_reg,
             dense_l2_reg=dense_l2_reg,
             early_stop_patience=early_stop_patience,
-            model_id=model_id
+            **kwargs
         )
         
         self.user_dense_features = list(user_dense_features) if user_dense_features else []

nextrec/basic/session.py

@@ -0,0 +1,150 @@
+"""Session and experiment utilities.
+
+This module centralizes session/experiment management so the rest of the
+framework writes all artifacts to a consistent location:: <pwd>/log/<experiment_id>/
+
+Within that folder we keep model parameters, checkpoints, training metrics,
+evaluation metrics, and consolidated log output. When users do not provide an
+``experiment_id`` a timestamp-based identifier is generated once per process to
+avoid scattering files across multiple directories. Test runs are redirected to
+temporary folders so local trees are not polluted.
+
+Date: create on 23/11/2025
+Author: Yang Zhou,zyaztec@gmail.com
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+__all__ = [
+    "Session",
+    "resolve_save_path",
+    "create_session",
+]
+
+@dataclass(frozen=True)
+class Session:
+    """Encapsulate standard folders for a NextRec experiment."""
+
+    experiment_id: str
+    root: Path
+
+    @property
+    def logs_dir(self) -> Path:
+        return self._ensure_dir(self.root)
+
+    @property
+    def checkpoints_dir(self) -> Path:
+        return self._ensure_dir(self.root)
+
+    @property
+    def predictions_dir(self) -> Path:
+        return self._ensure_dir(self.root / "predictions")
+    
+    @property
+    def processor_dir(self) -> Path:
+        return self._ensure_dir(self.root / "processor")
+
+    @property
+    def params_dir(self) -> Path:
+        return self._ensure_dir(self.root)
+
+    @property
+    def metrics_dir(self) -> Path:
+        return self._ensure_dir(self.root)
+
+    def save_text(self, name: str, content: str) -> Path:
+        """Convenience helper: write a text file under logs_dir."""
+        path = self.logs_dir / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        return path
+
+    @staticmethod
+    def _ensure_dir(path: Path) -> Path:
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+def create_session(experiment_id: str | Path | None = None) -> Session:
+    """Create a :class:`Session` instance with prepared directories."""
+
+    if experiment_id is not None and str(experiment_id).strip():
+        exp_id = str(experiment_id).strip()
+    else:
+        exp_id = "nextrec_session_" + datetime.now().strftime("%Y%m%d")
+
+    if (
+        os.getenv("PYTEST_CURRENT_TEST")
+        or os.getenv("PYTEST_RUNNING")
+        or os.getenv("NEXTREC_TEST_MODE") == "1"
+    ):
+        session_path = Path(tempfile.gettempdir()) / "nextrec_logs" / exp_id
+    else:
+        # export NEXTREC_LOG_DIR=/data/nextrec/logs
+        base_dir = Path(os.getenv("NEXTREC_LOG_DIR", Path.cwd() / "nextrec_logs"))
+        session_path = base_dir / exp_id
+
+    session_path.mkdir(parents=True, exist_ok=True)
+    root = session_path.resolve()
+
+    return Session(experiment_id=exp_id, root=root)
+
+def resolve_save_path(
+    path: str | Path | None,
+    default_dir: str | Path,
+    default_name: str,
+    suffix: str,
+    add_timestamp: bool = False,
+) -> Path:
+    """
+    Normalize and create a save path.
+
+    - If ``path`` is ``None`` or has no suffix, place the file under
+      ``default_dir``.
+    - If ``path`` has no suffix, its stem is used as the file name; otherwise
+      ``default_name``.
+    - Relative paths with a suffix are also anchored under ``default_dir``.
+    - Enforces ``suffix`` (with leading dot) and optionally appends a
+      timestamp.
+    - Parent directories are created.
+    """
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") if add_timestamp else None
+
+    normalized_suffix = suffix if suffix.startswith(".") else f".{suffix}"
+
+    if path is not None and Path(path).suffix:
+        target = Path(path)
+        if not target.is_absolute():
+            target = Path(default_dir) / target
+        if target.suffix != normalized_suffix:
+            target = target.with_suffix(normalized_suffix)
+        if timestamp:
+            target = target.with_name(f"{target.stem}_{timestamp}{normalized_suffix}")
+        target.parent.mkdir(parents=True, exist_ok=True)
+        return target.resolve()
+
+    base_dir = Path(default_dir)
+    candidate = Path(path) if path is not None else None
+
+    if candidate is not None:
+        if candidate.exists() and candidate.is_dir():
+            base_dir = candidate
+            file_stem = default_name
+        else:
+            base_dir = candidate.parent if candidate.parent not in (Path("."), Path("")) else base_dir
+            file_stem = candidate.name or default_name
+    else:
+        file_stem = default_name
+
+    base_dir.mkdir(parents=True, exist_ok=True)
+    if timestamp:
+        file_stem = f"{file_stem}_{timestamp}"
+
+    return (base_dir / f"{file_stem}{normalized_suffix}").resolve()
+
+

nextrec/data/__init__.py

@@ -4,16 +4,21 @@ Data utilities package for NextRec
 This package provides data processing and manipulation utilities.
 
 Date: create on 13/11/2025
-Author:
-    Yang Zhou, zyaztec@gmail.com
+Author: Yang Zhou, zyaztec@gmail.com
 """
 
 from nextrec.data.data_utils import (
     collate_fn,
     get_column_data,
+    default_output_dir,
     split_dict_random,
     build_eval_candidates,
+    resolve_file_paths,
+    iter_file_chunks,
+    read_table,
+    load_dataframes,
 )
+from nextrec.basic.features import FeatureConfig
 
 # For backward compatibility, keep utils accessible
 from nextrec.data import data_utils
@@ -21,7 +26,13 @@ from nextrec.data import data_utils
 __all__ = [
     'collate_fn',
     'get_column_data',
+    'default_output_dir',
     'split_dict_random',
     'build_eval_candidates',
+    'resolve_file_paths',
+    'iter_file_chunks',
+    'read_table',
+    'load_dataframes',
+    'FeatureConfig',
     'data_utils',
 ]