Core Module

The core module is the foundation of OmniCache-AI — the central orchestrator, key generation, policies, invalidation, metrics, serialization, compression, stampede protection, cache warming, and multi-tenant namespacing.

---

Components

Component	Module	Description
CacheManager	omnicache_ai.core.cache_manager	Central orchestrator — get, set, invalidate, for_tenant()
CacheKeyBuilder	omnicache_ai.core.key_builder	namespace:type:sha256[:16] canonical keys
CacheMetrics	omnicache_ai.core.metrics	Hit/miss/eviction counters + provider cache savings
Serializer	omnicache_ai.core.serializer	Pluggable encode/decode — PickleSerializer, JsonSerializer
Compressor	omnicache_ai.core.compressor	Optional compression — GzipCompressor, NoopCompressor
StampedeShield	omnicache_ai.core.stampede	Per-key lock — prevents concurrent duplicate LLM calls
RequestConfig	omnicache_ai.core.request_config	Per-request TTL / threshold / skip_cache overrides
CacheWarmer	omnicache_ai.core.warmer	Bulk warm from query lists or CSV
TTLPolicy	omnicache_ai.core.policies	Global + per-layer TTL configuration
EvictionPolicy	omnicache_ai.core.policies	LRU / TTL-only strategy
InvalidationEngine	omnicache_ai.core.invalidation	Tag-based bulk eviction
Observability	omnicache_ai.core.exporters	Prometheus + OpenTelemetry exporters
OmnicacheSettings	omnicache_ai.config.settings	Unified config dataclass + from_env()

---

Architecture

---

Quick Example

from omnicache_ai import CacheManager, OmnicacheSettings, CacheMetrics

manager = CacheManager.from_settings(OmnicacheSettings.from_env())

key = manager.key_builder.build("response", "my prompt")
manager.set(key, b"cached-result", tags=["model:gpt-4o"])
value = manager.get(key)

# Per-tenant scope
tenant = manager.for_tenant("customer-42")

# Metrics
snap = manager.metrics.snapshot()
print(f"Hit rate: {snap['hit_rate']:.0%}")

# Tag invalidation
manager.invalidate("model:gpt-4o")

---

Next Steps

• CacheManager — central API
• CacheMetrics — hit rate and cost tracking
• StampedeShield — concurrency safety
• CacheWarmer — pre-populate on startup
• Observability — Prometheus / OTEL export