cornac 2.5.0__tar.gz → 2.6.0__tar.gz

{cornac-2.5.0/cornac.egg-info → cornac-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cornac
-Version: 2.5.0
+Version: 2.6.0
 Summary: A Comparative Framework for Multimodal Recommender Systems
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -229,7 +229,6 @@ Requires-Dist: tqdm
 Requires-Dist: powerlaw
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
-Requires-Dist: pytest-pep8; extra == "tests"
 Requires-Dist: pytest-xdist; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
 Requires-Dist: Flask; extra == "tests"
@@ -295,7 +294,7 @@ Additional dependencies required by models are listed [here](README.md#Models).
 
 Some algorithm implementations use `OpenMP` to support multi-threading. For Mac OS users, in order to run those algorithms efficiently, you might need to install `gcc` from Homebrew to have an OpenMP compiler:
 ```bash
-brew install gcc | brew link gcc
+brew install gcc && brew link gcc
 ```
 
 ## Getting started: your first Cornac experiment
@@ -347,10 +346,9 @@ bpr.save("save_dir", save_trainset=True)
 ```
 After that, the model can be deployed easily by running Cornac serving app as follows:
 ```bash
-$ FLASK_APP='cornac.serving.app' \
-  MODEL_PATH='save_dir/BPR' \
+$ MODEL_PATH='save_dir/BPR' \
   MODEL_CLASS='cornac.models.BPR' \
-  flask run --host localhost --port 8080
+  flask --app cornac.serving.app run --host localhost --port 8080  # requires Flask>=2.2 (older Flask: FLASK_APP='cornac.serving.app' flask run ...)
 
 # Running on http://localhost:8080
 ```
@@ -393,7 +391,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E
 | 2023 | [Scalable Approximate NonSymmetric Autoencoder (SANSA)](cornac/models/sansa), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.sansa.recom_sansa), [paper](https://dl.acm.org/doi/10.1145/3604915.3608827) | Collaborative Filtering | [requirements](cornac/models/sansa/requirements.txt), CPU | [quick-start](examples/sansa_movielens.py), [150k-items](examples/sansa_tradesy.py)
 | 2022 | [Disentangled Multimodal Representation Learning for Recommendation (DMRL)](cornac/models/dmrl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.dmrl.recom_dmrl), [paper](https://arxiv.org/pdf/2203.05406.pdf) | Content-Based / Text & Image | [requirements](cornac/models/dmrl/requirements.txt), CPU / GPU | [quick-start](examples/dmrl_example.py)
 | 2021 | [Bilateral Variational Autoencoder for Collaborative Filtering (BiVAECF)](cornac/models/bivaecf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.bivaecf.recom_bivaecf), [paper](https://dl.acm.org/doi/pdf/10.1145/3437963.3441759) | Collaborative Filtering / Content-Based | [requirements](cornac/models/bivaecf/requirements.txt), CPU / GPU | [quick-start](https://github.com/PreferredAI/bi-vae), [deep-dive](https://github.com/recommenders-team/recommenders/blob/main/examples/02_model_collaborative_filtering/cornac_bivae_deep_dive.ipynb)
-|      | [GPT-2 for Sequential Recommendation (GPT2Rec)](cornac/models/gpt2rec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.gpt2rec.recom_gpt2rec), [paper](https://dl.acm.org/doi/10.1145/3460231.3474255) | Next-Item | [requirements](cornac/models/gpt2rec/requirements.txt), CPU / GPU | [quick-start](examples/transformer_rec_diginetica.py)
+|      | [Transformers4Rec-style Unified Transformer Recommender (TransformerRec)](cornac/models/transformer_rec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.transformer_rec.recom_transformer_rec), [paper](https://dl.acm.org/doi/10.1145/3460231.3474255) | Next-Item | [requirements](cornac/models/transformer_rec/requirements.txt), CPU / GPU | [quick-start](examples/transformer_rec_diginetica.py)
 |      | [Causal Inference for Visual Debiasing in Visually-Aware Recommendation (CausalRec)](cornac/models/causalrec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.causalrec.recom_causalrec), [paper](https://arxiv.org/abs/2107.02390) | Content-Based / Image | [requirements](cornac/models/causalrec/requirements.txt), CPU / GPU | [quick-start](examples/causalrec_clothing.py)
 |      | [Explainable Recommendation with Comparative Constraints on Product Aspects (ComparER)](cornac/models/comparer), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.comparer.recom_comparer_sub), [paper](https://dl.acm.org/doi/pdf/10.1145/3437963.3441754) | Explainable | CPU | [quick-start](https://github.com/PreferredAI/ComparER)
 | 2020 | [Adversarial Multimedia Recommendation (AMR)](cornac/models/amr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.amr.recom_amr), [paper](https://ieeexplore.ieee.org/document/8618394) | Content-Based / Image | [requirements](cornac/models/amr/requirements.txt), CPU / GPU | [quick-start](examples/amr_clothing.py)

{cornac-2.5.0 → cornac-2.6.0}/README.md

@@ -58,7 +58,7 @@ Additional dependencies required by models are listed [here](README.md#Models).
 
 Some algorithm implementations use `OpenMP` to support multi-threading. For Mac OS users, in order to run those algorithms efficiently, you might need to install `gcc` from Homebrew to have an OpenMP compiler:
 ```bash
-brew install gcc | brew link gcc
+brew install gcc && brew link gcc
 ```
 
 ## Getting started: your first Cornac experiment
@@ -110,10 +110,9 @@ bpr.save("save_dir", save_trainset=True)
 ```
 After that, the model can be deployed easily by running Cornac serving app as follows:
 ```bash
-$ FLASK_APP='cornac.serving.app' \
-  MODEL_PATH='save_dir/BPR' \
+$ MODEL_PATH='save_dir/BPR' \
   MODEL_CLASS='cornac.models.BPR' \
-  flask run --host localhost --port 8080
+  flask --app cornac.serving.app run --host localhost --port 8080  # requires Flask>=2.2 (older Flask: FLASK_APP='cornac.serving.app' flask run ...)
 
 # Running on http://localhost:8080
 ```
@@ -156,7 +155,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E
 | 2023 | [Scalable Approximate NonSymmetric Autoencoder (SANSA)](cornac/models/sansa), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.sansa.recom_sansa), [paper](https://dl.acm.org/doi/10.1145/3604915.3608827) | Collaborative Filtering | [requirements](cornac/models/sansa/requirements.txt), CPU | [quick-start](examples/sansa_movielens.py), [150k-items](examples/sansa_tradesy.py)
 | 2022 | [Disentangled Multimodal Representation Learning for Recommendation (DMRL)](cornac/models/dmrl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.dmrl.recom_dmrl), [paper](https://arxiv.org/pdf/2203.05406.pdf) | Content-Based / Text & Image | [requirements](cornac/models/dmrl/requirements.txt), CPU / GPU | [quick-start](examples/dmrl_example.py)
 | 2021 | [Bilateral Variational Autoencoder for Collaborative Filtering (BiVAECF)](cornac/models/bivaecf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.bivaecf.recom_bivaecf), [paper](https://dl.acm.org/doi/pdf/10.1145/3437963.3441759) | Collaborative Filtering / Content-Based | [requirements](cornac/models/bivaecf/requirements.txt), CPU / GPU | [quick-start](https://github.com/PreferredAI/bi-vae), [deep-dive](https://github.com/recommenders-team/recommenders/blob/main/examples/02_model_collaborative_filtering/cornac_bivae_deep_dive.ipynb)
-|      | [GPT-2 for Sequential Recommendation (GPT2Rec)](cornac/models/gpt2rec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.gpt2rec.recom_gpt2rec), [paper](https://dl.acm.org/doi/10.1145/3460231.3474255) | Next-Item | [requirements](cornac/models/gpt2rec/requirements.txt), CPU / GPU | [quick-start](examples/transformer_rec_diginetica.py)
+|      | [Transformers4Rec-style Unified Transformer Recommender (TransformerRec)](cornac/models/transformer_rec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.transformer_rec.recom_transformer_rec), [paper](https://dl.acm.org/doi/10.1145/3460231.3474255) | Next-Item | [requirements](cornac/models/transformer_rec/requirements.txt), CPU / GPU | [quick-start](examples/transformer_rec_diginetica.py)
 |      | [Causal Inference for Visual Debiasing in Visually-Aware Recommendation (CausalRec)](cornac/models/causalrec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.causalrec.recom_causalrec), [paper](https://arxiv.org/abs/2107.02390) | Content-Based / Image | [requirements](cornac/models/causalrec/requirements.txt), CPU / GPU | [quick-start](examples/causalrec_clothing.py)
 |      | [Explainable Recommendation with Comparative Constraints on Product Aspects (ComparER)](cornac/models/comparer), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.comparer.recom_comparer_sub), [paper](https://dl.acm.org/doi/pdf/10.1145/3437963.3441754) | Explainable | CPU | [quick-start](https://github.com/PreferredAI/ComparER)
 | 2020 | [Adversarial Multimedia Recommendation (AMR)](cornac/models/amr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.amr.recom_amr), [paper](https://ieeexplore.ieee.org/document/8618394) | Content-Based / Image | [requirements](cornac/models/amr/requirements.txt), CPU / GPU | [quick-start](examples/amr_clothing.py)

{cornac-2.5.0 → cornac-2.6.0}/cornac/__init__.py

@@ -23,4 +23,4 @@ from . import utils
 # Also importable from root
 from .experiment import Experiment
 
-__version__ = "2.5.0"
+__version__ = "2.6.0"

{cornac-2.5.0 → cornac-2.6.0}/cornac/data/dataset.py

@@ -1203,6 +1203,20 @@ class SequentialDataset(Dataset):
         extra_pos = ts_pos + 1
         extra_data = [data[i][extra_pos] for i in valid_idx] if fmt in ["SITJson", "USITJson"] else None
 
+        if timestamps is not None and len(timestamps) > 1:
+            order = np.argsort(session_indices, kind="stable")
+            s = session_indices[order]
+            t = timestamps[order]
+            decreasing = (t[1:] < t[:-1]) & (s[1:] == s[:-1])
+            if decreasing.any():
+                n_bad = int(decreasing.sum())
+                warnings.warn(
+                    f"{n_bad} interaction(s) are not in chronological order within "
+                    "their session. Sequential models treat input row order as the "
+                    "ground-truth sequence; sort your data by (session, timestamp) "
+                    "before building the dataset."
+                )
+
         dataset = cls(
             num_users=len(global_uid_map),
             num_sessions=len(set(session_indices)),

{cornac-2.5.0 → cornac-2.6.0}/cornac/datasets/__init__.py

@@ -16,6 +16,7 @@
 from . import amazon_clothing
 from . import amazon_digital_music
 from . import amazon_office
+from . import amazon_review
 from . import amazon_toy
 from . import citeulike
 from . import cosmetics

cornac-2.6.0/cornac/datasets/amazon_review.py

@@ -0,0 +1,108 @@
+# Copyright 2026 The Cornac Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""
+Amazon Product Review datasets.
+
+There are three versions: '2014', '2018', and '2023' available.
+'2014' is the version used in the Semantic-ID literature (e.g., TIGER).
+
+Source: https://cseweb.ucsd.edu/~jmcauley/datasets/amazon/links.html
+"""
+
+import gzip
+import json
+import os
+from typing import List
+
+from ..data import Reader
+from ..utils import cache
+
+# category -> reviews_<cat>_5.json.gz
+_CATEGORY_FILES = {
+    "beauty": "Beauty",
+    "sports": "Sports_and_Outdoors",
+    "toys": "Toys_and_Games",
+}
+
+_BASE_URL = "https://snap.stanford.edu/data/amazon/productGraph/categoryFiles"
+
+
+def _preprocess(gz_path: str, csv_path: str) -> None:
+    """Parse the raw 5-core reviews into ``user,item,rating,timestamp`` rows.
+
+    Only mechanical cleaning is applied (drop rows with a missing field);
+    rows are sorted chronologically per user so downstream sequential builders
+    receive time-ordered sessions.
+    """
+    rows = []
+    with gzip.open(gz_path, "rt", encoding="utf-8") as f:
+        for line in f:
+            r = json.loads(line)
+            user = r.get("reviewerID")
+            item = r.get("asin")
+            rating = r.get("overall")
+            timestamp = r.get("unixReviewTime")
+            if user is None or item is None or rating is None or timestamp is None:
+                continue
+            rows.append((user, item, float(rating), int(timestamp)))
+
+    rows.sort(key=lambda x: (x[0], x[3]))  # (user, timestamp)
+
+    with open(csv_path, "w") as f:
+        for user, item, rating, timestamp in rows:
+            f.write(f"{user},{item},{rating},{timestamp}\n")
+
+
+def load_feedback(category: str, version: str = "2014", fmt: str = "UIRT", reader: Reader = None) -> List:
+    """Load the user-item review feedback, chronologically ordered per user.
+
+    Parameters
+    ----------
+    category: str, required
+        One of ``'beauty'``, ``'sports'``, ``'toys'`` -- the three categories
+        used by TIGER and subsequent Semantic-ID papers.
+
+    version: str, default: '2014'
+        Dataset version. Only ``'2014'`` (McAuley 5-core) is currently supported;
+        2018 and 2023 are available, but 2014 is the version used throughout the Semantic-ID literature.
+
+    fmt: str, default: 'UIRT'
+        Data format; the underlying file has user, item, rating, and timestamp
+        columns, so ``'UIR'`` and ``'UI'`` are also valid.
+
+    reader: `obj:cornac.data.Reader`, default: None
+        Reader object used to read the data.
+
+    Returns
+    -------
+    data: array-like
+        Data in the form of a list of tuples (user, item, rating, timestamp).
+    """
+    if category not in _CATEGORY_FILES:
+        raise ValueError(f"category='{category}' not supported; " f"choose one of {sorted(_CATEGORY_FILES)}")
+    if version != "2014":
+        raise ValueError(f"version='{version}' not supported; only '2014' (McAuley 5-core) " "is available")
+
+    stem = _CATEGORY_FILES[category]
+    gz_path = cache(
+        url=f"{_BASE_URL}/reviews_{stem}_5.json.gz",
+        relative_path=f"amazon_review/{category}_{version}.json.gz",
+    )
+    csv_path = f"{gz_path[:-len('.json.gz')]}.csv"
+    if not os.path.exists(csv_path):
+        _preprocess(gz_path, csv_path)
+
+    reader = Reader() if reader is None else reader
+    return reader.read(csv_path, fmt=fmt, sep=",")

{cornac-2.5.0 → cornac-2.6.0}/cornac/datasets/movielens.py

@@ -28,28 +28,28 @@ VALID_DATA_FORMATS = ["UIR", "UIRT"]
 MovieLens = namedtuple("MovieLens", ["url", "unzip", "path", "sep", "skip"])
 ML_DATASETS = {
     "100K": MovieLens(
-        "http://files.grouplens.org/datasets/movielens/ml-100k/u.data",
+        "https://files.grouplens.org/datasets/movielens/ml-100k/u.data",
         False,
         "ml-100k/u.data",
         "\t",
         0,
     ),
     "1M": MovieLens(
-        "http://files.grouplens.org/datasets/movielens/ml-1m.zip",
+        "https://files.grouplens.org/datasets/movielens/ml-1m.zip",
         True,
         "ml-1m/ratings.dat",
         "::",
         0,
     ),
     "10M": MovieLens(
-        "http://files.grouplens.org/datasets/movielens/ml-10m.zip",
+        "https://files.grouplens.org/datasets/movielens/ml-10m.zip",
         True,
         "ml-10M100K/ratings.dat",
         "::",
         0,
     ),
     "20M": MovieLens(
-        "http://files.grouplens.org/datasets/movielens/ml-20m.zip",
+        "https://files.grouplens.org/datasets/movielens/ml-20m.zip",
         True,
         "ml-20m/ratings.csv",
         ",",

{cornac-2.5.0 → cornac-2.6.0}/cornac/eval_methods/next_item_evaluation.py

@@ -23,6 +23,7 @@ from tqdm.auto import tqdm
 from ..data import SequentialDataset
 from ..experiment.result import Result
 from ..models import NextItemRecommender
+from ..utils import validate_format
 from . import BaseMethod
 
 EVALUATION_MODES = frozenset([
@@ -189,6 +190,19 @@ class NextItemEvaluation(BaseMethod):
     verbose: bool, optional, default: False
         Output running log.
 
+    Notes
+    -----
+    **Data splitting.** Ratio-based splitting (inherited from
+    :obj:`BaseMethod`) and per-user leave-last-out both leak future
+    information into training: a random split trains on interactions that
+    postdate the test items, while leave-last-out places each user's held-out
+    item at a different absolute time, so training on one user includes other
+    users' later interactions (popularity drift then distorts results). The
+    recommended protocol is a single global temporal cutoff; use
+    :meth:`from_timestamps` for a leakage-free, session-level split.
+    Per-user leave-last-out remains available via :meth:`leave_last_out`
+    for comparability with published results.
+
     """
 
     def __init__(
@@ -335,7 +349,10 @@ class NextItemEvaluation(BaseMethod):
         -------
         res: :obj:`cornac.experiment.Result`
         """
-        if not isinstance(model, NextItemRecommender):
+        base_model = getattr(model, "model", None)
+        if not isinstance(model, NextItemRecommender) and not isinstance(
+            base_model, NextItemRecommender
+        ):
             raise ValueError("model must be a NextItemRecommender but '%s' is provided" % type(model))
 
         if self.train_set is None:
@@ -466,3 +483,290 @@ class NextItemEvaluation(BaseMethod):
             test_data=test_data,
             val_data=val_data,
         )
+
+    @classmethod
+    def from_timestamps(
+        cls,
+        data,
+        test_timestamp,
+        val_timestamp=None,
+        fmt="USIT",
+        exclude_unknowns=True,
+        mode="last",
+        seed=None,
+        verbose=False,
+        **kwargs,
+    ):
+        """Constructing evaluation method by a global temporal split.
+
+        Sessions are split by a single global time horizon so that no
+        training session is evaluated against future information shared across
+        users. This is the leakage-free protocol recommended by the
+        offline-evaluation literature (see Notes).
+
+        Parameters
+        ----------
+        data: list, required
+            Raw preference data in the tuple format given by `fmt`.
+
+        test_timestamp: float, required
+            Absolute timestamp (same unit as the timestamps in `data`) marking
+            the start of the test period. Sessions whose last event is at or
+            after this timestamp form the test set.
+
+        val_timestamp: float, optional, default: None
+            Absolute timestamp marking the start of the validation period. If
+            None, no validation set is created and the training set absorbs
+            everything before `test_timestamp`. Must be strictly smaller than
+            `test_timestamp`.
+
+        fmt: str, default: 'USIT'
+            Format of the input data. Currently, we are supporting:
+
+            'SIT': Session, Item, Timestamp
+            'USIT': User, Session, Item, Timestamp
+            'SITJson': Session, Item, Timestamp, Json
+            'USITJson': User, Session, Item, Timestamp, Json
+
+        exclude_unknowns: bool, optional, default: True
+            Whether to exclude unknown users/items in evaluation.
+
+        mode: str, optional, default: 'last'
+            Evaluation mode is either 'next' or 'last'.
+            If 'last', only evaluate the last item.
+            If 'next', evaluate every next item in the sequence.
+
+        seed: int, optional, default: None
+            Random seed for reproducibility.
+
+        verbose: bool, optional, default: False
+            The verbosity flag.
+
+        Returns
+        -------
+        method: :obj:`<cornac.eval_methods.NextItemEvaluation>`
+            Evaluation method object.
+
+        Notes
+        -----
+        Sessions are atomic: each session is assigned to exactly one split by
+        the timestamp of its **last event** ``last_ts = max(t of session)``:
+
+        - train: ``last_ts < val_timestamp``
+        - val:   ``val_timestamp <= last_ts < test_timestamp``
+        - test:  ``last_ts >= test_timestamp``
+
+        ``>=`` goes to the later split (same convention as
+        :obj:`cornac.eval_methods.TimestampSplit`). With
+        ``val_timestamp=None``, train is ``last_ts < test_timestamp``.
+
+        Assigning whole sessions by last event keeps sessions intact (an
+        interaction-level cutoff would truncate straddling sessions), bounding
+        residual leakage by session length (Hidasi & Czapp, RecSys 2023).
+        Rows keep their original relative order within each partition, as
+        required by :obj:`cornac.data.SequentialDataset.build`.
+
+        References
+        ----------
+        Meng et al. (2020). Exploring Data Splitting Strategies for the
+        Evaluation of Recommendation Models. RecSys 2020.
+
+        Ji et al. (2023). A Critical Study on Data Leakage in Recommender
+        System Offline Evaluation. ACM TOIS 2023.
+
+        Hidasi & Czapp (2023). Widespread Flaws in Offline Evaluation of
+        Recommender Systems. RecSys 2023.
+
+        """
+        fmt = validate_format(fmt, ["SIT", "USIT", "SITJson", "USITJson"])
+
+        if val_timestamp is not None and val_timestamp >= test_timestamp:
+            raise ValueError(
+                "val_timestamp ({}) must be strictly smaller than "
+                "test_timestamp ({}).".format(val_timestamp, test_timestamp)
+            )
+
+        sid_pos = 1 if fmt in ["USIT", "USITJson"] else 0
+        ts_pos = 3 if fmt in ["USIT", "USITJson"] else 2
+
+        # Pass 1: last event timestamp per session.
+        last_ts = {}
+        for tup in data:
+            sid = tup[sid_pos]
+            t = float(tup[ts_pos])
+            if sid not in last_ts or t > last_ts[sid]:
+                last_ts[sid] = t
+
+        # Pass 2: route tuples, preserving original relative order.
+        train_data, val_data, test_data = [], [], []
+        for tup in data:
+            ts = last_ts[tup[sid_pos]]
+            if ts >= test_timestamp:
+                test_data.append(tup)
+            elif val_timestamp is not None and ts >= val_timestamp:
+                val_data.append(tup)
+            else:
+                train_data.append(tup)
+
+        if len(train_data) == 0:
+            raise ValueError(
+                "Empty train partition: no session ends before the cutoff "
+                "({}).".format(test_timestamp if val_timestamp is None else val_timestamp)
+            )
+        if len(test_data) == 0:
+            raise ValueError(
+                "Empty test partition: no session ends at or after "
+                "test_timestamp ({}).".format(test_timestamp)
+            )
+        if val_timestamp is not None and len(val_data) == 0:
+            warnings.warn(
+                "Empty validation partition: no session ends in "
+                "[{}, {}). Proceeding with no validation set.".format(
+                    val_timestamp, test_timestamp
+                )
+            )
+            val_data = None
+
+        if verbose:
+            def _n_sessions(part):
+                return len({tup[sid_pos] for tup in part}) if part else 0
+
+            print("---")
+            print("Global temporal split:")
+            print(
+                "Train: {} sessions, {} interactions".format(
+                    _n_sessions(train_data), len(train_data)
+                )
+            )
+            print(
+                "Val: {} sessions, {} interactions".format(
+                    _n_sessions(val_data), len(val_data) if val_data else 0
+                )
+            )
+            print(
+                "Test: {} sessions, {} interactions".format(
+                    _n_sessions(test_data), len(test_data)
+                )
+            )
+
+        return cls.from_splits(
+            train_data=train_data,
+            test_data=test_data,
+            val_data=val_data,
+            fmt=fmt,
+            exclude_unknowns=exclude_unknowns,
+            seed=seed,
+            verbose=verbose,
+            mode=mode,
+            **kwargs,
+        )
+
+    @classmethod
+    def leave_last_out(
+        cls,
+        data,
+        fmt="UIRT",
+        exclude_unknowns=True,
+        mode="last",
+        seed=None,
+        verbose=False,
+        **kwargs,
+    ):
+        """Constructing evaluation method by per-user leave-last-out.
+
+        Each user's interactions are sorted chronologically and treated as one
+        session (session id = user id). The last item is held out for testing
+        and the second-to-last for validation — the common protocol in the
+        sequential recommendation literature (SASRec, BERT4Rec, ...).
+
+        Parameters
+        ----------
+        data: list, required
+            Raw preference data in the quadruplet format
+            [(user_id, item_id, rating, timestamp)]. Ratings are ignored
+            (implicit next-item feedback).
+
+        fmt: str, default: 'UIRT'
+            Format of the input data. Only 'UIRT' is supported.
+
+        exclude_unknowns: bool, optional, default: True
+            Whether to exclude unknown users/items in evaluation.
+
+        mode: str, optional, default: 'last'
+            Evaluation mode is either 'next' or 'last'.
+            If 'last', only evaluate the last item.
+            If 'next', evaluate every next item in the sequence.
+
+        seed: int, optional, default: None
+            Random seed for reproducibility.
+
+        verbose: bool, optional, default: False
+            The verbosity flag.
+
+        Returns
+        -------
+        method: :obj:`<cornac.eval_methods.NextItemEvaluation>`
+            Evaluation method object.
+
+        Notes
+        -----
+        Per user (chronological, stable sort — tied timestamps keep input
+        order), with cumulative sequences:
+
+        - train: ``seq[:-2]``
+        - val:   ``seq[:-1]`` (target = second-to-last item)
+        - test:  ``seq`` (target = last item)
+
+        Users with fewer than 3 interactions are dropped from all splits.
+
+        This protocol leaks future information across users: each held-out
+        item sits at a different absolute time, so training includes other
+        users' later interactions (Ji et al., A Critical Study on Data
+        Leakage in Recommender System Offline Evaluation, ACM TOIS 2023).
+        It is provided for comparability with published results; prefer
+        :meth:`from_timestamps` for a leakage-free protocol.
+
+        """
+        fmt = validate_format(fmt, ["UIRT"])
+
+        by_user = OrderedDict()
+        for u, i, _, t in data:
+            by_user.setdefault(u, []).append((float(t), i, t))
+
+        train_data, val_data, test_data = [], [], []
+        n_skipped = 0
+        for u, events in by_user.items():
+            if len(events) < 3:
+                n_skipped += 1
+                continue
+            events.sort(key=lambda x: x[0])
+            seq = [(u, u, i, t) for _, i, t in events]
+            train_data.extend(seq[:-2])
+            val_data.extend(seq[:-1])
+            test_data.extend(seq)
+
+        if len(train_data) == 0:
+            raise ValueError(
+                "Empty train set: no user has at least 3 interactions."
+            )
+
+        if verbose:
+            print("---")
+            print("Leave-last-out split (user = session):")
+            print(
+                "{} users kept, {} users with < 3 interactions dropped".format(
+                    len(by_user) - n_skipped, n_skipped
+                )
+            )
+
+        return cls.from_splits(
+            train_data=train_data,
+            test_data=test_data,
+            val_data=val_data,
+            fmt="USIT",
+            exclude_unknowns=exclude_unknowns,
+            seed=seed,
+            verbose=verbose,
+            mode=mode,
+            **kwargs,
+        )

{cornac-2.5.0 → cornac-2.6.0}/cornac/hyperopt.py

@@ -17,9 +17,10 @@
 import numpy as np
 from itertools import product
 
-from .models import Recommender
+from .models import Recommender, NextItemRecommender
 from .metrics import RatingMetric, RankingMetric
 from .eval_methods import rating_eval, ranking_eval
+from .eval_methods.next_item_evaluation import ranking_eval as next_item_ranking_eval
 from .utils import get_rng
 
 
@@ -147,6 +148,16 @@ class BaseSearch(Recommender):
 
             if isinstance(self.metric, RatingMetric):
                 score = rating_eval(model, [self.metric], val_set)[0][0]
+            elif isinstance(model, NextItemRecommender):
+                score = next_item_ranking_eval(
+                    model,
+                    [self.metric],
+                    train_set,
+                    val_set,
+                    exclude_unknowns=self.eval_method.exclude_unknowns,
+                    mode=self.eval_method.mode,
+                    verbose=False,
+                )[0][0]
             else:
                 score = ranking_eval(
                     model,
@@ -171,9 +182,17 @@ class BaseSearch(Recommender):
 
         return self
 
-    def score(self, user_idx, item_idx=None):
+    def transform(self, test_set):
+        """Delegate test-set transformation to the best searched model."""
+        return self.best_model.transform(test_set)
+
+    def score(self, user_idx, *args, **kwargs):
         """Scoring using the best searched model"""
-        return self.best_model.score(user_idx, item_idx)
+        return self.best_model.score(user_idx, *args, **kwargs)
+
+    def rank(self, user_idx, item_indices=None, k=-1, **kwargs):
+        """Ranking using the best searched model"""
+        return self.best_model.rank(user_idx, item_indices, k, **kwargs)
 
 
 class GridSearch(BaseSearch):
@@ -263,7 +282,7 @@ class RandomSearch(BaseSearch):
         """Generate searching points"""
         param_set = []
         keys = [d.name for d in self.space]
-        rng = get_rng(self.model.seed)
+        rng = get_rng(getattr(self.model, "seed", None))
         while len(param_set) < self.n_trails:
             params = [d._sample(rng) for d in self.space]
             param_set.append(dict(zip(keys, params)))

{cornac-2.5.0 → cornac-2.6.0}/cornac/models/__init__.py

@@ -50,7 +50,6 @@ from .fpmc import FPMC
 from .gcmc import GCMC
 from .global_avg import GlobalAvg
 from .gp_top import GPTop
-from .gpt2rec import GPT2Rec
 from .gru4rec import GRU4Rec
 from .hft import HFT
 from .hpf import HPF
@@ -84,6 +83,7 @@ from .sorec import SoRec
 from .spop import SPop
 from .svd import SVD
 from .tifuknn import TIFUKNN
+from .transformer_rec import TransformerRec
 from .trirank import TriRank
 from .upcf import UPCF
 from .vaecf import VAECF