recnexteval 0.1.0__py3-none-any.whl

recnexteval/registries/__init__.py

@@ -0,0 +1,67 @@
+"""Registries for algorithms, metrics, and datasets.
+
+This module provides registries for storing and managing algorithms, metrics,
+and datasets used in experiments. Registries help keep track of valid classes
+and enable easy instantiation of components.
+
+## Registries
+
+Registries store algorithms, metrics, and datasets by default and allow
+registration of new components via the `register` function.
+
+Example:
+    ```python
+    from recnexteval.pipelines import ALGORITHM_REGISTRY
+    from recnexteval.algorithms import ItemKNNStatic
+
+    algo = ALGORITHM_REGISTRY.get("ItemKNNStatic")(K=10)
+    ALGORITHM_REGISTRY.register("algo_1", ItemKNNStatic)
+    ```
+
+### Available Registries
+
+- `ALGORITHM_REGISTRY`: Registry for algorithms
+- `DATASET_REGISTRY`: Registry for datasets
+- `METRIC_REGISTRY`: Registry for metrics
+- `AlgorithmRegistry`: Class for creating algorithm registries
+- `DatasetRegistry`: Class for creating dataset registries
+- `MetricRegistry`: Class for creating metric registries
+
+## Entries
+
+Entries store algorithms and metrics in registries. They maintain the class
+and parameters used to instantiate each component. These entries are used by
+`EvaluatorPipeline` to instantiate algorithms and metrics.
+
+### Available Entries
+
+- `AlgorithmEntry`: Entry for algorithms
+- `MetricEntry`: Entry for metrics
+
+"""
+
+from .algorithm import (
+    ALGORITHM_REGISTRY,
+    AlgorithmEntry,
+    AlgorithmRegistry,
+)
+from .base import Registry
+from .dataset import DATASET_REGISTRY, DatasetRegistry
+from .metric import (
+    METRIC_REGISTRY,
+    MetricEntry,
+    MetricRegistry,
+)
+
+
+__all__ = [
+    "ALGORITHM_REGISTRY",
+    "AlgorithmEntry",
+    "AlgorithmRegistry",
+    "DATASET_REGISTRY",
+    "DatasetRegistry",
+    "METRIC_REGISTRY",
+    "MetricEntry",
+    "MetricRegistry",
+    "Registry",
+]

recnexteval/registries/algorithm.py

@@ -0,0 +1,68 @@
+import importlib
+import logging
+import uuid
+from typing import Any, NamedTuple
+
+from ..algorithms import Algorithm
+from .base import Registry
+
+
+logger = logging.getLogger(__name__)
+
+
+class AlgorithmRegistry(Registry[Algorithm]):
+    """Registry for easy retrieval of algorithm types by name.
+
+    The registry is pre-registered with all recnexteval algorithms.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the algorithm registry.
+
+        The registry is initialized with the `recnexteval.algorithms` module
+        so that all built-in algorithms are available by default.
+        """
+        module = importlib.import_module("recnexteval.algorithms")
+        super().__init__(module)
+
+
+ALGORITHM_REGISTRY = AlgorithmRegistry()
+"""Registry instantiation for algorithms.
+
+Contains the recnexteval algorithms by default and allows registration of
+new algorithms via the `register` function.
+
+Examples:
+    ```python
+    from recnexteval.pipelines import ALGORITHM_REGISTRY
+
+    # Construct an ItemKNN object with parameter K=20
+    algo = ALGORITHM_REGISTRY.get("ItemKNN")(K=20)
+
+    from recnexteval.algorithms import ItemKNN
+
+    ALGORITHM_REGISTRY.register("HelloWorld", ItemKNN)
+
+    # Also construct an ItemKNN object with parameter K=20
+    algo = ALGORITHM_REGISTRY.get("HelloWorld")(K=20)
+    ```
+"""
+
+
+class AlgorithmEntry(NamedTuple):
+    """Entry for the algorithm registry.
+
+    The intended use of this class is to store the name of the algorithm and
+    the parameters that the algorithm should take. Mainly this is used during
+    the building phase of the evaluator pipeline in `Builder`.
+
+    Attributes:
+        name: Name of the algorithm.
+        params: Parameters that do not require optimization as key-value
+            pairs, where the key is the hyperparameter name and the value is
+            the value it should take.
+    """
+
+    name: str
+    uuid: uuid.UUID | None = None
+    params: None | dict[str, Any] = None

recnexteval/registries/base.py

@@ -0,0 +1,131 @@
+import inspect
+import logging
+from types import ModuleType
+from typing import Generic, TypeVar
+
+from ..models import BaseModel
+
+
+logger = logging.getLogger(__name__)
+
+
+T = TypeVar('T', bound=BaseModel)
+
+
+class Registry(Generic[T], BaseModel):
+    """A Registry is a wrapper for a dictionary that maps names to Python types.
+
+    Most often, this is used to map names to classes.
+    """
+
+    def __init__(self, src: ModuleType) -> None:
+        self.registered: dict[str, type[T]] = {}
+        self.src = src
+        self._register_all_src()
+
+    def _register_all_src(self) -> None:
+        """Register all classes from the src module."""
+        if not hasattr(self.src, "__all__"):
+            raise AttributeError(f"Source module {self.src} has no __all__ attribute")
+        if self.src.__all__ is None:
+            raise AttributeError(f"Source module {self.src} has __all__ set to None")
+        for class_name in self.src.__all__:
+            try:
+                cls = getattr(self.src, class_name)
+                if not inspect.isclass(cls):
+                    continue
+                self.register(class_name, cls)
+            except AttributeError:
+                # Skip if the attribute doesn't exist
+                continue
+
+    def __getitem__(self, key: str) -> type[T]:
+        """Retrieve the type for the given key.
+
+        Args:
+            key: The key of the type to fetch.
+
+        Returns:
+            The class type associated with the key.
+
+        Raises:
+            KeyError: If the key is not found in the registry.
+        """
+        try:
+            return self.registered[key]
+        except KeyError:
+            raise KeyError(f"key `{key}` not found in registry")
+
+    def __contains__(self, key: str) -> bool:
+        """Check if the given key is known to the registry.
+
+        Args:
+            key: The key to check.
+
+        Returns:
+            True if the key is known, False otherwise.
+        """
+        try:
+            self[key]
+            return True
+        except KeyError:
+            return False
+
+    def get(self, key: str) -> type[T]:
+        """Retrieve the value for this key.
+
+        This value is a Python type, most often a class.
+
+        Args:
+            key: The key to fetch.
+
+        Returns:
+            The class type associated with the key.
+
+        Raises:
+            KeyError: If the key is not found in the registry.
+        """
+        return self[key]
+
+    def register(self, key: str, cls: type[T]) -> None:
+        """Register a new Python type (most often a class).
+
+        After registration, the key can be used to fetch the Python type from the registry.
+
+        Args:
+            key: Key to register the type at. Needs to be unique to the registry.
+            cls: Class to register.
+
+        Raises:
+            KeyError: If the key is already registered.
+        """
+        if key in self.registered:
+            raise KeyError(f"key `{key}` already registered")
+        self.registered[key] = cls
+
+    def get_registered_keys(self, include_base: bool = False) -> list[str]:
+        """Get a list of all registered keys.
+
+        Returns:
+            A list of all registered keys.
+        """
+        if include_base:
+            return list(self.registered.keys())
+        else:
+            return [key for key, cls in self.registered.items() if not getattr(cls, "IS_BASE", True)]
+
+    def registered_values(self) -> list[type[T]]:
+        """Get a list of all registered types.
+
+        Returns:
+            A list of all registered types.
+        """
+        return [self.registered[key] for key in self.get_registered_keys(include_base=False)]
+
+    def registered_items(self) -> list[tuple[str, type[T]]]:
+        """Get a list of all registered key-type pairs.
+
+        Returns:
+            A list of all registered key-type pairs.
+        """
+        return [(key, self.registered[key]) for key in self.get_registered_keys(include_base=False)]

recnexteval/registries/dataset.py

@@ -0,0 +1,37 @@
+import importlib
+
+from ..datasets import Dataset
+from .base import Registry
+
+
+class DatasetRegistry(Registry[Dataset]):
+    """Registry for easy retrieval of dataset types by name.
+
+    The registry comes preregistered with all the recnexteval datasets.
+    """
+
+    def __init__(self) -> None:
+        module = importlib.import_module('recnexteval.datasets')
+        super().__init__(module)
+
+
+DATASET_REGISTRY = DatasetRegistry()
+"""Registry for datasets.
+
+Contains the recnexteval metrics by default,
+and allows registration of new metrics via the `register` function.
+
+Example:
+    ```python
+    from recnexteval.pipelines import METRIC_REGISTRY
+
+    # Construct a Recall object with parameter K=20
+    algo = METRIC_REGISTRY.get('Recall')(K=20)
+
+    from recnexteval.algorithms import Recall
+    METRIC_REGISTRY.register('HelloWorld', Recall)
+
+    # Also construct a Recall object with parameter K=20
+    algo = METRIC_REGISTRY.get('HelloWorld')(K=20)
+    ```
+"""

recnexteval/registries/metric.py

@@ -0,0 +1,57 @@
+import importlib
+from typing import NamedTuple
+
+from ..metrics import Metric
+from .base import Registry
+
+
+class MetricRegistry(Registry[Metric]):
+    """Registry for easy retrieval of metric types by name.
+
+    The registry comes preregistered with all the recnexteval metrics.
+    """
+
+    def __init__(self) -> None:
+        module = importlib.import_module('recnexteval.metrics')
+        super().__init__(module)
+
+
+METRIC_REGISTRY = MetricRegistry()
+"""Registry for metrics.
+
+Contains the recnexteval metrics by default and allows registration of new
+metrics via the ``register`` function.
+
+Example:
+    ```python
+    from recnexteval.pipelines import METRIC_REGISTRY
+
+    # Construct a Recall object with parameter K=20
+    algo = METRIC_REGISTRY.get("Recall")(K=20)
+
+    from recnexteval.algorithms import Recall
+
+    METRIC_REGISTRY.register("HelloWorld", Recall)
+
+    # Also construct a Recall object with parameter K=20
+    algo = METRIC_REGISTRY.get("HelloWorld")(K=20)
+    ```
+"""
+
+
+class MetricEntry(NamedTuple):
+    """Entry for the metric registry.
+
+    The intended use of this class is to store the name of the metric and the
+    top-K value for the metric specified by the user.
+
+    Mainly this will happen during the building phase of the evaluator
+    pipeline in :class:`Builder`.
+
+    Attributes:
+        name: Name of the algorithm.
+        K: Top-K value for the metric.
+    """
+
+    name: str
+    K: None | int = None

recnexteval/settings/__init__.py

@@ -0,0 +1,127 @@
+"""Settings module for data splitting strategies.
+
+The setting module contains classes that define how the data is split. To
+generalize the splitting of the data, the interactions are first sorted in
+temporal order, and then the split is performed based on the setting. As this
+library only considers dataset with timestamp, we will consider the case of the
+single time point setting and the sliding window setting. The single time point
+setting is analogous to Setting 3 of [@sun2023]. The sliding window setting
+is analogous to Setting 1 of [@sun2023].
+
+![data_split_definition](../../../assets/_static/data_split_definition.png)
+
+Observe the diagram below where the data split for Setting 1 is shown below. The
+unlabeled data will contain interactions that are masked which occurs after the
+current timestamp. The ground truth data will contain the actual interactions
+which will be used for evaluation and then released to the algorithm.
+
+![setting1_no_seq](../../../assets/_static/setting1_no_seq.png)
+
+While the this setting allows us to test the algorithm in a real-world scenario,
+there are times when the algorithm might require some sequential data before
+a prediction can be made. While it is not the role of the evaluating platform
+to provide this data, we have included the option to provide the last n interactions.
+
+## Data Components
+
+Each split produces three data components:
+
+- **background_data**: Data that is used to train the algorithm before the first
+  split.
+
+- **unlabeled_data**: Data that is released to the algorithm for prediction.
+  Contains the ID to be predicted and is labeled with "-1". Timestamps of the
+  interactions to be predicted are preserved. Can contain the last n interactions
+  split if specified in the parameter. The purpose is to provide sequential
+  data to the algorithm.
+
+- **ground_truth_data**: Data that is used to evaluate the algorithm. This data
+  will contain the actual interactions. The unlabeled data with the masked data
+  is a subset of the ground truth to ensure that there is an actual corresponding
+  value to evaluate the prediction against.
+
+
+## Available Settings
+
+- `Setting`: Base class for data splitting settings
+- `SingleTimePointSetting`: Single time point splitting strategy
+- `SlidingWindowSetting`: Sliding window splitting strategy
+- `LeaveNOutSetting`: Leave-N-out cross-validation strategy
+
+## Usage
+
+Settings are stateful. Thus, the initialization of the setting object only stores
+the parameters that are passed. Calling of `Setting.split` is necessary
+such that the attributes `Setting.background_data`, `Setting.unlabeled_data`
+and `Setting.ground_truth_data` are populated.
+
+```python
+from recnexteval.datasets import AmazonMovieDataset
+from recnexteval.settings import SlidingWindowSetting
+
+dataset = AmazonMovieDataset(use_default_filters=False)
+data = dataset.load()
+
+setting = SlidingWindowSetting(
+    background_t=1530000000,
+    window_size=60 * 60 * 24 * 30,  # 30 days
+    n_seq_data=1,
+    top_K=10
+)
+
+setting.split(data)
+```
+
+## Splitters
+
+Splitters are stateless utilities that split data into past and future interactions.
+They abstract splitting logic from the setting architecture, enabling flexible
+implementations.
+
+### Available Splitters
+
+- `TimestampSplitter`: Split data by timestamp
+- `NLastInteractionTimestampSplitter`: Split using N past interactions and timestamp
+- `NLastInteractionSplitter`: Split using N last interactions
+
+## Processors
+
+Processors handle data transformation. The current implementation masks prediction
+data and injects it into unlabeled data. Custom processors can implement additional
+transformations.
+
+### Available Processors
+
+- `Processor`: Base class for data processors
+- `PredictionDataProcessor`: Masks and injects prediction data
+
+## Exceptions
+
+- `EOWSettingError`: Raised when end of window is reached
+"""
+
+from .base import Setting
+from .exception import EOWSettingError
+from .leave_n_out_setting import LeaveNOutSetting
+from .processor import PredictionDataProcessor, Processor
+from .single_time_point_setting import SingleTimePointSetting
+from .sliding_window_setting import SlidingWindowSetting
+from .splitters import (
+    NLastInteractionSplitter,
+    NLastInteractionTimestampSplitter,
+    TimestampSplitter,
+)
+
+
+__all__ = [
+    "Setting",
+    "SingleTimePointSetting",
+    "SlidingWindowSetting",
+    "LeaveNOutSetting",
+    "Processor",
+    "PredictionDataProcessor",
+    "TimestampSplitter",
+    "NLastInteractionTimestampSplitter",
+    "NLastInteractionSplitter",
+    "EOWSettingError",
+]