refinement of upcoming tracks
This commit is contained in:
@@ -1,29 +1,144 @@
|
||||
# Implementation Plan: Cache Analytics Display (cache_analytics_20260306)
|
||||
|
||||
## Phase 1: Cache Stats Integration
|
||||
- [ ] Task: Initialize MMA Environment
|
||||
- [ ] Task: Verify get_gemini_cache_stats
|
||||
- WHERE: src/ai_client.py
|
||||
- WHAT: Check existing function
|
||||
- HOW: Review implementation
|
||||
> **Reference:** [Spec](./spec.md) | [Architecture Guide](../../../docs/guide_architecture.md)
|
||||
|
||||
## 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
|
||||
- [ ] Task: Create cache panel
|
||||
- WHERE: src/gui_2.py
|
||||
- WHAT: Display cache stats
|
||||
- HOW: imgui widgets
|
||||
- SAFETY: Handle no cache
|
||||
Focus: Create the GUI panel structure
|
||||
|
||||
## Phase 3: TTL & Controls
|
||||
- [ ] Task: Display TTL countdown
|
||||
- WHERE: src/gui_2.py
|
||||
- WHAT: Time until cache rebuild
|
||||
- HOW: Calculate from cache_created_at
|
||||
- [ ] Task: Add clear button
|
||||
- WHERE: src/gui_2.py
|
||||
- WHAT: Manual cache clear
|
||||
- HOW: Call ai_client.cleanup()
|
||||
- [ ] 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
|
||||
|
||||
## Phase 4: Verification
|
||||
- [ ] Task: Test cache display
|
||||
- [ ] Task: Conductor - Phase Verification
|
||||
- [ ] 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:
|
||||
```python
|
||||
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:
|
||||
```python
|
||||
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`
|
||||
|
||||
Reference in New Issue
Block a user