PolyHedra / src /polyhedra /core /cache.py
yf176
fix: cache.py SyntaxError β€” move _SENTINEL to module level, remove walrus op from default param
d8110c3
Raw History Blame Contribute Delete
8.47 kB
"""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:<session_id> ResearchState / QuantState
artifact:<session_id>:<path> Artifact contents keyed by path
llm:<prompt_hash> LLM output keyed by prompt hash
api:<provider>:<endpoint>:<params> 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 ``<session_dir>/.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