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