advalcache 0.1.0__py3-none-any.whl

advalcache/_scoring.py

@@ -0,0 +1,157 @@
+"""advalcache/_scoring.py — Pure AdVal scoring math.
+
+All functions are stateless and dependency-free. They operate on plain
+floats and return floats, making them trivially unit-testable and safely
+reusable by both the sync and async engines.
+
+The score equation:
+    score(i) = hotness(i) x pain(i) x freshness(i) / size_units(i)
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Constants (tunable at the Cache level via CacheConfig)
+# ---------------------------------------------------------------------------
+
+#: LRFU decay constant. Half-life ≈ ln2/0.001 ≈ 693 s.
+LAMBDA_DEFAULT: float = 0.001
+
+#: Objects that never change: treat freshness as 1.0 regardless of age.
+FRESH_ALWAYS_ABOVE_S: float = 1_800.0
+
+#: Floor so sub-KB objects don't divide by near-zero.
+SIZE_UNITS_FLOOR: float = 0.25
+
+#: 1 KB reference unit for logarithmic size scaling.
+_SIZE_REF_BYTES: float = 1_024.0
+
+
+# ---------------------------------------------------------------------------
+# Hotness (LRFU decayed counter)
+# ---------------------------------------------------------------------------
+
+def touch_hotness(
+    current_hotness: float,
+    last_access_ts: float,
+    now_ts: float,
+    decay_lambda: float = LAMBDA_DEFAULT,
+) -> float:
+    """Return updated LRFU hotness after an access at now_ts.
+
+    Formula: c <- 1 + c * exp(-lambda * dt)
+
+    At short dt the new access dominates (recency-like).
+    At long dt the exponent shrinks, so historic count dominates (frequency-like).
+
+    Complexity: O(1) — one exp() call.
+    """
+    dt = max(0.0, now_ts - last_access_ts)
+    return 1.0 + current_hotness * math.exp(-decay_lambda * dt)
+
+
+# ---------------------------------------------------------------------------
+# Freshness (Poisson staleness probability)
+# ---------------------------------------------------------------------------
+
+def get_freshness(
+    last_sync_ts: float,
+    now_ts: float,
+    change_interval_s: float,
+) -> float:
+    """P(copy still valid) = exp(-dt / T) for a Poisson mutation process.
+
+    Returns 1.0 for immutable objects (change_interval_s <= 0 or >= FRESH_ALWAYS_ABOVE_S).
+
+    Complexity: O(1) — one exp() call.
+    """
+    if change_interval_s <= 0.0 or change_interval_s >= FRESH_ALWAYS_ABOVE_S:
+        return 1.0
+    dt = max(0.0, now_ts - last_sync_ts)
+    return math.exp(-dt / change_interval_s)
+
+
+# ---------------------------------------------------------------------------
+# Pain (p99-normalised regeneration cost)
+# ---------------------------------------------------------------------------
+
+def pain_normalized(
+    regen_ms: float,
+    regen_usd: float,
+    p99_ms: float = 2_000.0,
+    p99_usd: float = 0.05,
+    w_lat: float = 0.5,
+    w_usd: float = 0.5,
+) -> float:
+    """Blended regeneration pain, normalised to (0, 1].
+
+    Both latency and dollar cost are normalised by p99 (not max) so
+    milliseconds don't drown out dollars.
+
+    Complexity: O(1).
+    """
+    pain_lat = min(1.0, max(0.01, regen_ms / max(1e-9, p99_ms)))
+    pain_usd = min(1.0, max(0.0, regen_usd / max(1e-9, p99_usd)))
+    return w_lat * pain_lat + w_usd * pain_usd
+
+
+# ---------------------------------------------------------------------------
+# Size units (logarithmic scaling)
+# ---------------------------------------------------------------------------
+
+def size_units(size_bytes: int) -> float:
+    """log1p(bytes / 1 KB), floored at SIZE_UNITS_FLOOR.
+
+    Logarithmic so a 5 MB image is penalised ~12x vs a 1 KB record, not 5000x.
+
+    Complexity: O(1) — one log1p() call.
+    """
+    return max(SIZE_UNITS_FLOOR, math.log1p(size_bytes / _SIZE_REF_BYTES))
+
+
+# ---------------------------------------------------------------------------
+# Full score
+# ---------------------------------------------------------------------------
+
+def compute_score(
+    hotness: float,
+    regen_ms: float,
+    regen_usd: float,
+    last_sync_ts: float,
+    now_ts: float,
+    change_interval_s: float,
+    size_bytes: int,
+    p99_ms: float = 2_000.0,
+    p99_usd: float = 0.05,
+    w_lat: float = 0.5,
+    w_usd: float = 0.5,
+) -> float:
+    """Full AdVal value score: hotness x pain x freshness / size_units.
+
+    Higher score = more valuable. Lower-score entries are evicted first.
+
+    Complexity: O(1) — three O(1) components combined.
+    """
+    pain = pain_normalized(regen_ms, regen_usd, p99_ms, p99_usd, w_lat, w_usd)
+    fresh = get_freshness(last_sync_ts, now_ts, change_interval_s)
+    su = size_units(size_bytes)
+    return (hotness * pain * fresh) / su
+
+
+# ---------------------------------------------------------------------------
+# Size estimation (when caller omits size_bytes)
+# ---------------------------------------------------------------------------
+
+def estimate_size_bytes(value: Any) -> int:
+    """Shallow sys.getsizeof estimate, good enough for eviction decisions.
+
+    Complexity: O(1) — shallow sizeof, does not traverse nested objects.
+    """
+    try:
+        return max(1, sys.getsizeof(value))
+    except Exception:
+        return 256

advalcache/adapters/__init__.py

@@ -0,0 +1,2 @@
+# advalcache/adapters/__init__.py
+"""Framework adapters for advalcache."""

advalcache/adapters/django.py

@@ -0,0 +1,139 @@
+"""advalcache/adapters/django.py — Django cache backend adapter.
+
+Implements Django's BaseCache interface backed by AdVal.
+
+Usage in settings.py:
+    CACHES = {
+        "default": {
+            "BACKEND": "advalcache.adapters.django.AdValDjangoCache",
+            "CAPACITY_MB": 512,
+            "COST_MAP": {
+                # key prefix -> cost parameters
+                "session:": {"regen_ms": 5,   "regen_usd": 0.0,   "change_interval_s": 1800},
+                "api:":     {"regen_ms": 800, "regen_usd": 0.015, "change_interval_s": 300},
+                # "_default" is used when no prefix matches
+                "_default": {"regen_ms": 50,  "regen_usd": 0.0,   "change_interval_s": 600},
+            },
+        }
+    }
+"""
+
+from __future__ import annotations
+
+import pickle
+import time
+from typing import Any, Dict, Iterable, Optional
+
+try:
+    from django.core.cache.backends.base import BaseCache, DEFAULT_CACHE_ALIAS
+    _HAS_DJANGO = True
+except ImportError:
+    _HAS_DJANGO = False
+
+from advalcache import Cache, CacheConfig
+
+_DEFAULT_COST = {"regen_ms": 50.0, "regen_usd": 0.0, "change_interval_s": 600.0}
+
+
+def _resolve_cost(key: str, cost_map: Dict[str, Any]) -> Dict[str, float]:
+    for prefix, params in cost_map.items():
+        if prefix == "_default":
+            continue
+        if key.startswith(prefix):
+            return params
+    return cost_map.get("_default", _DEFAULT_COST)
+
+
+if _HAS_DJANGO:
+    class AdValDjangoCache(BaseCache):
+        """Django cache backend backed by AdVal in-memory engine."""
+
+        def __init__(self, server: str = "", params: Optional[Dict[str, Any]] = None) -> None:
+            # Django passes LOCATION as server; params contains all CACHE keys
+            super().__init__(params or {})
+            p = params or {}
+            capacity_mb = float(p.get("CAPACITY_MB", 256.0))
+            self._cost_map: Dict[str, Any] = p.get("COST_MAP", {"_default": _DEFAULT_COST})
+            self._cache = Cache(capacity_mb=capacity_mb)
+            # Expiry tracking: Django has timeout semantics, AdVal uses change_interval
+            self._expiry: Dict[str, float] = {}
+
+        def _serialize(self, value: Any) -> bytes:
+            return pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+
+        def _deserialize(self, raw: bytes) -> Any:
+            return pickle.loads(raw)  # noqa: S301
+
+        def get_backend_timeout(self, timeout: Optional[int] = None) -> Optional[float]:
+            if timeout is None:
+                return self.default_timeout
+            return timeout
+
+        def add(self, key: str, value: Any, timeout: Optional[int] = None, version: Optional[int] = None) -> bool:
+            k = self.make_key(key, version)
+            if self._cache.get(k) is not None:
+                return False
+            return self.set(key, value, timeout, version)
+
+        def get(self, key: str, default: Any = None, version: Optional[int] = None) -> Any:
+            k = self.make_key(key, version)
+            # Check Django-level expiry
+            exp = self._expiry.get(k)
+            if exp is not None and time.time() > exp:
+                self._cache.invalidate(k)
+                self._expiry.pop(k, None)
+                return default
+            result = self._cache.get(k)
+            if result is None:
+                return default
+            raw, _fresh, _freshness, _score = result
+            try:
+                return self._deserialize(raw)
+            except Exception:
+                return default
+
+        def set(self, key: str, value: Any, timeout: Optional[int] = None, version: Optional[int] = None) -> bool:
+            k = self.make_key(key, version)
+            raw = self._serialize(value)
+            cost = _resolve_cost(k, self._cost_map)
+            t = self.get_backend_timeout(timeout)
+            change_interval = t if t is not None else cost.get("change_interval_s", 600.0)
+            if t is not None:
+                self._expiry[k] = time.time() + t
+            return self._cache.put(
+                key=k, value=raw,
+                regen_ms=cost.get("regen_ms", 50.0),
+                regen_usd=cost.get("regen_usd", 0.0),
+                change_interval_s=change_interval,
+            )
+
+        def delete(self, key: str, version: Optional[int] = None) -> bool:
+            k = self.make_key(key, version)
+            self._expiry.pop(k, None)
+            return self._cache.invalidate(k)
+
+        def has_key(self, key: str, version: Optional[int] = None) -> bool:
+            return self.get(key, version=version) is not None
+
+        def clear(self) -> bool:
+            self._expiry.clear()
+            self._cache.clear()
+            return True
+
+        def get_many(self, keys: Iterable[str], version: Optional[int] = None) -> Dict[str, Any]:
+            return {k: v for k in keys if (v := self.get(k, version=version)) is not None}
+
+        def set_many(self, mapping: Dict[str, Any], timeout: Optional[int] = None, version: Optional[int] = None) -> list:
+            return [k for k, v in mapping.items() if not self.set(k, v, timeout, version)]
+
+        def delete_many(self, keys: Iterable[str], version: Optional[int] = None) -> None:
+            for k in keys:
+                self.delete(k, version)
+
+else:
+    class AdValDjangoCache:  # type: ignore[no-redef]
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "advalcache Django adapter requires 'django'. "
+                "Install with: pip install advalcache[django]"
+            )

advalcache/adapters/fastapi.py

@@ -0,0 +1,80 @@
+"""advalcache/adapters/fastapi.py — FastAPI middleware + dependency injection.
+
+Usage:
+    from advalcache.adapters.fastapi import AdValCacheMiddleware, get_cache
+
+    app.add_middleware(AdValCacheMiddleware, capacity_mb=256)
+
+    @app.get("/quote/{ticker}")
+    async def get_quote(ticker: str, cache=Depends(get_cache)):
+        hit = cache.get(f"quote:{ticker}")
+        if hit:
+            return hit[0]
+        data = await fetch_live(ticker)
+        cache.put(f"quote:{ticker}", data, regen_ms=200, regen_usd=0.01, change_interval_s=30)
+        return data
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+try:
+    from fastapi import Request
+    from starlette.middleware.base import BaseHTTPMiddleware
+    _HAS_FASTAPI = True
+except ImportError:
+    _HAS_FASTAPI = False
+
+from advalcache import Cache, CacheConfig
+
+# Module-level singleton — populated by middleware
+_cache_instance: Optional[Cache] = None
+
+
+def get_cache() -> Cache:
+    """FastAPI dependency that returns the shared AdVal cache instance.
+
+    Must use AdValCacheMiddleware (or call init_cache()) first.
+    """
+    if _cache_instance is None:
+        raise RuntimeError(
+            "advalcache: no cache instance found. "
+            "Add AdValCacheMiddleware to your app or call advalcache.adapters.fastapi.init_cache()."
+        )
+    return _cache_instance
+
+
+def init_cache(capacity_mb: float = 256.0, config: Optional[CacheConfig] = None) -> Cache:
+    """Manually initialise the shared cache (without middleware)."""
+    global _cache_instance
+    _cache_instance = Cache(capacity_mb=capacity_mb, config=config)
+    return _cache_instance
+
+
+if _HAS_FASTAPI:
+    class AdValCacheMiddleware(BaseHTTPMiddleware):
+        """Starlette/FastAPI middleware that creates and stores a shared AdVal cache.
+
+        The cache is accessible in any route via ``Depends(get_cache)``.
+        """
+
+        def __init__(
+            self,
+            app: Any,
+            capacity_mb: float = 256.0,
+            config: Optional[CacheConfig] = None,
+        ) -> None:
+            super().__init__(app)
+            global _cache_instance
+            _cache_instance = Cache(capacity_mb=capacity_mb, config=config)
+
+        async def dispatch(self, request: Request, call_next: Any) -> Any:
+            return await call_next(request)
+else:
+    class AdValCacheMiddleware:  # type: ignore[no-redef]
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "advalcache FastAPI adapter requires 'fastapi'. "
+                "Install with: pip install advalcache[fastapi]"
+            )

advalcache/adapters/sqlalchemy.py

@@ -0,0 +1,83 @@
+"""advalcache/adapters/sqlalchemy.py — SQLAlchemy query result caching decorator.
+
+Usage:
+    from advalcache.adapters.sqlalchemy import cache_query
+    from advalcache import Cache
+
+    cache = Cache(capacity_mb=256)
+
+    @cache_query(cache, regen_ms=50, regen_usd=0.0, change_interval_s=60)
+    def get_user(session, user_id: int):
+        return session.query(User).filter_by(id=user_id).first()
+
+    # Works with any ORM query function — session arg is NOT part of the cache key.
+"""
+
+from __future__ import annotations
+
+import functools
+import reprlib
+from typing import Any, Callable, Optional
+
+from advalcache import Cache
+
+_repr = reprlib.Repr()
+_repr.maxstring = 64
+_repr.maxother = 32
+
+
+def cache_query(
+    cache: Cache,
+    regen_ms: float = 50.0,
+    regen_usd: float = 0.0,
+    change_interval_s: float = 300.0,
+    cls: str = "db_query",
+    key_prefix: str = "sql:",
+) -> Callable:
+    """Decorator factory for caching SQLAlchemy query results with AdVal.
+
+    The first argument to the decorated function is assumed to be a SQLAlchemy
+    session and is excluded from the cache key. All remaining args and kwargs
+    are used to build the key.
+
+    Args:
+        cache: An AdVal Cache instance.
+        regen_ms: Estimated DB query latency in milliseconds.
+        regen_usd: DB query cost in USD (0 for most queries).
+        change_interval_s: How often this query's result may change (seconds).
+        cls: Object class label for telemetry.
+        key_prefix: Prefix prepended to all auto-generated cache keys.
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # args[0] is assumed to be the SQLAlchemy session — exclude from key
+            cache_args = args[1:] if len(args) > 1 else ()
+            arg_part = _repr.repr(cache_args)
+            kw_part = _repr.repr(sorted(kwargs.items()))
+            key = f"{key_prefix}{func.__module__}.{func.__qualname__}:{arg_part}:{kw_part}"
+
+            result = cache.get(key)
+            if result is not None:
+                value, _fresh, _freshness, _score = result
+                return value
+
+            value = func(*args, **kwargs)
+            cache.put(
+                key=key, value=value, cls=cls,
+                regen_ms=regen_ms, regen_usd=regen_usd,
+                change_interval_s=change_interval_s,
+            )
+            return value
+
+        def invalidate(*args: Any, **kwargs: Any) -> bool:
+            cache_args = args[1:] if len(args) > 1 else ()
+            arg_part = _repr.repr(cache_args)
+            kw_part = _repr.repr(sorted(kwargs.items()))
+            key = f"{key_prefix}{func.__module__}.{func.__qualname__}:{arg_part}:{kw_part}"
+            return cache.invalidate(key)
+
+        wrapper.invalidate = invalidate  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator

advalcache/config.py

@@ -0,0 +1,80 @@
+"""advalcache/config.py — CacheConfig: validated configuration dataclass."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class CacheConfig:
+    """All tuning knobs for an AdVal cache instance.
+
+    All parameters have sensible defaults so ``Cache(capacity_mb=256)`` works
+    out of the box with no further configuration required.
+
+    Args:
+        capacity_mb: Maximum resident memory in megabytes. Default 256 MB.
+        decay_lambda: LRFU hotness decay constant. Half-life ≈ ln2/lambda seconds.
+            Default 0.001 (half-life ≈ 693 s ≈ 11.5 min).
+        refresh_threshold: Freshness level below which a background refresh is
+            considered. 0.30 means "refresh when copy is <30% likely to be valid".
+        refresh_min_score: Minimum AdVal score an entry must have to be worth
+            a background refresh. Prevents refreshing junk that is about to be evicted.
+        max_refresh_workers: Thread pool size for background refresh callbacks.
+        eviction_pool_fraction: Fraction of resident keys sampled for each eviction.
+            10% balances quality and O(n) cost.
+        p99_ms: Catalog p99 regeneration latency (ms) used to normalise the pain term.
+            Defaults to 2000 ms if not set.
+        p99_usd: Catalog p99 regeneration cost (USD) used to normalise the pain term.
+            Defaults to $0.05 if not set.
+        max_events: Maximum number of recent cache events kept in memory for the
+            built-in event log / observability server.
+        obs_port: If set, the built-in FastAPI observability server starts on this port
+            when the cache is created. Requires ``advalcache[fastapi]`` extra.
+        key_prefix: Optional global prefix prepended to all auto-generated cache keys.
+            Useful for multi-tenant isolation (e.g. ``key_prefix="tenant_42:"``).
+    """
+
+    capacity_mb: float = 256.0
+    decay_lambda: float = 0.001
+    refresh_threshold: float = 0.30
+    refresh_min_score: float = 0.35
+    max_refresh_workers: int = 4
+    eviction_pool_fraction: float = 0.10
+    p99_ms: float = 2_000.0
+    p99_usd: float = 0.05
+    max_events: int = 200
+    obs_port: Optional[int] = None
+    key_prefix: str = ""
+
+    def __post_init__(self) -> None:
+        errors = []
+        if self.capacity_mb <= 0:
+            errors.append(f"capacity_mb must be > 0, got {self.capacity_mb}")
+        if not 0.0 < self.decay_lambda < 1.0:
+            errors.append(f"decay_lambda must be in (0, 1), got {self.decay_lambda}")
+        if not 0.0 <= self.refresh_threshold <= 1.0:
+            errors.append(f"refresh_threshold must be in [0, 1], got {self.refresh_threshold}")
+        if not 0.0 <= self.refresh_min_score <= 10.0:
+            errors.append(f"refresh_min_score must be in [0, 10], got {self.refresh_min_score}")
+        if self.max_refresh_workers < 1:
+            errors.append(f"max_refresh_workers must be >= 1, got {self.max_refresh_workers}")
+        if not 0.0 < self.eviction_pool_fraction <= 1.0:
+            errors.append(f"eviction_pool_fraction must be in (0, 1], got {self.eviction_pool_fraction}")
+        if errors:
+            raise ValueError("CacheConfig validation errors:\n  " + "\n  ".join(errors))
+
+    def engine_kwargs(self) -> dict:
+        """Return kwargs suitable for constructing AdValEngine."""
+        return {
+            "capacity_mb": self.capacity_mb,
+            "decay_lambda": self.decay_lambda,
+            "refresh_threshold": self.refresh_threshold,
+            "refresh_min_score": self.refresh_min_score,
+            "max_refresh_workers": self.max_refresh_workers,
+            "eviction_pool_fraction": self.eviction_pool_fraction,
+            "p99_ms": self.p99_ms,
+            "p99_usd": self.p99_usd,
+            "max_events": self.max_events,
+        }