ZerdaZerda

cache.config_cache

On this page

Every dataclass and enum in this module is documented in narrative form on the Configuration page (with defaults, environment variables, and cross-references to the code that reads each field). This page is the terse structural reference; see Configuration for guidance and caveats.

Enums

StorageBackend

str, Enum — REDIS = "redis", SQLITE = "sqlite", MEMORY = "memory". Selects the backend built by build_storage().

EvictionPolicy

str, Enum — REWARD_LRU = "reward_lru", LRU = "lru", LFU = "lfu", TTL = "ttl". Field type of EvictionConfig.policy. In the analyzed source, CacheManager's eviction cycle always applies the reward/usage/recency composite scoring from CachePolicyLearner regardless of which EvictionPolicy is configured — the enum's other members are not currently branched on anywhere.

EmbeddingProvider

str, Enum — OPENAI = "openai", HUGGINGFACE = "huggingface", OLLAMA = "ollama", MOCK = "mock". Selects the provider built by build_embedding_provider().

RoutingDecision

str, Enum — EXACT_HIT = "exact_hit", SEMANTIC_HIT = "semantic_hit", TENANT_HIT = "tenant_hit", LLM_FALLBACK = "llm_fallback". Returned inside CacheLookupResult.decision and RoutingResult.decision.

[!NOTE] TENANT_HIT is declared but never assigned RoutingDecision.TENANT_HIT exists as an enum member, and CacheMetricsCollector tracks a _tenant_hits counter and exposes a tenant_hit_rate in its snapshot — but nowhere in CacheManager is RoutingDecision.TENANT_HIT actually returned, nor is _tenant_hits ever incremented, in the analyzed source. tenant_hit_rate will always read 0.0. See Known Issues.

Sub-configuration dataclasses

DataclassKey fieldsConsumed by
RedisConfighost, port, db, password, ssl, socket_timeout, socket_connect_timeout, max_connections, key_prefixRedisStorage
SQLiteConfigdb_path, wal_mode, cache_size_kbSQLiteStorage
EmbeddingConfigprovider, model_name, dimension, batch_size, cache_embeddings, embedding_cache_size, openai_api_key, hf_model_name, ollama_url, request_timeoutCachedEmbedder, embedding providers
SemanticConfigsimilarity_threshold, adaptive_threshold, threshold_min/max/step, index_type, max_index_sizeCacheManager, EmbeddingIndex
CostConfigper-1K-token costs, cost_weight/quality_weight/latency_weight, target_latency_msCostModel, DecisionEngine
RLConfigprior_alpha/beta, exploration_bonus, feedback reward/penalty, similarity_bonus_scale, usage_decay, min_reward_to_keepCachePolicyLearner
TenantConfigdefault_memory_quota_mb, default_request_quota_rpm, default_max_entries, enable_shared_cache, isolation_strictTenantManager
SecurityConfigmax_query_length, max_response_length, enable_injection_check, injection_patterns_path, enable_pii_scrub, hmac_secretSecurityGuard
EvictionConfigpolicy, check_interval_s, max_age_s, reward_weight/usage_weight/recency_weightCacheManager eviction timer
PerformanceConfigenable_async, coalescing_window_ms, embedding_batch_size, io_threads, max_concurrent_llm_callsDeclared for forward compatibility; largely unread in the analyzed source (see Configuration)

CacheConfig

Python · 30 lines
@dataclass
class CacheConfig:
    storage_backend: StorageBackend = StorageBackend.SQLITE
    redis: RedisConfig
    sqlite: SQLiteConfig
    embedding: EmbeddingConfig
    semantic: SemanticConfig
    cost: CostConfig
    rl: RLConfig
    tenant: TenantConfig
    security: SecurityConfig
    eviction: EvictionConfig
    performance: PerformanceConfig
    l1_max_items: int = 100
    l2_max_items: int = 1000
    l3_max_items: int = 10000
    l1_max_size_mb: float = 10.0
    l2_max_size_mb: float = 100.0
    l3_max_size_mb: float = 1000.0
    default_ttl: Optional[float] = None
    default_ttl_s: Optional[float] = 3600.0
    cache_dir: str = "./cache_storage"
    log_level: str = "INFO"
    enable_stats: bool = True
    auto_cleanup_interval: int = 3600
    l1_speed_ns: int = 100
    l2_speed_ns: int = 1000
    l3_speed_ns: int = 10000
    l2_to_l1_hits: int = 10
    size_bytes: int = 1024

(Field list reflects the class's effective defaults after Python resolves the source's duplicate assignments — see the warning in Configuration.)

Methods

__post_init__(self) -> None

Calls self._validate().

_validate(self) -> None

Raises ValueError for any of:

  • l1_max_items < 1
  • l2_max_items < l1_max_items
  • l3_max_items < l2_max_items
  • any of l1_max_size_mb, l2_max_size_mb, l3_max_size_mb <= 0
  • default_ttl is not None and default_ttl <= 0

from_env(cls) -> CacheConfig (classmethod)

Builds a CacheConfig overriding l1_max_items, l2_max_items, l3_max_items, cache_dir, and default_ttl from CACHE_L1_MAX_ITEMS, CACHE_L2_MAX_ITEMS, CACHE_L3_MAX_ITEMS, CACHE_DIR, CACHE_DEFAULT_TTL respectively. Every other field (including storage_backend, redis, embedding, etc.) takes its normal dataclass default.

Python
config = CacheConfig.from_env()

to_dict(self) -> dict

Returns a plain dict of exactly eight fields: l1_max_items, l2_max_items, l3_max_items, l1_max_size_mb, l2_max_size_mb, l3_max_size_mb, default_ttl, cache_dir. This is a partial serialization — it does not include storage_backend, redis, embedding, security, or any other sub-configuration.

Examples

Python · 16 lines
from zerda.cache import CacheConfig, StorageBackend

# Defaults
cfg = CacheConfig()

# From environment
cfg = CacheConfig.from_env()

# Explicit overrides
cfg = CacheConfig(storage_backend=StorageBackend.MEMORY, l1_max_items=200)

# Invalid configuration raises immediately
try:
    CacheConfig(l1_max_items=0)
except ValueError as e:
    print(e)   # "l1_max_items must be at least 1"
  • Configuration — full field-by-field guide with defaults and caveats
  • build_storage() — reads storage_backend, sqlite, redis
  • CacheManager — the primary consumer of CacheConfig
  • MultiLevelCache — consumes the l1/l2/l3_max_items, l1/l2/l3_max_size_mb, cache_dir, default_ttl, l2_to_l1_hits, and auto_cleanup_interval fields

Related pages