manual_slop/conductor/tracks/cache_analytics_20260306/plan.md

Implementation Plan: Cache Analytics Display (cache_analytics_20260306)

Reference: Spec | Architecture Guide

Phase 1: Foundation & Research

Focus: Verify existing infrastructure and set up panel structure

• Task 1.1: Initialize MMA Environment

  • Run activate_skill mma-orchestrator before starting

• Task 1.2: Verify ai_client.get_gemini_cache_stats()

  • WHERE: src/ai_client.py lines ~200-230
  • WHAT: Confirm function exists and returns expected dict structure
  • HOW: Use manual-slop_py_get_definition on get_gemini_cache_stats
  • OUTPUT: Document exact return dict structure in task notes

• Task 1.3: Verify ai_client.cleanup()

  • WHERE: src/ai_client.py line ~220
  • WHAT: Confirm function clears _gemini_cache
  • HOW: Use manual-slop_py_get_definition on cleanup
  • SAFETY: Note that cleanup() also clears other resources - document side effects

Phase 2: Panel Implementation

Focus: Create the GUI panel structure

• Task 2.1: Add cache panel state variables

  • WHERE: src/gui_2.py in App.__init__ (around line 170)
  • WHAT: Add minimal state if needed (likely none - read directly from ai_client)
  • HOW: Follow existing state initialization pattern
  • CODE STYLE: 1-space indentation
  • SAFETY: No locks needed - read-only access to ai_client globals

• Task 2.2: Create _render_cache_panel() method

  • WHERE: src/gui_2.py after other _render_*_panel() methods
  • WHAT: New method that displays 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()
     # Render stats...
    

  • CODE STYLE: 1-space indentation, NO COMMENTS

• Task 2.3: Integrate panel into main GUI

  • WHERE: src/gui_2.py in _gui_func() method
  • WHAT: Call _render_cache_panel() in appropriate location
  • HOW: Add near token budget panel or in settings area
  • SAFETY: Ensure not called during modal dialogs

Phase 3: Statistics Display

Focus: Implement the visual statistics rendering

• Task 3.1: Implement cache status display

  • WHERE: src/gui_2.py in _render_cache_panel()
  • WHAT: Show cache existence and age
  • HOW:
    • imgui.text(f"Cache Active: {stats['cache_exists']}")
    • imgui.text(f"Age: {format_age(stats['cache_age_seconds'])}")
  • HELPER: Create format_age(seconds: float) -> str helper
  • CODE STYLE: 1-space indentation

• Task 3.2: Implement TTL countdown display

  • WHERE: src/gui_2.py in _render_cache_panel()
  • WHAT: Show remaining TTL with percentage
  • HOW:
    • remaining = stats['ttl_remaining']
    • percentage = (remaining / stats['ttl_seconds']) * 100
    • Use imgui.progress_bar() for visual
  • VISUAL: Warning color when percentage < 20% (use vec4 colors defined at top of file)

• Task 3.3: Implement requests counter (optional enhancement)

  • WHERE: src/gui_2.py in _render_cache_panel()
  • WHAT: Show estimated "requests while cache active"
  • HOW: Add self._cache_request_count: int = 0 state, increment on send
  • SAFETY: This requires hooking into send flow - may skip if complex

Phase 4: Manual Controls

Focus: Implement the cache clear functionality

• Task 4.1: Add clear cache button

  • WHERE: src/gui_2.py in _render_cache_panel()
  • WHAT: Button that clears the Gemini cache
  • HOW:

    if imgui.button("Clear Cache"):
     ai_client.cleanup()
     # Optionally set a flag to show "Cache cleared" message
    

  • SAFETY: cleanup() clears ALL caches, not just Gemini - document this

• Task 4.2: Add clear confirmation/feedback

  • WHERE: src/gui_2.py in _render_cache_panel()
  • WHAT: Show feedback after clear
  • HOW: Add self._cache_just_cleared: bool = False flag, show message, auto-clear after 3s
  • CODE STYLE: 1-space indentation

Phase 5: Testing

Focus: Verify all functionality works correctly

• Task 5.1: Write unit tests for cache panel

  • WHERE: tests/test_cache_panel.py (new file)
  • WHAT: Test panel visibility, stats display, clear button
  • HOW: Use mock_app or app_instance fixture from conftest.py
  • PATTERN: Follow test_gui_phase4.py as reference
  • CODE STYLE: 1-space indentation

• Task 5.2: Write integration test with live_gui

  • WHERE: tests/test_cache_panel.py
  • WHAT: Test with actual Gemini provider (or mock)
  • HOW: Use live_gui fixture, set provider to 'gemini', verify panel shows
  • ARTIFACTS: Write to tests/artifacts/

• Task 5.3: Conductor - Phase Verification

  • Run targeted tests: uv run pytest tests/test_cache_panel.py -v
  • Verify no lint errors in modified files
  • Manual visual verification in GUI

Implementation Notes

Thread Safety Analysis

• ai_client.get_gemini_cache_stats() reads _gemini_cache and _gemini_cache_created_at
• These are set on the asyncio worker thread during _send_gemini()
• Reading from GUI thread is safe (atomic types) but values may be slightly stale
• No locks required for display purposes

Code Style Checklist

• 1-space indentation throughout
• CRLF line endings on Windows
• No comments unless explicitly documenting complex logic
• Type hints on all new functions
• Follow existing vec4 color naming pattern

Files Modified

• src/gui_2.py: Add _render_cache_panel(), integrate into _gui_func()
• tests/test_cache_panel.py: New test file

Dependencies

• Existing: src/ai_client.py::get_gemini_cache_stats()
• Existing: src/ai_client.py::cleanup()
• Existing: imgui_bundle::imgui