keras-rs-nightly 0.0.1.dev2025030803__tar.gz → 0.0.1.dev2025031003__tar.gz

{keras_rs_nightly-0.0.1.dev2025030803 → keras_rs_nightly-0.0.1.dev2025031003}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: keras-rs-nightly
-Version: 0.0.1.dev2025030803
+Version: 0.0.1.dev2025031003
 Summary: Multi-backend recommender systems with Keras 3.
 Author-email: Keras RS team <keras-rs@google.com>
 License: Apache License 2.0

{keras_rs_nightly-0.0.1.dev2025030803 → keras_rs_nightly-0.0.1.dev2025031003}/keras_rs/api/__init__.py

@@ -5,5 +5,6 @@ since your modifications would be overwritten.
 """
 
 from keras_rs.api import layers
+from keras_rs.api import losses
 from keras_rs.src.version import __version__
 from keras_rs.src.version import version

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/api/losses/__init__.py

@@ -0,0 +1,14 @@
+"""DO NOT EDIT.
+
+This file was autogenerated. Do not edit it by hand,
+since your modifications would be overwritten.
+"""
+
+from keras_rs.src.losses.pairwise_hinge_loss import PairwiseHingeLoss
+from keras_rs.src.losses.pairwise_logistic_loss import PairwiseLogisticLoss
+from keras_rs.src.losses.pairwise_mean_squared_error import (
+    PairwiseMeanSquaredError,
+)
+from keras_rs.src.losses.pairwise_soft_zero_one_loss import (
+    PairwiseSoftZeroOneLoss,
+)

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/src/losses/pairwise_hinge_loss.py

@@ -0,0 +1,26 @@
+from keras import ops
+
+from keras_rs.src import types
+from keras_rs.src.api_export import keras_rs_export
+from keras_rs.src.losses.pairwise_loss import PairwiseLoss
+from keras_rs.src.losses.pairwise_loss import pairwise_loss_subclass_doc_string
+
+
+@keras_rs_export("keras_rs.losses.PairwiseHingeLoss")
+class PairwiseHingeLoss(PairwiseLoss):
+    def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
+        return ops.relu(ops.subtract(ops.array(1), pairwise_logits))
+
+
+formula = "loss = sum_{i} sum_{j} I(y_i > y_j) * max(0, 1 - (s_i - s_j))"
+explanation = """
+      - `max(0, 1 - (s_i - s_j))` is the hinge loss, which penalizes cases where
+        the score difference `s_i - s_j` is not sufficiently large when
+        `y_i > y_j`.
+"""
+extra_args = ""
+PairwiseHingeLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
+    formula=formula,
+    explanation=explanation,
+    extra_args=extra_args,
+)

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/src/losses/pairwise_logistic_loss.py

@@ -0,0 +1,35 @@
+from keras import ops
+
+from keras_rs.src import types
+from keras_rs.src.api_export import keras_rs_export
+from keras_rs.src.losses.pairwise_loss import PairwiseLoss
+from keras_rs.src.losses.pairwise_loss import pairwise_loss_subclass_doc_string
+
+
+@keras_rs_export("keras_rs.losses.PairwiseLogisticLoss")
+class PairwiseLogisticLoss(PairwiseLoss):
+    def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
+        return ops.add(
+            ops.relu(ops.negative(pairwise_logits)),
+            ops.log(
+                ops.add(
+                    ops.array(1),
+                    ops.exp(ops.negative(ops.abs(pairwise_logits))),
+                )
+            ),
+        )
+
+
+formula = "loss = sum_{i} sum_{j} I(y_i > y_j) * log(1 + exp(-(s_i - s_j)))"
+explanation = """
+      - `log(1 + exp(-(s_i - s_j)))` is the logistic loss, which penalizes
+        cases where the score difference `s_i - s_j` is not sufficiently large
+        when `y_i > y_j`. This function provides a smooth approximation of the
+        ideal step function, making it suitable for gradient-based optimization.
+"""
+extra_args = ""
+PairwiseLogisticLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
+    formula=formula,
+    explanation=explanation,
+    extra_args=extra_args,
+)

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/src/losses/pairwise_loss.py

@@ -0,0 +1,134 @@
+import abc
+from typing import Optional
+
+import keras
+from keras import ops
+
+from keras_rs.src import types
+from keras_rs.src.utils.pairwise_loss_utils import pairwise_comparison
+from keras_rs.src.utils.pairwise_loss_utils import process_loss_call_inputs
+
+
+class PairwiseLoss(keras.losses.Loss, abc.ABC):
+    """Base class for pairwise ranking losses.
+
+    Pairwise loss functions are designed for ranking tasks, where the goal is to
+    correctly order items within each list. Any pairwise loss function computes
+    the loss value by comparing pairs of items within each list, penalizing
+    cases where an item with a higher true label has a lower predicted score
+    than an item with a lower true label.
+
+    In order to implement any kind of pairwise loss, override the
+    `pairwise_loss` method.
+    """
+
+    # TODO: Add `temperature`, `lambda_weights`.
+
+    @abc.abstractmethod
+    def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
+        raise NotImplementedError(
+            "All subclasses of `keras_rs.losses.pairwise_loss.PairwiseLoss`"
+            "must implement the `pairwise_loss()` method."
+        )
+
+    def compute_unreduced_loss(
+        self,
+        labels: types.Tensor,
+        logits: types.Tensor,
+        mask: Optional[types.Tensor] = None,
+    ) -> tuple[types.Tensor, types.Tensor]:
+        # Mask all values less than 0 (since less than 0 implies invalid
+        # labels).
+        valid_mask = ops.greater_equal(labels, ops.cast(0.0, labels.dtype))
+
+        if mask is not None:
+            valid_mask = ops.logical_and(valid_mask, mask)
+
+        pairwise_labels, pairwise_logits = pairwise_comparison(
+            labels=labels,
+            logits=logits,
+            mask=valid_mask,
+            logits_op=ops.subtract,
+        )
+
+        return self.pairwise_loss(pairwise_logits), pairwise_labels
+
+    def call(
+        self,
+        y_true: types.Tensor,
+        y_pred: types.Tensor,
+    ) -> types.Tensor:
+        """
+        Args:
+            y_true: tensor or dict. Ground truth values. If tensor, of shape
+                `(list_size)` for unbatched inputs or `(batch_size, list_size)`
+                for batched inputs. If an item has a label of -1, it is ignored
+                in loss computation. If it is a dictionary, it should have two
+                keys: `"labels"` and `"mask"`. `"mask"` can be used to ignore
+                elements in loss computation, i.e., pairs will not be formed
+                with those items. Note that the final mask is an and of the
+                passed mask, and `labels == -1`.
+            y_pred: tensor. The predicted values, of shape `(list_size)` for
+                unbatched inputs or `(batch_size, list_size)` for batched
+                inputs. Should be of the same shape as `y_true`.
+        """
+        mask = None
+        if isinstance(y_true, dict):
+            if "labels" not in y_true:
+                raise ValueError(
+                    '`"labels"` should be present in `y_true`. Received: '
+                    f"`y_true` = {y_true}"
+                )
+
+            mask = y_true.get("mask", None)
+            y_true = y_true["labels"]
+
+        y_true, y_pred, mask = process_loss_call_inputs(y_true, y_pred, mask)
+
+        losses, weights = self.compute_unreduced_loss(
+            labels=y_true, logits=y_pred, mask=mask
+        )
+        losses = ops.multiply(losses, weights)
+        losses = ops.sum(losses, axis=-1)
+        return losses
+
+
+pairwise_loss_subclass_doc_string = (
+    "Computes pairwise hinge loss between true labels and predicted scores."
+    """
+    This loss function is designed for ranking tasks, where the goal is to
+    correctly order items within each list. It computes the loss by comparing
+    pairs of items within each list, penalizing cases where an item with a
+    higher true label has a lower predicted score than an item with a lower
+    true label.
+
+    For each list of predicted scores `s` in `y_pred` and the corresponding list
+    of true labels `y` in `y_true`, the loss is computed as follows:
+
+    ```
+    {formula}
+    ```
+
+    where:
+      - `y_i` and `y_j` are the true labels of items `i` and `j`, respectively.
+      - `s_i` and `s_j` are the predicted scores of items `i` and `j`,
+        respectively.
+      - `I(y_i > y_j)` is an indicator function that equals 1 if `y_i > y_j`,
+        and 0 otherwise.{explanation}
+    Args:{extra_args}
+        reduction: Type of reduction to apply to the loss. In almost all cases
+            this should be `"sum_over_batch_size"`. Supported options are
+            `"sum"`, `"sum_over_batch_size"`, `"mean"`,
+            `"mean_with_sample_weight"` or `None`. `"sum"` sums the loss,
+            `"sum_over_batch_size"` and `"mean"` sum the loss and divide by the
+            sample size, and `"mean_with_sample_weight"` sums the loss and
+            divides by the sum of the sample weights. `"none"` and `None`
+            perform no aggregation. Defaults to `"sum_over_batch_size"`.
+        name: Optional name for the loss instance.
+        dtype: The dtype of the loss's computations. Defaults to `None`, which
+            means using `keras.backend.floatx()`. `keras.backend.floatx()` is a
+            `"float32"` unless set to different value
+            (via `keras.backend.set_floatx()`). If a `keras.DTypePolicy` is
+            provided, then the `compute_dtype` will be utilized.
+    """
+)

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/src/losses/pairwise_mean_squared_error.py

@@ -0,0 +1,71 @@
+from typing import Optional
+
+from keras import ops
+
+from keras_rs.src import types
+from keras_rs.src.api_export import keras_rs_export
+from keras_rs.src.losses.pairwise_loss import PairwiseLoss
+from keras_rs.src.losses.pairwise_loss import pairwise_loss_subclass_doc_string
+from keras_rs.src.utils.pairwise_loss_utils import apply_pairwise_op
+
+
+@keras_rs_export("keras_rs.losses.PairwiseMeanSquaredError")
+class PairwiseMeanSquaredError(PairwiseLoss):
+    def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
+        # Since we override `compute_unreduced_loss`, we do not need to
+        # implement this method.
+        pass
+
+    def compute_unreduced_loss(
+        self,
+        labels: types.Tensor,
+        logits: types.Tensor,
+        mask: Optional[types.Tensor] = None,
+    ) -> tuple[types.Tensor, types.Tensor]:
+        # Override `PairwiseLoss.compute_unreduced_loss` since pairwise weights
+        # for MSE are computed differently.
+
+        batch_size, list_size = ops.shape(labels)
+
+        # Mask all values less than 0 (since less than 0 implies invalid
+        # labels).
+        valid_mask = ops.greater_equal(labels, ops.cast(0.0, labels.dtype))
+
+        if mask is not None:
+            valid_mask = ops.logical_and(valid_mask, mask)
+
+        # Compute the difference for all pairs in a list. The output is a tensor
+        # with shape `(batch_size, list_size, list_size)`, where `[:, i, j]`
+        # stores information for pair `(i, j)`.
+        pairwise_labels_diff = apply_pairwise_op(labels, ops.subtract)
+        pairwise_logits_diff = apply_pairwise_op(logits, ops.subtract)
+        valid_pair = apply_pairwise_op(valid_mask, ops.logical_and)
+        pairwise_mse = ops.square(pairwise_labels_diff - pairwise_logits_diff)
+
+        # Compute weights.
+        pairwise_weights = ops.ones_like(pairwise_mse)
+        # Exclude self pairs.
+        pairwise_weights = ops.subtract(
+            pairwise_weights,
+            ops.tile(ops.eye(list_size, list_size), (batch_size, 1, 1)),
+        )
+        # Include only valid pairs.
+        pairwise_weights = ops.multiply(
+            pairwise_weights, ops.cast(valid_pair, dtype=pairwise_weights.dtype)
+        )
+
+        return pairwise_mse, pairwise_weights
+
+
+formula = "loss = sum_{i} sum_{j} I(y_i > y_j) * (s_i - s_j)^2"
+explanation = """
+      - `(s_i - s_j)^2` is the squared difference between the predicted scores
+        of items `i` and `j`, which penalizes discrepancies between the
+        predicted order of items relative to their true order.
+"""
+extra_args = ""
+PairwiseMeanSquaredError.__doc__ = pairwise_loss_subclass_doc_string.format(
+    formula=formula,
+    explanation=explanation,
+    extra_args=extra_args,
+)

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/src/losses/pairwise_soft_zero_one_loss.py

@@ -0,0 +1,31 @@
+from keras import ops
+
+from keras_rs.src import types
+from keras_rs.src.api_export import keras_rs_export
+from keras_rs.src.losses.pairwise_loss import PairwiseLoss
+from keras_rs.src.losses.pairwise_loss import pairwise_loss_subclass_doc_string
+
+
+@keras_rs_export("keras_rs.losses.PairwiseSoftZeroOneLoss")
+class PairwiseSoftZeroOneLoss(PairwiseLoss):
+    def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
+        return ops.where(
+            ops.greater(pairwise_logits, ops.array(0.0)),
+            ops.subtract(ops.array(1.0), ops.sigmoid(pairwise_logits)),
+            ops.sigmoid(ops.negative(pairwise_logits)),
+        )
+
+
+formula = "loss = sum_{i} sum_{j} I(y_i > y_j) * (1 - sigmoid(s_i - s_j))"
+explanation = """
+      - `(1 - sigmoid(s_i - s_j))` represents the soft zero-one loss, which
+        approximates the ideal zero-one loss (which would be 1 if `s_i < s_j`
+        and 0 otherwise) with a smooth, differentiable function. This makes it
+        suitable for gradient-based optimization.
+"""
+extra_args = ""
+PairwiseSoftZeroOneLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
+    formula=formula,
+    explanation=explanation,
+    extra_args=extra_args,
+)

keras_rs_nightly-0.0.1.dev2025031003/keras_rs/src/utils/pairwise_loss_utils.py

@@ -0,0 +1,100 @@
+from typing import Callable, Optional
+
+from keras import ops
+
+from keras_rs.src import types
+from keras_rs.src.utils.keras_utils import check_shapes_compatible
+
+
+def apply_pairwise_op(x: types.Tensor, op: ops) -> types.Tensor:
+    return op(
+        ops.expand_dims(x, axis=-1),
+        ops.expand_dims(x, axis=-2),
+    )
+
+
+def pairwise_comparison(
+    labels: types.Tensor,
+    logits: types.Tensor,
+    mask: types.Tensor,
+    logits_op: Callable[[types.Tensor, types.Tensor], types.Tensor],
+) -> tuple[types.Tensor, types.Tensor]:
+    # Compute the difference for all pairs in a list. The output is a tensor
+    # with shape `(batch_size, list_size, list_size)`, where `[:, i, j]` stores
+    # information for pair `(i, j)`.
+    pairwise_labels_diff = apply_pairwise_op(labels, ops.subtract)
+    pairwise_logits = apply_pairwise_op(logits, logits_op)
+
+    # Keep only those cases where `l_i < l_j`.
+    pairwise_labels = ops.cast(
+        ops.greater(pairwise_labels_diff, 0), dtype=labels.dtype
+    )
+    if mask is not None:
+        valid_pairs = apply_pairwise_op(mask, ops.logical_and)
+        pairwise_labels = ops.multiply(
+            pairwise_labels, ops.cast(valid_pairs, dtype=pairwise_labels.dtype)
+        )
+
+    return pairwise_labels, pairwise_logits
+
+
+def process_loss_call_inputs(
+    y_true: types.Tensor,
+    y_pred: types.Tensor,
+    mask: Optional[types.Tensor] = None,
+) -> tuple[types.Tensor, types.Tensor, Optional[types.Tensor]]:
+    """
+    Utility function for processing inputs for pairwise losses.
+
+    This utility function does three things:
+
+    - Checks that `y_true`, `y_pred` are of rank 1 or 2;
+    - Checks that `y_true`, `y_pred`, `mask` have the same shape;
+    - Adds batch dimension if rank = 1.
+    """
+
+    y_true_shape = ops.shape(y_true)
+    y_true_rank = len(y_true_shape)
+    y_pred_shape = ops.shape(y_pred)
+    y_pred_rank = len(y_pred_shape)
+    if mask is not None:
+        mask_shape = ops.shape(mask)
+        mask_rank = len(mask_shape)
+
+    # Check ranks and shapes.
+    def check_rank(
+        x_rank: int,
+        allowed_ranks: tuple[int, ...] = (1, 2),
+        tensor_name: Optional[str] = None,
+    ) -> None:
+        if x_rank not in allowed_ranks:
+            raise ValueError(
+                f"`{tensor_name}` should have a rank from `{allowed_ranks}`."
+                f"Received: `{x_rank}`."
+            )
+
+    check_rank(y_true_rank, tensor_name="y_true")
+    check_rank(y_pred_rank, tensor_name="y_pred")
+    if mask is not None:
+        check_rank(mask_rank, tensor_name="mask")
+    if not check_shapes_compatible(y_true_shape, y_pred_shape):
+        raise ValueError(
+            "`y_true` and `y_pred` should have the same shape. Received: "
+            f"`y_true.shape` = {y_true_shape}, `y_pred.shape` = {y_pred_shape}."
+        )
+    if mask is not None and not check_shapes_compatible(
+        y_true_shape, mask_shape
+    ):
+        raise ValueError(
+            "`y_true['labels']` and `y_true['mask']` should have the same "
+            f"shape. Received: `y_true['labels'].shape` = {y_true_shape}, "
+            f"`y_true['mask'].shape` = {mask_shape}."
+        )
+
+    if y_true_rank == 1:
+        y_true = ops.expand_dims(y_true, axis=0)
+        y_pred = ops.expand_dims(y_pred, axis=0)
+        if mask is not None:
+            mask = ops.expand_dims(mask, axis=0)
+
+    return y_true, y_pred, mask

{keras_rs_nightly-0.0.1.dev2025030803 → keras_rs_nightly-0.0.1.dev2025031003}/keras_rs/src/version.py

@@ -1,7 +1,7 @@
 from keras_rs.src.api_export import keras_rs_export
 
 # Unique source of truth for the version number.
-__version__ = "0.0.1.dev2025030803"
+__version__ = "0.0.1.dev2025031003"
 
 
 @keras_rs_export("keras_rs.version")

{keras_rs_nightly-0.0.1.dev2025030803 → keras_rs_nightly-0.0.1.dev2025031003}/keras_rs_nightly.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: keras-rs-nightly
-Version: 0.0.1.dev2025030803
+Version: 0.0.1.dev2025031003
 Summary: Multi-backend recommender systems with Keras 3.
 Author-email: Keras RS team <keras-rs@google.com>
 License: Apache License 2.0

{keras_rs_nightly-0.0.1.dev2025030803 → keras_rs_nightly-0.0.1.dev2025031003}/keras_rs_nightly.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 keras_rs/__init__.py
 keras_rs/api/__init__.py
 keras_rs/api/layers/__init__.py
+keras_rs/api/losses/__init__.py
 keras_rs/src/__init__.py
 keras_rs/src/api_export.py
 keras_rs/src/types.py
@@ -15,8 +16,15 @@ keras_rs/src/layers/retrieval/__init__.py
 keras_rs/src/layers/retrieval/brute_force_retrieval.py
 keras_rs/src/layers/retrieval/hard_negative_mining.py
 keras_rs/src/layers/retrieval/sampling_probability_correction.py
+keras_rs/src/losses/__init__.py
+keras_rs/src/losses/pairwise_hinge_loss.py
+keras_rs/src/losses/pairwise_logistic_loss.py
+keras_rs/src/losses/pairwise_loss.py
+keras_rs/src/losses/pairwise_mean_squared_error.py
+keras_rs/src/losses/pairwise_soft_zero_one_loss.py
 keras_rs/src/utils/__init__.py
 keras_rs/src/utils/keras_utils.py
+keras_rs/src/utils/pairwise_loss_utils.py
 keras_rs_nightly.egg-info/PKG-INFO
 keras_rs_nightly.egg-info/SOURCES.txt
 keras_rs_nightly.egg-info/dependency_links.txt