File size: 8,474 Bytes
cc23e2a d8110c3 cc23e2a d8110c3 cc23e2a d8110c3 cc23e2a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 | """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
|