Skip to main content

OmnicacheSettings

OmnicacheSettings is a dataclass that centralizes every configuration knob in OmniCache-AI. It can be constructed programmatically or loaded from OMNICACHE_* environment variables.

Overview​

Managing cache configuration across backends, TTLs, namespaces, and vector stores can quickly become scattered. OmnicacheSettings provides a single source of truth:

  • All fields have sensible defaults, so you can start with OmnicacheSettings() and override only what you need.
  • The from_env() classmethod reads OMNICACHE_* environment variables, making it easy to configure caching per deployment without code changes.
  • Pass the settings object to CacheManager.from_settings() to get a fully-wired cache manager in one call.

Usage​

Programmatic Configuration​

from omnicache_ai.config.settings import OmnicacheSettings

# All defaults -- in-memory backend, 1h TTL, no vector backend
settings = OmnicacheSettings()

# Customized for production
settings = OmnicacheSettings(
    backend="redis",
    redis_url="redis://cache.internal:6379/0",
    namespace="prod",
    default_ttl=7200,
    ttl_response=300,
    vector_backend="faiss",
    embedding_dim=1536,
    semantic_threshold=0.93,
)

From Environment Variables​

from omnicache_ai.config.settings import OmnicacheSettings

settings = OmnicacheSettings.from_env()

Set the environment variables before running your application:

export OMNICACHE_BACKEND=redis
export OMNICACHE_REDIS_URL=redis://cache.internal:6379/0
export OMNICACHE_NAMESPACE=prod
export OMNICACHE_DEFAULT_TTL=7200
export OMNICACHE_TTL_RESPONSE=300
export OMNICACHE_VECTOR_BACKEND=faiss
export OMNICACHE_EMBEDDING_DIM=1536
export OMNICACHE_SEMANTIC_THRESHOLD=0.93
ENV OMNICACHE_BACKEND=redis
ENV OMNICACHE_REDIS_URL=redis://cache:6379/0
ENV OMNICACHE_NAMESPACE=prod
ENV OMNICACHE_DEFAULT_TTL=7200
ENV OMNICACHE_TTL_RESPONSE=300
OMNICACHE_BACKEND=redis
OMNICACHE_REDIS_URL=redis://cache.internal:6379/0
OMNICACHE_NAMESPACE=prod
OMNICACHE_DEFAULT_TTL=7200
OMNICACHE_TTL_RESPONSE=300
OMNICACHE_VECTOR_BACKEND=faiss
OMNICACHE_EMBEDDING_DIM=1536
tip

Use a .env file with a library like python-dotenv to keep environment variables organized during development. Call dotenv.load_dotenv() before OmnicacheSettings.from_env().

Wiring to CacheManager​

from omnicache_ai import CacheManager, OmnicacheSettings

# One-line production setup
manager = CacheManager.from_settings(OmnicacheSettings.from_env())

# Or with explicit settings
manager = CacheManager.from_settings(OmnicacheSettings(
    backend="disk",
    disk_path="/data/cache",
))

Configuration Fields​

Backend Selection​

FieldTypeDefaultDescription
backend"memory" | "redis" | "disk""memory"Primary storage backend
redis_urlstr"redis://localhost:6379/0"Redis connection URL (used when backend="redis")
disk_pathstr"/tmp/omnicache"Directory path for disk cache (used when backend="disk")
max_memory_entriesint10000Maximum entries for InMemoryBackend

Key Generation​

FieldTypeDefaultDescription
namespacestr"omnicache"Prefix applied to every cache key
key_hash_algo"sha256" | "md5""sha256"Hash algorithm for key generation

TTL Configuration​

FieldTypeDefaultDescription
default_ttlint | None3600Default TTL in seconds; None disables expiry
ttl_embeddingint | None86400TTL for embedding cache entries (24 hours)
ttl_retrievalint | None3600TTL for retrieval cache entries (1 hour)
ttl_contextint | None1800TTL for context cache entries (30 minutes)
ttl_responseint | None600TTL for response cache entries (10 minutes)

Semantic / Vector Configuration​

FieldTypeDefaultDescription
semantic_thresholdfloat0.95Minimum cosine similarity for a semantic cache hit
vector_backend"faiss" | "chroma" | "none""none"Vector similarity backend
embedding_dimint1536Embedding vector dimension (used by FAISS backend)
note

The embedding_dim default of 1536 matches OpenAI's text-embedding-3-small model. Adjust this to match your embedding model's output dimension.

Environment Variable Reference​

Every field maps to an OMNICACHE_* environment variable. The from_env() classmethod handles type conversion automatically.

VariableTypeDefaultMaps to
OMNICACHE_BACKENDstrmemorybackend
OMNICACHE_REDIS_URLstrredis://localhost:6379/0redis_url
OMNICACHE_DISK_PATHstr/tmp/omnicachedisk_path
OMNICACHE_DEFAULT_TTLint | "none"3600default_ttl
OMNICACHE_SEMANTIC_THRESHOLDfloat0.95semantic_threshold
OMNICACHE_VECTOR_BACKENDstrnonevector_backend
OMNICACHE_EMBEDDING_DIMint1536embedding_dim
OMNICACHE_MAX_MEMORY_ENTRIESint10000max_memory_entries
OMNICACHE_KEY_HASH_ALGOstrsha256key_hash_algo
OMNICACHE_NAMESPACEstromnicachenamespace
OMNICACHE_TTL_EMBEDDINGint | "none"86400ttl_embedding
OMNICACHE_TTL_RETRIEVALint | "none"3600ttl_retrieval
OMNICACHE_TTL_CONTEXTint | "none"1800ttl_context
OMNICACHE_TTL_RESPONSEint | "none"600ttl_response
Disabling TTL via environment

Set any TTL variable to the string "none" (case-insensitive) to disable expiry for that cache type:

export OMNICACHE_TTL_EMBEDDING=none

API Reference​

Constructor​

@dataclass
class OmnicacheSettings:
    backend: Literal["memory", "redis", "disk"] = "memory"
    redis_url: str = "redis://localhost:6379/0"
    disk_path: str = "/tmp/omnicache"
    default_ttl: int | None = 3600
    semantic_threshold: float = 0.95
    vector_backend: Literal["faiss", "chroma", "none"] = "none"
    embedding_dim: int = 1536
    max_memory_entries: int = 10_000
    key_hash_algo: Literal["sha256", "md5"] = "sha256"
    namespace: str = "omnicache"
    ttl_embedding: int | None = 86400
    ttl_retrieval: int | None = 3600
    ttl_context: int | None = 1800
    ttl_response: int | None = 600

Methods​

MethodSignatureReturnsDescription
from_envfrom_env()OmnicacheSettingsClassmethod: build settings from OMNICACHE_* environment variables

Method Details​

from_env()​

Build an OmnicacheSettings instance by reading OMNICACHE_* environment variables. Any variable not set falls back to the field's default value. Integer fields are parsed with int(), float fields with float(), and TTL fields accept the string "none" to represent None.

import os
os.environ["OMNICACHE_BACKEND"] = "disk"
os.environ["OMNICACHE_DISK_PATH"] = "/data/cache"
os.environ["OMNICACHE_DEFAULT_TTL"] = "7200"

settings = OmnicacheSettings.from_env()
print(settings.backend)      # "disk"
print(settings.disk_path)    # "/data/cache"
print(settings.default_ttl)  # 7200

Example Configurations​

Development (In-Memory)​

settings = OmnicacheSettings(
    backend="memory",
    max_memory_entries=1000,
    default_ttl=60,
    namespace="dev",
)

Production (Redis + FAISS)​

settings = OmnicacheSettings(
    backend="redis",
    redis_url="redis://cache.internal:6379/0",
    namespace="prod",
    default_ttl=3600,
    ttl_response=300,
    vector_backend="faiss",
    embedding_dim=1536,
    semantic_threshold=0.93,
    key_hash_algo="sha256",
)

Disk-Based (Serverless / Edge)​

settings = OmnicacheSettings(
    backend="disk",
    disk_path="/tmp/omnicache",
    default_ttl=1800,
    vector_backend="none",
)
warning

When using backend="redis", ensure the Redis server is reachable at the configured redis_url. The CacheManager.from_settings() factory will attempt to connect immediately.

Next Steps​