From 570a824780deda5a33e85ed51894120739c0dc90 Mon Sep 17 00:00:00 2001 From: "Dhanji R. Prasanna" Date: Thu, 29 Jan 2026 11:22:59 +1100 Subject: [PATCH] Rename archivist agent to huffman Named after David Huffman, inventor of Huffman coding - compression that preserves information with fewer bits. Fits the agent's purpose: compact memory, preserve semantics. --- README.md | 2 +- agents/{archivist.md => huffman.md} | 6 +- .../tests/cache_stats_integration_test.rs | 277 ++++++++++++++++++ 3 files changed, 281 insertions(+), 4 deletions(-) rename agents/{archivist.md => huffman.md} (97%) create mode 100644 crates/g3-core/tests/cache_stats_integration_test.rs diff --git a/README.md b/README.md index df3d8e8..5395e87 100644 --- a/README.md +++ b/README.md @@ -373,7 +373,7 @@ g3 comes with several embedded agents that work out of the box: | **carmack** | Code readability and craft - simplifies, refactors, improves naming | | **hopper** | Testing and quality - writes tests, finds edge cases | | **euler** | Architecture and dependencies - analyzes structure, finds coupling | -| **archivist** | Memory maintenance - compacts, deduplicates, increases signal | +| **huffman** | Memory maintenance - compacts, deduplicates, increases signal | | **lamport** | Concurrency and correctness - reviews async code, finds race conditions | | **fowler** | Refactoring patterns - applies design patterns, reduces duplication | | **breaker** | Adversarial testing - finds bugs, creates minimal repros | diff --git a/agents/archivist.md b/agents/huffman.md similarity index 97% rename from agents/archivist.md rename to agents/huffman.md index 3aaf215..518d3ae 100644 --- a/agents/archivist.md +++ b/agents/huffman.md @@ -1,6 +1,6 @@ -SYSTEM PROMPT — "Archivist" (Memory Compaction & Signal Agent) +SYSTEM PROMPT — "Huffman" (Memory Compaction & Signal Agent) -You are Archivist: a knowledge maintenance agent. +You are Huffman: a knowledge maintenance agent. Your job is to **increase signal and reduce noise** in workspace memory, without deleting semantic information. @@ -210,4 +210,4 @@ COMMIT CHANGES WHEN DONE When you're done, and have a high degree of confidence, commit your changes: - Into a single, atomic commit - The commit message should summarize: entries merged, bytes saved, concepts preserved -- NEVER override author/email; instead put "Agent: archivist" in the message body +- NEVER override author/email; instead put "Agent: huffman" in the message body diff --git a/crates/g3-core/tests/cache_stats_integration_test.rs b/crates/g3-core/tests/cache_stats_integration_test.rs new file mode 100644 index 0000000..22d21b6 --- /dev/null +++ b/crates/g3-core/tests/cache_stats_integration_test.rs @@ -0,0 +1,277 @@ +//! Integration tests for CacheStats accumulation through streaming. +//! +//! CHARACTERIZATION: These tests verify that cache statistics are correctly +//! accumulated through the streaming completion flow when the provider reports +//! cache usage data. +//! +//! What this test protects: +//! - CacheStats fields are accumulated correctly from provider usage data +//! - Cache hit detection works (cache_read_tokens > 0 means cache hit) +//! - Stats are accessible via get_stats() and include cache section +//! +//! What this test intentionally does NOT assert: +//! - Exact formatting of stats output (that's presentation layer) +//! - Provider-specific cache control headers (tested in provider tests) +//! - Internal implementation of how cache stats are stored + +use g3_core::ui_writer::NullUiWriter; +use g3_core::Agent; +use g3_providers::mock::{MockChunk, MockProvider, MockResponse}; +use g3_providers::{ProviderRegistry, Usage}; +use tempfile::TempDir; + +/// Helper to create an agent with a mock provider +async fn create_agent_with_mock(provider: MockProvider) -> (Agent, TempDir) { + let temp_dir = TempDir::new().unwrap(); + + let mut registry = ProviderRegistry::new(); + registry.register(provider); + + let config = g3_config::Config::default(); + + let agent = Agent::new_for_test( + config, + NullUiWriter, + registry, + ).await.expect("Failed to create agent"); + + (agent, temp_dir) +} + +/// Create a MockResponse with specific cache statistics +fn response_with_cache_stats( + content: &str, + prompt_tokens: u32, + completion_tokens: u32, + cache_creation_tokens: u32, + cache_read_tokens: u32, +) -> MockResponse { + MockResponse::custom( + vec![ + MockChunk::content(content), + MockChunk::finished("end_turn"), + ], + Usage { + prompt_tokens, + completion_tokens, + total_tokens: prompt_tokens + completion_tokens, + cache_creation_tokens, + cache_read_tokens, + }, + ) +} + +/// Test: Cache stats are accumulated from a single response +/// +/// Verifies that when a provider returns usage data with cache tokens, +/// those values are accumulated in the agent's CacheStats. +#[tokio::test] +async fn test_cache_stats_accumulated_from_single_response() { + // Create a response with cache creation tokens (first request, cache miss) + let provider = MockProvider::new() + .with_response(response_with_cache_stats( + "Hello! I'm here to help.", + 1000, // prompt_tokens + 50, // completion_tokens + 800, // cache_creation_tokens (cache miss, creating cache) + 0, // cache_read_tokens (no cache hit) + )); + + let (mut agent, _temp_dir) = create_agent_with_mock(provider).await; + + // Execute a task to trigger the streaming flow + let result = agent.execute_task("Hello", None, false).await; + assert!(result.is_ok(), "Task should succeed: {:?}", result.err()); + + // Get stats and verify cache section is present + let stats = agent.get_stats(); + + // Verify cache stats section exists + assert!(stats.contains("Prompt Cache Statistics"), + "Stats should contain cache section. Got:\n{}", stats); + + // Verify API calls tracked + assert!(stats.contains("API Calls:") && stats.contains("1"), + "Should show 1 API call. Got:\n{}", stats); + + // Verify cache creation tokens tracked + assert!(stats.contains("Cache Created:") && stats.contains("800"), + "Should show 800 cache creation tokens. Got:\n{}", stats); + + // Verify no cache hits (first request) + assert!(stats.contains("Cache Hits:") && stats.contains("0"), + "Should show 0 cache hits for first request. Got:\n{}", stats); +} + +/// Test: Cache hits are detected when cache_read_tokens > 0 +/// +/// Verifies that when a provider returns cache_read_tokens > 0, +/// it's counted as a cache hit. +#[tokio::test] +async fn test_cache_hit_detection() { + // Create a response with cache read tokens (cache hit) + let provider = MockProvider::new() + .with_response(response_with_cache_stats( + "Using cached context!", + 1000, // prompt_tokens + 30, // completion_tokens + 0, // cache_creation_tokens (no new cache) + 750, // cache_read_tokens (cache hit!) + )); + + let (mut agent, _temp_dir) = create_agent_with_mock(provider).await; + + let result = agent.execute_task("Hello again", None, false).await; + assert!(result.is_ok()); + + let stats = agent.get_stats(); + + // Verify cache hit was counted + assert!(stats.contains("Cache Hits:") && stats.contains("1"), + "Should show 1 cache hit. Got:\n{}", stats); + + // Verify cache read tokens tracked + assert!(stats.contains("Cache Read:") && stats.contains("750"), + "Should show 750 cache read tokens. Got:\n{}", stats); +} + +/// Test: Cache stats accumulate across multiple requests +/// +/// Verifies that cache statistics are accumulated correctly across +/// multiple streaming completions. +#[tokio::test] +async fn test_cache_stats_accumulate_across_requests() { + // First request: cache miss, creates cache + // Second request: cache hit, reads from cache + // Third request: partial cache hit + let provider = MockProvider::new() + .with_responses(vec![ + response_with_cache_stats("First response", 1000, 50, 800, 0), + response_with_cache_stats("Second response", 1200, 40, 0, 800), + response_with_cache_stats("Third response", 1500, 60, 200, 600), + ]); + + let (mut agent, _temp_dir) = create_agent_with_mock(provider).await; + + // Execute three tasks + agent.execute_task("First question", None, false).await.unwrap(); + agent.execute_task("Second question", None, false).await.unwrap(); + agent.execute_task("Third question", None, false).await.unwrap(); + + let stats = agent.get_stats(); + + // Verify total API calls + assert!(stats.contains("API Calls:") && stats.contains("3"), + "Should show 3 API calls. Got:\n{}", stats); + + // Verify cache hits (requests 2 and 3 had cache_read_tokens > 0) + assert!(stats.contains("Cache Hits:") && stats.contains("2"), + "Should show 2 cache hits. Got:\n{}", stats); + + // Verify total cache creation: 800 + 0 + 200 = 1000 + assert!(stats.contains("Cache Created:") && stats.contains("1000"), + "Should show 1000 total cache creation tokens. Got:\n{}", stats); + + // Verify total cache read: 0 + 800 + 600 = 1400 + assert!(stats.contains("Cache Read:") && stats.contains("1400"), + "Should show 1400 total cache read tokens. Got:\n{}", stats); + + // Verify total input tokens: 1000 + 1200 + 1500 = 3700 + assert!(stats.contains("Total Input Tokens:") && stats.contains("3700"), + "Should show 3700 total input tokens. Got:\n{}", stats); +} + +/// Test: Cache efficiency percentage is calculated correctly +/// +/// Verifies that the cache efficiency metric (% of input from cache) +/// is displayed in the stats output. +#[tokio::test] +async fn test_cache_efficiency_displayed() { + // Create a response where 50% of input comes from cache + let provider = MockProvider::new() + .with_response(response_with_cache_stats( + "Efficient response", + 1000, // prompt_tokens (total input) + 50, // completion_tokens + 0, // cache_creation_tokens + 500, // cache_read_tokens (50% of input) + )); + + let (mut agent, _temp_dir) = create_agent_with_mock(provider).await; + + agent.execute_task("Test efficiency", None, false).await.unwrap(); + + let stats = agent.get_stats(); + + // Verify cache efficiency is displayed + assert!(stats.contains("Cache Efficiency:"), + "Should show cache efficiency. Got:\n{}", stats); + + // Verify it shows 50% (500/1000) + assert!(stats.contains("50.0%"), + "Should show 50.0% cache efficiency. Got:\n{}", stats); +} + +/// Test: Zero cache stats are handled gracefully +/// +/// Verifies that when no cache tokens are reported, the stats +/// still display correctly without errors. +#[tokio::test] +async fn test_zero_cache_stats_handled() { + // Response with no cache tokens at all + let provider = MockProvider::new() + .with_response(response_with_cache_stats( + "No cache used", + 500, // prompt_tokens + 25, // completion_tokens + 0, // cache_creation_tokens + 0, // cache_read_tokens + )); + + let (mut agent, _temp_dir) = create_agent_with_mock(provider).await; + + agent.execute_task("Test no cache", None, false).await.unwrap(); + + let stats = agent.get_stats(); + + // Should still have cache section + assert!(stats.contains("Prompt Cache Statistics"), + "Should contain cache section even with zero stats. Got:\n{}", stats); + + // Should show 0 cache hits + assert!(stats.contains("Cache Hits:") && stats.contains("0"), + "Should show 0 cache hits. Got:\n{}", stats); + + // Should show 0% efficiency (or handle division by zero gracefully) + assert!(stats.contains("Cache Efficiency:"), + "Should show cache efficiency even when 0. Got:\n{}", stats); +} + +/// Test: Hit rate percentage is calculated correctly +/// +/// Verifies that the hit rate (cache_hit_calls / total_calls) is +/// displayed correctly. +#[tokio::test] +async fn test_hit_rate_calculation() { + // 2 cache hits out of 4 calls = 50% hit rate + let provider = MockProvider::new() + .with_responses(vec![ + response_with_cache_stats("Miss 1", 1000, 50, 500, 0), // miss + response_with_cache_stats("Hit 1", 1000, 50, 0, 500), // hit + response_with_cache_stats("Miss 2", 1000, 50, 200, 0), // miss + response_with_cache_stats("Hit 2", 1000, 50, 0, 800), // hit + ]); + + let (mut agent, _temp_dir) = create_agent_with_mock(provider).await; + + agent.execute_task("Q1", None, false).await.unwrap(); + agent.execute_task("Q2", None, false).await.unwrap(); + agent.execute_task("Q3", None, false).await.unwrap(); + agent.execute_task("Q4", None, false).await.unwrap(); + + let stats = agent.get_stats(); + + // Verify hit rate is 50% + assert!(stats.contains("Hit Rate:") && stats.contains("50.0%"), + "Should show 50.0% hit rate. Got:\n{}", stats); +}