Skip to main content

Intelligent Cache Adapter

The intelligent cache layer wraps the configured CachePort backend and adds adaptive policies for hot keys, namespace-aware TTL defaults, and negative caching of frequent misses. Enable it when you need higher cache hit ratios without rewriting callers.

Enabling the Adapter​

Set the feature flag and optional tuning knobs via environment variables (values shown are defaults):

export ENABLE_INTELLIGENT_CACHE=true
export INTELLIGENT_CACHE_NEGATIVE_TTL=30        # seconds for negative-cache sentinels
export INTELLIGENT_CACHE_HOT_THRESHOLD=5        # accesses before boosting TTL
export INTELLIGENT_CACHE_HOT_BOOST_SECONDS=60   # TTL extension for hot keys
export INTELLIGENT_CACHE_MAX_TTL=86400          # hard cap for boosted TTL

When enabled, the dependency injection container wraps the base cache adapter with IntelligentCachePortAdapter. Namespace defaults automatically apply (rufid: = CACHE_TTL, function: = max(300, CACHE_TTL)) and the adapter remains API-compatible with CachePort.

Behaviour Highlights​

  • Negative caching: the first miss stores a sentinel entry for INTELLIGENT_CACHE_NEGATIVE_TTL seconds to reduce stampedes.
  • Hot key TTL boosts: keys read more than INTELLIGENT_CACHE_HOT_THRESHOLD times receive a TTL extension capped by INTELLIGENT_CACHE_MAX_TTL.
  • Namespace TTLs: calls that omit ttl_seconds default to per-prefix TTLs or fall back to CACHE_TTL.
  • Graceful degradation: if Redis connectivity fails, the intelligent layer transparently wraps the in-memory fallback.

Verification​

Contract tests live under tests/unit/adapters/cache/test_intelligent_cache_adapter.py. Run them directly or rely on the provider matrix workflow to ensure regression coverage:

pytest tests/unit/adapters/cache/test_intelligent_cache_adapter.py

When the adapter is enabled through the registry, tests/unit/adapters/registry/test_provider_registry.py::test_intelligent_cache_wrapper_enabled verifies wiring behaviour.