cloud-dog-cache 0.2.0__py3-none-any.whl

cloud_dog_cache/backends/redis.py

@@ -0,0 +1,102 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""Redis cache backend (optional — requires ``redis`` package)."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Optional
+
+from cloud_dog_cache.models import CacheEntry
+from cloud_dog_cache.stats import CacheStats
+
+
+class RedisCacheBackend:
+    """Redis-backed cache with TTL and tag-based invalidation.
+
+    Requires the ``redis`` package: ``pip install redis``.
+    """
+
+    def __init__(self, *, redis_url: str, key_prefix: str = "cdc:") -> None:
+        """Initialise with Redis connection URL."""
+        import redis.asyncio as aioredis
+
+        self._client = aioredis.from_url(redis_url, decode_responses=True)
+        self._prefix = key_prefix
+        self._hits = 0
+        self._misses = 0
+        self._evictions = 0
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}{key}"
+
+    def _tag_key(self, tag: str) -> str:
+        return f"{self._prefix}tag:{tag}"
+
+    async def get(self, key: str) -> Optional[CacheEntry]:
+        """Retrieve a cached entry from Redis."""
+        raw = await self._client.get(self._key(key))
+        if raw is None:
+            self._misses += 1
+            return None
+        data = json.loads(raw)
+        self._hits += 1
+        return CacheEntry(
+            key=key,
+            value=data["value"],
+            created_at=datetime.fromisoformat(data["created_at"]),
+            tags=tuple(data.get("tags", ())),
+        )
+
+    async def set(self, key: str, entry: CacheEntry, ttl: int) -> None:
+        """Store a cache entry in Redis with TTL."""
+        data = {
+            "value": entry.value,
+            "created_at": entry.created_at.isoformat(),
+            "tags": list(entry.tags),
+        }
+        pipe = self._client.pipeline()
+        pipe.setex(self._key(key), ttl, json.dumps(data, default=str))
+        for tag in entry.tags:
+            pipe.sadd(self._tag_key(tag), key)
+            pipe.expire(self._tag_key(tag), ttl)
+        await pipe.execute()
+
+    async def delete(self, key: str) -> None:
+        """Remove a single entry from Redis."""
+        await self._client.delete(self._key(key))
+
+    async def flush(self) -> None:
+        """Remove all entries with the configured prefix."""
+        keys = []
+        async for key in self._client.scan_iter(match=f"{self._prefix}*"):
+            keys.append(key)
+        if keys:
+            await self._client.delete(*keys)
+
+    async def stats(self) -> CacheStats:
+        """Return statistics (approximate for Redis)."""
+        count = 0
+        async for _ in self._client.scan_iter(match=f"{self._prefix}*"):
+            count += 1
+        return CacheStats(
+            hits=self._hits,
+            misses=self._misses,
+            entries=count,
+            evictions=self._evictions,
+        )
+
+    async def flush_by_tag(self, tag: str) -> int:
+        """Remove all entries tagged with the given tag."""
+        members = await self._client.smembers(self._tag_key(tag))
+        removed = 0
+        if members:
+            pipe = self._client.pipeline()
+            for member in members:
+                pipe.delete(self._key(member))
+            await pipe.execute()
+            removed = len(members)
+            await self._client.delete(self._tag_key(tag))
+        return removed

cloud_dog_cache/decorator.py

@@ -0,0 +1,94 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""@cached decorator for transparent function result caching."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, Sequence
+
+from cloud_dog_cache.keys import cache_key
+from cloud_dog_cache.manager import get_cache_manager
+
+
+def cached(
+    *,
+    ttl: int = 3600,
+    invalidate_on: Sequence[str] = (),
+    key_params: Sequence[str] | None = None,
+    context_hash_param: str = "",
+    model_config_hash_param: str = "",
+    prompt_hash_param: str = "",
+) -> Callable:
+    """Decorator that caches async function results.
+
+    Args:
+        ttl: Time-to-live in seconds for cached entries.
+        invalidate_on: Event names that trigger invalidation of this function's cache.
+        key_params: Explicit parameter names to include in the cache key.
+            If None, all parameters are included.
+        context_hash_param: Name of the parameter containing the context hash.
+        model_config_hash_param: Name of the parameter containing the model config hash.
+        prompt_hash_param: Name of the parameter containing the prompt hash.
+
+    Returns:
+        A decorator that wraps async functions with caching logic.
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        fn_name = f"{fn.__module__}.{fn.__qualname__}"
+
+        @functools.wraps(fn)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            manager = get_cache_manager()
+            if manager is None or not manager.enabled:
+                return await fn(*args, **kwargs)
+
+            # Build parameter dict from function signature
+            sig = inspect.signature(fn)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            all_params = dict(bound.arguments)
+
+            # Select key params
+            if key_params is not None:
+                params = {k: all_params[k] for k in key_params if k in all_params}
+            else:
+                params = all_params
+
+            # Extract hash params
+            ctx_hash = (
+                str(params.pop(context_hash_param, "")) if context_hash_param else ""
+            )
+            model_hash = (
+                str(params.pop(model_config_hash_param, ""))
+                if model_config_hash_param
+                else ""
+            )
+            p_hash = str(params.pop(prompt_hash_param, "")) if prompt_hash_param else ""
+
+            key = cache_key(
+                fn_name,
+                params=params,
+                context_hash=ctx_hash,
+                model_config_hash=model_hash,
+                prompt_hash=p_hash,
+            )
+
+            # Check cache
+            cached_value = await manager.get(key)
+            if cached_value is not None:
+                return cached_value
+
+            # Execute and cache
+            result = await fn(*args, **kwargs)
+            tags = tuple(invalidate_on)
+            await manager.set(key, result, ttl=ttl, tags=tags)
+            return result
+
+        wrapper.__cache_function_name__ = fn_name
+        return wrapper
+
+    return decorator

cloud_dog_cache/invalidation.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""Event-based cache invalidation hooks."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Well-known invalidation event names.
+CONTEXT_REBUILD = "context_rebuild"
+CONFIG_CHANGE = "config_change"
+PROMPT_CHANGE = "prompt_change"
+MANUAL_FLUSH = "manual_flush"
+
+
+async def invalidate_event(event_name: str) -> int:
+    """Fire an invalidation event, flushing cache entries tagged with *event_name*.
+
+    Returns the number of entries removed.
+    """
+    from cloud_dog_cache.manager import get_cache_manager
+
+    manager = get_cache_manager()
+    if manager is None:
+        return 0
+    removed = await manager.backend.flush_by_tag(event_name)
+    logger.info("cache_invalidation", extra={"event": event_name, "removed": removed})
+    return removed

cloud_dog_cache/keys.py

@@ -0,0 +1,59 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""Cache key generation and hashing."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def _stable_json(obj: Any) -> str:
+    """Produce a deterministic JSON representation for hashing."""
+    if isinstance(obj, dict):
+        return json.dumps(
+            {k: _stable_json(v) for k, v in sorted(obj.items())}, sort_keys=True
+        )
+    if isinstance(obj, (list, tuple)):
+        return json.dumps([_stable_json(v) for v in obj])
+    if isinstance(obj, set):
+        return json.dumps(sorted(str(v) for v in obj))
+    return json.dumps(obj, default=str)
+
+
+def cache_key(
+    function_name: str,
+    *,
+    params: dict[str, Any] | None = None,
+    context_hash: str = "",
+    model_config_hash: str = "",
+    prompt_hash: str = "",
+) -> str:
+    """Generate a deterministic cache key from function identity and input hashes.
+
+    The key includes the function name, sorted input parameters, and optional
+    hashes for context state, model configuration, and prompt templates. Any
+    change in these components produces a different key, ensuring stale results
+    are never served.
+    """
+    parts = [
+        function_name,
+        _stable_json(params or {}),
+        context_hash,
+        model_config_hash,
+        prompt_hash,
+    ]
+    combined = "|".join(parts)
+    return hashlib.sha256(combined.encode("utf-8")).hexdigest()
+
+
+def hash_text(text: str) -> str:
+    """Return a stable SHA-256 hex digest of the given text."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def hash_config(config: dict[str, Any]) -> str:
+    """Return a stable hash of a configuration dict."""
+    return hashlib.sha256(_stable_json(config).encode("utf-8")).hexdigest()

cloud_dog_cache/manager.py

@@ -0,0 +1,95 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""CacheManager — orchestrates cache backends, logging, and statistics."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from cloud_dog_cache.backends.memory import MemoryCacheBackend
+from cloud_dog_cache.models import CacheConfig, CacheEntry
+from cloud_dog_cache.stats import CacheStats
+
+logger = logging.getLogger(__name__)
+
+_MANAGER: CacheManager | None = None
+
+
+class CacheManager:
+    """Central cache orchestrator.
+
+    Wraps a pluggable backend with logging, config-driven enable/disable,
+    and statistics collection.
+    """
+
+    def __init__(self, config: CacheConfig | None = None) -> None:
+        """Initialise with configuration."""
+        self.config = config or CacheConfig()
+        self.backend = self._build_backend()
+
+    def _build_backend(self) -> Any:
+        """Instantiate the configured backend."""
+        if self.config.backend == "redis" and self.config.redis_url:
+            from cloud_dog_cache.backends.redis import RedisCacheBackend
+
+            return RedisCacheBackend(redis_url=self.config.redis_url)
+        return MemoryCacheBackend(max_entries=self.config.max_entries)
+
+    @property
+    def enabled(self) -> bool:
+        """Return whether caching is active."""
+        return self.config.enabled
+
+    async def get(self, key: str) -> Optional[Any]:
+        """Retrieve a cached value. Return None on miss or when disabled."""
+        if not self.enabled:
+            return None
+        entry = await self.backend.get(key)
+        if entry is None:
+            logger.debug("cache_miss", extra={"key": key[:16]})
+            return None
+        logger.debug("cache_hit", extra={"key": key[:16]})
+        return entry.value
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        ttl: int | None = None,
+        tags: tuple[str, ...] = (),
+    ) -> None:
+        """Store a value in the cache."""
+        if not self.enabled:
+            return
+        effective_ttl = ttl if ttl is not None else self.config.ttl_seconds
+        entry = CacheEntry(key=key, value=value, tags=tags)
+        await self.backend.set(key, entry, effective_ttl)
+        logger.debug("cache_set", extra={"key": key[:16], "ttl": effective_ttl})
+
+    async def delete(self, key: str) -> None:
+        """Remove a single cache entry."""
+        await self.backend.delete(key)
+
+    async def flush(self) -> None:
+        """Remove all cache entries."""
+        await self.backend.flush()
+        logger.info("cache_flushed")
+
+    async def stats(self) -> CacheStats:
+        """Return current cache statistics."""
+        return await self.backend.stats()
+
+
+def init_cache(config: CacheConfig | None = None) -> CacheManager:
+    """Initialise the global cache manager singleton."""
+    global _MANAGER
+    _MANAGER = CacheManager(config)
+    return _MANAGER
+
+
+def get_cache_manager() -> CacheManager | None:
+    """Return the global cache manager, or None if not initialised."""
+    return _MANAGER

cloud_dog_cache/memory.py

@@ -0,0 +1,206 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""Agent memory primitives — scoped namespaces, hierarchical TTL, tenant isolation.
+
+W28B-305: Distributed memory on cloud_dog_cache. No new memory package.
+"""
+
+from __future__ import annotations
+
+import enum
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional, Sequence
+
+from cloud_dog_cache.manager import CacheManager, get_cache_manager
+
+
+class MemoryScope(enum.Enum):
+    """Hierarchical memory scopes with default TTL ordering.
+
+    REQUEST < SESSION < USER_PROFILE < GLOBAL
+    """
+
+    REQUEST = "request"
+    SESSION = "session"
+    USER_PROFILE = "user_profile"
+    GLOBAL = "global"
+
+
+# Default TTL per scope (seconds). Callers can override.
+DEFAULT_SCOPE_TTL: dict[MemoryScope, int] = {
+    MemoryScope.REQUEST: 300,        # 5 minutes
+    MemoryScope.SESSION: 3600,       # 1 hour
+    MemoryScope.USER_PROFILE: 86400, # 24 hours
+    MemoryScope.GLOBAL: 604800,      # 7 days
+}
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryNamespace:
+    """A scoped, tenant-isolated namespace for agent memory.
+
+    Keys are prefixed with ``mem:{tenant}:{scope}:{namespace}:`` to ensure
+    isolation across tenants, scopes, and logical namespaces.
+    """
+
+    tenant_id: str
+    scope: MemoryScope
+    namespace: str = ""
+
+    def _prefix(self) -> str:
+        parts = ["mem", self.tenant_id, self.scope.value]
+        if self.namespace:
+            parts.append(self.namespace)
+        return ":".join(parts) + ":"
+
+    def full_key(self, key: str) -> str:
+        """Return the fully-qualified cache key."""
+        return f"{self._prefix()}{key}"
+
+    def tag(self) -> str:
+        """Return the invalidation tag for this namespace."""
+        return self._prefix().rstrip(":")
+
+
+@dataclass
+class MemoryEntry:
+    """A single memory entry with scope metadata."""
+
+    key: str
+    value: Any
+    scope: MemoryScope
+    tenant_id: str
+    namespace: str = ""
+    created_at: float = field(default_factory=time.time)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class MemoryStore:
+    """Agent memory store backed by CacheManager.
+
+    Provides scoped get/set/list/clear operations with tenant isolation
+    and hierarchical TTL defaults.
+    """
+
+    def __init__(
+        self,
+        tenant_id: str,
+        *,
+        manager: CacheManager | None = None,
+        scope_ttl: dict[MemoryScope, int] | None = None,
+    ) -> None:
+        self._tenant_id = tenant_id
+        self._manager = manager
+        self._scope_ttl = dict(DEFAULT_SCOPE_TTL)
+        if scope_ttl:
+            self._scope_ttl.update(scope_ttl)
+
+    @property
+    def manager(self) -> CacheManager:
+        if self._manager is not None:
+            return self._manager
+        m = get_cache_manager()
+        if m is None:
+            raise RuntimeError("CacheManager not initialised; call init_cache() first")
+        return m
+
+    def _ns(self, scope: MemoryScope, namespace: str = "") -> MemoryNamespace:
+        return MemoryNamespace(
+            tenant_id=self._tenant_id,
+            scope=scope,
+            namespace=namespace,
+        )
+
+    def _ttl(self, scope: MemoryScope, ttl: int | None = None) -> int:
+        if ttl is not None:
+            return ttl
+        return self._scope_ttl.get(scope, 3600)
+
+    async def get(
+        self,
+        key: str,
+        scope: MemoryScope = MemoryScope.SESSION,
+        namespace: str = "",
+    ) -> Any | None:
+        """Retrieve a memory value by key and scope."""
+        ns = self._ns(scope, namespace)
+        return await self.manager.get(ns.full_key(key))
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        scope: MemoryScope = MemoryScope.SESSION,
+        namespace: str = "",
+        ttl: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Store a memory value with scope-appropriate TTL."""
+        ns = self._ns(scope, namespace)
+        effective_ttl = self._ttl(scope, ttl)
+        # Wrap value with metadata for richer retrieval
+        wrapped = {
+            "v": value,
+            "scope": scope.value,
+            "tenant": self._tenant_id,
+            "ns": namespace,
+            "ts": time.time(),
+        }
+        if metadata:
+            wrapped["meta"] = metadata
+        await self.manager.set(
+            ns.full_key(key),
+            wrapped,
+            ttl=effective_ttl,
+            tags=(ns.tag(),),
+        )
+
+    async def delete(
+        self,
+        key: str,
+        scope: MemoryScope = MemoryScope.SESSION,
+        namespace: str = "",
+    ) -> None:
+        """Remove a single memory entry."""
+        ns = self._ns(scope, namespace)
+        await self.manager.delete(ns.full_key(key))
+
+    async def clear_scope(
+        self,
+        scope: MemoryScope,
+        namespace: str = "",
+    ) -> int:
+        """Clear all entries in a scope/namespace. Returns count removed."""
+        ns = self._ns(scope, namespace)
+        return await self.manager.backend.flush_by_tag(ns.tag())
+
+    async def clear_tenant(self) -> int:
+        """Clear all entries for this tenant across all scopes."""
+        total = 0
+        for scope in MemoryScope:
+            total += await self.clear_scope(scope)
+        return total
+
+
+class VectorSearchAdapter:
+    """Optional adapter for semantic search over memory entries.
+
+    This is a protocol/interface — concrete implementations connect to
+    index-retriever, Qdrant, ChromaDB, etc.
+    """
+
+    async def index(self, key: str, text: str, metadata: dict[str, Any] | None = None) -> None:
+        """Index a memory entry for semantic search."""
+        raise NotImplementedError
+
+    async def search(self, query: str, *, top_k: int = 5, filter: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Search memory entries by semantic similarity."""
+        raise NotImplementedError
+
+    async def delete(self, key: str) -> None:
+        """Remove a memory entry from the search index."""
+        raise NotImplementedError

cloud_dog_cache/models.py

@@ -0,0 +1,41 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""Cache entry and configuration models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    """A single cached result with metadata."""
+
+    key: str
+    value: Any
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime | None = None
+    hit_count: int = 0
+    tags: tuple[str, ...] = ()
+
+    @property
+    def expired(self) -> bool:
+        """Return True if this entry has passed its TTL."""
+        if self.expires_at is None:
+            return False
+        return datetime.now(timezone.utc) >= self.expires_at
+
+
+@dataclass(frozen=True, slots=True)
+class CacheConfig:
+    """Runtime cache configuration."""
+
+    enabled: bool = True
+    backend: str = "memory"
+    ttl_seconds: int = 3600
+    max_entries: int = 1000
+    max_memory_mb: int = 256
+    redis_url: str = ""

cloud_dog_cache/runtime.py

@@ -0,0 +1,57 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+
+"""Runtime initialisation helper — reads cache config from cloud_dog_config."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cloud_dog_cache.manager import CacheManager, init_cache
+from cloud_dog_cache.models import CacheConfig
+
+
+def init_cache_from_config(config: Any = None) -> CacheManager:
+    """Initialise the global cache manager from cloud_dog_config.
+
+    Reads ``cache.enabled``, ``cache.backend``, ``cache.ttl_seconds``,
+    ``cache.max_entries``, ``cache.redis_url`` from the platform config.
+    """
+    if config is None:
+        try:
+            from cloud_dog_config import get_config
+
+            config = get_config
+        except ImportError:
+            config = lambda key, default=None: default  # noqa: E731
+
+    def _get(key: str, default: Any = None) -> Any:
+        if callable(config):
+            return config(key) or default
+        return getattr(config, "get", lambda k, d=None: d)(key, default)
+
+    cache_config = CacheConfig(
+        enabled=_to_bool(_get("cache.enabled", True)),
+        backend=str(_get("cache.backend", "memory") or "memory"),
+        ttl_seconds=_to_int(_get("cache.ttl_seconds", 3600)),
+        max_entries=_to_int(_get("cache.max_entries", 1000)),
+        redis_url=str(_get("cache.redis_url", "") or ""),
+    )
+    return init_cache(cache_config)
+
+
+def _to_bool(value: Any) -> bool:
+    """Coerce a config value to bool."""
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return True
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _to_int(value: Any) -> int:
+    """Coerce a config value to int."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0