Add SemanticCache TTL refresh controls

[omribz156]

Summary

• add refresh_ttl_on_hit to SemanticCache so the default sliding-window TTL behavior stays unchanged but can be disabled at cache construction
• add refresh_ttl per-call overrides for check() and acheck()
• document the opt-out in the LLM cache TTL guide and add sync/async integration coverage

Closes #603

Verification

• uv run black --check redisvl/extensions/cache/llm/semantic.py tests/integration/test_llmcache.py
• uv run python -m compileall redisvl/extensions/cache/llm/semantic.py tests/integration/test_llmcache.py
• python -c "import json, pathlib; json.loads(pathlib.Path('docs/user_guide/03_llmcache.ipynb').read_text(encoding='utf-8')); print('notebook json ok')"
• git diff --check

I also attempted uv run pytest tests/integration/test_llmcache.py -k "ttl_refresh or ttl_refresh_setting", but this local machine does not have Docker on PATH, so testcontainers failed before running the selected tests with FileNotFoundError: [WinError 2] while invoking docker compose.

This was implemented with Codex assistance and manually reviewed before submission.

---

Note

Low Risk
Backward-compatible API defaults preserve current TTL-on-hit behavior; risk is mainly misconfiguration of cache eviction if refresh is disabled in production.

Overview
Adds optional control over whether cache hits extend entry lifetime in SemanticCache, while keeping today’s sliding-window TTL behavior as the default.

refresh_ttl_on_hit (default True) on construction disables TTL extension on every hit when set to False. refresh_ttl on check() / acheck() overrides that default for a single lookup (e.g. refresh_ttl=False for a read-only hit). Matched keys only call expire / aexpire when refresh is enabled.

The LLM cache user guide documents the new scenarios and examples; integration tests assert sync/async paths skip or perform refresh via mocks.

^{Reviewed by Cursor Bugbot for commit 8c773ba. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

Hi, I’m Jit, a friendly security platform designed to help developers build secure applications from day zero with an MVS (Minimal viable security) mindset.

In case there are security findings, they will be communicated to you as a comment inside the PR.

Hope you’ll enjoy using Jit.

Questions? Comments? Want to learn more? Get in touch with us.

[Copilot]

Pull request overview

Adds opt-out controls for SemanticCache’s sliding-window TTL behavior, allowing callers to disable “refresh TTL on hit” at construction time and/or override it per check() / acheck() call, with corresponding documentation and integration coverage.

Changes:

• Add refresh_ttl_on_hit (default True) to SemanticCache plus refresh_ttl: bool | None override on check() / acheck().
• Update integration tests to verify TTL refresh can be skipped/enabled for sync and async cache hits.
• Update the LLM cache user guide notebook to document the new TTL refresh controls and scenarios.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
redisvl/extensions/cache/llm/semantic.py	Adds cache-level and per-call controls for whether TTL is refreshed on cache hits (sync + async).
tests/integration/test_llmcache.py	Adds new integration tests covering skip/override behavior for TTL refresh in check() / acheck().
docs/user_guide/03_llmcache.ipynb	Documents how to disable/override TTL refresh behavior and updates TTL behavior table/examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[omribz156]

Thanks, fixed in 3dfafaa. The async TTL-refresh assertions now use assert_not_awaited() and assert_awaited_once(). Verified with black --check, compileall, and git diff --check.