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
Default behavior is unchanged (refresh_ttl_on_hit=True); risk is limited to callers who disable refresh and may see entries expire sooner than before when they relied on implicit TTL extension on reads.

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

refresh_ttl_on_hit (default True) can be set to False at construction so check() / acheck() no longer call expire on matched keys. refresh_ttl on each lookup overrides that default for a single read (e.g. refresh_ttl=False for a pure read).

The LLM cache user guide documents the new scenarios and examples; integration tests cover sync/async paths and per-call overrides via mocked expire / aexpire.

^{Reviewed by Cursor Bugbot for commit 362ca90. 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.

[vishal-bala]

Looks good aside from one minor comment! Should be good to go once we have that addressed.

[vishal-bala]

Since this class inherits from BaseLLMCache, you'll want to make the corresponding update on there as well. Otherwise type-checkers will complain

[omribz156]

Thanks, fixed in 362ca90. I added the matching refresh_ttl parameter to BaseLLMCache.check() and BaseLLMCache.acheck(), plus the sync docstring note, so SemanticCache stays compatible with the base interface. Verified with python -m compileall on base.py/semantic.py and git diff --check.