From bcb2351298915565f4abce5e07dd800f2e4a7717 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Tue, 13 Oct 2026 17:45:57 +0200 Subject: [PATCH 01/12] perf: run SemanticCache.check() as KNN with a client-side threshold check() and acheck() searched with a VectorRangeQuery, so Redis discarded every candidate beyond distance_threshold and a miss carried no information about how close it came. They now run a KNN VectorQuery for num_results candidates and keep those at or within the threshold in Python, inclusive as the range radius was. On the FLAT index the cache always uses, both queries are exhaustive, so hit and miss decisions match. Measured on Redis 8.4.7 they agreed on 3,000 of 3,000 samples per configuration and on 200 of 200 queries within 2e-6 of the threshold. The one theoretical difference is that the client compares the distance as Redis returns it, rounded to 12 significant digits, so a distance within about 1e-12 of the threshold can now fall on the other side of it. Unfiltered lookups take 2-3% longer. With a tag filter matching 10% of entries they take 13% less time at 1,000 entries and 36% less at 10,000, because KNN compares vectors only within the filtered subset where the range query scanned the whole index. The nearest candidate's distance is now in hand on every lookup, which the planned OpenTelemetry instrumentation reports. A per-call distance_threshold is still validated as the range query validated it: TypeError for a non-number, ValueError for a negative value. An id-only row (the Redis 8.8+ expiry race) still reaches _process_cache_results and is skipped there rather than raising. Query construction and the threshold filter are shared by the sync and async paths. --- redisvl/extensions/cache/llm/schema.py | 2 + redisvl/extensions/cache/llm/semantic.py | 90 +++++++++++++------ tests/integration/test_llmcache.py | 44 +++++++++ tests/unit/test_extension_result_hardening.py | 9 ++ 4 files changed, 117 insertions(+), 28 deletions(-) diff --git a/redisvl/extensions/cache/llm/schema.py b/redisvl/extensions/cache/llm/schema.py index c0cdd4e24..4442b7ac8 100644 --- a/redisvl/extensions/cache/llm/schema.py +++ b/redisvl/extensions/cache/llm/schema.py @@ -128,6 +128,8 @@ def from_params(cls, name: str, prefix: str, vector_dims: int, dtype: str): "dims": vector_dims, "datatype": dtype, "distance_metric": "cosine", + # SemanticCache.check() filters an exact KNN by + # threshold; HNSW would make its hits approximate. "algorithm": "flat", }, }, diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 439423cc2..cbe7eaa20 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -23,7 +23,7 @@ UPDATED_AT_FIELD_NAME, ) from redisvl.index import AsyncSearchIndex, SearchIndex -from redisvl.query import VectorRangeQuery +from redisvl.query import VectorQuery from redisvl.query.filter import FilterExpression from redisvl.redis.utils import hashify from redisvl.utils.log import get_logger @@ -486,6 +486,8 @@ def check( # (exact match only), so only fall back on None. if distance_threshold is None: distance_threshold = self._distance_threshold + else: + self._validate_distance_threshold(distance_threshold) # Vectorize prompt if not provided if vector is None and prompt is not None: @@ -497,23 +499,12 @@ def check( else: raise ValueError("Failed to generate a valid vector for the query.") - # Create the vector search query - query = VectorRangeQuery( - vector=vector, - vector_field_name=CACHE_VECTOR_FIELD_NAME, - return_fields=self.return_fields, - distance_threshold=distance_threshold, - num_results=num_results, - return_score=True, - filter_expression=filter_expression, - dtype=self._vectorizer.dtype, - ) - # Search the cache! - cache_search_results = self._index.query(query) + query = self._build_check_query(vector, num_results, filter_expression) + candidates = self._index.query(query) redis_keys, cache_hits = self._process_cache_results( - cache_search_results, - return_fields, # type: ignore + self._within_threshold(candidates, distance_threshold), + return_fields, ) # Refresh TTL on all found keys @@ -581,6 +572,8 @@ async def acheck( # (exact match only), so only fall back on None. if distance_threshold is None: distance_threshold = self._distance_threshold + else: + self._validate_distance_threshold(distance_threshold) # Vectorize prompt if not provided if vector is None and prompt is not None: @@ -592,29 +585,70 @@ async def acheck( else: raise ValueError("Failed to generate a valid vector for the query.") - # Create the vector search query - query = VectorRangeQuery( + # Search the cache! + query = self._build_check_query(vector, num_results, filter_expression) + candidates = await aindex.query(query) + redis_keys, cache_hits = self._process_cache_results( + self._within_threshold(candidates, distance_threshold), + return_fields, + ) + + # Refresh TTL on all found keys async + await asyncio.gather(*[self.aexpire(key) for key in redis_keys]) + + return cache_hits + + def _build_check_query( + self, + vector: list[float], + num_results: int, + filter_expression: FilterExpression | None, + ) -> VectorQuery: + """Build the KNN lookup shared by :meth:`check` and :meth:`acheck`. + + :meth:`_within_threshold` then applies the distance threshold, so the + nearest distance is known even on a miss. + """ + return VectorQuery( vector=vector, vector_field_name=CACHE_VECTOR_FIELD_NAME, return_fields=self.return_fields, - distance_threshold=distance_threshold, num_results=num_results, return_score=True, filter_expression=filter_expression, dtype=self._vectorizer.dtype, ) - # Search the cache! - cache_search_results = await aindex.query(query) - redis_keys, cache_hits = self._process_cache_results( - cache_search_results, - return_fields, # type: ignore - ) + @staticmethod + def _within_threshold( + candidates: list[dict[str, Any]], distance_threshold: float + ) -> list[dict[str, Any]]: + """Keep the candidates whose distance is at most the threshold. - # Refresh TTL on all found keys async - await asyncio.gather(*[self.aexpire(key) for key in redis_keys]) + Inclusive, as a range query's radius is, at the precision of the + distance Redis returns (12 significant digits). A candidate with no distance + (an id-only row from the Redis 8.8+ expiry race) is kept so that + :meth:`_process_cache_results` skips it with its usual warning. + """ + return [ + candidate + for candidate in candidates + if (distance := candidate.get(VectorQuery.DISTANCE_ID)) is None + or float(distance) <= distance_threshold + ] - return cache_hits + @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, diff --git a/tests/integration/test_llmcache.py b/tests/integration/test_llmcache.py index 4f5c59184..a0fa1e47e 100644 --- a/tests/integration/test_llmcache.py +++ b/tests/integration/test_llmcache.py @@ -596,6 +596,38 @@ async def test_acheck_with_zero_distance_threshold(cache): assert (await cache.acheck("what's the capital of france?")) != [] +@pytest.mark.parametrize("use_async", [False, True]) +async def test_check_threshold_is_inclusive(cache, vectorizer, use_async): + """A candidate at the threshold, as Redis reports its distance, hits; one + just beyond it does not.""" + prompts = [ + "what is the capital of france?", + "what's the capital of france?", + "how do I bake sourdough bread?", + ] + for prompt in prompts: + cache.store(prompt, "response", vector=vectorizer.embed(prompt)) + query = vectorizer.embed(prompts[0]) + + async def check(distance_threshold): + kwargs = dict( + vector=query, num_results=3, distance_threshold=distance_threshold + ) + return await cache.acheck(**kwargs) if use_async else cache.check(**kwargs) + + everything = await check(2) + distances = [hit["vector_distance"] for hit in everything] + assert len(distances) == 3 and distances == sorted(distances) + + at_threshold = await check(distances[1]) + assert [hit["key"] for hit in at_threshold] == [ + hit["key"] for hit in everything[:2] + ] + + beyond_threshold = await check(distances[1] - 1e-6) + assert [hit["key"] for hit in beyond_threshold] == [everything[0]["key"]] + + def test_check_invalid_input(cache): with pytest.raises(ValueError): cache.check() @@ -603,6 +635,12 @@ def test_check_invalid_input(cache): with pytest.raises(TypeError): cache.check(prompt="test", return_fields="bad value") + with pytest.raises(ValueError): + cache.check(prompt="test", distance_threshold=-0.1) + + with pytest.raises(TypeError): + cache.check(prompt="test", distance_threshold="0.1") + @pytest.mark.asyncio async def test_async_check_invalid_input(cache): @@ -612,6 +650,12 @@ async def test_async_check_invalid_input(cache): with pytest.raises(TypeError): await cache.acheck(prompt="test", return_fields="bad value") + with pytest.raises(ValueError): + await cache.acheck(prompt="test", distance_threshold=-0.1) + + with pytest.raises(TypeError): + await cache.acheck(prompt="test", distance_threshold="0.1") + def test_bad_connection_info(vectorizer, worker_id): with pytest.raises(ConnectionError): diff --git a/tests/unit/test_extension_result_hardening.py b/tests/unit/test_extension_result_hardening.py index a8b10a56b..717738643 100644 --- a/tests/unit/test_extension_result_hardening.py +++ b/tests/unit/test_extension_result_hardening.py @@ -61,6 +61,15 @@ def test_process_cache_results_bad_then_valid_ordering(): assert redis_keys == ["llmcache:key1"] # only the valid hit's key +def test_within_threshold_leaves_id_only_hit_for_the_skip_path(): + """The threshold filter must not raise on a hit with no distance.""" + far_hit = {**_valid_cache_hit(), "vector_distance": "0.3"} + candidates = [{"id": "llmcache:expired"}, far_hit] + assert SemanticCache._within_threshold(candidates, 0.2) == [ + {"id": "llmcache:expired"} + ] + + @pytest.mark.parametrize("as_text", [True, False]) def test_format_context_drops_id_only_message(as_text, caplog): """A message with 'id' but no entry_id/session_tag hits the KeyError arm.""" From a3fa48f9a5656b4e7d3c38d09fdd21b49a5fa154 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:51:06 +0100 Subject: [PATCH 02/12] fix(cache): apply one distance-threshold rule to SemanticCache The cache-wide threshold (__init__, set_threshold) accepted 0 to 2, while a per-call override (check, acheck) accepted any non-negative number, including values above 2, booleans and NaN, which turned every lookup into a silent miss. Both paths now share _validate_distance_threshold: a real number from 0 to 2 inclusive, refusing bool (TypeError), strings (TypeError) and NaN (ValueError), with set_threshold's existing ValueError message. --- redisvl/extensions/cache/llm/semantic.py | 49 ++++++++++++------ tests/unit/test_semantic_cache_threshold.py | 56 +++++++++++++++++++++ 2 files changed, 89 insertions(+), 16 deletions(-) create mode 100644 tests/unit/test_semantic_cache_threshold.py diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 781731df3..4c76dd590 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -1,3 +1,4 @@ +import numbers from typing import Any from pydantic import ValidationError @@ -299,13 +300,11 @@ 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 = self._validate_distance_threshold(distance_threshold) def delete(self) -> None: """Delete the cache and its index entirely. @@ -469,6 +468,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 @@ -486,7 +487,7 @@ def check( if distance_threshold is None: distance_threshold = self._distance_threshold else: - self._validate_distance_threshold(distance_threshold) + distance_threshold = self._validate_distance_threshold(distance_threshold) # Vectorize prompt if not provided if vector is None and prompt is not None: @@ -552,6 +553,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 @@ -571,7 +574,7 @@ async def acheck( if distance_threshold is None: distance_threshold = self._distance_threshold else: - self._validate_distance_threshold(distance_threshold) + distance_threshold = self._validate_distance_threshold(distance_threshold) # Vectorize prompt if not provided if vector is None and prompt is not None: @@ -636,17 +639,31 @@ def _within_threshold( ] @staticmethod - def _validate_distance_threshold(distance_threshold: float) -> None: - """Validate a per-call ``distance_threshold`` override. + def _validate_distance_threshold(distance_threshold: float) -> float: + """Validate a distance threshold and return it as a float. + + One rule for the cache-wide threshold and for a per-call override: a + real number from 0 to 2 inclusive, the range of the COSINE distance the + cache schema uses. A bool is refused even though it is an ``int``, and + NaN fails the range check, which it would otherwise pass silently by + matching nothing. Raises: - TypeError: If the threshold is not a float or int. - ValueError: If the threshold is negative. + TypeError: If the threshold is not a real number, or is a bool. + ValueError: If the threshold is not between 0 and 2, or is NaN. """ - 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__}" + ) + if not 0 <= distance_threshold <= 2: + raise ValueError( + f"Distance must be between 0 and 2, got {distance_threshold}" + ) + return float(distance_threshold) def _process_cache_results( self, diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py new file mode 100644 index 000000000..29eb73f26 --- /dev/null +++ b/tests/unit/test_semantic_cache_threshold.py @@ -0,0 +1,56 @@ +"""SemanticCache applies one distance-threshold rule everywhere. + +The cache-wide threshold (``__init__`` and ``set_threshold``) and a per-call +override (``check`` and ``acheck``) accept the same values and refuse the rest +with the same exception. Hermetic: an invalid override is refused before the +cache touches Redis or its vectorizer. +""" + +import re +from unittest.mock import AsyncMock + +import numpy as np +import pytest + +from redisvl.extensions.cache.llm import SemanticCache + +ACCEPTED = [0, 0.0, 2, 2.0, 0.5, np.float32(0.5)] + +REFUSED = [ + pytest.param(2 + 1e-9, ValueError, id="just-above-2"), + pytest.param(-1e-9, ValueError, id="just-below-0"), + pytest.param(float("nan"), ValueError, id="nan"), + pytest.param(True, TypeError, id="true"), + pytest.param(False, TypeError, id="false"), + pytest.param("0.5", TypeError, id="numeric-string"), +] + + +@pytest.fixture +def cache(): + # Bypass __init__, which would connect to Redis and load a vectorizer. + cache = SemanticCache.__new__(SemanticCache) + cache._distance_threshold = 0.1 + cache._get_async_index = AsyncMock() + return cache + + +@pytest.mark.parametrize("value", ACCEPTED) +def test_set_threshold_accepts_the_closed_range(cache, value): + cache.set_threshold(value) + + assert cache.distance_threshold == float(value) + assert type(cache.distance_threshold) is float + + +@pytest.mark.parametrize("value, error", REFUSED) +async def test_every_path_refuses_alike(cache, value, error): + with pytest.raises(error) as expected: + cache.set_threshold(value) + match = re.escape(str(expected.value)) + + with pytest.raises(error, match=match): + cache.check(vector=[0.1], distance_threshold=value) + with pytest.raises(error, match=match): + await cache.acheck(vector=[0.1], distance_threshold=value) + assert cache.distance_threshold == 0.1 From 96b60d006407088ac0be7a7cda8971cf86e2bce2 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 12:53:31 +0100 Subject: [PATCH 03/12] fix(cache): document the threshold rule and test the accept path Cover np.float32 and the 0/2 boundaries through check and acheck as well as set_threshold, and list the new TypeError on __init__. --- redisvl/extensions/cache/llm/semantic.py | 10 +++++--- tests/unit/test_semantic_cache_threshold.py | 28 ++++++++++++++++----- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 4c76dd590..dd9a6a1de 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -108,7 +108,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. @@ -458,7 +460,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. Returns: List[Dict[str, Any]]: A list of dicts containing the requested @@ -543,7 +546,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. Returns: List[Dict[str, Any]]: A list of dicts containing the requested diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py index 29eb73f26..dc8601324 100644 --- a/tests/unit/test_semantic_cache_threshold.py +++ b/tests/unit/test_semantic_cache_threshold.py @@ -7,14 +7,14 @@ """ import re -from unittest.mock import AsyncMock +from unittest.mock import AsyncMock, Mock import numpy as np import pytest from redisvl.extensions.cache.llm import SemanticCache -ACCEPTED = [0, 0.0, 2, 2.0, 0.5, np.float32(0.5)] +ACCEPTED = [0, 2, np.float32(0.5)] REFUSED = [ pytest.param(2 + 1e-9, ValueError, id="just-above-2"), @@ -28,19 +28,35 @@ @pytest.fixture def cache(): - # Bypass __init__, which would connect to Redis and load a vectorizer. + # Bypass __init__, which would connect to Redis and load a vectorizer, and + # stub what a lookup touches so that it returns no candidates. cache = SemanticCache.__new__(SemanticCache) cache._distance_threshold = 0.1 - cache._get_async_index = AsyncMock() + 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 @pytest.mark.parametrize("value", ACCEPTED) -def test_set_threshold_accepts_the_closed_range(cache, value): +async def test_every_path_accepts_the_closed_range(cache, value): + applied = [] + cache._within_threshold = ( + lambda candidates, threshold: applied.append(threshold) or candidates + ) + + cache.check(vector=[0.1], distance_threshold=value) + await cache.acheck(vector=[0.1], distance_threshold=value) cache.set_threshold(value) + assert applied == [float(value)] * 2 assert cache.distance_threshold == float(value) - assert type(cache.distance_threshold) is float + assert all(type(t) is float for t in [*applied, cache.distance_threshold]) @pytest.mark.parametrize("value, error", REFUSED) From c3e27d3f5d9c7ad818a1721bbf2980ecb0440b82 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 13:47:51 +0100 Subject: [PATCH 04/12] fix(message-history): validate SemanticMessageHistory distance thresholds Apply SemanticCache's distance-threshold rule to SemanticMessageHistory: the constructor, set_distance_threshold and the get_relevant override now accept a real number from 0 to 2 inclusive and refuse strings, bools, NaN and values outside the COSINE range. Move the rule into redisvl.utils.utils.validate_cosine_distance_threshold so that both classes share it. --- redisvl/extensions/cache/llm/semantic.py | 37 ++-------- .../message_history/semantic_history.py | 41 +++++++++-- redisvl/utils/utils.py | 24 +++++++ tests/unit/test_semantic_history_threshold.py | 68 +++++++++++++++++++ 4 files changed, 132 insertions(+), 38 deletions(-) create mode 100644 tests/unit/test_semantic_history_threshold.py diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index dd9a6a1de..f84daeea2 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -1,4 +1,3 @@ -import numbers from typing import Any from pydantic import ValidationError @@ -31,6 +30,7 @@ current_timestamp, deprecated_argument, serialize, + validate_cosine_distance_threshold, validate_vector_dims, ) from redisvl.utils.vectorize.base import BaseVectorizer @@ -306,7 +306,9 @@ def set_threshold(self, distance_threshold: float) -> None: ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance), or is NaN. """ - self._distance_threshold = self._validate_distance_threshold(distance_threshold) + self._distance_threshold = validate_cosine_distance_threshold( + distance_threshold + ) def delete(self) -> None: """Delete the cache and its index entirely. @@ -490,7 +492,7 @@ def check( if distance_threshold is None: distance_threshold = self._distance_threshold else: - distance_threshold = 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: @@ -578,7 +580,7 @@ async def acheck( if distance_threshold is None: distance_threshold = self._distance_threshold else: - distance_threshold = 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: @@ -642,33 +644,6 @@ def _within_threshold( or float(distance) <= distance_threshold ] - @staticmethod - def _validate_distance_threshold(distance_threshold: float) -> float: - """Validate a distance threshold and return it as a float. - - One rule for the cache-wide threshold and for a per-call override: a - real number from 0 to 2 inclusive, the range of the COSINE distance the - cache schema uses. A bool is refused even though it is an ``int``, and - NaN fails the range check, which it would otherwise pass silently by - matching nothing. - - Raises: - TypeError: If the threshold is not a real number, or is a bool. - ValueError: If the threshold is not between 0 and 2, 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 <= 2: - raise ValueError( - f"Distance must be between 0 and 2, got {distance_threshold}" - ) - return float(distance_threshold) - 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..59baf6ace 100644 --- a/redisvl/extensions/message_history/semantic_history.py +++ b/redisvl/extensions/message_history/semantic_history.py @@ -23,7 +23,12 @@ 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 ( + deprecated_argument, + serialize, + validate_cosine_distance_threshold, + validate_vector_dims, +) from redisvl.utils.vectorize import BaseVectorizer, HFTextVectorizer logger = get_logger(__name__) @@ -61,7 +66,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 +85,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 @@ -258,7 +268,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,8 +282,11 @@ 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") @@ -286,6 +300,8 @@ def get_relevant( # (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) return_fields = [ SESSION_FIELD_NAME, @@ -423,8 +439,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/utils/utils.py b/redisvl/utils/utils.py index 0e0ec28de..9c042e794 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,29 @@ def denorm_cosine_distance(value: float) -> float: return max(2 - 2 * value, 0) +def validate_cosine_distance_threshold(distance_threshold: float) -> float: + """Validate a COSINE distance threshold and return it as a float. + + A real number from 0 to 2 inclusive, the range of Redis COSINE distance. A + bool is refused even though it is an ``int``, and NaN fails the range + check, which it would otherwise pass silently by matching nothing. + + Raises: + TypeError: If the threshold is not a real number, or is a bool. + ValueError: If the threshold is not between 0 and 2, 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 <= 2: + raise ValueError(f"Distance must be between 0 and 2, got {distance_threshold}") + return float(distance_threshold) + + def norm_l2_distance(value: float) -> float: """ Normalize the L2 distance. diff --git a/tests/unit/test_semantic_history_threshold.py b/tests/unit/test_semantic_history_threshold.py new file mode 100644 index 000000000..d60b59947 --- /dev/null +++ b/tests/unit/test_semantic_history_threshold.py @@ -0,0 +1,68 @@ +"""SemanticMessageHistory applies one distance-threshold rule everywhere. + +The history-wide threshold (``__init__`` and ``set_distance_threshold``) and a +per-call override (``get_relevant``) accept the same values and refuse the rest +with the same exception, the rule ``SemanticCache`` uses. Hermetic: an invalid +threshold is refused before the history touches Redis or its vectorizer. +""" + +import re +from unittest.mock import Mock + +import numpy as np +import pytest + +from redisvl.extensions.message_history import SemanticMessageHistory +from redisvl.query.filter import Tag +from redisvl.utils.vectorize import BaseVectorizer + +ACCEPTED = [0, 2, np.float32(0.5)] + +REFUSED = [ + pytest.param(2 + 1e-9, ValueError, id="just-above-2"), + pytest.param(-1e-9, ValueError, id="just-below-0"), + pytest.param(float("nan"), ValueError, id="nan"), + pytest.param(True, TypeError, id="true"), + pytest.param(False, TypeError, id="false"), + pytest.param("0.5", TypeError, id="numeric-string"), +] + + +@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 + + +@pytest.mark.parametrize("value", ACCEPTED) +def test_every_path_accepts_the_closed_range(history, value): + history.get_relevant("prompt", distance_threshold=value) + history.set_distance_threshold(value) + + (query,), _ = history._index.query.call_args + assert query.distance_threshold == float(value) + assert history.distance_threshold == float(value) + assert type(history.distance_threshold) is float + + +@pytest.mark.parametrize("value, error", REFUSED) +def test_every_path_refuses_alike(history, value, error): + with pytest.raises(error) as expected: + history.set_distance_threshold(value) + match = re.escape(str(expected.value)) + + with pytest.raises(error, match=match): + history.get_relevant("prompt", distance_threshold=value) + with pytest.raises(error, match=match): + SemanticMessageHistory( + "history", vectorizer=Mock(spec=BaseVectorizer), distance_threshold=value + ) + assert history.distance_threshold == 0.1 + history._vectorizer.embed.assert_not_called() + history._index.query.assert_not_called() From 968e362739757a9f6998f727ef3f7ccb560044f5 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 13:49:44 +0100 Subject: [PATCH 05/12] fix(message-history): check the threshold before any early exit Refuse a bad distance threshold before the constructor loads the default vectorizer, and before get_relevant returns early for top_k=0, so that every path refuses the same values. --- .../message_history/semantic_history.py | 14 ++++++++------ tests/unit/test_semantic_history_threshold.py | 15 ++++++++++----- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/redisvl/extensions/message_history/semantic_history.py b/redisvl/extensions/message_history/semantic_history.py index 59baf6ace..ac61af076 100644 --- a/redisvl/extensions/message_history/semantic_history.py +++ b/redisvl/extensions/message_history/semantic_history.py @@ -97,6 +97,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) @@ -290,12 +292,6 @@ def get_relevant( """ if type(top_k) != int or top_k < 0: raise ValueError("top_k must be an integer greater than or equal to -1") - 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: @@ -303,6 +299,12 @@ def get_relevant( 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) + return_fields = [ SESSION_FIELD_NAME, ROLE_FIELD_NAME, diff --git a/tests/unit/test_semantic_history_threshold.py b/tests/unit/test_semantic_history_threshold.py index d60b59947..11cc326a0 100644 --- a/tests/unit/test_semantic_history_threshold.py +++ b/tests/unit/test_semantic_history_threshold.py @@ -14,7 +14,6 @@ from redisvl.extensions.message_history import SemanticMessageHistory from redisvl.query.filter import Tag -from redisvl.utils.vectorize import BaseVectorizer ACCEPTED = [0, 2, np.float32(0.5)] @@ -52,7 +51,13 @@ def test_every_path_accepts_the_closed_range(history, value): @pytest.mark.parametrize("value, error", REFUSED) -def test_every_path_refuses_alike(history, value, error): +def test_every_path_refuses_alike(history, monkeypatch, value, error): + # 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")), + ) + with pytest.raises(error) as expected: history.set_distance_threshold(value) match = re.escape(str(expected.value)) @@ -60,9 +65,9 @@ def test_every_path_refuses_alike(history, value, error): with pytest.raises(error, match=match): history.get_relevant("prompt", distance_threshold=value) with pytest.raises(error, match=match): - SemanticMessageHistory( - "history", vectorizer=Mock(spec=BaseVectorizer), distance_threshold=value - ) + history.get_relevant("prompt", top_k=0, distance_threshold=value) + with pytest.raises(error, match=match): + SemanticMessageHistory("history", distance_threshold=value) assert history.distance_threshold == 0.1 history._vectorizer.embed.assert_not_called() history._index.query.assert_not_called() From 4783dd17b5ea8bb4afe98a010472f5d5db46caac Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 13:50:20 +0100 Subject: [PATCH 06/12] fix(router): validate route distance thresholds on assignment Route.distance_threshold was checked only at construction, so update_route_thresholds and direct assignment accepted NaN, bools, strings and out-of-range numbers, which then reached the aggregation FILTER. Route now validates on assignment, and update_route_thresholds checks every value before applying any. --- redisvl/extensions/router/schema.py | 7 +- redisvl/extensions/router/semantic.py | 24 ++++-- tests/unit/test_route_threshold_validation.py | 74 +++++++++++++++++++ 3 files changed, 99 insertions(+), 6 deletions(-) create mode 100644 tests/unit/test_route_threshold_validation.py 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 5b3778a2d..c43654623 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, @@ -38,6 +39,8 @@ logger = get_logger(__name__) +_DISTANCE_THRESHOLD_ADAPTER = TypeAdapter(DistanceThreshold) + class SemanticRouter(BaseModel): """Semantic Router for managing and querying route vectors.""" @@ -300,7 +303,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 +319,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: @@ -1254,7 +1266,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/tests/unit/test_route_threshold_validation.py b/tests/unit/test_route_threshold_validation.py new file mode 100644 index 000000000..856fd7039 --- /dev/null +++ b/tests/unit/test_route_threshold_validation.py @@ -0,0 +1,74 @@ +"""Hermetic tests that a route's distance threshold is validated on every path. + +The threshold is interpolated into the router's aggregation FILTER, so a value +that slips past validation either breaks routing silently (NaN, out of range) +or rewrites the query (a string). The constructor has always enforced (0, 2]; +these pin assignment and `update_route_thresholds` to the same rule. +""" + +import math + +import pytest +from pydantic import ValidationError + +from redisvl.extensions.router.schema import Route +from redisvl.extensions.router.semantic import SemanticRouter + +INVALID = [math.nan, True, "0.5", 3, 0] +INVALID_IDS = ["nan", "bool", "numeric_string", "above_range", "zero"] + + +def _route(name="greeting", threshold=0.5): + return Route(name=name, references=["hello"], distance_threshold=threshold) + + +def _router(*routes): + # update_route_thresholds touches only `routes`, so skip the index setup. + # Passing `vectorizer` keeps model_construct from building the default + # HuggingFace one, which would download a model. + return SemanticRouter.model_construct(routes=list(routes), vectorizer=None) + + +@pytest.mark.parametrize("value", INVALID, ids=INVALID_IDS) +def test_constructor_and_assignment_reject_the_same_values(value): + with pytest.raises(ValidationError): + _route(threshold=value) + + route = _route() + with pytest.raises(ValidationError): + route.distance_threshold = value + assert route.distance_threshold == 0.5 + + +def test_assignment_rejects_none(): + route = _route() + with pytest.raises(ValidationError): + route.distance_threshold = None + + +@pytest.mark.parametrize("value", [2, 2.0, 1e-9]) +def test_assignment_accepts_the_range_bounds(value): + route = _route() + route.distance_threshold = value + assert route.distance_threshold == value + + +@pytest.mark.parametrize("value", INVALID + [None], ids=INVALID_IDS + ["none"]) +def test_update_route_thresholds_rejects_invalid_values(value): + router = _router(_route()) + with pytest.raises(ValidationError): + router.update_route_thresholds({"greeting": value}) + assert router.route_thresholds == {"greeting": 0.5} + + +def test_update_route_thresholds_applies_nothing_when_any_value_is_invalid(): + router = _router(_route("greeting"), _route("farewell")) + with pytest.raises(ValidationError): + router.update_route_thresholds({"greeting": 0.9, "farewell": math.nan}) + assert router.route_thresholds == {"greeting": 0.5, "farewell": 0.5} + + +def test_update_route_thresholds_accepts_upper_bound(): + router = _router(_route("greeting"), _route("farewell")) + router.update_route_thresholds({"greeting": 2, "farewell": 0.25}) + assert router.route_thresholds == {"greeting": 2.0, "farewell": 0.25} From fa15f25bfcb1278f967aef4592dbb4c16cba9083 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 30 Oct 2026 13:53:34 +0100 Subject: [PATCH 07/12] test(router): fold None into the shared invalid-threshold cases --- tests/unit/test_route_threshold_validation.py | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/tests/unit/test_route_threshold_validation.py b/tests/unit/test_route_threshold_validation.py index 856fd7039..5aba67bba 100644 --- a/tests/unit/test_route_threshold_validation.py +++ b/tests/unit/test_route_threshold_validation.py @@ -14,8 +14,8 @@ from redisvl.extensions.router.schema import Route from redisvl.extensions.router.semantic import SemanticRouter -INVALID = [math.nan, True, "0.5", 3, 0] -INVALID_IDS = ["nan", "bool", "numeric_string", "above_range", "zero"] +INVALID = [math.nan, True, "0.5", 3, 0, None] +INVALID_IDS = ["nan", "bool", "numeric_string", "above_range", "zero", "none"] def _route(name="greeting", threshold=0.5): @@ -40,12 +40,6 @@ def test_constructor_and_assignment_reject_the_same_values(value): assert route.distance_threshold == 0.5 -def test_assignment_rejects_none(): - route = _route() - with pytest.raises(ValidationError): - route.distance_threshold = None - - @pytest.mark.parametrize("value", [2, 2.0, 1e-9]) def test_assignment_accepts_the_range_bounds(value): route = _route() @@ -53,7 +47,7 @@ def test_assignment_accepts_the_range_bounds(value): assert route.distance_threshold == value -@pytest.mark.parametrize("value", INVALID + [None], ids=INVALID_IDS + ["none"]) +@pytest.mark.parametrize("value", INVALID, ids=INVALID_IDS) def test_update_route_thresholds_rejects_invalid_values(value): router = _router(_route()) with pytest.raises(ValidationError): From b8808d03b2b3cf416e783325b9d767c674e3df8d Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Mon, 9 Nov 2026 17:16:06 +0100 Subject: [PATCH 08/12] test(cache): give the hermetic threshold fixture what the telemetry wrapper reads main's check and acheck now run inside _telemetry.operation, which reads cache.name, and resolve refresh_ttl_on_hit. --- tests/unit/test_semantic_cache_threshold.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py index dc8601324..55f2db32b 100644 --- a/tests/unit/test_semantic_cache_threshold.py +++ b/tests/unit/test_semantic_cache_threshold.py @@ -31,6 +31,8 @@ def cache(): # Bypass __init__, which would connect to Redis and load a vectorizer, and # stub what a lookup touches so that it returns no candidates. 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( From d9896fd4436227c62fae90b3a46b5f311d60b2b4 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Thu, 19 Nov 2026 16:40:22 +0100 Subject: [PATCH 09/12] test(cache): keep only threshold cases that fail without the fix Drop the 0 and 2 accept cases, which the integration tests already run end to end, and the False case, which reaches the same bool branch as True. Reword the validator docstring's NaN sentence. --- redisvl/extensions/cache/llm/semantic.py | 6 +++--- tests/unit/test_semantic_cache_threshold.py | 7 ++++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 2191dc177..c70fa3ad6 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -682,9 +682,9 @@ def _validate_distance_threshold(distance_threshold: float) -> float: One rule for the cache-wide threshold and for a per-call override: a real number from 0 to 2 inclusive, the range of the COSINE distance the - cache schema uses. A bool is refused even though it is an ``int``, and - NaN fails the range check, which it would otherwise pass silently by - matching nothing. + cache schema uses. 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. diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py index 55f2db32b..87a288ceb 100644 --- a/tests/unit/test_semantic_cache_threshold.py +++ b/tests/unit/test_semantic_cache_threshold.py @@ -14,14 +14,14 @@ from redisvl.extensions.cache.llm import SemanticCache -ACCEPTED = [0, 2, np.float32(0.5)] +# The 0 and 2 boundaries run end to end in tests/integration/test_llmcache.py. +ACCEPTED = [np.float32(0.5)] REFUSED = [ pytest.param(2 + 1e-9, ValueError, id="just-above-2"), pytest.param(-1e-9, ValueError, id="just-below-0"), pytest.param(float("nan"), ValueError, id="nan"), pytest.param(True, TypeError, id="true"), - pytest.param(False, TypeError, id="false"), pytest.param("0.5", TypeError, id="numeric-string"), ] @@ -46,7 +46,7 @@ def cache(): @pytest.mark.parametrize("value", ACCEPTED) -async def test_every_path_accepts_the_closed_range(cache, value): +async def test_every_path_accepts_a_numpy_scalar_as_a_float(cache, value): applied = [] cache._within_threshold = ( lambda candidates, threshold: applied.append(threshold) or candidates @@ -58,6 +58,7 @@ async def test_every_path_accepts_the_closed_range(cache, value): assert applied == [float(value)] * 2 assert cache.distance_threshold == float(value) + # A numpy scalar must not reach the client-side filter or the span attribute. assert all(type(t) is float for t in [*applied, cache.distance_threshold]) From e434aff46296ac23ec22190d7e5d9d49808478cd Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Thu, 19 Nov 2026 16:45:18 +0100 Subject: [PATCH 10/12] fix: refuse bool and NaN distance thresholds in every sibling site Apply the cosine threshold rule to LangCacheSemanticCache overrides (0-2 on the redis scale, 0-1 normalized), refuse bool and NaN in VectorRangeQuery.set_distance_threshold, and refuse bool and strings in Vector.max_distance before pydantic coerces them. SemanticCache now clamps a reported distance to 2 before comparing it, as norm_cosine_distance does, because float32 rounding can put an exactly opposite vector just above 2 and past the largest allowed threshold. Trim router and history tests that pass without the fix. --- redisvl/extensions/cache/llm/langcache.py | 14 +++++++--- redisvl/extensions/cache/llm/semantic.py | 4 ++- redisvl/query/aggregate.py | 16 ++++++----- redisvl/query/query.py | 17 ++++++++---- redisvl/utils/utils.py | 22 +++++++++------ tests/unit/test_aggregation_types.py | 2 +- tests/unit/test_langcache_semantic_cache.py | 27 +++++++++++++++++++ tests/unit/test_query_types.py | 7 +++++ tests/unit/test_route_threshold_validation.py | 9 ++----- tests/unit/test_semantic_cache_threshold.py | 7 +++++ tests/unit/test_semantic_history_threshold.py | 7 ++--- 11 files changed, 98 insertions(+), 34 deletions(-) diff --git a/redisvl/extensions/cache/llm/langcache.py b/redisvl/extensions/cache/llm/langcache.py index b3d1ab684..e87fff037 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, diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 46fb41584..aee01e94b 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -675,7 +675,9 @@ def _within_threshold( candidate for candidate in candidates if (distance := candidate.get(VectorQuery.DISTANCE_ID)) is None - or float(distance) <= distance_threshold + # Clamped as norm_cosine_distance is: float32 rounding can report an + # exactly opposite vector a little above 2, past the largest threshold. + or min(float(distance), 2.0) <= distance_threshold ] def _process_cache_results( diff --git a/redisvl/query/aggregate.py b/redisvl/query/aggregate.py index dd0604d2d..feb407d35 100644 --- a/redisvl/query/aggregate.py +++ b/redisvl/query/aggregate.py @@ -1,3 +1,4 @@ +import numbers from typing import Any, Self from pydantic import BaseModel, Field, field_validator, model_validator @@ -48,14 +49,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..c57122db2 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,19 @@ 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 """ - if not isinstance(distance_threshold, (float, int)): + if isinstance(distance_threshold, bool) or not isinstance( + distance_threshold, numbers.Real + ): raise TypeError("distance_threshold must be of type float or int") - if distance_threshold < 0: - raise ValueError("distance_threshold must be non-negative") + # 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 56a8cc6b0..52a082c22 100644 --- a/redisvl/utils/utils.py +++ b/redisvl/utils/utils.py @@ -293,17 +293,21 @@ def denorm_cosine_distance(value: float) -> float: return max(2 - 2 * value, 0) -def validate_cosine_distance_threshold(distance_threshold: float) -> float: +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 2 inclusive, the range of Redis COSINE distance. 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. + 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 2, or is NaN. + 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 @@ -312,8 +316,10 @@ def validate_cosine_distance_threshold(distance_threshold: float) -> float: "distance_threshold must be a real number, got " f"{type(distance_threshold).__name__}" ) - if not 0 <= distance_threshold <= 2: - raise ValueError(f"Distance must be between 0 and 2, got {distance_threshold}") + 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) diff --git a/tests/unit/test_aggregation_types.py b/tests/unit/test_aggregation_types.py index aaac82fd2..d3e757e2d 100644 --- a/tests/unit/test_aggregation_types.py +++ b/tests/unit/test_aggregation_types.py @@ -471,7 +471,7 @@ 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 diff --git a/tests/unit/test_langcache_semantic_cache.py b/tests/unit/test_langcache_semantic_cache.py index e49ca06ee..3c05caaeb 100644 --- a/tests/unit/test_langcache_semantic_cache.py +++ b/tests/unit/test_langcache_semantic_cache.py @@ -321,6 +321,33 @@ 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, error", + [ + ("redis", 2.5, ValueError), + ("redis", float("nan"), ValueError), + ("normalized", 1.5, ValueError), + ("normalized", True, TypeError), + ("normalized", "0.2", TypeError), + ], + ) + def test_check_refuses_invalid_distance_threshold( + self, mock_langcache_client, distance_scale, distance_threshold, error + ): + """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(error): + 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..faa828e0c 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 of type"): + 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_threshold_validation.py b/tests/unit/test_route_threshold_validation.py index 5aba67bba..4a97e4470 100644 --- a/tests/unit/test_route_threshold_validation.py +++ b/tests/unit/test_route_threshold_validation.py @@ -40,13 +40,6 @@ def test_constructor_and_assignment_reject_the_same_values(value): assert route.distance_threshold == 0.5 -@pytest.mark.parametrize("value", [2, 2.0, 1e-9]) -def test_assignment_accepts_the_range_bounds(value): - route = _route() - route.distance_threshold = value - assert route.distance_threshold == value - - @pytest.mark.parametrize("value", INVALID, ids=INVALID_IDS) def test_update_route_thresholds_rejects_invalid_values(value): router = _router(_route()) @@ -63,6 +56,8 @@ def test_update_route_thresholds_applies_nothing_when_any_value_is_invalid(): def test_update_route_thresholds_accepts_upper_bound(): + # Passes before the fix too: it pins that the new up-front check keeps the + # inclusive bound and still applies valid values. router = _router(_route("greeting"), _route("farewell")) router.update_route_thresholds({"greeting": 2, "farewell": 0.25}) assert router.route_thresholds == {"greeting": 2.0, "farewell": 0.25} diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py index 87a288ceb..06553a4fa 100644 --- a/tests/unit/test_semantic_cache_threshold.py +++ b/tests/unit/test_semantic_cache_threshold.py @@ -62,6 +62,13 @@ async def test_every_path_accepts_a_numpy_scalar_as_a_float(cache, value): assert all(type(t) is float for t in [*applied, cache.distance_threshold]) +def test_the_largest_threshold_keeps_a_rounded_opposite_vector(): + # Measured on Redis 8.10.3: FLOAT32 COSINE, 1536 dims, query against -query. + candidates = [{"vector_distance": "2.00000023842"}] + + assert SemanticCache._within_threshold(candidates, 2.0) == candidates + + @pytest.mark.parametrize("value, error", REFUSED) async def test_every_path_refuses_alike(cache, value, error): with pytest.raises(error) as expected: diff --git a/tests/unit/test_semantic_history_threshold.py b/tests/unit/test_semantic_history_threshold.py index 11cc326a0..8a2ca8054 100644 --- a/tests/unit/test_semantic_history_threshold.py +++ b/tests/unit/test_semantic_history_threshold.py @@ -15,14 +15,15 @@ from redisvl.extensions.message_history import SemanticMessageHistory from redisvl.query.filter import Tag -ACCEPTED = [0, 2, np.float32(0.5)] +# 2 pins the inclusive upper bound, which no integration test reaches; 0 is +# covered end to end in tests/integration/test_message_history.py. +ACCEPTED = [2, np.float32(0.5)] REFUSED = [ pytest.param(2 + 1e-9, ValueError, id="just-above-2"), pytest.param(-1e-9, ValueError, id="just-below-0"), pytest.param(float("nan"), ValueError, id="nan"), pytest.param(True, TypeError, id="true"), - pytest.param(False, TypeError, id="false"), pytest.param("0.5", TypeError, id="numeric-string"), ] @@ -40,7 +41,7 @@ def history(): @pytest.mark.parametrize("value", ACCEPTED) -def test_every_path_accepts_the_closed_range(history, value): +def test_every_path_accepts_a_valid_threshold_as_a_float(history, value): history.get_relevant("prompt", distance_threshold=value) history.set_distance_threshold(value) From a80b6b4f5dc121a62bb10f48731df465063c5056 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Thu, 19 Nov 2026 16:54:35 +0100 Subject: [PATCH 11/12] fix: validate thresholds before loading models, and on Vector assignment SemanticCache now refuses a bad threshold before it builds the default vectorizer, as SemanticMessageHistory does. Vector validates max_distance on assignment as well as construction, since it is interpolated into the query. Name the real-number rule in VectorRangeQuery's TypeError and list the new errors in LangCache's check and acheck. Test the shared rule once in test_utils.py and keep one wiring check per entry point; move the router cases into test_route_schema.py. --- redisvl/extensions/cache/llm/langcache.py | 6 ++ redisvl/extensions/cache/llm/semantic.py | 2 + redisvl/query/aggregate.py | 5 +- redisvl/query/query.py | 8 +- tests/unit/test_aggregation_types.py | 5 ++ tests/unit/test_langcache_semantic_cache.py | 16 ++-- tests/unit/test_query_types.py | 2 +- tests/unit/test_route_schema.py | 24 +++++ tests/unit/test_route_threshold_validation.py | 63 ------------- tests/unit/test_semantic_cache_threshold.py | 90 ++++++++----------- tests/unit/test_semantic_history_threshold.py | 60 ++++--------- tests/unit/test_utils.py | 30 +++++++ 12 files changed, 139 insertions(+), 172 deletions(-) delete mode 100644 tests/unit/test_route_threshold_validation.py diff --git a/redisvl/extensions/cache/llm/langcache.py b/redisvl/extensions/cache/llm/langcache.py index e87fff037..99af75f27 100644 --- a/redisvl/extensions/cache/llm/langcache.py +++ b/redisvl/extensions/cache/llm/langcache.py @@ -308,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") @@ -390,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 aee01e94b..f8d8756b5 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -136,6 +136,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__( diff --git a/redisvl/query/aggregate.py b/redisvl/query/aggregate.py index feb407d35..f4b3edb73 100644 --- a/redisvl/query/aggregate.py +++ b/redisvl/query/aggregate.py @@ -1,7 +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 @@ -32,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" diff --git a/redisvl/query/query.py b/redisvl/query/query.py index c57122db2..b0d63dd12 100644 --- a/redisvl/query/query.py +++ b/redisvl/query/query.py @@ -993,12 +993,16 @@ def set_distance_threshold(self, distance_threshold: float): Raises: TypeError: If distance_threshold is not a real number, or is a bool - ValueError: If distance_threshold is negative or NaN + ValueError: If distance_threshold is negative or NaN, or above 1 + when normalize_vector_distance is True """ if isinstance(distance_threshold, bool) or not isinstance( distance_threshold, numbers.Real ): - raise TypeError("distance_threshold must be of type float or int") + 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( diff --git a/tests/unit/test_aggregation_types.py b/tests/unit/test_aggregation_types.py index d3e757e2d..e2e179d03 100644 --- a/tests/unit/test_aggregation_types.py +++ b/tests/unit/test_aggregation_types.py @@ -477,6 +477,11 @@ def test_vector_object_validation(): 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 3c05caaeb..00bacebf8 100644 --- a/tests/unit/test_langcache_semantic_cache.py +++ b/tests/unit/test_langcache_semantic_cache.py @@ -322,17 +322,11 @@ def test_check_with_distance_threshold(self, mock_langcache_client): assert call_kwargs["similarity_threshold"] == 0.8 @pytest.mark.parametrize( - "distance_scale, distance_threshold, error", - [ - ("redis", 2.5, ValueError), - ("redis", float("nan"), ValueError), - ("normalized", 1.5, ValueError), - ("normalized", True, TypeError), - ("normalized", "0.2", TypeError), - ], + "distance_scale, distance_threshold", + [("redis", 2.5), ("normalized", 1.5)], ) - def test_check_refuses_invalid_distance_threshold( - self, mock_langcache_client, distance_scale, distance_threshold, error + 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 @@ -344,7 +338,7 @@ def test_check_refuses_invalid_distance_threshold( distance_scale=distance_scale, ) - with pytest.raises(error): + with pytest.raises(ValueError): cache.check(prompt="What is Python?", distance_threshold=distance_threshold) mock_client.search.assert_not_called() diff --git a/tests/unit/test_query_types.py b/tests/unit/test_query_types.py index faa828e0c..0f85c1226 100644 --- a/tests/unit/test_query_types.py +++ b/tests/unit/test_query_types.py @@ -845,7 +845,7 @@ def test_vector_range_query_error_handling(): 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 of type"): + 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"): 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_route_threshold_validation.py b/tests/unit/test_route_threshold_validation.py deleted file mode 100644 index 4a97e4470..000000000 --- a/tests/unit/test_route_threshold_validation.py +++ /dev/null @@ -1,63 +0,0 @@ -"""Hermetic tests that a route's distance threshold is validated on every path. - -The threshold is interpolated into the router's aggregation FILTER, so a value -that slips past validation either breaks routing silently (NaN, out of range) -or rewrites the query (a string). The constructor has always enforced (0, 2]; -these pin assignment and `update_route_thresholds` to the same rule. -""" - -import math - -import pytest -from pydantic import ValidationError - -from redisvl.extensions.router.schema import Route -from redisvl.extensions.router.semantic import SemanticRouter - -INVALID = [math.nan, True, "0.5", 3, 0, None] -INVALID_IDS = ["nan", "bool", "numeric_string", "above_range", "zero", "none"] - - -def _route(name="greeting", threshold=0.5): - return Route(name=name, references=["hello"], distance_threshold=threshold) - - -def _router(*routes): - # update_route_thresholds touches only `routes`, so skip the index setup. - # Passing `vectorizer` keeps model_construct from building the default - # HuggingFace one, which would download a model. - return SemanticRouter.model_construct(routes=list(routes), vectorizer=None) - - -@pytest.mark.parametrize("value", INVALID, ids=INVALID_IDS) -def test_constructor_and_assignment_reject_the_same_values(value): - with pytest.raises(ValidationError): - _route(threshold=value) - - route = _route() - with pytest.raises(ValidationError): - route.distance_threshold = value - assert route.distance_threshold == 0.5 - - -@pytest.mark.parametrize("value", INVALID, ids=INVALID_IDS) -def test_update_route_thresholds_rejects_invalid_values(value): - router = _router(_route()) - with pytest.raises(ValidationError): - router.update_route_thresholds({"greeting": value}) - assert router.route_thresholds == {"greeting": 0.5} - - -def test_update_route_thresholds_applies_nothing_when_any_value_is_invalid(): - router = _router(_route("greeting"), _route("farewell")) - with pytest.raises(ValidationError): - router.update_route_thresholds({"greeting": 0.9, "farewell": math.nan}) - assert router.route_thresholds == {"greeting": 0.5, "farewell": 0.5} - - -def test_update_route_thresholds_accepts_upper_bound(): - # Passes before the fix too: it pins that the new up-front check keeps the - # inclusive bound and still applies valid values. - router = _router(_route("greeting"), _route("farewell")) - router.update_route_thresholds({"greeting": 2, "farewell": 0.25}) - assert router.route_thresholds == {"greeting": 2.0, "farewell": 0.25} diff --git a/tests/unit/test_semantic_cache_threshold.py b/tests/unit/test_semantic_cache_threshold.py index 06553a4fa..d9d9d5497 100644 --- a/tests/unit/test_semantic_cache_threshold.py +++ b/tests/unit/test_semantic_cache_threshold.py @@ -1,35 +1,22 @@ -"""SemanticCache applies one distance-threshold rule everywhere. +"""SemanticCache applies its distance-threshold rule on every path. -The cache-wide threshold (``__init__`` and ``set_threshold``) and a per-call -override (``check`` and ``acheck``) accept the same values and refuse the rest -with the same exception. Hermetic: an invalid override is refused before the -cache touches Redis or its vectorizer. +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. """ -import re from unittest.mock import AsyncMock, Mock -import numpy as np import pytest from redisvl.extensions.cache.llm import SemanticCache -# The 0 and 2 boundaries run end to end in tests/integration/test_llmcache.py. -ACCEPTED = [np.float32(0.5)] - -REFUSED = [ - pytest.param(2 + 1e-9, ValueError, id="just-above-2"), - pytest.param(-1e-9, ValueError, id="just-below-0"), - pytest.param(float("nan"), ValueError, id="nan"), - pytest.param(True, TypeError, id="true"), - pytest.param("0.5", TypeError, id="numeric-string"), -] - @pytest.fixture def cache(): # Bypass __init__, which would connect to Redis and load a vectorizer, and - # stub what a lookup touches so that it returns no candidates. + # stub what a lookup touches. cache = SemanticCache.__new__(SemanticCache) cache.name = "test_threshold" cache.refresh_ttl_on_hit = True @@ -45,38 +32,39 @@ def cache(): return cache -@pytest.mark.parametrize("value", ACCEPTED) -async def test_every_path_accepts_a_numpy_scalar_as_a_float(cache, value): - applied = [] - cache._within_threshold = ( - lambda candidates, threshold: applied.append(threshold) or candidates +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 - cache.check(vector=[0.1], distance_threshold=value) - await cache.acheck(vector=[0.1], distance_threshold=value) - cache.set_threshold(value) - - assert applied == [float(value)] * 2 - assert cache.distance_threshold == float(value) - # A numpy scalar must not reach the client-side filter or the span attribute. - assert all(type(t) is float for t in [*applied, cache.distance_threshold]) - - -def test_the_largest_threshold_keeps_a_rounded_opposite_vector(): - # Measured on Redis 8.10.3: FLOAT32 COSINE, 1536 dims, query against -query. - candidates = [{"vector_distance": "2.00000023842"}] - - assert SemanticCache._within_threshold(candidates, 2.0) == candidates - - -@pytest.mark.parametrize("value, error", REFUSED) -async def test_every_path_refuses_alike(cache, value, error): - with pytest.raises(error) as expected: - cache.set_threshold(value) - match = re.escape(str(expected.value)) - with pytest.raises(error, match=match): - cache.check(vector=[0.1], distance_threshold=value) - with pytest.raises(error, match=match): - await cache.acheck(vector=[0.1], distance_threshold=value) - 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 index 8a2ca8054..350b4bc8d 100644 --- a/tests/unit/test_semantic_history_threshold.py +++ b/tests/unit/test_semantic_history_threshold.py @@ -1,32 +1,18 @@ -"""SemanticMessageHistory applies one distance-threshold rule everywhere. +"""SemanticMessageHistory applies its distance-threshold rule on every path. -The history-wide threshold (``__init__`` and ``set_distance_threshold``) and a -per-call override (``get_relevant``) accept the same values and refuse the rest -with the same exception, the rule ``SemanticCache`` uses. Hermetic: an invalid -threshold is refused before the history touches Redis or its vectorizer. +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. """ -import re from unittest.mock import Mock -import numpy as np import pytest from redisvl.extensions.message_history import SemanticMessageHistory from redisvl.query.filter import Tag -# 2 pins the inclusive upper bound, which no integration test reaches; 0 is -# covered end to end in tests/integration/test_message_history.py. -ACCEPTED = [2, np.float32(0.5)] - -REFUSED = [ - pytest.param(2 + 1e-9, ValueError, id="just-above-2"), - pytest.param(-1e-9, ValueError, id="just-below-0"), - pytest.param(float("nan"), ValueError, id="nan"), - pytest.param(True, TypeError, id="true"), - pytest.param("0.5", TypeError, id="numeric-string"), -] - @pytest.fixture def history(): @@ -40,35 +26,23 @@ def history(): return history -@pytest.mark.parametrize("value", ACCEPTED) -def test_every_path_accepts_a_valid_threshold_as_a_float(history, value): - history.get_relevant("prompt", distance_threshold=value) - history.set_distance_threshold(value) - - (query,), _ = history._index.query.call_args - assert query.distance_threshold == float(value) - assert history.distance_threshold == float(value) - assert type(history.distance_threshold) is float - - -@pytest.mark.parametrize("value, error", REFUSED) -def test_every_path_refuses_alike(history, monkeypatch, value, error): +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")), ) - - with pytest.raises(error) as expected: - history.set_distance_threshold(value) - match = re.escape(str(expected.value)) - - with pytest.raises(error, match=match): - history.get_relevant("prompt", distance_threshold=value) - with pytest.raises(error, match=match): - history.get_relevant("prompt", top_k=0, distance_threshold=value) - with pytest.raises(error, match=match): - SemanticMessageHistory("history", distance_threshold=value) + 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_utils.py b/tests/unit/test_utils.py index bf8dd29ba..4efc7f551 100644 --- a/tests/unit/test_utils.py +++ b/tests/unit/test_utils.py @@ -21,6 +21,7 @@ lazy_import, match_pattern, norm_cosine_distance, + validate_cosine_distance_threshold, ) @@ -45,6 +46,35 @@ 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_norm_denorm_cosine(): input = 0.6 assert input == round(denorm_cosine_distance(norm_cosine_distance(input)), 6) From 7f6d98541c71dc2e2a91408229f63962fb2c7338 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Fri, 20 Nov 2026 10:16:35 +0100 Subject: [PATCH 12/12] fix: treat a COSINE threshold of 2 as matching everything on every path Redis can report an exactly opposite vector a little above 2 (measured on 8.10.3: 2.00000024 for FLOAT32). cosine_distance_bound widens a threshold of 2 past that, and SemanticCache's client-side compare, the message history's range radius, and the router's range radius and min/avg FILTER all use it. A summed router distance keeps its threshold unchanged. --- redisvl/extensions/cache/llm/semantic.py | 5 ++- .../message_history/semantic_history.py | 3 +- redisvl/extensions/router/semantic.py | 17 +++++++--- redisvl/utils/utils.py | 13 ++++++++ tests/unit/test_semantic_history_threshold.py | 9 ++++++ tests/unit/test_semantic_router_queries.py | 32 +++++++++++++++++++ tests/unit/test_utils.py | 7 ++++ 7 files changed, 78 insertions(+), 8 deletions(-) diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index f8d8756b5..844a0a466 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -28,6 +28,7 @@ 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, @@ -677,9 +678,7 @@ def _within_threshold( candidate for candidate in candidates if (distance := candidate.get(VectorQuery.DISTANCE_ID)) is None - # Clamped as norm_cosine_distance is: float32 rounding can report an - # exactly opposite vector a little above 2, past the largest threshold. - or min(float(distance), 2.0) <= distance_threshold + or float(distance) <= cosine_distance_bound(distance_threshold) ] def _process_cache_results( diff --git a/redisvl/extensions/message_history/semantic_history.py b/redisvl/extensions/message_history/semantic_history.py index ac61af076..75784ad8a 100644 --- a/redisvl/extensions/message_history/semantic_history.py +++ b/redisvl/extensions/message_history/semantic_history.py @@ -24,6 +24,7 @@ from redisvl.query.filter import Tag from redisvl.utils.log import get_logger from redisvl.utils.utils import ( + cosine_distance_bound, deprecated_argument, serialize, validate_cosine_distance_threshold, @@ -338,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, diff --git a/redisvl/extensions/router/semantic.py b/redisvl/extensions/router/semantic.py index ff715cb41..441b17613 100644 --- a/redisvl/extensions/router/semantic.py +++ b/redisvl/extensions/router/semantic.py @@ -29,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, @@ -423,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 @@ -460,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) ) @@ -507,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"], ) diff --git a/redisvl/utils/utils.py b/redisvl/utils/utils.py index 52a082c22..7a69ea405 100644 --- a/redisvl/utils/utils.py +++ b/redisvl/utils/utils.py @@ -293,6 +293,19 @@ 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: diff --git a/tests/unit/test_semantic_history_threshold.py b/tests/unit/test_semantic_history_threshold.py index 350b4bc8d..575d6019e 100644 --- a/tests/unit/test_semantic_history_threshold.py +++ b/tests/unit/test_semantic_history_threshold.py @@ -26,6 +26,15 @@ def history(): 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( 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 4efc7f551..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, @@ -75,6 +76,12 @@ def test_validate_cosine_distance_threshold_refuses(threshold, max_distance, err 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)