add selection params

integration/test_collection_diversity.py

@@ -0,0 +1,117 @@
+import pytest
+
+from integration.conftest import CollectionFactory
+from weaviate.classes.query import Diversity
+from weaviate.collections.classes.config import Configure, DataType, Property
+from weaviate.collections.classes.data import DataObject
+
+
+def _create_clustered_collection(collection_factory: CollectionFactory):
+    """Create a collection with 3 tight clusters (a, b, c) of vectors in 3D."""
+    collection = collection_factory(
+        properties=[Property(name="text", data_type=DataType.TEXT)],
+        vectorizer_config=Configure.Vectorizer.none(),
+    )
+    if collection._connection._weaviate_version.is_lower_than(1, 37, 0):
+        pytest.skip("Diversity selection requires Weaviate >= 1.37.0")
+    collection.data.insert_many(
+        [
+            DataObject(properties={"text": "a1"}, vector=[1.0, 0.0, 0.0]),
+            DataObject(properties={"text": "a2"}, vector=[0.95, 0.05, 0.0]),
+            DataObject(properties={"text": "a3"}, vector=[0.9, 0.1, 0.0]),
+            DataObject(properties={"text": "b1"}, vector=[0.0, 1.0, 0.0]),
+            DataObject(properties={"text": "b2"}, vector=[0.05, 0.95, 0.0]),
+            DataObject(properties={"text": "c1"}, vector=[0.0, 0.0, 1.0]),
+        ]
+    )
+    return collection
+
+
+def test_near_vector_diversity_selection(collection_factory: CollectionFactory) -> None:
+    """Verify that the client passes diversity_selection to the server correctly.
+
+    Two orthogonal assertions — server-side logic (MMR itself) is out of scope:
+    - ``balance`` reaches the server: balance=0.0 produces a different UUID ordering than balance=1.0
+    - ``limit`` reaches the server: len(result) == mmr_limit
+    """
+    collection = _create_clustered_collection(collection_factory)
+    mmr_limit = 3
+
+    balance_0 = collection.query.near_vector(
+        near_vector=[1.0, 0.0, 0.0],
+        diversity_selection=Diversity.mmr(limit=mmr_limit, balance=0.0),
+    ).objects
+    balance_1 = collection.query.near_vector(
+        near_vector=[1.0, 0.0, 0.0],
+        diversity_selection=Diversity.mmr(limit=mmr_limit, balance=1.0),
+    ).objects
+
+    # mmr_limit reaches the server → result count equals it
+    assert len(balance_0) == mmr_limit
+    assert len(balance_1) == mmr_limit
+    # balance reaches the server → different ordering
+    assert [o.uuid for o in balance_0] != [o.uuid for o in balance_1]
+
+
+def test_near_text_diversity_selection(collection_factory: CollectionFactory) -> None:
+    """Smoke test: diversity_selection kwarg is wired through the near_text entry point."""
+    collection = collection_factory(
+        properties=[Property(name="name", data_type=DataType.TEXT)],
+        vectorizer_config=Configure.Vectorizer.text2vec_contextionary(
+            vectorize_collection_name=False
+        ),
+    )
+    if collection._connection._weaviate_version.is_lower_than(1, 37, 0):
+        pytest.skip("Diversity selection requires Weaviate >= 1.37.0")
+    for name in ["banana", "apple", "orange", "car", "truck", "bike"]:
+        collection.data.insert({"name": name})
+
+    result = collection.query.near_text(
+        query="fruit",
+        diversity_selection=Diversity.mmr(limit=3, balance=0.5),
+    )
+    assert len(result.objects) == 3
+
+
+def test_near_object_diversity_selection(collection_factory: CollectionFactory) -> None:
+    """Smoke test: diversity_selection kwarg is wired through the near_object entry point."""
+    collection = _create_clustered_collection(collection_factory)
+    anchor = next(iter(collection.query.fetch_objects().objects)).uuid
+
+    result = collection.query.near_object(
+        near_object=anchor,
+        diversity_selection=Diversity.mmr(limit=3, balance=0.5),
+    )
+    assert len(result.objects) == 3
+
+
+def test_generate_diversity_selection(collection_factory: CollectionFactory) -> None:
+    """Smoke test: diversity_selection kwarg is wired through the .generate namespace."""
+    collection = collection_factory(
+        properties=[Property(name="name", data_type=DataType.TEXT)],
+        vectorizer_config=Configure.Vectorizer.text2vec_contextionary(
+            vectorize_collection_name=False
+        ),
+        generative_config=Configure.Generative.custom("generative-dummy"),
+    )
+    if collection._connection._weaviate_version.is_lower_than(1, 37, 0):
+        pytest.skip("Diversity selection requires Weaviate >= 1.37.0")
+    for name in ["banana", "apple", "orange", "car", "truck", "bike"]:
+        collection.data.insert({"name": name})
+
+    result = collection.generate.near_text(
+        query="fruit",
+        single_prompt="Describe {name}",
+        diversity_selection=Diversity.mmr(limit=3, balance=0.5),
+    )
+    assert len(result.objects) == 3
+
+
+def test_diversity_selection_api_surface() -> None:
+    """Test the public API surface of Diversity: factory guard + mmr factory method."""
+    # Direct instantiation of the factory class fails
+    with pytest.raises(TypeError):
+        Diversity()
+
+    # Diversity.mmr() produces an MMR-configured selection object
+    assert Diversity.mmr(limit=3, balance=0.5).limit == 3

weaviate/classes/query.py

@@ -5,6 +5,7 @@
     BM25OperatorFactory as BM25Operator,
 )
 from weaviate.collections.classes.grpc import (
+    Diversity,
     GroupBy,
     HybridFusion,
     HybridVector,
@@ -21,6 +22,7 @@
 from weaviate.collections.classes.types import GeoCoordinate
 
 __all__ = [
+    "Diversity",
     "Filter",
     "FilterReturn",
     "GeoCoordinate",

weaviate/collections/classes/grpc.py

@@ -268,6 +268,36 @@ class Rerank(_WeaviateInput):
     query: Optional[str] = Field(default=None)
 
 
+@dataclass
+class MMR:
+    """Define MMR (Maximal Marginal Relevance) diversity selection.
+
+    Args:
+        limit: Optional number of candidates to consider for diversification.
+        balance: Optional MMR lambda in [0.0, 1.0] — 1.0 is pure relevance, 0.0 is pure diversity.
+    """
+
+    limit: Optional[int] = None
+    balance: Optional[float] = None
+
+
+class Diversity:
+    """Use this factory class to apply diversity selection to search results via MMR."""
+
+    def __init__(self) -> None:
+        raise TypeError("Diversity cannot be instantiated directly. Use Diversity.mmr(...).")
+
+    @staticmethod
+    def mmr(limit: Optional[int] = None, balance: Optional[float] = None) -> MMR:
+        """Maximal Marginal Relevance diversity selection.
+
+        Args:
+            limit: Number of candidates to consider for diversification.
+            balance: MMR lambda in [0.0, 1.0] — 1.0 pure relevance, 0.0 pure diversity.
+        """
+        return MMR(limit=limit, balance=balance)
+
+
 @dataclass
 class BM25OperatorOptions:
     # replace with ClassVar[base_search_pb2.SearchOperatorOptions.Operator] once python 3.10 is removed
@@ -559,7 +589,11 @@ def near_vector(
         Returns:
             A `_HybridNearVector` object to be used in the `vector` parameter of the `query.hybrid` and `generate.hybrid` search methods.
         """
-        return _HybridNearVector(vector=vector, distance=distance, certainty=certainty)
+        return _HybridNearVector(
+            vector=vector,
+            distance=distance,
+            certainty=certainty,
+        )
 
 
 class _QueryReference(_WeaviateInput):

weaviate/collections/grpc/query.py

@@ -18,6 +18,7 @@
 from weaviate.collections.classes.config import ConsistencyLevel
 from weaviate.collections.classes.filters import FilterReturn
 from weaviate.collections.classes.grpc import (
+    MMR,
     PROPERTIES,
     PROPERTY,
     REFERENCE,
@@ -262,6 +263,7 @@ def near_vector(
         return_metadata: Optional[_MetadataQuery] = None,
         return_properties: Union[PROPERTIES, bool, None] = None,
         return_references: Optional[REFERENCES] = None,
+        diversity_selection: Optional[MMR] = None,
     ) -> search_get_pb2.SearchRequest:
         return self.__create_request(
             limit=limit,
@@ -275,7 +277,11 @@ def near_vector(
             autocut=autocut,
             group_by=group_by,
             near_vector=self._parse_near_vector(
-                near_vector, certainty, distance, target_vector=target_vector
+                near_vector,
+                certainty,
+                distance,
+                target_vector=target_vector,
+                diversity_selection=diversity_selection,
             ),
         )
 
@@ -296,6 +302,7 @@ def near_object(
         return_metadata: Optional[_MetadataQuery] = None,
         return_properties: Union[PROPERTIES, bool, None] = None,
         return_references: Optional[REFERENCES] = None,
+        diversity_selection: Optional[MMR] = None,
     ) -> search_get_pb2.SearchRequest:
         return self.__create_request(
             limit=limit,
@@ -308,7 +315,13 @@ def near_object(
             rerank=rerank,
             autocut=autocut,
             group_by=group_by,
-            near_object=self._parse_near_object(near_object, certainty, distance, target_vector),
+            near_object=self._parse_near_object(
+                near_object,
+                certainty,
+                distance,
+                target_vector,
+                diversity_selection=diversity_selection,
+            ),
         )
 
     def near_text(
@@ -330,6 +343,7 @@ def near_text(
         return_metadata: Optional[_MetadataQuery] = None,
         return_properties: Union[PROPERTIES, bool, None] = None,
         return_references: Optional[REFERENCES] = None,
+        diversity_selection: Optional[MMR] = None,
     ) -> search_get_pb2.SearchRequest:
         return self.__create_request(
             limit=limit,
@@ -349,6 +363,7 @@ def near_text(
                 move_away=move_away,
                 move_to=move_to,
                 target_vector=target_vector,
+                diversity_selection=diversity_selection,
             ),
         )
 
@@ -370,6 +385,7 @@ def near_media(
         return_metadata: Optional[_MetadataQuery] = None,
         return_properties: Union[PROPERTIES, bool, None] = None,
         return_references: Optional[REFERENCES] = None,
+        diversity_selection: Optional[MMR] = None,
     ) -> search_get_pb2.SearchRequest:
         return self.__create_request(
             limit=limit,
@@ -388,6 +404,7 @@ def near_media(
                 certainty,
                 distance,
                 target_vector,
+                diversity_selection=diversity_selection,
             ),
         )