@llm-dev-ops/agentics-cli 1.4.27 → 1.4.29

package/dist/bundled-agents/memory-graph-agents/src/storage/cache.rs

@@ -1,288 +0,0 @@
-//! High-performance caching layer for storage operations
-//!
-//! This module provides an async-safe, thread-safe caching layer using moka
-//! to dramatically reduce read latency for frequently accessed nodes and edges.
-
-use crate::types::{Edge, EdgeId, Node, NodeId};
-use moka::future::Cache;
-use std::time::Duration;
-
-/// Multi-level cache for nodes and edges
-///
-/// Provides LRU-based caching with automatic eviction and TTL support.
-/// All operations are async and thread-safe.
-#[derive(Clone)]
-pub struct StorageCache {
-    /// Cache for node lookups by ID
-    node_cache: Cache<NodeId, Node>,
-    /// Cache for edge lookups by ID
-    edge_cache: Cache<EdgeId, Edge>,
-}
-
-impl StorageCache {
-    /// Create a new storage cache with default settings
-    ///
-    /// Default configuration:
-    /// - Node cache: 10,000 entries
-    /// - Edge cache: 50,000 entries
-    /// - TTL: 5 minutes
-    pub fn new() -> Self {
-        Self::with_capacity(10_000, 50_000)
-    }
-
-    /// Create a cache with custom capacities
-    pub fn with_capacity(node_capacity: u64, edge_capacity: u64) -> Self {
-        let node_cache = Cache::builder()
-            .max_capacity(node_capacity)
-            .time_to_live(Duration::from_secs(300)) // 5 minutes
-            .build();
-
-        let edge_cache = Cache::builder()
-            .max_capacity(edge_capacity)
-            .time_to_live(Duration::from_secs(300))
-            .build();
-
-        Self {
-            node_cache,
-            edge_cache,
-        }
-    }
-
-    /// Create a cache with custom TTL
-    pub fn with_ttl(ttl_secs: u64) -> Self {
-        let node_cache = Cache::builder()
-            .max_capacity(10_000)
-            .time_to_live(Duration::from_secs(ttl_secs))
-            .build();
-
-        let edge_cache = Cache::builder()
-            .max_capacity(50_000)
-            .time_to_live(Duration::from_secs(ttl_secs))
-            .build();
-
-        Self {
-            node_cache,
-            edge_cache,
-        }
-    }
-
-    /// Get a node from cache
-    pub async fn get_node(&self, id: &NodeId) -> Option<Node> {
-        self.node_cache.get(id).await
-    }
-
-    /// Insert a node into cache
-    pub async fn insert_node(&self, id: NodeId, node: Node) {
-        self.node_cache.insert(id, node).await;
-    }
-
-    /// Remove a node from cache
-    pub async fn invalidate_node(&self, id: &NodeId) {
-        self.node_cache.invalidate(id).await;
-    }
-
-    /// Get an edge from cache
-    pub async fn get_edge(&self, id: &EdgeId) -> Option<Edge> {
-        self.edge_cache.get(id).await
-    }
-
-    /// Insert an edge into cache
-    pub async fn insert_edge(&self, id: EdgeId, edge: Edge) {
-        self.edge_cache.insert(id, edge).await;
-    }
-
-    /// Remove an edge from cache
-    pub async fn invalidate_edge(&self, id: &EdgeId) {
-        self.edge_cache.invalidate(id).await;
-    }
-
-    /// Get cache statistics
-    ///
-    /// Returns current cache sizes. Note that hit/miss rates are not tracked
-    /// by default in moka cache to minimize performance overhead.
-    pub async fn stats(&self) -> CacheStats {
-        // Sync pending tasks to get accurate counts
-        self.node_cache.run_pending_tasks().await;
-        self.edge_cache.run_pending_tasks().await;
-
-        CacheStats {
-            node_cache_size: self.node_cache.entry_count(),
-            edge_cache_size: self.edge_cache.entry_count(),
-            node_cache_hits: 0, // Hit tracking not enabled by default
-            node_cache_misses: 0,
-            edge_cache_hits: 0,
-            edge_cache_misses: 0,
-        }
-    }
-
-    /// Clear all caches
-    pub fn clear(&self) {
-        self.node_cache.invalidate_all();
-        self.edge_cache.invalidate_all();
-    }
-}
-
-impl Default for StorageCache {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-/// Cache statistics
-#[derive(Debug, Clone)]
-pub struct CacheStats {
-    /// Number of nodes in cache
-    pub node_cache_size: u64,
-    /// Number of edges in cache
-    pub edge_cache_size: u64,
-    /// Node cache hits
-    pub node_cache_hits: u64,
-    /// Node cache misses
-    pub node_cache_misses: u64,
-    /// Edge cache hits
-    pub edge_cache_hits: u64,
-    /// Edge cache misses
-    pub edge_cache_misses: u64,
-}
-
-impl CacheStats {
-    /// Calculate node cache hit rate
-    pub fn node_hit_rate(&self) -> f64 {
-        let total = self.node_cache_hits + self.node_cache_misses;
-        if total == 0 {
-            0.0
-        } else {
-            self.node_cache_hits as f64 / total as f64
-        }
-    }
-
-    /// Calculate edge cache hit rate
-    pub fn edge_hit_rate(&self) -> f64 {
-        let total = self.edge_cache_hits + self.edge_cache_misses;
-        if total == 0 {
-            0.0
-        } else {
-            self.edge_cache_hits as f64 / total as f64
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::types::{ConversationSession, PromptNode, SessionId};
-
-    #[tokio::test]
-    async fn test_cache_creation() {
-        let cache = StorageCache::new();
-        let stats = cache.stats().await;
-
-        assert_eq!(stats.node_cache_size, 0);
-        assert_eq!(stats.edge_cache_size, 0);
-    }
-
-    #[tokio::test]
-    async fn test_node_cache() {
-        let cache = StorageCache::new();
-
-        let session = ConversationSession::new();
-        let node = Node::Session(session.clone());
-        let node_id = node.id();
-
-        // Cache miss initially
-        assert!(cache.get_node(&node_id).await.is_none());
-
-        // Insert into cache
-        cache.insert_node(node_id, node.clone()).await;
-
-        // Cache hit
-        let cached = cache.get_node(&node_id).await;
-        assert!(cached.is_some());
-        assert_eq!(cached.unwrap().id(), node_id);
-    }
-
-    #[tokio::test]
-    async fn test_node_cache_invalidation() {
-        let cache = StorageCache::new();
-
-        let session = ConversationSession::new();
-        let node = Node::Session(session);
-        let node_id = node.id();
-
-        cache.insert_node(node_id, node).await;
-        assert!(cache.get_node(&node_id).await.is_some());
-
-        cache.invalidate_node(&node_id).await;
-        // Give cache time to process invalidation
-        tokio::time::sleep(tokio::time::Duration::from_millis(10)).await;
-
-        // Note: Moka might still return the value briefly after invalidation
-        // This is expected behavior for async caches
-    }
-
-    #[tokio::test]
-    async fn test_cache_stats() {
-        let cache = StorageCache::new();
-
-        let session = ConversationSession::new();
-        let node = Node::Session(session);
-        let node_id = node.id();
-
-        // Miss - no entry yet
-        let result = cache.get_node(&node_id).await;
-        assert!(result.is_none());
-
-        // Insert
-        cache.insert_node(node_id, node.clone()).await;
-
-        // Hit - entry should be present
-        let result = cache.get_node(&node_id).await;
-        assert!(result.is_some());
-
-        // stats() now syncs pending tasks before returning
-        let stats = cache.stats().await;
-        assert_eq!(stats.node_cache_size, 1);
-        // Note: Hit/miss tracking not enabled by default in moka for performance
-    }
-
-    #[tokio::test]
-    async fn test_custom_capacity() {
-        let cache = StorageCache::with_capacity(100, 200);
-        let stats = cache.stats().await;
-
-        // Cache should be empty initially
-        assert_eq!(stats.node_cache_size, 0);
-    }
-
-    #[tokio::test]
-    async fn test_concurrent_cache_access() {
-        let cache = StorageCache::new();
-        let cache_clone1 = cache.clone();
-        let cache_clone2 = cache.clone();
-
-        let session_id = SessionId::new();
-
-        let handle1 = tokio::spawn(async move {
-            for i in 0..50 {
-                let prompt = PromptNode::new(session_id, format!("Prompt {}", i));
-                let node = Node::Prompt(prompt.clone());
-                cache_clone1.insert_node(prompt.id, node).await;
-            }
-        });
-
-        let handle2 = tokio::spawn(async move {
-            for i in 50..100 {
-                let prompt = PromptNode::new(session_id, format!("Prompt {}", i));
-                let node = Node::Prompt(prompt.clone());
-                cache_clone2.insert_node(prompt.id, node).await;
-            }
-        });
-
-        handle1.await.unwrap();
-        handle2.await.unwrap();
-
-        // stats() will sync pending tasks before returning counts
-        let stats = cache.stats().await;
-        assert_eq!(stats.node_cache_size, 100);
-    }
-}

package/dist/bundled-agents/memory-graph-agents/src/storage/mod.rs

@@ -1,202 +0,0 @@
-//! Storage backend for persisting graph data
-
-mod async_sled_backend;
-mod cache;
-mod pooled_backend;
-mod serialization;
-mod sled_backend;
-
-pub use async_sled_backend::AsyncSledBackend;
-pub use cache::{CacheStats, StorageCache};
-pub use pooled_backend::{PoolConfig, PoolMetrics, PoolMetricsSnapshot, PooledAsyncBackend};
-pub use serialization::{SerializationFormat, Serializer};
-pub use sled_backend::SledBackend;
-
-use crate::error::Result;
-use crate::types::{Edge, EdgeId, Node, NodeId, SessionId};
-use async_trait::async_trait;
-
-/// Trait defining storage backend operations
-pub trait StorageBackend: Send + Sync {
-    /// Store a node in the backend
-    fn store_node(&self, node: &Node) -> Result<()>;
-
-    /// Retrieve a node by ID
-    fn get_node(&self, id: &NodeId) -> Result<Option<Node>>;
-
-    /// Delete a node
-    fn delete_node(&self, id: &NodeId) -> Result<()>;
-
-    /// Store an edge
-    fn store_edge(&self, edge: &Edge) -> Result<()>;
-
-    /// Retrieve an edge by ID
-    fn get_edge(&self, id: &EdgeId) -> Result<Option<Edge>>;
-
-    /// Delete an edge
-    fn delete_edge(&self, id: &EdgeId) -> Result<()>;
-
-    /// Get all nodes in a session
-    fn get_session_nodes(&self, session_id: &SessionId) -> Result<Vec<Node>>;
-
-    /// Get all edges from a node
-    fn get_outgoing_edges(&self, node_id: &NodeId) -> Result<Vec<Edge>>;
-
-    /// Get all edges to a node
-    fn get_incoming_edges(&self, node_id: &NodeId) -> Result<Vec<Edge>>;
-
-    /// Flush any pending writes
-    fn flush(&self) -> Result<()>;
-
-    /// Get storage statistics
-    fn stats(&self) -> Result<StorageStats>;
-}
-
-/// Statistics about storage usage
-#[derive(Debug, Clone)]
-pub struct StorageStats {
-    /// Total number of nodes
-    pub node_count: u64,
-    /// Total number of edges
-    pub edge_count: u64,
-    /// Total storage size in bytes
-    pub storage_bytes: u64,
-    /// Number of sessions
-    pub session_count: u64,
-}
-
-/// Async trait defining storage backend operations
-///
-/// This trait provides async versions of all storage operations for use with Tokio runtime.
-/// It enables high-performance concurrent operations and non-blocking I/O.
-#[async_trait]
-pub trait AsyncStorageBackend: Send + Sync {
-    /// Store a node in the backend asynchronously
-    async fn store_node(&self, node: &Node) -> Result<()>;
-
-    /// Retrieve a node by ID asynchronously
-    async fn get_node(&self, id: &NodeId) -> Result<Option<Node>>;
-
-    /// Delete a node asynchronously
-    async fn delete_node(&self, id: &NodeId) -> Result<()>;
-
-    /// Store an edge asynchronously
-    async fn store_edge(&self, edge: &Edge) -> Result<()>;
-
-    /// Retrieve an edge by ID asynchronously
-    async fn get_edge(&self, id: &EdgeId) -> Result<Option<Edge>>;
-
-    /// Delete an edge asynchronously
-    async fn delete_edge(&self, id: &EdgeId) -> Result<()>;
-
-    /// Get all nodes in a session asynchronously
-    async fn get_session_nodes(&self, session_id: &SessionId) -> Result<Vec<Node>>;
-
-    /// Get all edges from a node asynchronously
-    async fn get_outgoing_edges(&self, node_id: &NodeId) -> Result<Vec<Edge>>;
-
-    /// Get all edges to a node asynchronously
-    async fn get_incoming_edges(&self, node_id: &NodeId) -> Result<Vec<Edge>>;
-
-    /// Flush any pending writes asynchronously
-    async fn flush(&self) -> Result<()>;
-
-    /// Get storage statistics asynchronously
-    async fn stats(&self) -> Result<StorageStats>;
-
-    /// Batch store multiple nodes asynchronously for improved performance
-    async fn store_nodes_batch(&self, nodes: &[Node]) -> Result<Vec<NodeId>> {
-        let mut ids = Vec::with_capacity(nodes.len());
-        for node in nodes {
-            self.store_node(node).await?;
-            ids.push(node.id());
-        }
-        Ok(ids)
-    }
-
-    /// Batch store multiple edges asynchronously for improved performance
-    async fn store_edges_batch(&self, edges: &[Edge]) -> Result<Vec<EdgeId>> {
-        let mut ids = Vec::with_capacity(edges.len());
-        for edge in edges {
-            self.store_edge(edge).await?;
-            ids.push(edge.id);
-        }
-        Ok(ids)
-    }
-
-    /// Stream nodes from a session for memory-efficient iteration over large result sets
-    ///
-    /// This method returns a stream that yields nodes one at a time, avoiding the need
-    /// to load all nodes into memory at once. This is particularly useful for sessions
-    /// with thousands of nodes.
-    ///
-    /// # Examples
-    ///
-    /// ```no_run
-    /// use llm_memory_graph::storage::AsyncSledBackend;
-    /// use llm_memory_graph::storage::AsyncStorageBackend;
-    /// use llm_memory_graph::types::SessionId;
-    /// use futures::stream::StreamExt;
-    ///
-    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// let backend = AsyncSledBackend::open("./data/graph.db").await?;
-    /// let session_id = SessionId::new();
-    ///
-    /// let mut stream = backend.get_session_nodes_stream(&session_id);
-    /// let mut count = 0;
-    /// while let Some(node) = stream.next().await {
-    ///     let node = node?;
-    ///     // Process node without loading all into memory
-    ///     count += 1;
-    /// }
-    /// println!("Processed {} nodes", count);
-    /// # Ok(())
-    /// # }
-    /// ```
-    fn get_session_nodes_stream(
-        &self,
-        session_id: &SessionId,
-    ) -> std::pin::Pin<Box<dyn futures::stream::Stream<Item = Result<Node>> + Send + '_>> {
-        // Default implementation: load all and convert to stream
-        // Backends should override for true streaming from storage
-        let session_id = *session_id;
-        Box::pin(async_stream::stream! {
-            match self.get_session_nodes(&session_id).await {
-                Ok(nodes) => {
-                    for node in nodes {
-                        yield Ok(node);
-                    }
-                }
-                Err(e) => yield Err(e),
-            }
-        })
-    }
-
-    /// Count nodes in a session without loading them into memory
-    ///
-    /// This is more efficient than `get_session_nodes().await?.len()` for large sessions
-    /// as it only counts without deserializing node data.
-    ///
-    /// # Examples
-    ///
-    /// ```no_run
-    /// use llm_memory_graph::storage::AsyncSledBackend;
-    /// use llm_memory_graph::storage::AsyncStorageBackend;
-    /// use llm_memory_graph::types::SessionId;
-    ///
-    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// let backend = AsyncSledBackend::open("./data/graph.db").await?;
-    /// let session_id = SessionId::new();
-    ///
-    /// let count = backend.count_session_nodes(&session_id).await?;
-    /// println!("Session has {} nodes", count);
-    /// # Ok(())
-    /// # }
-    /// ```
-    async fn count_session_nodes(&self, session_id: &SessionId) -> Result<usize> {
-        // Default implementation: load and count
-        // Backends should override for O(1) counting if possible
-        let nodes = self.get_session_nodes(session_id).await?;
-        Ok(nodes.len())
-    }
-}