Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
bcb2351
perf: run SemanticCache.check() as KNN with a client-side threshold
vishal-bala Oct 13, 2026
27ea055
Merge remote-tracking branch 'origin/main' into feat/FDE-83-otel/01-F…
vishal-bala Oct 15, 2026
abd9a06
Merge remote-tracking branch 'origin/main' into feat/FDE-83-otel/01-F…
vishal-bala Oct 20, 2026
0a58d96
Merge remote-tracking branch 'origin/main' into feat/FDE-83-otel/01-F…
vishal-bala Oct 30, 2026
a3fa48f
fix(cache): apply one distance-threshold rule to SemanticCache
vishal-bala Oct 30, 2026
96b60d0
fix(cache): document the threshold rule and test the accept path
vishal-bala Oct 30, 2026
c3e27d3
fix(message-history): validate SemanticMessageHistory distance thresh…
vishal-bala Oct 30, 2026
968e362
fix(message-history): check the threshold before any early exit
vishal-bala Oct 30, 2026
4783dd1
fix(router): validate route distance thresholds on assignment
vishal-bala Oct 30, 2026
fa15f25
test(router): fold None into the shared invalid-threshold cases
vishal-bala Oct 30, 2026
c96914a
Merge remote-tracking branch 'origin/main' into fix/semantic-cache-un…
vishal-bala Nov 9, 2026
b8808d0
test(cache): give the hermetic threshold fixture what the telemetry w…
vishal-bala Nov 9, 2026
a8e6f65
Merge remote-tracking branch 'origin/main' into fix/semantic-cache-un…
vishal-bala Nov 19, 2026
d9896fd
test(cache): keep only threshold cases that fail without the fix
vishal-bala Nov 19, 2026
7afd8af
Merge branch 'fix/message-history-distance-threshold' into fix/semant…
vishal-bala Nov 19, 2026
2fed630
Merge branch 'fix/validate-route-threshold-assignment' into fix/seman…
vishal-bala Nov 19, 2026
e434aff
fix: refuse bool and NaN distance thresholds in every sibling site
vishal-bala Nov 19, 2026
a80b6b4
fix: validate thresholds before loading models, and on Vector assignment
vishal-bala Nov 19, 2026
7f6d985
fix: treat a COSINE threshold of 2 as matching everything on every path
vishal-bala Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions redisvl/extensions/cache/llm/langcache.py
Original file line number Diff line number Diff line change
Expand Up @@ -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__)

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -300,6 +308,9 @@ def check(

Raises:
ValueError: If prompt is not provided.
TypeError: If `distance_threshold` is not a real number, or is a bool.
ValueError: If `distance_threshold` is NaN or outside its scale's
range: [0, 1] for "normalized", [0, 2] for "redis".
"""
if not prompt:
raise ValueError("prompt is required for LangCache search")
Expand Down Expand Up @@ -382,6 +393,9 @@ async def acheck(

Raises:
ValueError: If prompt is not provided.
TypeError: If `distance_threshold` is not a real number, or is a bool.
ValueError: If `distance_threshold` is NaN or outside its scale's
range: [0, 1] for "normalized", [0, 2] for "redis".
"""
if not prompt:
raise ValueError("prompt is required for LangCache search")
Expand Down
49 changes: 24 additions & 25 deletions redisvl/extensions/cache/llm/semantic.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,11 @@
from redisvl.redis.utils import hashify
from redisvl.utils.log import get_logger
from redisvl.utils.utils import (
cosine_distance_bound,
current_timestamp,
deprecated_argument,
serialize,
validate_cosine_distance_threshold,
validate_vector_dims,
)
from redisvl.utils.vectorize.base import BaseVectorizer
Expand Down Expand Up @@ -111,7 +113,9 @@ def __init__(
Raises:
TypeError: If an invalid vectorizer is provided.
TypeError: If the TTL value is not an int.
ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance).
TypeError: If the threshold is not a real number, or is a bool.
ValueError: If the threshold is not between 0 and 2 (Redis COSINE
distance), or is NaN.
ValueError: If existing schema does not match new schema and overwrite is False.
ValueError: If both create_index is False and overwrite is True.

Expand All @@ -133,6 +137,8 @@ def __init__(
connection_kwargs = connection_kwargs or {}
if not create_index and overwrite:
raise ValueError(CREATE_INDEX_OVERWRITE_CONFLICT)
# Refuse a bad threshold before loading the default vectorizer.
validate_cosine_distance_threshold(distance_threshold)

# Call parent class with all shared parameters
super().__init__(
Expand Down Expand Up @@ -305,13 +311,13 @@ def set_threshold(self, distance_threshold: float) -> None:
the cache.

Raises:
ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance).
TypeError: If the threshold is not a real number, or is a bool.
ValueError: If the threshold is not between 0 and 2 (Redis COSINE
distance), or is NaN.
"""
if not 0 <= float(distance_threshold) <= 2:
raise ValueError(
f"Distance must be between 0 and 2, got {distance_threshold}"
)
self._distance_threshold = float(distance_threshold)
self._distance_threshold = validate_cosine_distance_threshold(
distance_threshold
)

def delete(self) -> None:
"""Delete the cache and its index entirely.
Expand Down Expand Up @@ -470,7 +476,8 @@ def check(
that can be used to filter cache results. Defaults to None and
the full cache will be searched.
distance_threshold (Optional[float]): The threshold for semantic
vector distance.
vector distance, in Redis COSINE units [0-2]. Defaults to None,
which uses the cache's threshold.
refresh_ttl (Optional[bool]): Whether this cache hit should refresh
matched entries' TTL. If None, uses the cache-level
refresh_ttl_on_hit setting.
Expand All @@ -483,6 +490,8 @@ def check(
ValueError: If neither a `prompt` nor a `vector` is specified.
ValueError: if 'vector' has incorrect dimensions.
TypeError: If `return_fields` is not a list when provided.
TypeError: If `distance_threshold` is not a real number, or is a bool.
ValueError: If `distance_threshold` is not between 0 and 2, or is NaN.

.. code-block:: python

Expand All @@ -500,7 +509,7 @@ def check(
if distance_threshold is None:
distance_threshold = self._distance_threshold
else:
self._validate_distance_threshold(distance_threshold)
distance_threshold = validate_cosine_distance_threshold(distance_threshold)

# Vectorize prompt if not provided
if vector is None and prompt is not None:
Expand Down Expand Up @@ -564,7 +573,8 @@ async def acheck(
that can be used to filter cache results. Defaults to None and
the full cache will be searched.
distance_threshold (Optional[float]): The threshold for semantic
vector distance.
vector distance, in Redis COSINE units [0-2]. Defaults to None,
which uses the cache's threshold.
refresh_ttl (Optional[bool]): Whether this cache hit should refresh
matched entries' TTL. If None, uses the cache-level
refresh_ttl_on_hit setting.
Expand All @@ -577,6 +587,8 @@ async def acheck(
ValueError: If neither a `prompt` nor a `vector` is specified.
ValueError: if 'vector' has incorrect dimensions.
TypeError: If `return_fields` is not a list when provided.
TypeError: If `distance_threshold` is not a real number, or is a bool.
ValueError: If `distance_threshold` is not between 0 and 2, or is NaN.

.. code-block:: python

Expand All @@ -596,7 +608,7 @@ async def acheck(
if distance_threshold is None:
distance_threshold = self._distance_threshold
else:
self._validate_distance_threshold(distance_threshold)
distance_threshold = validate_cosine_distance_threshold(distance_threshold)

# Vectorize prompt if not provided
if vector is None and prompt is not None:
Expand Down Expand Up @@ -666,22 +678,9 @@ def _within_threshold(
candidate
for candidate in candidates
if (distance := candidate.get(VectorQuery.DISTANCE_ID)) is None
or float(distance) <= distance_threshold
or float(distance) <= cosine_distance_bound(distance_threshold)
]

@staticmethod
def _validate_distance_threshold(distance_threshold: float) -> None:
"""Validate a per-call ``distance_threshold`` override.

Raises:
TypeError: If the threshold is not a float or int.
ValueError: If the threshold is negative.
"""
if not isinstance(distance_threshold, (float, int)):
raise TypeError("distance_threshold must be of type float or int")
if distance_threshold < 0:
raise ValueError("distance_threshold must be non-negative")

def _process_cache_results(
self,
cache_search_results: list[dict[str, Any]],
Expand Down
56 changes: 43 additions & 13 deletions redisvl/extensions/message_history/semantic_history.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,13 @@
from redisvl.query import CountQuery, FilterQuery, RangeQuery
from redisvl.query.filter import Tag
from redisvl.utils.log import get_logger
from redisvl.utils.utils import deprecated_argument, serialize, validate_vector_dims
from redisvl.utils.utils import (
cosine_distance_bound,
deprecated_argument,
serialize,
validate_cosine_distance_threshold,
validate_vector_dims,
)
from redisvl.utils.vectorize import BaseVectorizer, HFTextVectorizer

logger = get_logger(__name__)
Expand Down Expand Up @@ -61,7 +67,8 @@ def __init__(
Defaults to None and will be replaced with the index name.
vectorizer (Optional[BaseVectorizer]): The vectorizer used to create embeddings.
distance_threshold (float): The maximum semantic distance to be
included in the context. Defaults to 0.3.
included in the context, in Redis COSINE units [0-2]. Defaults
to 0.3.
redis_client (Optional[Redis]): A Redis client instance. Defaults to
None.
redis_url (str, optional): The redis url. Defaults to redis://localhost:6379.
Expand All @@ -79,6 +86,10 @@ def __init__(
Defaults to True.

Raises:
TypeError: If the distance threshold is not a real number, or is a
bool.
ValueError: If the distance threshold is not between 0 and 2
(Redis COSINE distance), or is NaN.
ValueError: If both create_index is False and overwrite is True.

The proposed schema will support a single vector embedding constructed
Expand All @@ -87,6 +98,8 @@ def __init__(
connection_kwargs = connection_kwargs or {}
if not create_index and overwrite:
raise ValueError(CREATE_INDEX_OVERWRITE_CONFLICT)
# Refuse a bad threshold before loading the default vectorizer.
validate_cosine_distance_threshold(distance_threshold)

super().__init__(name, session_tag)

Expand Down Expand Up @@ -258,7 +271,8 @@ def get_relevant(
session_tag (Optional[str]): Tag of the entries linked to a specific
conversation session. Defaults to instance ULID.
distance_threshold (Optional[float]): The threshold for semantic
vector distance.
vector distance, in Redis COSINE units [0-2]. Defaults to None,
which uses the history's threshold.
fall_back (bool): Whether to drop back to recent conversation history
if no relevant context is found.
raw (bool): Whether to return the full Redis hash entry or just the
Expand All @@ -271,22 +285,27 @@ def get_relevant(
Union[List[str], List[Dict[str,str]]: Either a list of strings, or a
list of prompts and responses in JSON containing the most relevant.

Raises ValueError: if top_k is not an integer greater or equal to 0,
or if role contains invalid values.
Raises:
ValueError: If top_k is not an integer greater or equal to 0, or if
role contains invalid values.
TypeError: If `distance_threshold` is not a real number, or is a bool.
ValueError: If `distance_threshold` is not between 0 and 2, or is NaN.
"""
if type(top_k) != int or top_k < 0:
raise ValueError("top_k must be an integer greater than or equal to -1")
# override distance threshold. Note: 0 is a valid distance threshold
# (exact match only), so only fall back on None.
if distance_threshold is None:
distance_threshold = self._distance_threshold
else:
distance_threshold = validate_cosine_distance_threshold(distance_threshold)

if top_k == 0:
return []

# Validate and normalize role parameter
roles_to_filter = self._validate_roles(role)

# override distance threshold. Note: 0 is a valid distance threshold
# (exact match only), so only fall back on None.
if distance_threshold is None:
distance_threshold = self._distance_threshold

return_fields = [
SESSION_FIELD_NAME,
ROLE_FIELD_NAME,
Expand Down Expand Up @@ -320,7 +339,7 @@ def get_relevant(
vector=self._vectorizer.embed(prompt),
vector_field_name=MESSAGE_VECTOR_FIELD_NAME,
return_fields=return_fields,
distance_threshold=distance_threshold,
distance_threshold=cosine_distance_bound(distance_threshold),
num_results=top_k,
return_score=True,
filter_expression=filter_expression,
Expand Down Expand Up @@ -423,8 +442,19 @@ def get_recent(
def distance_threshold(self):
return self._distance_threshold

def set_distance_threshold(self, threshold):
self._distance_threshold = threshold
def set_distance_threshold(self, threshold: float) -> None:
"""Set the history's semantic distance threshold.

Args:
threshold (float): The maximum semantic distance to be included in
the context, in Redis COSINE units [0-2].

Raises:
TypeError: If the threshold is not a real number, or is a bool.
ValueError: If the threshold is not between 0 and 2 (Redis COSINE
distance), or is NaN.
"""
self._distance_threshold = validate_cosine_distance_threshold(threshold)

def store(self, prompt: str, response: str, session_tag: str | None = None) -> None:
"""Insert a prompt:response pair into the message history. A timestamp
Expand Down
7 changes: 6 additions & 1 deletion redisvl/extensions/router/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
Loading
Loading