manual_slop/conductor/tracks/cache_analytics_20260306/plan.md

Implementation Plan: Cache Analytics Display (cache_analytics_20260306)

Reference: Spec | Architecture Guide

Phase 1: Verify Existing Infrastructure

Focus: Confirm ai_client.get_gemini_cache_stats() works

• Task 1.1: Initialize MMA Environment (skipped - already in context)
• Task 1.2: Verify get_gemini_cache_stats() - Function exists in ai_client.py

Phase 2: Panel Implementation

Focus: Create cache panel in GUI

• Task 2.1: Add cache panel state (if needed)

  • WHERE: src/gui_2.py App.__init__
  • WHAT: Minimal state for display
  • HOW: Likely none needed - read directly from ai_client

• Task 2.2: Create _render_cache_panel() method

  • WHERE: src/gui_2.py after other render methods
  • WHAT: Display cache statistics
  • HOW:

    def _render_cache_panel(self) -> None:
     if self.current_provider != "gemini":
      return
     if not imgui.collapsing_header("Cache Analytics"):
      return
     stats = ai_client.get_gemini_cache_stats()
     if not stats.get("cache_exists"):
      imgui.text("No active cache")
      return
     imgui.text(f"Age: {self._format_age(stats.get('cache_age_seconds', 0))}")
     imgui.text(f"TTL: {stats.get('ttl_remaining', 0):.0f}s remaining")
     # Progress bar for TTL
     ttl_pct = stats.get('ttl_remaining', 0) / stats.get('ttl_seconds', 3600)
     imgui.progress_bar(ttl_pct)
    

• Task 2.3: Add helper for age formatting

  • WHERE: src/gui_2.py
  • HOW:

    def _format_age(self, seconds: float) -> str:
     if seconds < 60:
      return f"{seconds:.0f}s"
     elif seconds < 3600:
      return f"{seconds/60:.0f}m {seconds%60:.0f}s"
     else:
      return f"{seconds/3600:.0f}h {(seconds%3600)/60:.0f}m"
    

Phase 3: Manual Controls

Focus: Add cache clear button

• Task 3.1: Add clear cache button
  • WHERE: src/gui_2.py _render_cache_panel()
  • HOW:

    if imgui.button("Clear Cache"):
     ai_client.cleanup()
     self._cache_cleared = True
    if getattr(self, '_cache_cleared', False):
     imgui.text_colored(vec4(100, 255, 100, 255), "Cache cleared - will rebuild on next request")
    

Phase 4: Integration

Focus: Add panel to main GUI

• Task 4.1: Integrate panel into layout
  • WHERE: src/gui_2.py _gui_func()
  • WHAT: Call _render_cache_panel() in settings or token budget area

Phase 5: Testing

• Task 5.1: Write unit tests
• Task 5.2: Conductor - Phase Verification