Add SemanticCache TTL refresh controls

docs/user_guide/03_llmcache.ipynb

@@ -22,7 +22,7 @@
     "- Store and retrieve cached LLM responses\n",
     "- Understand entry IDs and keys for fetching and deleting specific entries\n",
     "- Customize semantic similarity thresholds\n",
-    "- Configure TTL policies and understand TTL refresh behavior\n",
+    "- Configure TTL policies and control TTL refresh behavior\n",
     "- Implement access controls with tags and filters for multi-user scenarios"
    ]
   },
@@ -749,11 +749,13 @@
     "| Scenario | Behavior |\n",
     "|----------|----------|\n",
     "| `ttl=None` (default) | Entries persist forever. `check()` does not affect TTL. |\n",
-    "| `ttl=3600` at init | Entries get TTL on `store()`. TTL is **refreshed** on every `check()` hit. |\n",
-    "| Set TTL later with `set_ttl(3600)` | **Existing entries keep no TTL**, but `check()` will now **add** TTL to matched entries. |\n",
+    "| `ttl=3600` at init | Entries get TTL on `store()`. TTL is **refreshed** on every `check()` hit by default. |\n",
+    "| `refresh_ttl_on_hit=False` at init | Entries keep their stored TTL, and `check()` does not extend matched entries unless overridden per call. |\n",
+    "| `check(..., refresh_ttl=False)` | Skips TTL refresh for that lookup only. |\n",
+    "| Set TTL later with `set_ttl(3600)` | **Existing entries keep no TTL**, but `check()` will now **add** TTL to matched entries unless TTL refresh is disabled. |\n",
     "| Remove TTL with `set_ttl(None)` | Existing entries keep their TTL, but `check()` no longer refreshes it. |\n",
     "\n",
-    "**Important:** The `check()` method automatically refreshes TTL on all matched entries (sliding window pattern). This keeps frequently accessed entries alive but can unexpectedly add TTL to entries that were originally stored without one."
+    "**Important:** By default, the `check()` method refreshes TTL on all matched entries (sliding window pattern). This keeps frequently accessed entries alive but can unexpectedly add TTL to entries that were originally stored without one. Use `refresh_ttl_on_hit=False` or `check(..., refresh_ttl=False)` when cache reads should not extend entry lifetime."
    ]
   },
   {
@@ -769,7 +771,7 @@
    "source": [
     "### TTL Refresh on Check\n",
     "\n",
-    "When `check()` finds matching entries, it refreshes the TTL on **all** matched results, not just the one you use:"
+    "When `check()` finds matching entries, it refreshes the TTL on **all** matched results, not just the one you use. Pass `refresh_ttl=False` for an individual lookup that should behave as a pure read:"
    ]
   },
   {
@@ -794,6 +796,9 @@
     "# Every time check() finds this entry, TTL resets to 300 seconds\n",
     "result = llmcache.check(\"What is Python?\")  # TTL refreshed\n",
     "\n",
+    "# Skip TTL refresh for one lookup\n",
+    "result = llmcache.check(\"What is Python?\", refresh_ttl=False)\n",
+    "\n",
     "# Reset for next examples\n",
     "llmcache.set_ttl()\n",
     "llmcache.clear()"

redisvl/extensions/cache/llm/semantic.py

@@ -54,6 +54,7 @@ def __init__(
         redis_url: str = "redis://localhost:6379",
         connection_kwargs: dict[str, Any] = {},
         overwrite: bool = False,
+        refresh_ttl_on_hit: bool = True,
         **kwargs,
     ):
         """Semantic Cache for Large Language Models.
@@ -77,6 +78,8 @@ def __init__(
                 for the redis client. Defaults to empty {}.
             overwrite (bool): Whether or not to force overwrite the schema for
                 the semantic cache index. Defaults to false.
+            refresh_ttl_on_hit (bool): Whether cache hits refresh matched
+                entries' TTL by default. Defaults to True.
 
         Raises:
             TypeError: If an invalid vectorizer is provided.
@@ -93,6 +96,8 @@ def __init__(
             connection_kwargs=connection_kwargs,
         )
 
+        self.refresh_ttl_on_hit = refresh_ttl_on_hit
+
         # Handle the deprecated dtype parameter
         dtype = kwargs.pop("dtype", None)
 
@@ -353,6 +358,7 @@ def check(
         return_fields: list[str] | None = None,
         filter_expression: FilterExpression | None = None,
         distance_threshold: float | None = None,
+        refresh_ttl: bool | None = None,
     ) -> list[dict[str, Any]]:
         """Checks the semantic cache for results similar to the specified prompt
         or vector.
@@ -377,6 +383,9 @@ def check(
                 the full cache will be searched.
             distance_threshold (Optional[float]): The threshold for semantic
                 vector distance.
+            refresh_ttl (Optional[bool]): Whether this cache hit should refresh
+                matched entries' TTL. If None, uses the cache-level
+                refresh_ttl_on_hit setting.
 
         Returns:
             List[Dict[str, Any]]: A list of dicts containing the requested
@@ -430,9 +439,10 @@ def check(
             return_fields,  # type: ignore
         )
 
-        # Refresh TTL on all found keys
-        for key in redis_keys:
-            self.expire(key)
+        refresh_ttl = self.refresh_ttl_on_hit if refresh_ttl is None else refresh_ttl
+        if refresh_ttl:
+            for key in redis_keys:
+                self.expire(key)
 
         return cache_hits
 
@@ -444,6 +454,7 @@ async def acheck(
         return_fields: list[str] | None = None,
         filter_expression: FilterExpression | None = None,
         distance_threshold: float | None = None,
+        refresh_ttl: bool | None = None,
     ) -> list[dict[str, Any]]:
         """Async check the semantic cache for results similar to the specified prompt
         or vector.
@@ -468,6 +479,9 @@ async def acheck(
                 the full cache will be searched.
             distance_threshold (Optional[float]): The threshold for semantic
                 vector distance.
+            refresh_ttl (Optional[bool]): Whether this cache hit should refresh
+                matched entries' TTL. If None, uses the cache-level
+                refresh_ttl_on_hit setting.
 
         Returns:
             List[Dict[str, Any]]: A list of dicts containing the requested
@@ -523,8 +537,9 @@ async def acheck(
             return_fields,  # type: ignore
         )
 
-        # Refresh TTL on all found keys async
-        await asyncio.gather(*[self.aexpire(key) for key in redis_keys])
+        refresh_ttl = self.refresh_ttl_on_hit if refresh_ttl is None else refresh_ttl
+        if refresh_ttl:
+            await asyncio.gather(*[self.aexpire(key) for key in redis_keys])
 
         return cache_hits
 

tests/integration/test_llmcache.py

@@ -3,6 +3,7 @@
 import warnings
 from collections import namedtuple
 from time import sleep, time
+from unittest.mock import AsyncMock, patch
 
 import pytest
 from pydantic import ValidationError
@@ -393,6 +394,63 @@ def test_ttl_refresh(cache_with_ttl, vectorizer):
     assert len(check_result) == 1
 
 
+def test_check_can_skip_ttl_refresh(cache_with_ttl, vectorizer):
+    prompt = "This is a test prompt."
+    response = "This is a test response."
+    vector = vectorizer.embed(prompt)
+
+    cache_with_ttl.store(prompt, response, vector=vector)
+
+    with patch.object(cache_with_ttl, "expire") as expire:
+        check_result = cache_with_ttl.check(vector=vector, refresh_ttl=False)
+
+    assert len(check_result) == 1
+    expire.assert_not_called()
+
+
+def test_check_respects_cache_ttl_refresh_setting(
+    client, vectorizer, redis_url, worker_id
+):
+    skip_if_no_redis_search(client)
+    cache_instance = SemanticCache(
+        name=f"llmcache_no_refresh_{worker_id}",
+        vectorizer=vectorizer,
+        distance_threshold=0.2,
+        ttl=2,
+        redis_url=redis_url,
+        refresh_ttl_on_hit=False,
+    )
+    prompt = "This is a test prompt."
+    response = "This is a test response."
+    vector = vectorizer.embed(prompt)
+
+    try:
+        cache_instance.store(prompt, response, vector=vector)
+
+        with patch.object(cache_instance, "expire") as expire:
+            check_result = cache_instance.check(vector=vector)
+    finally:
+        cache_instance._index.delete(True)
+
+    assert len(check_result) == 1
+    expire.assert_not_called()
+
+
+def test_check_refresh_ttl_override(cache_with_ttl, vectorizer):
+    prompt = "This is a test prompt."
+    response = "This is a test response."
+    vector = vectorizer.embed(prompt)
+    cache_with_ttl.refresh_ttl_on_hit = False
+
+    cache_with_ttl.store(prompt, response, vector=vector)
+
+    with patch.object(cache_with_ttl, "expire") as expire:
+        check_result = cache_with_ttl.check(vector=vector, refresh_ttl=True)
+
+    assert len(check_result) == 1
+    expire.assert_called_once()
+
+
 @pytest.mark.asyncio
 async def test_async_ttl_refresh(cache_with_ttl, vectorizer):
     prompt = "This is a test prompt."
@@ -409,6 +467,39 @@ async def test_async_ttl_refresh(cache_with_ttl, vectorizer):
     assert len(check_result) == 1
 
 
+@pytest.mark.asyncio
+async def test_async_check_can_skip_ttl_refresh(cache_with_ttl, vectorizer):
+    prompt = "This is a test prompt."
+    response = "This is a test response."
+    vector = vectorizer.embed(prompt)
+
+    async with cache_with_ttl:
+        await cache_with_ttl.astore(prompt, response, vector=vector)
+
+        with patch.object(cache_with_ttl, "aexpire", new_callable=AsyncMock) as aexpire:
+            check_result = await cache_with_ttl.acheck(vector=vector, refresh_ttl=False)
+
+    assert len(check_result) == 1
+    aexpire.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_async_check_refresh_ttl_override(cache_with_ttl, vectorizer):
+    prompt = "This is a test prompt."
+    response = "This is a test response."
+    vector = vectorizer.embed(prompt)
+    cache_with_ttl.refresh_ttl_on_hit = False
+
+    async with cache_with_ttl:
+        await cache_with_ttl.astore(prompt, response, vector=vector)
+
+        with patch.object(cache_with_ttl, "aexpire", new_callable=AsyncMock) as aexpire:
+            check_result = await cache_with_ttl.acheck(vector=vector, refresh_ttl=True)
+
+    assert len(check_result) == 1
+    aexpire.assert_called_once()
+
+
 # Test manual expiration of single document
 def test_drop_document(cache, vectorizer):
     prompt = "This is a test prompt."