"""SharedCache — in-memory session cache for Polyhedra V4.3. Replaces file-based shared state with a per-session in-memory layer. The filesystem becomes a persistence backup only; agents never read directly from disk during a live chain. Cache key conventions: state: ResearchState / QuantState artifact:: Artifact contents keyed by path llm: LLM output keyed by prompt hash api::: API response keyed by call signature """ from __future__ import annotations import asyncio import hashlib import json import logging import time from pathlib import Path from typing import Any logger = logging.getLogger(__name__) # Per-prefix default TTLs (seconds) — overridden by env vars (see FR-1.4) _DEFAULT_TTL: dict[str, int | None] = { "state": None, # never expires mid-session "artifact": None, # never expires mid-session "llm": None, # never expires mid-session (FR-1.5) "api:market": 86_400, # 24 h (FR-1.4) "api:sentiment": 3_600, # 1 h (FR-1.4) "api:quote": 60, # 1 min (FR-1.4) } def _pick_ttl(key: str) -> int | None: """Return the default TTL for a cache key based on its prefix.""" for prefix, ttl in _DEFAULT_TTL.items(): if key.startswith(prefix): return ttl return None _SENTINEL = object() # sentinel for "use default TTL" def prompt_hash(prompt: str) -> str: """Return a stable hex digest for a prompt string (used for llm:* keys).""" return hashlib.sha256(prompt.encode()).hexdigest()[:16] class _Entry: __slots__ = ("value", "expires_at") def __init__(self, value: Any, ttl: int | None) -> None: self.value = value self.expires_at: float | None = (time.monotonic() + ttl) if ttl is not None else None def is_expired(self) -> bool: if self.expires_at is None: return False return time.monotonic() > self.expires_at class CacheStats: """Hit / miss counters for the current session (FR-1.8 /poly cache status).""" def __init__(self) -> None: self.hits = 0 self.misses = 0 @property def total(self) -> int: return self.hits + self.misses @property def hit_rate(self) -> float: return self.hits / self.total if self.total else 0.0 def record_hit(self) -> None: self.hits += 1 def record_miss(self) -> None: self.misses += 1 def to_dict(self) -> dict[str, Any]: return { "hits": self.hits, "misses": self.misses, "total": self.total, "hit_rate_pct": round(self.hit_rate * 100, 1), } class SharedCache: """ Per-session in-memory cache. All agent reads go through the cache. FileWriter keeps cache and disk in sync — this object is never written to directly by agents. Scope: per-process, per-session. Not shared across sessions. """ def __init__(self) -> None: self._store: dict[str, _Entry] = {} self.stats = CacheStats() # ------------------------------------------------------------------ # # Core API (FR-1.1 – FR-1.7) # ------------------------------------------------------------------ # def get(self, key: str) -> Any | None: """Return cached value or None on miss / expiry.""" entry = self._store.get(key) if entry is None: self.stats.record_miss() return None if entry.is_expired(): del self._store[key] self.stats.record_miss() return None self.stats.record_hit() return entry.value def set(self, key: str, value: Any, ttl: int | None = _SENTINEL) -> None: # type: ignore[assignment] """ Store a value under *key*. If *ttl* is omitted the default for the key's prefix is used. Pass ``ttl=None`` explicitly to store without expiry. """ resolved_ttl: int | None if ttl is _SENTINEL: resolved_ttl = _pick_ttl(key) else: resolved_ttl = ttl # type: ignore[assignment] self._store[key] = _Entry(value, resolved_ttl) def invalidate(self, key: str) -> None: """Remove a single key.""" self._store.pop(key, None) def invalidate_prefix(self, prefix: str) -> None: """Remove all keys whose name starts with *prefix* (FR-1.6).""" victims = [k for k in self._store if k.startswith(prefix)] for k in victims: del self._store[k] if victims: logger.debug("SharedCache: invalidated %d keys with prefix %r", len(victims), prefix) def clear(self) -> None: """Flush the entire in-memory cache (FR-1.8 /poly cache clear).""" self._store.clear() logger.info("SharedCache: flushed all entries") # ------------------------------------------------------------------ # # Persistence helpers (FR-1.9) # ------------------------------------------------------------------ # def flush_to_disk(self, session_dir: str | Path) -> None: """ Persist serialisable cache entries to ``/.cache_snapshot.json``. Called by the Coordinator at session end or on explicit flush. Non-serialisable entries (e.g. numpy arrays) are silently skipped. """ base = Path(session_dir) snapshot: dict[str, Any] = {} for key, entry in self._store.items(): if entry.is_expired(): continue try: json.dumps(entry.value) # serialisability check snapshot[key] = { "value": entry.value, "expires_at": entry.expires_at, } except (TypeError, ValueError): pass # skip non-serialisable (numpy arrays, etc.) out = base / ".cache_snapshot.json" out.parent.mkdir(parents=True, exist_ok=True) try: out.write_text(json.dumps(snapshot, indent=2), encoding="utf-8") logger.debug("SharedCache: flushed %d entries to %s", len(snapshot), out) except Exception as exc: logger.warning("SharedCache.flush_to_disk failed: %s", exc) def warm_from_disk(self, session_dir: str | Path) -> None: """ Restore cache from a disk snapshot (cold-start recovery, FR-1.9). Only entries that have not yet expired are loaded. """ snapshot_path = Path(session_dir) / ".cache_snapshot.json" if not snapshot_path.exists(): return try: raw = json.loads(snapshot_path.read_text(encoding="utf-8")) except Exception as exc: logger.warning("SharedCache.warm_from_disk failed to parse snapshot: %s", exc) return now = time.monotonic() loaded = 0 for key, data in raw.items(): expires_at: float | None = data.get("expires_at") if expires_at is not None and now > expires_at: continue # skip expired entry = _Entry.__new__(_Entry) entry.value = data["value"] entry.expires_at = expires_at self._store[key] = entry loaded += 1 logger.debug("SharedCache: warmed %d entries from %s", loaded, snapshot_path) # ------------------------------------------------------------------ # # Convenience: async flush (for Coordinator background use) # ------------------------------------------------------------------ # async def async_flush_to_disk(self, session_dir: str | Path) -> None: """Non-blocking disk flush — runs flush_to_disk in a thread executor.""" loop = asyncio.get_event_loop() await loop.run_in_executor(None, self.flush_to_disk, session_dir) # ------------------------------------------------------------------ # # Internals # ------------------------------------------------------------------ # _SENTINEL = object() # class-level sentinel for default TTL detection def __len__(self) -> int: return len(self._store) def __contains__(self, key: str) -> bool: entry = self._store.get(key) if entry is None: return False if entry.is_expired(): del self._store[key] return False return True