feat: Constrain diversity for DPP, add scale factor (Pringled#10)

* Added constraint for dpp * Added constraint for dpp * Added constraint for dpp * Added constraint for dpp * Added constraint for dpp

Author: Pringled

README.md

@@ -35,14 +35,15 @@ from pyversity import diversify, Strategy
 embeddings = np.random.randn(100, 256)
 scores = np.random.rand(100)
 
-# Diversify with with a chosen strategy (in this case MMR) and a diversity of 0.5 (balanced)
+# Diversify the result
 diversified_result = diversify(
  embeddings=embeddings,
  scores=scores,
- k=10,
- strategy=Strategy.MMR,
- diversity=0.5
+ k=10, # Number of items to select
+ strategy=Strategy.MMR, # Diversification strategy to use
+ diversity=0.5 # Diversity parameter (higher values prioritize diversity)
 )
+
 # Get the indicices of the diversified result
 diversified_indices = diversified_result.indices
 ```

src/pyversity/pyversity.py

@@ -22,7 +22,7 @@ def diversify(
  :param k: The number of items to select for the diversified result.
  :param strategy: The diversification strategy to apply.
  Supported strategies are: 'mmr' (default), 'msd', 'cover', and 'dpp'.
- :param diversity: Diversity parameter. Higher values prioritize diversity and lower values prioritize relevance.
+ :param diversity: Diversity parameter (range of [0, 1]). Higher values prioritize diversity and lower values prioritize relevance.
  :param **kwargs: Additional keyword arguments passed to the specific strategy function.
  :return: A DiversificationResult containing the selected item indices,
  their marginal gains, the strategy used, and the parameters.

src/pyversity/strategies/dpp.py

@@ -17,6 +17,7 @@ def dpp(
  scores: np.ndarray,
  k: int,
  diversity: float = 0.5,
+ scale: float = 1.0,
 ) -> DiversificationResult:
  """
  Greedy determinantal point process (DPP) selection.
@@ -30,12 +31,17 @@ def dpp(
  :param k: Number of items to select.
  :param diversity: Controls the influence of relevance scores in the DPP kernel (inverse of beta parameter).
  Higher values increase the emphasis on diversity.
+ :param scale: Optional scaling factor for the beta parameter to adjust relevance influence.
  :return: A DiversificationResult containing the selected item indices,
  their marginal gains, the strategy used, and the parameters.
+ :raises ValueError: If diversity is not in [0, 1].
  """
+ if not (0.0 <= float(diversity) <= 1.0):
+ raise ValueError("diversity must be in [0, 1]")
+
  # Beta parameter to control relevance influence in DPP kernel.
  # This is the inverse of diversity to align with common notation.
- beta = 1 - diversity
+ beta = (1 - diversity) * scale
 
  # Prepare inputs
  feature_matrix, relevance_scores, top_k, early_exit = prepare_inputs(embeddings, scores, k)
@@ -46,6 +52,7 @@ def dpp(
  marginal_gains=np.empty(0, np.float32),
  strategy=Strategy.DPP,
  diversity=diversity,
+ parameters={"scale": scale},
  )
  # Normalize feature vectors to unit length for cosine similarity
  feature_matrix = normalize_rows(feature_matrix)
@@ -102,4 +109,5 @@ def dpp(
  marginal_gains=marginal_gains[:step],
  strategy=Strategy.DPP,
  diversity=diversity,
+ parameters={"scale": scale},
  )