fix: honor distance_threshold=0 in semantic cache and message history (#650)

Fixes #649

### Problem

The per-call `distance_threshold` override was resolved with a
truthiness check:

```python
distance_threshold = distance_threshold or self._distance_threshold
```

`0.0` is falsy, so a caller passing `distance_threshold=0`
(exact-match-only) had it silently replaced by the instance default and
received fuzzy cache hits instead. `0` is a valid threshold everywhere
else: `set_threshold()` accepts `0 <= x <= 2` and
`VectorRangeQuery.set_distance_threshold()` rejects only negatives.

The failure mode is a false cache hit so the caller gets a cached
response to a prompt they never asked, believing fuzzy matching was off.

### Fix

Fall back to the configured default only when the override is `None`.
Applied in `SemanticCache.check()`, `SemanticCache.acheck()`, and
`SemanticMessageHistory.get_relevant()`.

### Tests

Added `test_check_with_zero_distance_threshold` and
`test_acheck_with_zero_distance_threshold` to
`tests/integration/test_llmcache.py`. Each stores a prompt, asserts a
near-paraphrase does **not** hit at `distance_threshold=0`, and asserts
it **does** hit at the cache default (so the test fails for the right
reason rather than by accident).

Verified against the real suite (Python 3.12, Redis 8.4 via the repo's
compose fixture):

- before the fix: both new tests fail with `AssertionError: assert
[{'entry_id': ...}] == []`
- after the fix: both pass
- full `tests/integration/test_llmcache.py`: **62 passed**

### Scope note

I left the `ttl = ttl or self._ttl` occurrences alone. A TTL of 0 isn't
meaningful in Redis and the suite already rejects it (`test_bad_ttl`),
so the falsy-fallback is harmless there. Happy to widen the scope if
maintainers prefer consistency.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Small, targeted behavior fix in lookup paths with clear regression
tests; no API or schema changes beyond honoring an already-valid
threshold value.
> 
> **Overview**
> Fixes a bug where per-call **`distance_threshold`** overrides used
`distance_threshold or self._distance_threshold`, so **`0`**
(exact-match-only in Redis COSINE distance) was treated as unset and
replaced by the instance default—causing **false cache hits** and fuzzy
context when callers intended strict matching.
> 
> **`SemanticCache.check()`**, **`SemanticCache.acheck()`**, and
**`SemanticMessageHistory.get_relevant()`** now fall back to the
configured default only when the override is **`None`**.
> 
> Integration tests cover sync/async cache checks and semantic history
retrieval: near-paraphrases must not match at
**`distance_threshold=0`**, while the same queries still match at the
default threshold.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5620780. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: nickleodoen

redisvl/extensions/cache/llm/semantic.py

@@ -398,8 +398,10 @@ def check(
         if return_fields and not isinstance(return_fields, list):
             raise TypeError("Return fields must be a list of values.")
 
-        # Use overrides or defaults
-        distance_threshold = distance_threshold or self._distance_threshold
+        # Use overrides or defaults. 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
 
         # Vectorize prompt if not provided
         if vector is None and prompt is not None:
@@ -491,8 +493,10 @@ async def acheck(
         if return_fields and not isinstance(return_fields, list):
             raise TypeError("Return fields must be a list of values.")
 
-        # Use overrides or defaults
-        distance_threshold = distance_threshold or self._distance_threshold
+        # Use overrides or defaults. 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
 
         # Vectorize prompt if not provided
         if vector is None and prompt is not None:

redisvl/extensions/message_history/semantic_history.py

@@ -231,8 +231,10 @@ def get_relevant(
         # Validate and normalize role parameter
         roles_to_filter = self._validate_roles(role)
 
-        # override distance threshold
-        distance_threshold = distance_threshold or self._distance_threshold
+        # 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,

tests/integration/test_llmcache.py

@@ -577,6 +577,33 @@ def test_check_no_match(cache, vectorizer):
     assert len(check_result) == 0
 
 
+def test_check_with_zero_distance_threshold(cache):
+    """A per-call distance_threshold of 0 must be honored, not treated as unset.
+
+    Regression test: `distance_threshold or self._distance_threshold` treated the
+    valid threshold 0 as falsy and silently fell back to the cache default, so
+    callers requesting exact-match-only lookups received fuzzy matches.
+    """
+    cache.store("what is the capital of france?", "paris")
+
+    # Semantically similar but not identical -> must NOT hit at threshold 0
+    assert cache.check("what's the capital of france?", distance_threshold=0) == []
+
+    # Sanity check: the same query does hit at the cache's default threshold
+    assert cache.check("what's the capital of france?") != []
+
+
+@pytest.mark.asyncio
+async def test_acheck_with_zero_distance_threshold(cache):
+    """Async variant: a per-call distance_threshold of 0 must be honored."""
+    await cache.astore("what is the capital of france?", "paris")
+
+    assert (
+        await cache.acheck("what's the capital of france?", distance_threshold=0)
+    ) == []
+    assert (await cache.acheck("what's the capital of france?")) != []
+
+
 def test_check_invalid_input(cache):
     with pytest.raises(ValueError):
         cache.check()

tests/integration/test_message_history.py

@@ -606,6 +606,30 @@ def test_semantic_add_and_get_relevant(semantic_history):
         bad_context = semantic_history.get_relevant("test prompt", top_k="3")
 
 
+@requires_hf
+def test_semantic_get_relevant_with_zero_distance_threshold(semantic_history):
+    """A per-call distance_threshold of 0 must be honored, not treated as unset.
+
+    Regression test: `distance_threshold or self._distance_threshold` treated the
+    valid threshold 0 as falsy and silently fell back to the configured default,
+    so callers requesting exact-match-only context received fuzzy matches.
+    """
+    semantic_history.store(
+        prompt="list of common fruits",
+        response="apples, oranges, bananas, strawberries",
+    )
+    semantic_history.set_distance_threshold(0.5)
+
+    # Semantically similar but not identical -> must NOT match at threshold 0
+    assert (
+        semantic_history.get_relevant("list of typical fruits", distance_threshold=0)
+        == []
+    )
+
+    # Sanity check: the same query does match at the configured default
+    assert semantic_history.get_relevant("list of typical fruits") != []
+
+
 @requires_hf
 def test_semantic_get_raw(semantic_history):
     semantic_history.store("first prompt", "first response")