keras-rs-nightly 0.0.1.dev2025042803__py3-none-any.whl → 0.0.1.dev2025043003__py3-none-any.whl

keras_rs/src/layers/feature_interaction/dot_interaction.py

@@ -30,6 +30,53 @@ class DotInteraction(keras.layers.Layer):
             but is much slower.
         **kwargs: Args to pass to the base class.
 
+    Example:
+
+    ```python
+    # 1. Simple forward pass
+    batch_size = 2
+    embedding_dim = 32
+    feature1 = np.random.randn(batch_size, embedding_dim)
+    feature2 = np.random.randn(batch_size, embedding_dim)
+    feature3 = np.random.randn(batch_size, embedding_dim)
+    feature_interactions = keras_rs.layers.DotInteraction()(
+        [feature1, feature2, feature3]
+    )
+
+    # 2. After embedding layer in a model
+    vocabulary_size = 32
+    embedding_dim = 6
+
+    # Create a simple model containing the layer.
+    feature_input_1 = keras.Input(shape=(), name='indices_1', dtype="int32")
+    feature_input_2 = keras.Input(shape=(), name='indices_2', dtype="int32")
+    feature_input_3 = keras.Input(shape=(), name='indices_3', dtype="int32")
+    x1 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(feature_input_1)
+    x2 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(feature_input_2)
+    x3 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(feature_input_3)
+    feature_interactions = keras_rs.layers.DotInteraction()([x1, x2, x3])
+    output = keras.layers.Dense(units=10)(x2)
+    model = keras.Model(
+        [feature_input_1, feature_input_2, feature_input_3], output
+    )
+
+    # Call the model on the inputs.
+    batch_size = 2
+    f1 = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    f2 = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    f3 = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    outputs = model([f1, f2, f3])
+    ```
+
     References:
     - [M. Naumov et al.](https://arxiv.org/abs/1906.00091)
     """

keras_rs/src/layers/feature_interaction/feature_cross.py

@@ -57,13 +57,32 @@ class FeatureCross(keras.layers.Layer):
     Example:
 
     ```python
-    # after embedding layer in a functional model
-    input = keras.Input(shape=(), name='indices', dtype="int64")
-    x0 = keras.layers.Embedding(input_dim=32, output_dim=6)(x0)
-    x1 = FeatureCross()(x0, x0)
-    x2 = FeatureCross()(x0, x1)
+    # 1. Simple forward pass
+    batch_size = 2
+    embedding_dim = 32
+    feature1 = np.random.randn(batch_size, embedding_dim)
+    feature2 = np.random.randn(batch_size, embedding_dim)
+    crossed_features = keras_rs.layers.FeatureCross()(feature1, feature2)
+
+    # 2. After embedding layer in a model
+    vocabulary_size = 32
+    embedding_dim = 6
+
+    # Create a simple model containing the layer.
+    inputs = keras.Input(shape=(), name='indices', dtype="int32")
+    x0 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(inputs)
+    x1 = keras_rs.layers.FeatureCross()(x0, x0)
+    x2 = keras_rs.layers.FeatureCross()(x0, x1)
     logits = keras.layers.Dense(units=10)(x2)
-    model = keras.Model(input, logits)
+    model = keras.Model(inputs, logits)
+
+    # Call the model on the inputs.
+    batch_size = 2
+    input_data = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    outputs = model(input_data)
     ```
 
     References:

keras_rs/src/layers/retrieval/hard_negative_mining.py

@@ -12,11 +12,27 @@ MAX_FLOAT = ml_dtypes.finfo("float32").max / 100.0
 
 @keras_rs_export("keras_rs.layers.HardNegativeMining")
 class HardNegativeMining(keras.layers.Layer):
-    """Transforms logits and labels to return hard negatives.
+    """Filter logits and labels to return hard negatives.
+
+    The output will include logits and labels for the requested number of hard
+    negatives as well as the positive candidate.
 
     Args:
         num_hard_negatives: How many hard negatives to return.
         **kwargs: Args to pass to the base class.
+
+    Example:
+
+    ```python
+    # Create layer with the configured number of hard negatives to mine.
+    hard_negative_mining = keras_rs.layers.HardNegativeMining(
+        num_hard_negatives=10
+    )
+
+    # This will retrieve the top 10 negative candidates plus the positive
+    # candidate from `labels` for each row.
+    out_logits, out_labels = hard_negative_mining(in_logits, in_labels)
+    ```
     """
 
     def __init__(self, num_hard_negatives: int, **kwargs: Any) -> None:
@@ -33,15 +49,17 @@ class HardNegativeMining(keras.layers.Layer):
         negatives as well as the positive candidate.
 
         Args:
-            logits: logits tensor, typically `[batch_size, num_candidates]` but
-                can have more dimensions or be 1D as `[num_candidates]`.
-            labels: one-hot labels tensor, must be the same shape as `logits`.
+            logits: The logits tensor, typically `[batch_size, num_candidates]`
+                but can have more dimensions or be 1D as `[num_candidates]`.
+            labels: The one-hot labels tensor, must be the same shape as
+                `logits`.
 
         Returns:
-            tuple containing two tensors with the last dimension of
+            A tuple containing two tensors with the last dimension of
             `num_candidates` replaced with `num_hard_negatives + 1`.
-            - logits: `[..., num_hard_negatives + 1]` tensor of logits.
-            - labels: `[..., num_hard_negatives + 1]` one-hot tensor of labels.
+
+        * logits: `[..., num_hard_negatives + 1]` tensor of logits.
+        * labels: `[..., num_hard_negatives + 1]` one-hot tensor of labels.
         """
 
         # Number of sampled logits, i.e, the number of hard negatives to be

keras_rs/src/layers/retrieval/remove_accidental_hits.py

@@ -15,6 +15,18 @@ class RemoveAccidentalHits(keras.layers.Layer):
 
     Zeroes the logits of negative candidates that have the same ID as the
     positive candidate in that row.
+
+    Example:
+
+    ```python
+    # Create layer with the configured number of hard negatives to mine.
+    remove_accidental_hits = keras_rs.layers.RemoveAccidentalHits()
+
+    # This will zero the logits of negative candidates that have the same ID as
+    # the positive candidate from `labels` so as to not negatively impact the
+    # true positive.
+    logits = remove_accidental_hits(logits, labels, candidate_ids)
+    ```
     """
 
     def call(
@@ -29,16 +41,17 @@ class RemoveAccidentalHits(keras.layers.Layer):
         have the same ID as the positive candidate in that row.
 
         Args:
-            logits: logits tensor, typically `[batch_size, num_candidates]` but
-                can have more dimensions or be 1D as `[num_candidates]`.
-            labels: one-hot labels tensor, must be the same shape as `logits`.
-            candidate_ids: candidate identifiers tensor, can be
+            logits: The logits tensor, typically `[batch_size, num_candidates]`
+                but can have more dimensions or be 1D as `[num_candidates]`.
+            labels: The one-hot labels tensor, must be the same shape as
+                `logits`.
+            candidate_ids: The candidate identifiers tensor, can be
                 `[num_candidates]` or `[batch_size, num_candidates]` or have
                 more dimensions as long as they match the last dimensions of
                 `labels`.
 
         Returns:
-            logits: Modified logits with the same shape as the input logits.
+            The modified logits with the same shape as the input logits.
         """
         # A more principled way is to implement
         # `softmax_cross_entropy_with_logits` with a input mask. Here we

keras_rs/src/layers/retrieval/sampling_probability_correction.py

@@ -17,6 +17,18 @@ class SamplingProbabilityCorrection(keras.layers.Layer):
         epsilon: float. Small float added to sampling probability to avoid
             taking the log of zero. Defaults to 1e-6.
         **kwargs: Args to pass to the base class.
+
+    Example:
+
+    ```python
+    # Create the layer.
+    sampling_probability_correction = (
+        keras_rs.layers.SamplingProbabilityCorrection()
+    )
+
+    # Correct the logits based on the provided candidate sampling probability.
+    logits = sampling_probability_correction(logits, probabilities)
+    ```
     """
 
     def __init__(self, epsilon: float = 1e-6, **kwargs: Any) -> None:
@@ -32,11 +44,14 @@ class SamplingProbabilityCorrection(keras.layers.Layer):
         """Corrects input logits to account for candidate sampling probability.
 
         Args:
-            logits: The logits to correct.
-            candidate_sampling_probability: The sampling probability.
+            logits: The logits tensor to correct, typically
+                `[batch_size, num_candidates]` but can have more dimensions or
+                be 1D as `[num_candidates]`.
+            candidate_sampling_probability: The sampling probability with the
+                same shape as `logits`.
 
         Returns:
-            The corrected logits.
+            The corrected logits with the same shape as the input logits.
         """
         return logits - ops.log(
             ops.clip(candidate_sampling_probability, self.epsilon, 1.0)

keras_rs/src/losses/pairwise_hinge_loss.py

@@ -14,14 +14,77 @@ class PairwiseHingeLoss(PairwiseLoss):
 
 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`.
+    - `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 = ""
+example = """
+    With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseHingeLoss(),
+        ...
+    )
+    ```
+
+    As a standalone function with unbatched inputs:
+
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss()
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    2.32000
+
+    With batched inputs using default 'auto'/'sum_over_batch_size' reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss()
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    0.75
+
+    With masked inputs (useful for ragged inputs):
+
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    0.64999
+
+    With `sample_weight`:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss()
+    >>> pairwise_hinge_loss(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    1.02499
+
+    Using `'none'` reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    [[3. , 0. , 2. , 0.], [0., 0.20000005, 0.79999995, 0.]]
+"""
+
 PairwiseHingeLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="hinge loss",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/losses/pairwise_logistic_loss.py

@@ -22,15 +22,78 @@ class PairwiseLogisticLoss(PairwiseLoss):
 
 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.
+    - `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 = ""
+example = """
+    With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseLogisticLoss(),
+        ...
+    )
+    ```
+
+    As a standalone function with unbatched inputs:
+
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss()
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    >>> 1.70708
+
+    With batched inputs using default 'auto'/'sum_over_batch_size' reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss()
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    0.73936
+
+    With masked inputs (useful for ragged inputs):
+
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    0.53751
+
+    With `sample_weight`:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss()
+    >>> pairwise_logistic_loss(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    >>> 0.80337
+
+    Using `'none'` reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    [[2.126928, 0., 1.3132616, 0.48877698], [0., 0.20000005, 0.79999995, 0.]]
+"""
+
 PairwiseLogisticLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="logistic loss",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/losses/pairwise_loss.py

@@ -70,7 +70,8 @@ class PairwiseLoss(keras.losses.Loss, abc.ABC):
         y_true: types.Tensor,
         y_pred: types.Tensor,
     ) -> types.Tensor:
-        """
+        """Compute the pairwise loss.
+
         Args:
             y_true: tensor or dict. Ground truth values. If tensor, of shape
                 `(list_size)` for unbatched inputs or `(batch_size, list_size)`
@@ -83,6 +84,9 @@ class PairwiseLoss(keras.losses.Loss, abc.ABC):
             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`.
+
+        Returns:
+            The loss.
         """
         mask = None
         if isinstance(y_true, dict):
@@ -134,11 +138,12 @@ pairwise_loss_subclass_doc_string = (
     ```
 
     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}
+
+    - `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
@@ -154,5 +159,7 @@ pairwise_loss_subclass_doc_string = (
             `"float32"` unless set to different value
             (via `keras.backend.set_floatx()`). If a `keras.DTypePolicy` is
             provided, then the `compute_dtype` will be utilized.
-    """
+
+    Examples:
+{example}"""
 )

keras_rs/src/losses/pairwise_mean_squared_error.py

@@ -59,14 +59,77 @@ class PairwiseMeanSquaredError(PairwiseLoss):
 
 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.
+    - `(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 = ""
+example = """
+    With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseMeanSquaredError(),
+        ...
+    )
+    ```
+
+    As a standalone function with unbatched inputs:
+
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError()
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    >>> 19.10400
+
+    With batched inputs using default 'auto'/'sum_over_batch_size' reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError()
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    5.57999
+    
+    With masked inputs (useful for ragged inputs):
+
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    4.76000
+
+    With `sample_weight`:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError()
+    >>> pairwise_mse(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    11.0500
+
+    Using `'none'` reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    [[11., 17.,  5.,  5.], [2.04, 1.3199998, 1.6399999, 1.6399999]]
+"""
+
 PairwiseMeanSquaredError.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="mean squared error",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/losses/pairwise_soft_zero_one_loss.py

@@ -18,15 +18,81 @@ class PairwiseSoftZeroOneLoss(PairwiseLoss):
 
 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.
+    - `(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 = ""
+example = """
+    With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseSoftZeroOneLoss(),
+        ...
+    )
+    ```
+
+    As a standalone function with unbatched inputs:
+
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss()
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    0.86103
+
+    With batched inputs using default 'auto'/'sum_over_batch_size' reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss()
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    0.46202
+
+    With masked inputs (useful for ragged inputs):
+
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    0.29468
+
+    With `sample_weight`:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss()
+    >>> pairwise_soft_zero_one_loss(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    0.40478
+
+    Using `'none'` reduction:
+
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    [
+        [0.8807971 , 0., 0.73105854, 0.43557024],
+        [0., 0.31002545, 0.7191075 , 0.61961967]
+    ]
+"""
+
 PairwiseSoftZeroOneLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="soft zero-one loss",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/metrics/dcg.py

@@ -11,7 +11,7 @@ from keras_rs.src.metrics.ranking_metric import (
     ranking_metric_subclass_doc_string,
 )
 from keras_rs.src.metrics.ranking_metric import (
-    ranking_metric_subclass_doc_string_args,
+    ranking_metric_subclass_doc_string_post_desc,
 )
 from keras_rs.src.metrics.ranking_metrics_utils import compute_dcg
 from keras_rs.src.metrics.ranking_metrics_utils import default_gain_fn
@@ -111,22 +111,41 @@ DCG@k(y', w') = sum_{i=1}^{k} (gain_fn(y'_i) / rank_discount_fn(i))
 ```
 
 where:
-    - `y'_i` is the true relevance score of the item ranked at position `i`
-        (obtained by sorting `y_true` according to `y_pred`).
-    - `gain_fn` is the user-provided function mapping relevance `y'_i` to a
-        gain value. The default function (`default_gain_fn`) is typically
-        equivalent to `lambda y: 2**y - 1`.
-    - `rank_discount_fn` is the user-provided function mapping rank `i`
-        to a discount value. The default function (`default_rank_discount_fn`)
-        is typically equivalent to `lambda rank: 1 / log2(rank + 1)`.
-    - The final result aggregates these per-list scores.
-"""
+- `y'_i` is the true relevance score of the item ranked at position `i`
+  (obtained by sorting `y_true` according to `y_pred`).
+- `gain_fn` is the user-provided function mapping relevance `y'_i` to a
+  gain value. The default function (`default_gain_fn`) is typically
+  equivalent to `lambda y: 2**y - 1`.
+- `rank_discount_fn` is the user-provided function mapping rank `i`
+  to a discount value. The default function (`default_rank_discount_fn`)
+  is typically equivalent to `lambda rank: 1 / log2(rank + 1)`.
+- The final result aggregates these per-list scores."""
 extra_args = """
         gain_fn: callable. Maps relevance scores (`y_true`) to gain values. The
             default implements `2**y - 1`.
         rank_discount_fn: function. Maps rank positions to discount
             values. The default (`default_rank_discount_fn`) implements
             `1 / log2(rank + 1)`."""
+example = """
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 3, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> metric = keras_rs.metrics.DCG()(
+    ...     y_true=labels, y_pred=scores
+    ... )
+
+    Mask certain elements (can be used for uneven inputs):
+
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 3, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> mask = np.random.randint(0, 2, size=(batch_size, list_size), dtype=bool)
+    >>> metric = keras_rs.metrics.DCG()(
+    ...     y_true={"labels": labels, "mask": mask}, y_pred=scores
+    ... )
+"""
 
 DCG.__doc__ = format_docstring(
     ranking_metric_subclass_doc_string,
@@ -137,4 +156,6 @@ DCG.__doc__ = format_docstring(
     relevance_type=relevance_type,
     score_range_interpretation=score_range_interpretation,
     formula=formula,
-) + ranking_metric_subclass_doc_string_args.format(extra_args=extra_args)
+) + ranking_metric_subclass_doc_string_post_desc.format(
+    extra_args=extra_args, example=example
+)

keras_rs/src/metrics/mean_average_precision.py

@@ -7,7 +7,7 @@ from keras_rs.src.metrics.ranking_metric import (
     ranking_metric_subclass_doc_string,
 )
 from keras_rs.src.metrics.ranking_metric import (
-    ranking_metric_subclass_doc_string_args,
+    ranking_metric_subclass_doc_string_post_desc,
 )
 from keras_rs.src.metrics.ranking_metrics_utils import get_list_weights
 from keras_rs.src.metrics.ranking_metrics_utils import sort_by_scores
@@ -82,23 +82,39 @@ rel(j) = y_i if rank(s_i) = j
 ```
 
 where:
-    - `j` represents the rank position (starting from 1).
-    - `sum_j` indicates a summation over all ranks `j` from 1 up to the list
-        size (or `k`).
-    - `P@j(y, s)` denotes the Precision at rank `j`, calculated as the
-        number of relevant items found within the top `j` positions divided by
-        `j`.
-    - `rel(j)` represents the relevance of the item specifically at rank
-        `j`. `rel(j)` is 1 if the item at rank `j` is relevant, and 0
-        otherwise.
-    - `y_i` is the true relevance label of the original item `i` before
-        ranking.
-    - `rank(s_i)` is the rank position assigned to item `i` based on its
-        score `s_i`.
-    - `sum_i y_i` calculates the total number of relevant items in the
-        original list `y`.
-"""
+- `j` represents the rank position (starting from 1).
+- `sum_j` indicates a summation over all ranks `j` from 1 up to the list
+  size (or `k`).
+- `P@j(y, s)` denotes the Precision at rank `j`, calculated as the
+  number of relevant items found within the top `j` positions divided by `j`.
+- `rel(j)` represents the relevance of the item specifically at rank
+  `j`. `rel(j)` is 1 if the item at rank `j` is relevant, and 0 otherwise.
+- `y_i` is the true relevance label of the original item `i` before ranking.
+- `rank(s_i)` is the rank position assigned to item `i` based on its score
+  `s_i`.
+- `sum_i y_i` calculates the total number of relevant items in the original
+  list `y`."""
 extra_args = ""
+example = """
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> metric = keras_rs.metrics.MeanAveragePrecision()(
+    ...     y_true=labels, y_pred=scores
+    ... )
+
+    Mask certain elements (can be used for uneven inputs):
+
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> mask = np.random.randint(0, 2, size=(batch_size, list_size), dtype=bool)
+    >>> metric = keras_rs.metrics.MeanAveragePrecision()(
+    ...     y_true={"labels": labels, "mask": mask}, y_pred=scores
+    ... )
+"""
 
 MeanAveragePrecision.__doc__ = format_docstring(
     ranking_metric_subclass_doc_string,
@@ -109,4 +125,6 @@ MeanAveragePrecision.__doc__ = format_docstring(
     relevance_type=relevance_type,
     score_range_interpretation=score_range_interpretation,
     formula=formula,
-) + ranking_metric_subclass_doc_string_args.format(extra_args=extra_args)
+) + ranking_metric_subclass_doc_string_post_desc.format(
+    extra_args=extra_args, example=example
+)

keras_rs/src/metrics/mean_reciprocal_rank.py

@@ -7,7 +7,7 @@ from keras_rs.src.metrics.ranking_metric import (
     ranking_metric_subclass_doc_string,
 )
 from keras_rs.src.metrics.ranking_metric import (
-    ranking_metric_subclass_doc_string_args,
+    ranking_metric_subclass_doc_string_post_desc,
 )
 from keras_rs.src.metrics.ranking_metrics_utils import get_list_weights
 from keras_rs.src.metrics.ranking_metrics_utils import sort_by_scores
@@ -86,6 +86,27 @@ formula = """```
 MRR(y, s) = max_{i} y_{i} / rank(s_{i})
 ```"""
 extra_args = ""
+example = """
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> metric = keras_rs.metrics.MeanReciprocalRank()(
+    ...     y_true=labels, y_pred=scores
+    ... )
+
+    Mask certain elements (can be used for uneven inputs):
+
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> mask = np.random.randint(0, 2, size=(batch_size, list_size), dtype=bool)
+    >>> metric = keras_rs.metrics.MeanReciprocalRank()(
+    ...     y_true={"labels": labels, "mask": mask}, y_pred=scores
+    ... )
+"""
+
 MeanReciprocalRank.__doc__ = format_docstring(
     ranking_metric_subclass_doc_string,
     width=80,
@@ -95,4 +116,6 @@ MeanReciprocalRank.__doc__ = format_docstring(
     relevance_type=relevance_type,
     score_range_interpretation=score_range_interpretation,
     formula=formula,
-) + ranking_metric_subclass_doc_string_args.format(extra_args=extra_args)
+) + ranking_metric_subclass_doc_string_post_desc.format(
+    extra_args=extra_args, example=example
+)

keras_rs/src/metrics/ndcg.py

@@ -11,7 +11,7 @@ from keras_rs.src.metrics.ranking_metric import (
     ranking_metric_subclass_doc_string,
 )
 from keras_rs.src.metrics.ranking_metric import (
-    ranking_metric_subclass_doc_string_args,
+    ranking_metric_subclass_doc_string_post_desc,
 )
 from keras_rs.src.metrics.ranking_metrics_utils import compute_dcg
 from keras_rs.src.metrics.ranking_metrics_utils import default_gain_fn
@@ -109,7 +109,7 @@ class NDCG(RankingMetric):
 
 concept_sentence = (
     "It normalizes the Discounted Cumulative Gain (DCG) with the Ideal "
-    "Discounted Cumulative Gain (IDCG) for each list."
+    "Discounted Cumulative Gain (IDCG) for each list"
 )
 relevance_type = (
     "graded relevance scores (non-negative numbers where higher values "
@@ -124,11 +124,6 @@ score_range_interpretation = (
 )
 
 formula = """
-The metric calculates a weighted average nDCG score per list.
-For a single list, nDCG is computed as the ratio of the Discounted
-Cumulative Gain (DCG) of the predicted ranking to the Ideal Discounted
-Cumulative Gain (IDCG) of the best possible ranking:
-
 ```
 nDCG@k = DCG@k / IDCG@k
 ```
@@ -147,28 +142,44 @@ IDCG@k(y'') = sum_{i=1}^{k} (gain_fn(y''_i) / rank_discount_fn(i))
 ```
 
 where:
-    - `y'_i`: True relevance of the item at rank `i` in
-        the ranking induced by `y_pred`.
-    - `y''_i` True relevance of the item at rank `i` in
-        the *ideal* ranking (sorted by `y_true` descending).
-    - `gain_fn` is the user-provided function mapping relevance to gain.
-        The default function (`default_gain_fn`) is typically equivalent to
-        `lambda y: 2**y - 1`.
-    - `rank_discount_fn` is the user-provided function mapping rank `i`
-        (1-based) to a discount value. The default function
-        (`default_rank_discount_fn`) is typically equivalent to
-        `lambda rank: 1 / log2(rank + 1)`.
-    - If IDCG@k is 0 (e.g., no relevant items), nDCG@k is defined as 0.
-    - The final result often aggregates these per-list nDCG scores,
-        potentially involving normalization by list-specific weights, to
-        produce a weighted average.
-"""
+- `y'_i`: True relevance of the item at rank `i` in the ranking induced by
+  `y_pred`.
+- `y''_i` True relevance of the item at rank `i` in the *ideal* ranking (sorted
+  by `y_true` descending).
+- `gain_fn` is the user-provided function mapping relevance to gain. The default
+  function (`default_gain_fn`) is typically equivalent to `lambda y: 2**y - 1`.
+- `rank_discount_fn` is the user-provided function mapping rank `i` (1-based) to
+  a discount value. The default function (`default_rank_discount_fn`) is
+  typically equivalent to `lambda rank: 1 / log2(rank + 1)`.
+- If IDCG@k is 0 (e.g., no relevant items), nDCG@k is defined as 0.
+- The final result often aggregates these per-list nDCG scores, potentially
+  involving normalization by list-specific weights, to produce a weighted
+  average."""
 extra_args = """
-gain_fn: callable. Maps relevance scores (`y_true`) to gain values. The
-    default implements `2**y - 1`. Used for both DCG and IDCG.
-rank_discount_fn: callable. Maps rank positions (1-based) to discount
-    values. The default (`default_rank_discount_fn`) typically implements
-    `1 / log2(rank + 1)`. Used for both DCG and IDCG.
+        gain_fn: callable. Maps relevance scores (`y_true`) to gain values. The
+            default implements `2**y - 1`.
+        rank_discount_fn: function. Maps rank positions to discount
+            values. The default (`default_rank_discount_fn`) implements
+            `1 / log2(rank + 1)`."""
+example = """
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 3, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> metric = keras_rs.metrics.NDCG()(
+    ...     y_true=labels, y_pred=scores
+    ... )
+
+    Mask certain elements (can be used for uneven inputs):
+
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 3, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> mask = np.random.randint(0, 2, size=(batch_size, list_size), dtype=bool)
+    >>> metric = keras_rs.metrics.NDCG()(
+    ...     y_true={"labels": labels, "mask": mask}, y_pred=scores
+    ... )
 """
 
 NDCG.__doc__ = format_docstring(
@@ -181,4 +192,6 @@ NDCG.__doc__ = format_docstring(
     score_range_interpretation=score_range_interpretation,
     formula=formula,
     extra_args=extra_args,
-) + ranking_metric_subclass_doc_string_args.format(extra_args=extra_args)
+) + ranking_metric_subclass_doc_string_post_desc.format(
+    extra_args=extra_args, example=example
+)

keras_rs/src/metrics/precision_at_k.py

@@ -7,7 +7,7 @@ from keras_rs.src.metrics.ranking_metric import (
     ranking_metric_subclass_doc_string,
 )
 from keras_rs.src.metrics.ranking_metric import (
-    ranking_metric_subclass_doc_string_args,
+    ranking_metric_subclass_doc_string_post_desc,
 )
 from keras_rs.src.metrics.ranking_metrics_utils import get_list_weights
 from keras_rs.src.metrics.ranking_metrics_utils import sort_by_scores
@@ -82,6 +82,27 @@ P@k(y, s) = 1/k sum_i I[rank(s_i) < k] y_i
 where `y_i` is the relevance label (0/1) of the item ranked at position
 `i`, and `I[condition]` is 1 if the condition is met, otherwise 0."""
 extra_args = ""
+example = """
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> metric = keras_rs.metrics.PrecisionAtK()(
+    ...     y_true=labels, y_pred=scores
+    ... )
+
+    Mask certain elements (can be used for uneven inputs):
+
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> mask = np.random.randint(0, 2, size=(batch_size, list_size), dtype=bool)
+    >>> metric = keras_rs.metrics.PrecisionAtK()(
+    ...     y_true={"labels": labels, "mask": mask}, y_pred=scores
+    ... )
+"""
+
 PrecisionAtK.__doc__ = format_docstring(
     ranking_metric_subclass_doc_string,
     width=80,
@@ -91,4 +112,6 @@ PrecisionAtK.__doc__ = format_docstring(
     relevance_type=relevance_type,
     score_range_interpretation=score_range_interpretation,
     formula=formula,
-) + ranking_metric_subclass_doc_string_args.format(extra_args=extra_args)
+) + ranking_metric_subclass_doc_string_post_desc.format(
+    extra_args=extra_args, example=example
+)

keras_rs/src/metrics/ranking_metric.py

@@ -221,7 +221,6 @@ by sorting in descending order. {score_range_interpretation}.
 For each list of predicted scores `s` in `y_pred` and the corresponding list
 of true labels `y` in `y_true`, the per-query {metric_abbreviation} score is
 calculated as follows:
-
 {formula}
 
 The final {metric_abbreviation} score reported is typically the weighted
@@ -235,7 +234,7 @@ to get 1D weights. For more details, refer to
 `keras_rs.src.metrics.ranking_metrics_utils.get_list_weights`.
 """
 
-ranking_metric_subclass_doc_string_args = """
+ranking_metric_subclass_doc_string_post_desc = """
 
     Args:{extra_args}
         k: int. The number of top-ranked items to consider (the 'k' in 'top-k').
@@ -249,4 +248,7 @@ ranking_metric_subclass_doc_string_args = """
             `"float32"` unless set to different value
             (via `keras.backend.set_floatx()`). If a `keras.DTypePolicy` is
             provided, then the `compute_dtype` will be utilized.
+
+    Example:
+{example}
 """

keras_rs/src/metrics/recall_at_k.py

@@ -7,7 +7,7 @@ from keras_rs.src.metrics.ranking_metric import (
     ranking_metric_subclass_doc_string,
 )
 from keras_rs.src.metrics.ranking_metric import (
-    ranking_metric_subclass_doc_string_args,
+    ranking_metric_subclass_doc_string_post_desc,
 )
 from keras_rs.src.metrics.ranking_metrics_utils import get_list_weights
 from keras_rs.src.metrics.ranking_metrics_utils import sort_by_scores
@@ -73,6 +73,27 @@ R@k(y, s) = sum_i I[rank(s_i) < k] y_i / sum_j y_j
 where `y_i` is the relevance label (0/1) of the item ranked at position
 `i`, `I[condition]` is 1 if the condition is met, otherwise 0."""
 extra_args = ""
+example = """
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> metric = keras_rs.metrics.RecallAtK()(
+    ...     y_true=labels, y_pred=scores
+    ... )
+
+    Mask certain elements (can be used for uneven inputs):
+
+    >>> batch_size = 2
+    >>> list_size = 5
+    >>> labels = np.random.randint(0, 2, size=(batch_size, list_size))
+    >>> scores = np.random.random(size=(batch_size, list_size))
+    >>> mask = np.random.randint(0, 2, size=(batch_size, list_size), dtype=bool)
+    >>> metric = keras_rs.metrics.RecallAtK()(
+    ...     y_true={"labels": labels, "mask": mask}, y_pred=scores
+    ... )
+"""
+
 RecallAtK.__doc__ = format_docstring(
     ranking_metric_subclass_doc_string,
     width=80,
@@ -82,4 +103,6 @@ RecallAtK.__doc__ = format_docstring(
     relevance_type=relevance_type,
     score_range_interpretation=score_range_interpretation,
     formula=formula,
-) + ranking_metric_subclass_doc_string_args.format(extra_args=extra_args)
+) + ranking_metric_subclass_doc_string_post_desc.format(
+    extra_args=extra_args, example=example
+)

keras_rs/src/utils/doc_string_utils.py

@@ -30,8 +30,13 @@ def format_docstring(template: str, width: int = 80, **kwargs: Any) -> str:
                 textwrap.indent(formula_dedented, base_indent_str)
             )
         elif "where:" in stripped_block:
+            # Expect this to be already indented.
+            splitted_block = stripped_block.split("\n")
             processed_output.append(
-                textwrap.indent(stripped_block, base_indent_str)
+                textwrap.indent(
+                    splitted_block[0] + "\n\n" + "\n".join(splitted_block[1:]),
+                    base_indent_str,
+                )
             )
         else:
             processed_output.append(

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.dev2025042803"
+__version__ = "0.0.1.dev2025043003"
 
 
 @keras_rs_export("keras_rs.version")

{keras_rs_nightly-0.0.1.dev2025042803.dist-info → keras_rs_nightly-0.0.1.dev2025043003.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keras-rs-nightly
-Version: 0.0.1.dev2025042803
+Version: 0.0.1.dev2025043003
 Summary: Multi-backend recommender systems with Keras 3.
 Author-email: Keras team <keras-users@googlegroups.com>
 License: Apache License 2.0
@@ -36,6 +36,80 @@ This library is an extension of the core Keras API; all high-level modules
 receive that same level of polish as core Keras. If you are familiar with Keras,
 congratulations! You already understand most of Keras Recommenders.
 
+## Quick Links
+
+- [Home page](https://keras.io/keras_rs)
+- [Examples](https://keras.io/keras_rs/examples)
+- [API documentation](https://keras.io/keras_rs/api)
+
+## Quickstart
+
+### Train your own cross network
+
+Choose a backend:
+
+```python
+import os
+os.environ["KERAS_BACKEND"] = "jax"  # Or "tensorflow" or "torch"!
+```
+
+Import KerasRS and other libraries:
+
+```python
+import keras
+import keras_rs
+import numpy as np
+```
+
+Define a simple model using the `FeatureCross` layer:
+
+```python
+vocabulary_size = 32
+embedding_dim = 6
+
+inputs = keras.Input(shape=(), name='indices', dtype="int32")
+x0 = keras.layers.Embedding(
+    input_dim=vocabulary_size,
+    output_dim=embedding_dim
+)(inputs)
+x1 = keras_rs.layers.FeatureCross()(x0, x0)
+x2 = keras_rs.layers.FeatureCross()(x0, x1)
+output = keras.layers.Dense(units=10)(x2)
+model = keras.Model(inputs, output)
+```
+
+Compile the model:
+
+```python
+model.compile(
+    loss=keras.losses.MeanSquaredError(),
+    optimizer=keras.optimizers.Adam(learning_rate=3e-4)
+)
+```
+
+Call `model.fit()` on dummy data:
+
+```python
+batch_size = 2
+x = np.random.randint(0, vocabulary_size, size=(batch_size,))
+y = np.random.random(size=(batch_size,))
+model.fit(x, y=y)
+```
+
+### Use ranking losses and metrics
+
+If your task is to rank items in a list, you can make use of the ranking losses
+and metrics which KerasRS provides. Below, we use the pairwise hinge loss and
+track the nDCG metric:
+
+```python
+model.compile(
+    loss=keras_rs.losses.PairwiseHingeLoss(),
+    metrics=[keras_rs.metrics.NDCG()],
+    optimizer=keras.optimizers.Adam(learning_rate=3e-4),
+)
+```
+
 ## Installation
 
 Keras Recommenders is available on PyPI as `keras-rs`:

keras_rs_nightly-0.0.1.dev2025043003.dist-info/RECORD

@@ -0,0 +1,42 @@
+keras_rs/__init__.py,sha256=8sjHiPN2GhUqAq4V7Vh4FLLqYw20-jgdI26ZKX5sg6M,350
+keras_rs/layers/__init__.py,sha256=cvrFgFWg0RjI0ExUZOKZRdcN-FwTIkqhT33Vx8wGtjQ,905
+keras_rs/losses/__init__.py,sha256=m04QOgxIUfJ2MvCUKLgEof-UbSNKgUYLPnY-D9NAclI,573
+keras_rs/metrics/__init__.py,sha256=Qxpf6OFooIL9TIn2l3WgOea3HFRG0hq02glPAxtMZ9c,580
+keras_rs/src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/api_export.py,sha256=RsmG-DvO-cdFeAF9W6LRzms0kvtm-Yp9BAA_d-952zI,510
+keras_rs/src/types.py,sha256=UyOdgjqrqg_b58opnY8n6gTiDHKVR8z_bmEruehERBk,514
+keras_rs/src/version.py,sha256=6DQicfo43WsR2bsg-BdUHiGbBwGhNMF6hKd7NXYSW70,222
+keras_rs/src/layers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/layers/feature_interaction/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/layers/feature_interaction/dot_interaction.py,sha256=bRLz03_8VaYLNG4gbIKCzsSc26shKMmzmwCs8SujezE,8542
+keras_rs/src/layers/feature_interaction/feature_cross.py,sha256=rViVlJOGYG2f-uKTDQH7MdX2syRzIMkYYtAQUjz6F-0,8755
+keras_rs/src/layers/retrieval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/layers/retrieval/brute_force_retrieval.py,sha256=izdppBXxJH0KqYEg7Zsr-SL-SHgAmnFopXMPalEO3uw,5676
+keras_rs/src/layers/retrieval/hard_negative_mining.py,sha256=n5UftRcuuR7Lh75vOdFdqatpsYqJDHCsraNtAjeWvoM,3575
+keras_rs/src/layers/retrieval/remove_accidental_hits.py,sha256=WKoIhUSc6SvbgLXcSqNvFUnkuyXfxWwsC7nAgYbON_U,3773
+keras_rs/src/layers/retrieval/retrieval.py,sha256=hVOBF10SF2q_TgJdVUqztbnw5qQF-cxVRGdJbOKoL9M,4191
+keras_rs/src/layers/retrieval/sampling_probability_correction.py,sha256=3zD6LInxhyIvyujMleGqiuoPKsna2oaTN6JU6xMnW_M,1977
+keras_rs/src/losses/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/losses/pairwise_hinge_loss.py,sha256=tONOJpcwCw1mybwvyx8dAy5t6dDmlIn00enzWfQLXpQ,3049
+keras_rs/src/losses/pairwise_logistic_loss.py,sha256=40PFdCHDM7CLunT_PE3RbgxROVImw13dgVL3o3nzeNg,3473
+keras_rs/src/losses/pairwise_loss.py,sha256=1eux_u7PZ8BkAVdoZnt8nQxJuJeTQy_FJ8IspN5SsPc,6210
+keras_rs/src/losses/pairwise_loss_utils.py,sha256=xvdGvdKNkvGvIaWYEQziWTFNa5EJz7rdkVGgrsnDHUk,1246
+keras_rs/src/losses/pairwise_mean_squared_error.py,sha256=zFiSr2TNyJysgULxj9R_trpIMRNL_4MqpiAMNPUYmR0,4855
+keras_rs/src/losses/pairwise_soft_zero_one_loss.py,sha256=YddVtJS8tKEeb0YrqGzEsr-6IDxH4uRjFrYkZDMWpkk,3492
+keras_rs/src/metrics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/metrics/dcg.py,sha256=UT5EyStuMeF7kpVguF34u7__Hr0bWfSFqEoyX1F4dtA,5836
+keras_rs/src/metrics/mean_average_precision.py,sha256=fRptyVvhCtzg0rXhBaTfLmqo7dKIG7vS75HK0xuDvpg,4629
+keras_rs/src/metrics/mean_reciprocal_rank.py,sha256=R_LDAuKLK9buSD6hh3_nm0PksMhISbpuI6fR1MTsFWM,4034
+keras_rs/src/metrics/ndcg.py,sha256=OX8vqO5JoBm8I7NDOce0bXwtoGNEK0hGEQT8hYfqJDA,6935
+keras_rs/src/metrics/precision_at_k.py,sha256=A1pL5-Yo_DfDzUqAfqbF8TY39yqFgf_Fe1cxz0AsCfE,4029
+keras_rs/src/metrics/ranking_metric.py,sha256=GFtOszaDmP4Q1ky3KnyMNXR6OBu09Uk4aEOJyn5-JO4,10439
+keras_rs/src/metrics/ranking_metrics_utils.py,sha256=989J8pr6FRsA1HwBeF7SA8uQqjZT2XeCxKfRuMysWnQ,8828
+keras_rs/src/metrics/recall_at_k.py,sha256=allUQA6JvPcWXxtGUHXmZ_nOWHAOmuUrIy5s5Nxse-4,3695
+keras_rs/src/metrics/utils.py,sha256=6xanTNdwARn4ugzmb7ko2kwAhNhsnR4NhrpS_qW0IKc,2506
+keras_rs/src/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keras_rs/src/utils/doc_string_utils.py,sha256=CmqomepmaYcvpACpXEXkrJb8DMnvIgmYK-lJ53lYarY,1675
+keras_rs/src/utils/keras_utils.py,sha256=d28OdQP4GrJk4NIQS4n0KPtCbgOCxVU_vDnnI7ODpOw,1562
+keras_rs_nightly-0.0.1.dev2025043003.dist-info/METADATA,sha256=9RvG8sYrJD060w9nUrJ_vIVKwx_M3CzH_f0dquulVjg,5199
+keras_rs_nightly-0.0.1.dev2025043003.dist-info/WHEEL,sha256=ooBFpIzZCPdw3uqIQsOo4qqbA4ZRPxHnOH7peeONza0,91
+keras_rs_nightly-0.0.1.dev2025043003.dist-info/top_level.txt,sha256=pWs8X78Z0cn6lfcIb9VYOW5UeJ-TpoaO9dByzo7_FFo,9
+keras_rs_nightly-0.0.1.dev2025043003.dist-info/RECORD,,

{keras_rs_nightly-0.0.1.dev2025042803.dist-info → keras_rs_nightly-0.0.1.dev2025043003.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.0.0)
+Generator: setuptools (80.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

keras_rs_nightly-0.0.1.dev2025042803.dist-info/RECORD

@@ -1,42 +0,0 @@
-keras_rs/__init__.py,sha256=8sjHiPN2GhUqAq4V7Vh4FLLqYw20-jgdI26ZKX5sg6M,350
-keras_rs/layers/__init__.py,sha256=cvrFgFWg0RjI0ExUZOKZRdcN-FwTIkqhT33Vx8wGtjQ,905
-keras_rs/losses/__init__.py,sha256=m04QOgxIUfJ2MvCUKLgEof-UbSNKgUYLPnY-D9NAclI,573
-keras_rs/metrics/__init__.py,sha256=Qxpf6OFooIL9TIn2l3WgOea3HFRG0hq02glPAxtMZ9c,580
-keras_rs/src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/api_export.py,sha256=RsmG-DvO-cdFeAF9W6LRzms0kvtm-Yp9BAA_d-952zI,510
-keras_rs/src/types.py,sha256=UyOdgjqrqg_b58opnY8n6gTiDHKVR8z_bmEruehERBk,514
-keras_rs/src/version.py,sha256=7yE4X2uVxePL-l4daVZqTqrjFfoFLjBVYZA4sczaeoM,222
-keras_rs/src/layers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/layers/feature_interaction/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/layers/feature_interaction/dot_interaction.py,sha256=jGHcg0EiWxth6LTxG2yWgHcyx_GXrxvA61uQqpPfnDQ,6900
-keras_rs/src/layers/feature_interaction/feature_cross.py,sha256=5OCSI0vFYzJNmgkKcuHIbVv8U2q3UvS80-qZjPimDjM,8155
-keras_rs/src/layers/retrieval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/layers/retrieval/brute_force_retrieval.py,sha256=izdppBXxJH0KqYEg7Zsr-SL-SHgAmnFopXMPalEO3uw,5676
-keras_rs/src/layers/retrieval/hard_negative_mining.py,sha256=IWFrbw1h9z3AUw4oUBKf5_Aud4MTHO_AKdHfoyFa5As,3031
-keras_rs/src/layers/retrieval/remove_accidental_hits.py,sha256=Z84z2YgKspKeNdc5id8lf9TAyFsbCCz3acJxiKXYipc,3324
-keras_rs/src/layers/retrieval/retrieval.py,sha256=hVOBF10SF2q_TgJdVUqztbnw5qQF-cxVRGdJbOKoL9M,4191
-keras_rs/src/layers/retrieval/sampling_probability_correction.py,sha256=80vgOPfBiF-PC0dSyqS57IcIxOxi_Q_R7eSXHn1G0yI,1437
-keras_rs/src/losses/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/losses/pairwise_hinge_loss.py,sha256=nrIU0d1IcCAGo7RVxNitkldJhY2ZrXxjTV7Po27FXds,950
-keras_rs/src/losses/pairwise_logistic_loss.py,sha256=2dTtRmrNfvF_lOvHK0UQ518L2d4fkvQZDj30HWB5A2s,1305
-keras_rs/src/losses/pairwise_loss.py,sha256=rmDr_Qc3yA0CR8rUCCGjOgdbjYfC505BLNuITyb1n8k,6132
-keras_rs/src/losses/pairwise_loss_utils.py,sha256=xvdGvdKNkvGvIaWYEQziWTFNa5EJz7rdkVGgrsnDHUk,1246
-keras_rs/src/losses/pairwise_mean_squared_error.py,sha256=KhSRvjg4RpwhASP1Sl7PZoq2488P_uGDr9tZWzZhDVU,2764
-keras_rs/src/losses/pairwise_soft_zero_one_loss.py,sha256=QdWn-lyWQM-U9ID9xGQ7oK10q9XT6qd1gxVAKy8hZH4,1239
-keras_rs/src/metrics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/metrics/dcg.py,sha256=DzSBc9ZbgNavuHRt3wtVzdx4ouAaaqeYhd9NxQLPq0g,5120
-keras_rs/src/metrics/mean_average_precision.py,sha256=SF5NlhlyVL9L_YVkj_s_135f3-8hILVHRziSGafGyZI,3915
-keras_rs/src/metrics/mean_reciprocal_rank.py,sha256=4stq0MzyWNokMlol6BESDAMuoUFieDrFFc57ue94h4Y,3240
-keras_rs/src/metrics/ndcg.py,sha256=G7WNFoUaOhnf4vMF1jgcI4yGxieUfJv5E0upv4Qs1AQ,6545
-keras_rs/src/metrics/precision_at_k.py,sha256=u-mj49qamt448gxkOI9YIZMMrhgO8QmetRFXGGlWOqY,3247
-keras_rs/src/metrics/ranking_metric.py,sha256=cdFb4Lg2Z8P-02ImMGUAX4XeOUyzEE8TA6nB4fDgq0U,10411
-keras_rs/src/metrics/ranking_metrics_utils.py,sha256=989J8pr6FRsA1HwBeF7SA8uQqjZT2XeCxKfRuMysWnQ,8828
-keras_rs/src/metrics/recall_at_k.py,sha256=hlPnR5AtFjdd5AG0zLkLGVyLO5mWtp2bAu_cSOq9Fws,2919
-keras_rs/src/metrics/utils.py,sha256=6xanTNdwARn4ugzmb7ko2kwAhNhsnR4NhrpS_qW0IKc,2506
-keras_rs/src/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-keras_rs/src/utils/doc_string_utils.py,sha256=yVyQ8pYdl4gd4tKRhD8dXmQX1EwZeLiV3cCq3A1tUEk,1466
-keras_rs/src/utils/keras_utils.py,sha256=d28OdQP4GrJk4NIQS4n0KPtCbgOCxVU_vDnnI7ODpOw,1562
-keras_rs_nightly-0.0.1.dev2025042803.dist-info/METADATA,sha256=4W-DkQ0hKfcBFI6CAJzbJWAiNRGhLGFYrxLyGVo8GBM,3614
-keras_rs_nightly-0.0.1.dev2025042803.dist-info/WHEEL,sha256=ck4Vq1_RXyvS4Jt6SI0Vz6fyVs4GWg7AINwpsaGEgPE,91
-keras_rs_nightly-0.0.1.dev2025042803.dist-info/top_level.txt,sha256=pWs8X78Z0cn6lfcIb9VYOW5UeJ-TpoaO9dByzo7_FFo,9
-keras_rs_nightly-0.0.1.dev2025042803.dist-info/RECORD,,