diff --git a/redisvl/extensions/cache/llm/langcache.py b/redisvl/extensions/cache/llm/langcache.py index b3d1ab684..99af75f27 100644 --- a/redisvl/extensions/cache/llm/langcache.py +++ b/redisvl/extensions/cache/llm/langcache.py @@ -12,7 +12,11 @@ from redisvl.extensions.cache.llm.schema import CacheHit from redisvl.query.filter import FilterExpression from redisvl.utils.log import get_logger -from redisvl.utils.utils import denorm_cosine_distance, norm_cosine_distance +from redisvl.utils.utils import ( + denorm_cosine_distance, + norm_cosine_distance, + validate_cosine_distance_threshold, +) logger = get_logger(__name__) @@ -187,8 +191,12 @@ def _similarity_threshold(self, distance_threshold: float | None) -> float | Non if distance_threshold is None: return None if self._distance_scale == "redis": - return norm_cosine_distance(distance_threshold) - return 1.0 - float(distance_threshold) + return norm_cosine_distance( + validate_cosine_distance_threshold(distance_threshold) + ) + return 1.0 - validate_cosine_distance_threshold( + distance_threshold, max_distance=1 + ) def _build_search_kwargs( self, @@ -300,6 +308,9 @@ def check( Raises: ValueError: If prompt is not provided. + TypeError: If `distance_threshold` is not a real number, or is a bool. + ValueError: If `distance_threshold` is NaN or outside its scale's + range: [0, 1] for "normalized", [0, 2] for "redis". """ if not prompt: raise ValueError("prompt is required for LangCache search") @@ -382,6 +393,9 @@ async def acheck( Raises: ValueError: If prompt is not provided. + TypeError: If `distance_threshold` is not a real number, or is a bool. + ValueError: If `distance_threshold` is NaN or outside its scale's + range: [0, 1] for "normalized", [0, 2] for "redis". """ if not prompt: raise ValueError("prompt is required for LangCache search") diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 98a266c1f..844a0a466 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -28,9 +28,11 @@ from redisvl.redis.utils import hashify from redisvl.utils.log import get_logger from redisvl.utils.utils import ( + cosine_distance_bound, current_timestamp, deprecated_argument, serialize, + validate_cosine_distance_threshold, validate_vector_dims, ) from redisvl.utils.vectorize.base import BaseVectorizer @@ -111,7 +113,9 @@ def __init__( Raises: TypeError: If an invalid vectorizer is provided. TypeError: If the TTL value is not an int. - ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance). + TypeError: If the threshold is not a real number, or is a bool. + ValueError: If the threshold is not between 0 and 2 (Redis COSINE + distance), or is NaN. ValueError: If existing schema does not match new schema and overwrite is False. ValueError: If both create_index is False and overwrite is True. @@ -133,6 +137,8 @@ def __init__( connection_kwargs = connection_kwargs or {} if not create_index and overwrite: raise ValueError(CREATE_INDEX_OVERWRITE_CONFLICT) + # Refuse a bad threshold before loading the default vectorizer. + validate_cosine_distance_threshold(distance_threshold) # Call parent class with all shared parameters super().__init__( @@ -305,13 +311,13 @@ def set_threshold(self, distance_threshold: float) -> None: the cache. Raises: - ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance). + TypeError: If the threshold is not a real number, or is a bool. + ValueError: If the threshold is not between 0 and 2 (Redis COSINE + distance), or is NaN. """ - if not 0 <= float(distance_threshold) <= 2: - raise ValueError( - f"Distance must be between 0 and 2, got {distance_threshold}" - ) - self._distance_threshold = float(distance_threshold) + self._distance_threshold = validate_cosine_distance_threshold( + distance_threshold + ) def delete(self) -> None: """Delete the cache and its index entirely. @@ -470,7 +476,8 @@ def check( that can be used to filter cache results. Defaults to None and the full cache will be searched. distance_threshold (Optional[float]): The threshold for semantic - vector distance. + vector distance, in Redis COSINE units [0-2]. Defaults to None, + which uses the cache's threshold. refresh_ttl (Optional[bool]): Whether this cache hit should refresh matched entries' TTL. If None, uses the cache-level refresh_ttl_on_hit setting. @@ -483,6 +490,8 @@ def check( ValueError: If neither a `prompt` nor a `vector` is specified. ValueError: if 'vector' has incorrect dimensions. TypeError: If `return_fields` is not a list when provided. + TypeError: If `distance_threshold` is not a real number, or is a bool. + ValueError: If `distance_threshold` is not between 0 and 2, or is NaN. .. code-block:: python @@ -500,7 +509,7 @@ def check( if distance_threshold is None: distance_threshold = self._distance_threshold else: - self._validate_distance_threshold(distance_threshold) + distance_threshold = validate_cosine_distance_threshold(distance_threshold) # Vectorize prompt if not provided if vector is None and prompt is not None: @@ -564,7 +573,8 @@ async def acheck( that can be used to filter cache results. Defaults to None and the full cache will be searched. distance_threshold (Optional[float]): The threshold for semantic - vector distance. + vector distance, in Redis COSINE units [0-2]. Defaults to None, + which uses the cache's threshold. refresh_ttl (Optional[bool]): Whether this cache hit should refresh matched entries' TTL. If None, uses the cache-level refresh_ttl_on_hit setting. @@ -577,6 +587,8 @@ async def acheck( ValueError: If neither a `prompt` nor a `vector` is specified. ValueError: if 'vector' has incorrect dimensions. TypeError: If `return_fields` is not a list when provided. + TypeError: If `distance_threshold` is not a real number, or is a bool. + ValueError: If `distance_threshold` is not between 0 and 2, or is NaN. .. code-block:: python @@ -596,7 +608,7 @@ async def acheck( if distance_threshold is None: distance_threshold = self._distance_threshold else: - self._validate_distance_threshold(distance_threshold) + distance_threshold = validate_cosine_distance_threshold(distance_threshold) # Vectorize prompt if not provided if vector is None and prompt is not None: @@ -666,22 +678,9 @@ def _within_threshold( candidate for candidate in candidates if (distance := candidate.get(VectorQuery.DISTANCE_ID)) is None - or float(distance) <= distance_threshold + or float(distance) <= cosine_distance_bound(distance_threshold) ] - @staticmethod - def _validate_distance_threshold(distance_threshold: float) -> None: - """Validate a per-call ``distance_threshold`` override. - - Raises: - TypeError: If the threshold is not a float or int. - ValueError: If the threshold is negative. - """ - if not isinstance(distance_threshold, (float, int)): - raise TypeError("distance_threshold must be of type float or int") - if distance_threshold < 0: - raise ValueError("distance_threshold must be non-negative") - def _process_cache_results( self, cache_search_results: list[dict[str, Any]], diff --git a/redisvl/extensions/message_history/semantic_history.py b/redisvl/extensions/message_history/semantic_history.py index dc02c70bb..75784ad8a 100644 --- a/redisvl/extensions/message_history/semantic_history.py +++ b/redisvl/extensions/message_history/semantic_history.py @@ -23,7 +23,13 @@ from redisvl.query import CountQuery, FilterQuery, RangeQuery from redisvl.query.filter import Tag from redisvl.utils.log import get_logger -from redisvl.utils.utils import deprecated_argument, serialize, validate_vector_dims +from redisvl.utils.utils import ( + cosine_distance_bound, + deprecated_argument, + serialize, + validate_cosine_distance_threshold, + validate_vector_dims, +) from redisvl.utils.vectorize import BaseVectorizer, HFTextVectorizer logger = get_logger(__name__) @@ -61,7 +67,8 @@ def __init__( Defaults to None and will be replaced with the index name. vectorizer (Optional[BaseVectorizer]): The vectorizer used to create embeddings. distance_threshold (float): The maximum semantic distance to be - included in the context. Defaults to 0.3. + included in the context, in Redis COSINE units [0-2]. Defaults + to 0.3. redis_client (Optional[Redis]): A Redis client instance. Defaults to None. redis_url (str, optional): The redis url. Defaults to redis://localhost:6379. @@ -79,6 +86,10 @@ def __init__( Defaults to True. Raises: + TypeError: If the distance threshold is not a real number, or is a + bool. + ValueError: If the distance threshold is not between 0 and 2 + (Redis COSINE distance), or is NaN. ValueError: If both create_index is False and overwrite is True. The proposed schema will support a single vector embedding constructed @@ -87,6 +98,8 @@ def __init__( connection_kwargs = connection_kwargs or {} if not create_index and overwrite: raise ValueError(CREATE_INDEX_OVERWRITE_CONFLICT) + # Refuse a bad threshold before loading the default vectorizer. + validate_cosine_distance_threshold(distance_threshold) super().__init__(name, session_tag) @@ -258,7 +271,8 @@ def get_relevant( session_tag (Optional[str]): Tag of the entries linked to a specific conversation session. Defaults to instance ULID. distance_threshold (Optional[float]): The threshold for semantic - vector distance. + vector distance, in Redis COSINE units [0-2]. Defaults to None, + which uses the history's threshold. fall_back (bool): Whether to drop back to recent conversation history if no relevant context is found. raw (bool): Whether to return the full Redis hash entry or just the @@ -271,22 +285,27 @@ def get_relevant( Union[List[str], List[Dict[str,str]]: Either a list of strings, or a list of prompts and responses in JSON containing the most relevant. - Raises ValueError: if top_k is not an integer greater or equal to 0, - or if role contains invalid values. + Raises: + ValueError: If top_k is not an integer greater or equal to 0, or if + role contains invalid values. + TypeError: If `distance_threshold` is not a real number, or is a bool. + ValueError: If `distance_threshold` is not between 0 and 2, or is NaN. """ if type(top_k) != int or top_k < 0: raise ValueError("top_k must be an integer greater than or equal to -1") + # override distance threshold. Note: 0 is a valid distance threshold + # (exact match only), so only fall back on None. + if distance_threshold is None: + distance_threshold = self._distance_threshold + else: + distance_threshold = validate_cosine_distance_threshold(distance_threshold) + if top_k == 0: return [] # Validate and normalize role parameter roles_to_filter = self._validate_roles(role) - # override distance threshold. Note: 0 is a valid distance threshold - # (exact match only), so only fall back on None. - if distance_threshold is None: - distance_threshold = self._distance_threshold - return_fields = [ SESSION_FIELD_NAME, ROLE_FIELD_NAME, @@ -320,7 +339,7 @@ def get_relevant( vector=self._vectorizer.embed(prompt), vector_field_name=MESSAGE_VECTOR_FIELD_NAME, return_fields=return_fields, - distance_threshold=distance_threshold, + distance_threshold=cosine_distance_bound(distance_threshold), num_results=top_k, return_score=True, filter_expression=filter_expression, @@ -423,8 +442,19 @@ def get_recent( def distance_threshold(self): return self._distance_threshold - def set_distance_threshold(self, threshold): - self._distance_threshold = threshold + def set_distance_threshold(self, threshold: float) -> None: + """Set the history's semantic distance threshold. + + Args: + threshold (float): The maximum semantic distance to be included in + the context, in Redis COSINE units [0-2]. + + Raises: + TypeError: If the threshold is not a real number, or is a bool. + ValueError: If the threshold is not between 0 and 2 (Redis COSINE + distance), or is NaN. + """ + self._distance_threshold = validate_cosine_distance_threshold(threshold) def store(self, prompt: str, response: str, session_tag: str | None = None) -> None: """Insert a prompt:response pair into the message history. A timestamp diff --git a/redisvl/extensions/router/schema.py b/redisvl/extensions/router/schema.py index 9a8521337..82359f4a6 100644 --- a/redisvl/extensions/router/schema.py +++ b/redisvl/extensions/router/schema.py @@ -7,17 +7,22 @@ from redisvl.extensions.constants import ROUTE_VECTOR_FIELD_NAME from redisvl.schema import IndexSchema +DistanceThreshold = Annotated[float, Field(strict=True, gt=0, le=2)] +"""A route distance threshold: a real number in (0, 2].""" + class Route(BaseModel): """Model representing a routing path with associated metadata and thresholds.""" + model_config = ConfigDict(validate_assignment=True) + name: str """The name of the route.""" references: list[str] """List of reference phrases for the route.""" metadata: dict[str, Any] = Field(default={}) """Metadata associated with the route.""" - distance_threshold: Annotated[float, Field(strict=True, gt=0, le=2)] = 0.5 + distance_threshold: DistanceThreshold = 0.5 """Maximum distance for matching the route, inclusive.""" @field_validator("name") diff --git a/redisvl/extensions/router/semantic.py b/redisvl/extensions/router/semantic.py index 2f7c914e5..441b17613 100644 --- a/redisvl/extensions/router/semantic.py +++ b/redisvl/extensions/router/semantic.py @@ -3,7 +3,7 @@ import redis.commands.search.reducers as reducers import yaml -from pydantic import BaseModel, ConfigDict, Field, PrivateAttr +from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, TypeAdapter from redis.commands.search.aggregation import AggregateRequest, AggregateResult, Reducer from redis.exceptions import ResponseError @@ -15,6 +15,7 @@ ) from redisvl.extensions.router.schema import ( DistanceAggregationMethod, + DistanceThreshold, Route, RouteMatch, RoutingConfig, @@ -28,6 +29,7 @@ from redisvl.types import SyncRedisClient from redisvl.utils.log import get_logger from redisvl.utils.utils import ( + cosine_distance_bound, deprecated_argument, match_pattern, model_to_dict, @@ -38,6 +40,8 @@ logger = get_logger(__name__) +_DISTANCE_THRESHOLD_ADAPTER = TypeAdapter(DistanceThreshold) + class SemanticRouter(BaseModel): """Semantic Router for managing and querying route vectors.""" @@ -300,7 +304,7 @@ def route_names(self) -> list[str]: return [route.name for route in self.routes] @property - def route_thresholds(self) -> dict[str, float | None]: + def route_thresholds(self) -> dict[str, float]: """Get the distance thresholds for each route. Returns: @@ -316,15 +320,24 @@ def update_routing_config(self, routing_config: RoutingConfig): """ self.routing_config = routing_config - def update_route_thresholds(self, route_thresholds: dict[str, float | None]): + def update_route_thresholds(self, route_thresholds: dict[str, float]): """Update the distance thresholds for each route. + Thresholds follow the same rule as :class:`Route`: a real number in + (0, 2]. Every value is checked before any is applied, so an invalid + one leaves all thresholds unchanged. + Args: route_thresholds (Dict[str, float]): Dictionary of route names and their distance thresholds. + + Raises: + pydantic.ValidationError: If any threshold is not a real number in (0, 2]. """ + for threshold in route_thresholds.values(): + _DISTANCE_THRESHOLD_ADAPTER.validate_python(threshold) for route in self.routes: if route.name in route_thresholds: - route.distance_threshold = route_thresholds[route.name] # type: ignore + route.distance_threshold = route_thresholds[route.name] @staticmethod def _route_ref_key(index: SearchIndex, route_name: str, reference_hash: str) -> str: @@ -411,11 +424,19 @@ def _process_route(self, result: dict[str, Any]) -> RouteMatch | None: name=route_dict["route_name"], distance=float(route_dict["distance"]) ) - def _distance_threshold_filter(self) -> str: + def _distance_threshold_filter( + self, aggregation_method: DistanceAggregationMethod + ) -> str: """Apply distance threshold on a route by route basis.""" filter = "" for i, route in enumerate(self.routes): - filter_str = f"(@route_name == '{route.name}' && @distance <= {route.distance_threshold})" + # A min or avg never exceeds one reference's distance, so it gets the + # same rounding allowance at 2; a sum can legitimately pass 2. + if aggregation_method == DistanceAggregationMethod.sum: + bound = route.distance_threshold + else: + bound = cosine_distance_bound(route.distance_threshold) + filter_str = f"(@route_name == '{route.name}' && @distance <= {bound})" if i > 0: filter += " || " filter += filter_str @@ -448,7 +469,7 @@ def _build_aggregate_request( "@route_name", # type: ignore aggregation_func("vector_distance").alias("distance"), ) - .filter(self._distance_threshold_filter()) + .filter(self._distance_threshold_filter(aggregation_method)) .sort_by("@distance", max=max_k) # type: ignore .dialect(2) ) @@ -495,7 +516,7 @@ def _route_matches_request( vector_range_query = VectorRangeQuery( vector=vector, vector_field_name=ROUTE_VECTOR_FIELD_NAME, - distance_threshold=float(distance_threshold), + distance_threshold=cosine_distance_bound(float(distance_threshold)), return_fields=["route_name"], ) @@ -1254,7 +1275,9 @@ def delete_route_references( ) continue # Duplicate references share one hash, so every copy went with it. - route.references = [ref for ref in route.references if ref != reference] + # Edited in place: the list may empty here, which `Route` rejects on + # assignment, and emptied routes are dropped just below. + route.references[:] = [ref for ref in route.references if ref != reference] # A route whose last reference was just deleted has nothing left to match, # and `Route` rejects an empty reference list -- persisting one would write a diff --git a/redisvl/query/aggregate.py b/redisvl/query/aggregate.py index dd0604d2d..f4b3edb73 100644 --- a/redisvl/query/aggregate.py +++ b/redisvl/query/aggregate.py @@ -1,6 +1,7 @@ +import numbers from typing import Any, Self -from pydantic import BaseModel, Field, field_validator, model_validator +from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator from redis.commands.search.aggregation import AggregateRequest, Desc from redisvl.query.filter import FilterExpression, intersect_with_filter @@ -31,6 +32,9 @@ class Vector(BaseModel): max_distance: The maximum distance for vector range search (default: 2.0, range: [0.0, 2.0]) """ + # Validate max_distance on assignment too: it is interpolated into the query. + model_config = ConfigDict(validate_assignment=True) + vector: list[float] | bytes field_name: str dtype: str = "float32" @@ -48,14 +52,17 @@ def validate_dtype(cls, dtype: str) -> str: ) return dtype - @field_validator("max_distance") + @field_validator("max_distance", mode="before") @classmethod - def validate_max_distance(cls, max_distance: float) -> float: - if not isinstance(max_distance, (float, int)): - raise ValueError("max_distance must be a value between 0.0 and 2.0") - if max_distance < 0.0 or max_distance > 2.0: + def validate_max_distance(cls, max_distance: Any) -> float: + # Before pydantic's own coercion, which would turn True or "0.5" into a float. + if isinstance(max_distance, bool) or not isinstance(max_distance, numbers.Real): + raise ValueError( + f"max_distance must be a real number, got {type(max_distance).__name__}" + ) + if not 0.0 <= max_distance <= 2.0: raise ValueError("max_distance must be a value between 0.0 and 2.0") - return max_distance + return float(max_distance) @model_validator(mode="after") def validate_vector(self) -> Self: diff --git a/redisvl/query/query.py b/redisvl/query/query.py index ceb3aba6a..b0d63dd12 100644 --- a/redisvl/query/query.py +++ b/redisvl/query/query.py @@ -1,3 +1,4 @@ +import numbers from enum import StrEnum from typing import Any, Self @@ -991,13 +992,23 @@ def set_distance_threshold(self, distance_threshold: float): distance_threshold (float): Vector distance threshold. Raises: - TypeError: If distance_threshold is not a float or int - ValueError: If distance_threshold is negative + TypeError: If distance_threshold is not a real number, or is a bool + ValueError: If distance_threshold is negative or NaN, or above 1 + when normalize_vector_distance is True """ - if not isinstance(distance_threshold, (float, int)): - raise TypeError("distance_threshold must be of type float or int") - if distance_threshold < 0: - raise ValueError("distance_threshold must be non-negative") + if isinstance(distance_threshold, bool) or not isinstance( + distance_threshold, numbers.Real + ): + raise TypeError( + "distance_threshold must be a real number, got " + f"{type(distance_threshold).__name__}" + ) + # Written so that NaN fails too: it would make the range match nothing. + if not distance_threshold >= 0: + raise ValueError( + f"distance_threshold must be non-negative, got {distance_threshold}" + ) + distance_threshold = float(distance_threshold) if self._normalize_vector_distance: if distance_threshold > 1: raise ValueError( diff --git a/redisvl/utils/utils.py b/redisvl/utils/utils.py index 32cdcd2a1..7a69ea405 100644 --- a/redisvl/utils/utils.py +++ b/redisvl/utils/utils.py @@ -2,6 +2,7 @@ import importlib import inspect import json +import numbers import sys import warnings from contextlib import contextmanager @@ -292,6 +293,49 @@ def denorm_cosine_distance(value: float) -> float: return max(2 - 2 * value, 0) +def cosine_distance_bound(distance_threshold: float) -> float: + """Return the bound to test a reported COSINE distance against. + + A threshold of 2, the largest COSINE distance, is meant to match every + vector, but float rounding can report an exactly opposite vector a little + above 2: measured on Redis 8.10.3, 2.00000024 for FLOAT32 and up to 2.0006 + for FLOAT16. At 2 this returns 3, past any such overshoot, so a client-side + comparison, a ``VECTOR_RANGE`` radius and an aggregate ``FILTER`` all treat 2 + as matching everything. Below 2 it returns the threshold unchanged. + """ + return 3.0 if distance_threshold >= 2 else distance_threshold + + +def validate_cosine_distance_threshold( + distance_threshold: float, max_distance: float = 2 +) -> float: + """Validate a COSINE distance threshold and return it as a float. + + A real number from 0 to ``max_distance`` inclusive: 2, the range of Redis + COSINE distance, or 1 for a distance normalized to [0, 1]. A bool is + refused even though it is an ``int``. NaN fails the range check; accepted, + it would make every lookup miss without an error, because every comparison + with NaN is false. + + Raises: + TypeError: If the threshold is not a real number, or is a bool. + ValueError: If the threshold is not between 0 and ``max_distance``, or + is NaN. + """ + if isinstance(distance_threshold, bool) or not isinstance( + distance_threshold, numbers.Real + ): + raise TypeError( + "distance_threshold must be a real number, got " + f"{type(distance_threshold).__name__}" + ) + if not 0 <= distance_threshold <= max_distance: + raise ValueError( + f"Distance must be between 0 and {max_distance:g}, got {distance_threshold}" + ) + return float(distance_threshold) + + def norm_l2_distance(value: float) -> float: """ Normalize the L2 distance. diff --git a/tests/unit/test_aggregation_types.py b/tests/unit/test_aggregation_types.py index aaac82fd2..e2e179d03 100644 --- a/tests/unit/test_aggregation_types.py +++ b/tests/unit/test_aggregation_types.py @@ -471,12 +471,17 @@ def test_vector_object_validation(): assert isinstance(vec, Vector) # max_distance is bounded to [0, 2.0] - for distance in [-0.1, 2.001, 35, -float("inf"), +float("inf")]: + for distance in [-0.1, 2.001, 35, -float("inf"), +float("inf"), True, "0.5"]: with pytest.raises(ValueError): vec = Vector( vector=sample_vector, field_name="text embedding", max_distance=distance ) + # Assignment is validated too, since max_distance is interpolated into the query. + vec = Vector(vector=sample_vector, field_name="text embedding") + with pytest.raises(ValueError): + vec.max_distance = "1) | @x:[0 inf]" + def test_vector_object_handles_byte_conversion(): # test that passing an array of floats gets converted to bytes diff --git a/tests/unit/test_langcache_semantic_cache.py b/tests/unit/test_langcache_semantic_cache.py index e49ca06ee..00bacebf8 100644 --- a/tests/unit/test_langcache_semantic_cache.py +++ b/tests/unit/test_langcache_semantic_cache.py @@ -321,6 +321,27 @@ def test_check_with_distance_threshold(self, mock_langcache_client): call_kwargs = mock_client.search.call_args.kwargs assert call_kwargs["similarity_threshold"] == 0.8 + @pytest.mark.parametrize( + "distance_scale, distance_threshold", + [("redis", 2.5), ("normalized", 1.5)], + ) + def test_check_refuses_a_threshold_outside_its_scale( + self, mock_langcache_client, distance_scale, distance_threshold + ): + """An invalid threshold is refused before it reaches the LangCache API.""" + _, mock_client = mock_langcache_client + cache = LangCacheSemanticCache( + name="test", + server_url="https://api.example.com", + cache_id="test-cache", + api_key="test-key", + distance_scale=distance_scale, + ) + + with pytest.raises(ValueError): + cache.check(prompt="What is Python?", distance_threshold=distance_threshold) + mock_client.search.assert_not_called() + def test_check_with_attributes(self, mock_langcache_client): """Test checking the cache with attributes filtering.""" _, mock_client = mock_langcache_client diff --git a/tests/unit/test_query_types.py b/tests/unit/test_query_types.py index 7fe562fa9..0f85c1226 100644 --- a/tests/unit/test_query_types.py +++ b/tests/unit/test_query_types.py @@ -844,6 +844,13 @@ def test_vector_range_query_error_handling(): with pytest.raises(ValueError, match="epsilon must be non-negative"): query.set_epsilon(-0.1) + # A bool is an int, and NaN fails every comparison, so neither is a radius. + with pytest.raises(TypeError, match="distance_threshold must be a real number"): + query.set_distance_threshold(True) + + with pytest.raises(ValueError, match="distance_threshold must be non-negative"): + query.set_distance_threshold(float("nan")) + # Test invalid hybrid policy with pytest.raises(ValueError, match="hybrid_policy must be one of"): query.set_hybrid_policy("INVALID") diff --git a/tests/unit/test_route_schema.py b/tests/unit/test_route_schema.py index 19fe1f39f..73842af97 100644 --- a/tests/unit/test_route_schema.py +++ b/tests/unit/test_route_schema.py @@ -77,6 +77,30 @@ def test_route_invalid_threshold_zero(): assert "Input should be greater than 0" in str(excinfo.value) +def test_route_threshold_assignment_is_validated(): + route = Route(name="Test Route", references=["reference1"]) + with pytest.raises(ValidationError): + route.distance_threshold = float("nan") + assert route.distance_threshold == 0.5 + + +def test_update_route_thresholds_applies_nothing_when_any_value_is_invalid(): + from redisvl.extensions.router.semantic import SemanticRouter + + # update_route_thresholds touches only `routes`, so skip the index setup; + # vectorizer=None keeps model_construct from loading the default model. + router = SemanticRouter.model_construct( + routes=[ + Route(name="greeting", references=["hello"]), + Route(name="farewell", references=["bye"]), + ], + vectorizer=None, + ) + with pytest.raises(ValidationError): + router.update_route_thresholds({"greeting": 0.9, "farewell": float("nan")}) + assert router.route_thresholds == {"greeting": 0.5, "farewell": 0.5} + + def test_route_invalid_threshold_negative(): with pytest.raises(ValidationError) as excinfo: Route( diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py new file mode 100644 index 000000000..d9d9d5497 --- /dev/null +++ b/tests/unit/test_semantic_cache_threshold.py @@ -0,0 +1,70 @@ +"""SemanticCache applies its distance-threshold rule on every path. + +The rule itself is tested in tests/unit/test_utils.py; these check that the +constructor, ``set_threshold``, ``check`` and ``acheck`` all apply it, and that +a lookup keeps a candidate that float32 rounding reports just above 2. +Hermetic: Redis and the vectorizer are stubbed out. +""" + +from unittest.mock import AsyncMock, Mock + +import pytest + +from redisvl.extensions.cache.llm import SemanticCache + + +@pytest.fixture +def cache(): + # Bypass __init__, which would connect to Redis and load a vectorizer, and + # stub what a lookup touches. + cache = SemanticCache.__new__(SemanticCache) + cache.name = "test_threshold" + cache.refresh_ttl_on_hit = True + cache._distance_threshold = 0.1 + cache._index = Mock(query=Mock(return_value=[])) + cache._get_async_index = AsyncMock( + return_value=Mock(query=AsyncMock(return_value=[])) + ) + cache._check_vector_dims = Mock() + cache._build_check_query = Mock() + cache._expire_many = Mock() + cache._aexpire_many = AsyncMock() + return cache + + +async def test_every_path_refuses_an_invalid_threshold(cache, monkeypatch): + # The constructor must refuse before it loads the default vectorizer. + monkeypatch.setattr( + "redisvl.extensions.cache.llm.semantic.HFTextVectorizer", + Mock(side_effect=AssertionError("default vectorizer loaded")), + ) + with pytest.raises(ValueError, match="between 0 and 2"): + SemanticCache(distance_threshold=float("nan")) + + with pytest.raises(ValueError, match="between 0 and 2"): + cache.set_threshold(float("nan")) + with pytest.raises(ValueError, match="between 0 and 2"): + cache.check(vector=[0.1], distance_threshold=float("nan")) + with pytest.raises(ValueError, match="between 0 and 2"): + await cache.acheck(vector=[0.1], distance_threshold=float("nan")) + assert cache.distance_threshold == 0.1 + + +def test_the_largest_threshold_keeps_a_rounded_opposite_vector(cache): + # Measured on Redis 8.10.3: FLOAT32 COSINE, 1536 dims, a query against its + # own negation comes back just above 2. + cache._index.query.return_value = [ + { + "id": "llmcache:1", + "entry_id": "1", + "prompt": "p", + "response": "r", + "vector_distance": "2.00000023842", + "inserted_at": 1.0, + "updated_at": 1.0, + } + ] + + hits = cache.check(vector=[0.1], distance_threshold=2) + + assert [hit["entry_id"] for hit in hits] == ["1"] diff --git a/tests/unit/test_semantic_history_threshold.py b/tests/unit/test_semantic_history_threshold.py new file mode 100644 index 000000000..575d6019e --- /dev/null +++ b/tests/unit/test_semantic_history_threshold.py @@ -0,0 +1,57 @@ +"""SemanticMessageHistory applies its distance-threshold rule on every path. + +The rule itself is tested in tests/unit/test_utils.py; this checks that the +constructor, ``set_distance_threshold`` and ``get_relevant`` all apply it. +Hermetic: an invalid threshold is refused before the history touches Redis or +its vectorizer. +""" + +from unittest.mock import Mock + +import pytest + +from redisvl.extensions.message_history import SemanticMessageHistory +from redisvl.query.filter import Tag + + +@pytest.fixture +def history(): + # Bypass __init__, which would connect to Redis and load a vectorizer, and + # stub what a lookup touches so that it returns no messages. + history = SemanticMessageHistory.__new__(SemanticMessageHistory) + history._distance_threshold = 0.1 + history._default_session_filter = Tag("session_tag") == "s1" + history._vectorizer = Mock(embed=Mock(return_value=[0.1]), dtype="float32") + history._index = Mock(query=Mock(return_value=[])) + return history + + +def test_the_largest_threshold_widens_the_range_radius(history): + # The radius is applied by Redis, which can report an exactly opposite + # vector a little above 2, so 2 must not be sent as the radius itself. + history.get_relevant("prompt", distance_threshold=2) + + (query,), _ = history._index.query.call_args + assert query.distance_threshold > 2.001 + + +def test_every_path_refuses_an_invalid_threshold(history, monkeypatch): + # The constructor must refuse before it loads the default vectorizer. + monkeypatch.setattr( + "redisvl.extensions.message_history.semantic_history.HFTextVectorizer", + Mock(side_effect=AssertionError("default vectorizer loaded")), + ) + nan = float("nan") + + with pytest.raises(ValueError, match="between 0 and 2"): + SemanticMessageHistory("history", distance_threshold=nan) + with pytest.raises(ValueError, match="between 0 and 2"): + history.set_distance_threshold(nan) + with pytest.raises(ValueError, match="between 0 and 2"): + history.get_relevant("prompt", distance_threshold=nan) + # Checked before the top_k == 0 early return, not skipped by it. + with pytest.raises(ValueError, match="between 0 and 2"): + history.get_relevant("prompt", top_k=0, distance_threshold=nan) + assert history.distance_threshold == 0.1 + history._vectorizer.embed.assert_not_called() + history._index.query.assert_not_called() diff --git a/tests/unit/test_semantic_router_queries.py b/tests/unit/test_semantic_router_queries.py index 4eb4938c7..0e09e32c3 100644 --- a/tests/unit/test_semantic_router_queries.py +++ b/tests/unit/test_semantic_router_queries.py @@ -5,8 +5,16 @@ fixtures -- which matters because a defect here silently deletes data. """ +import re +from unittest.mock import Mock + import pytest +from redisvl.extensions.router.schema import ( + DistanceAggregationMethod, + Route, + RoutingConfig, +) from redisvl.extensions.router.semantic import SemanticRouter @@ -27,3 +35,27 @@ def test_empty_reference_id_is_rejected_rather_than_matching_everything(empty): def test_one_empty_id_rejects_the_whole_batch(): with pytest.raises(ValueError, match="non-empty"): SemanticRouter._make_filter_queries(["abc123", "", "def456"]) + + +@pytest.mark.parametrize( + "aggregation_method, filter_widened", + [(DistanceAggregationMethod.min, True), (DistanceAggregationMethod.sum, False)], +) +def test_a_route_threshold_of_2_allows_for_rounding(aggregation_method, filter_widened): + # Redis can report an exactly opposite vector a little above 2. The range + # radius always allows for that; the FILTER does too, except for a sum, + # which can legitimately pass 2. + router = SemanticRouter.model_construct( + name="router", + routes=[Route(name="a", references=["x"], distance_threshold=2)], + vectorizer=None, + routing_config=RoutingConfig(), + ) + router._index = Mock(aggregate=Mock(return_value=Mock(rows=[]))) + + router(vector=[0.1, 0.2], aggregation_method=aggregation_method) + + request, params = router._index.aggregate.call_args.args + (filter_bound,) = re.findall(r"@distance <= ([\d.]+)", str(request.build_args())) + assert params["distance_threshold"] > 2.001 + assert (float(filter_bound) > 2.001) is filter_widened diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py index bf8dd29ba..6ca331f15 100644 --- a/tests/unit/test_utils.py +++ b/tests/unit/test_utils.py @@ -14,6 +14,7 @@ ) from redisvl.utils.utils import ( assert_no_warnings, + cosine_distance_bound, denorm_cosine_distance, deprecated_argument, deprecated_class, @@ -21,6 +22,7 @@ lazy_import, match_pattern, norm_cosine_distance, + validate_cosine_distance_threshold, ) @@ -45,6 +47,41 @@ def test_denorm_cosine_distance(): assert denorm_cosine_distance(input) == expected +@pytest.mark.parametrize( + ("threshold", "max_distance"), + [(0, 2), (2, 2), (np.float32(0.5), 2), (1, 1)], +) +def test_validate_cosine_distance_threshold_accepts_the_closed_range( + threshold, max_distance +): + result = validate_cosine_distance_threshold(threshold, max_distance=max_distance) + + assert result == float(threshold) and type(result) is float + + +@pytest.mark.parametrize( + ("threshold", "max_distance", "error"), + [ + (2 + 1e-9, 2, ValueError), + (-1e-9, 2, ValueError), + (float("nan"), 2, ValueError), + (1 + 1e-9, 1, ValueError), + # A bool is an int, and a numeric string is not a number. + (True, 2, TypeError), + ("0.5", 2, TypeError), + ], +) +def test_validate_cosine_distance_threshold_refuses(threshold, max_distance, error): + with pytest.raises(error): + validate_cosine_distance_threshold(threshold, max_distance=max_distance) + + +def test_cosine_distance_bound_widens_only_the_largest_threshold(): + assert cosine_distance_bound(1.5) == 1.5 + # Past the largest overshoot measured on Redis 8.10.3, FLOAT16 at 2.0006. + assert cosine_distance_bound(2.0) > 2.001 + + def test_norm_denorm_cosine(): input = 0.6 assert input == round(denorm_cosine_distance(norm_cosine_distance(input)), 6)