reflex/pulse/
llm_cache.rs

1//! LLM response cache for Pulse narration
2//!
3//! Caches LLM-generated summaries keyed by structural context hash.
4//! Same structural inputs → cache hit, regardless of LLM provider or model.
5
6use anyhow::{Context, Result};
7use serde::{Deserialize, Serialize};
8use std::path::{Path, PathBuf};
9
10/// A cached LLM response
11#[derive(Debug, Clone, Serialize, Deserialize)]
12pub struct CachedResponse {
13    pub context_hash: String,
14    pub response: String,
15    pub timestamp: String,
16}
17
18/// LLM response cache manager
19pub struct LlmCache {
20    cache_dir: PathBuf,
21}
22
23impl LlmCache {
24    /// Create a new LLM cache at the given directory
25    pub fn new(reflex_cache_path: &Path) -> Self {
26        Self {
27            cache_dir: reflex_cache_path.join("pulse").join("llm-cache"),
28        }
29    }
30
31    /// Create from an already-resolved cache directory path
32    pub fn from_dir(cache_dir: PathBuf) -> Self {
33        Self { cache_dir }
34    }
35
36    /// Get the cache directory path
37    pub fn cache_dir(&self) -> &Path {
38        &self.cache_dir
39    }
40
41    /// Compute a cache key from structural context
42    ///
43    /// Key: blake3(snapshot_id + module_path + structural_context_hash)
44    pub fn compute_key(snapshot_id: &str, module_path: &str, context: &str) -> String {
45        let input = format!("{}:{}:{}", snapshot_id, module_path, context);
46        blake3::hash(input.as_bytes()).to_hex().to_string()
47    }
48
49    /// Look up a cached response
50    pub fn get(&self, key: &str) -> Result<Option<CachedResponse>> {
51        let path = self.cache_dir.join(format!("{}.json", key));
52        if !path.exists() {
53            return Ok(None);
54        }
55
56        let content = std::fs::read_to_string(&path).context("Failed to read LLM cache entry")?;
57        let cached: CachedResponse =
58            serde_json::from_str(&content).context("Failed to parse LLM cache entry")?;
59        Ok(Some(cached))
60    }
61
62    /// Store a response in the cache
63    pub fn put(&self, key: &str, context_hash: &str, response: &str) -> Result<()> {
64        std::fs::create_dir_all(&self.cache_dir).context("Failed to create LLM cache directory")?;
65
66        let entry = CachedResponse {
67            context_hash: context_hash.to_string(),
68            response: response.to_string(),
69            timestamp: chrono::Local::now().to_rfc3339(),
70        };
71
72        let json = serde_json::to_string_pretty(&entry)?;
73        let path = self.cache_dir.join(format!("{}.json", key));
74        std::fs::write(&path, json).context("Failed to write LLM cache entry")?;
75
76        Ok(())
77    }
78
79    /// Clear all cached responses
80    pub fn clear(&self) -> Result<()> {
81        if self.cache_dir.exists() {
82            std::fs::remove_dir_all(&self.cache_dir).context("Failed to clear LLM cache")?;
83        }
84        Ok(())
85    }
86
87    /// Count cached entries
88    pub fn count(&self) -> usize {
89        if !self.cache_dir.exists() {
90            return 0;
91        }
92        std::fs::read_dir(&self.cache_dir)
93            .map(|entries| entries.filter(|e| e.is_ok()).count())
94            .unwrap_or(0)
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    #[test]
103    fn test_cache_key_determinism() {
104        let key1 = LlmCache::compute_key("snap1", "src", "context_abc");
105        let key2 = LlmCache::compute_key("snap1", "src", "context_abc");
106        assert_eq!(key1, key2);
107
108        let key3 = LlmCache::compute_key("snap1", "src", "context_different");
109        assert_ne!(key1, key3);
110    }
111
112    #[test]
113    fn test_cache_roundtrip() {
114        let dir = tempfile::tempdir().unwrap();
115        let cache = LlmCache::new(dir.path());
116
117        let key = "test_key_123";
118        assert!(cache.get(key).unwrap().is_none());
119        assert_eq!(cache.count(), 0);
120
121        cache
122            .put(key, "hash123", "This module handles authentication.")
123            .unwrap();
124        assert_eq!(cache.count(), 1);
125
126        let cached = cache.get(key).unwrap().unwrap();
127        assert_eq!(cached.response, "This module handles authentication.");
128        assert_eq!(cached.context_hash, "hash123");
129    }
130}
reflex/pulse/llm_cache.rs

reflex/pulse/
llm_cache.rs
