archiving tracks

2026-03-08 13:29:53 -04:00
parent b44c0f42cd
commit 66338b3ba0
83 changed files with 0 additions and 0 deletions
--- a/conductor/archive/cache_analytics_20260306/index.md
+++ b/conductor/archive/cache_analytics_20260306/index.md
@@ -0,0 +1,9 @@
+# Cache Analytics Display
+
+**Track ID:** cache_analytics_20260306
+
+**Status:** Planned
+
+**See Also:**
+- [Spec](./spec.md)
+- [Plan](./plan.md)
--- a/conductor/archive/cache_analytics_20260306/metadata.json
+++ b/conductor/archive/cache_analytics_20260306/metadata.json
@@ -0,0 +1,9 @@
+{
+  "id": "cache_analytics_20260306",
+  "name": "Cache Analytics Display",
+  "status": "planned",
+  "created_at": "2026-03-06T00:00:00Z",
+  "updated_at": "2026-03-06T00:00:00Z",
+  "type": "feature",
+  "priority": "medium"
+}
--- a/conductor/archive/cache_analytics_20260306/plan.md
+++ b/conductor/archive/cache_analytics_20260306/plan.md
@@ -0,0 +1,76 @@
+# Implementation Plan: Cache Analytics Display (cache_analytics_20260306)
+
+> **Reference:** [Spec](./spec.md) | [Architecture Guide](../../../docs/guide_architecture.md)
+
+## Phase 1: Verify Existing Infrastructure
+Focus: Confirm ai_client.get_gemini_cache_stats() works
+
+- [x] Task 1.1: Initialize MMA Environment (skipped - already in context)
+- [x] 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:
+      ```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()
+       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:
+      ```python
+      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:
+      ```python
+      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
--- a/conductor/archive/cache_analytics_20260306/spec.md
+++ b/conductor/archive/cache_analytics_20260306/spec.md
@@ -0,0 +1,118 @@
+# Track Specification: Cache Analytics Display (cache_analytics_20260306)
+
+## Overview
+Gemini cache hit/miss visualization, memory usage, TTL status display. Uses existing `ai_client.get_gemini_cache_stats()` which is implemented but has no GUI representation.
+
+## Current State Audit
+
+### Already Implemented (DO NOT re-implement)
+- **`ai_client.get_gemini_cache_stats()`** (src/ai_client.py) - Returns dict with:
+  - `cache_exists`: bool - Whether a Gemini cache is active
+  - `cache_age_seconds`: float - Age of current cache in seconds
+  - `ttl_seconds`: int - Cache TTL (default 3600)
+  - `ttl_remaining`: float - Seconds until cache expires
+  - `created_at`: float - Unix timestamp of cache creation
+- **Gemini cache variables** (src/ai_client.py lines ~60-70):
+  - `_gemini_cache`: The `CachedContent` object or None
+  - `_gemini_cache_created_at`: float timestamp when cache was created
+  - `_GEMINI_CACHE_TTL`: int = 3600 (1 hour default)
+- **Cache invalidation logic** already handles 90% TTL proactive renewal
+
+### Gaps to Fill (This Track's Scope)
+- No GUI panel to display cache statistics
+- No visual indicator of cache health/TTL
+- No manual cache clear button in UI
+- No hit/miss tracking (Gemini API doesn't expose this directly - may need approximation)
+
+## Architectural Constraints
+
+### Threading & State Access
+- **Non-Blocking**: Cache queries MUST NOT block the UI thread. The `get_gemini_cache_stats()` function reads module-level globals (`_gemini_cache`, `_gemini_cache_created_at`) which are modified on the asyncio worker thread during `_send_gemini()`.
+- **No Lock Needed**: These are atomic reads (bool/float/int), but be aware they may be stale by render time. This is acceptable for display purposes.
+- **Cross-Thread Pattern**: Use `manual-slop_get_git_diff` to understand how other read-only stats are accessed in `gui_2.py` (e.g., `ai_client.get_comms_log()`).
+
+### GUI Integration
+- **Location**: Add to `_render_token_budget_panel()` in `gui_2.py` or create new `_render_cache_panel()` method.
+- **ImGui Pattern**: Use `imgui.collapsing_header("Cache Analytics")` to allow collapsing.
+- **Code Style**: 1-space indentation, no comments unless requested.
+
+### Performance
+- **Polling vs Pushing**: Cache stats are cheap to compute (just float math). Safe to recompute each frame when panel is open.
+- **No Event Needed**: Unlike MMA state, cache stats don't need event-driven updates.
+
+## Architecture Reference
+
+Consult these docs for implementation patterns:
+- **[docs/guide_architecture.md](../../../docs/guide_architecture.md)**: Thread domains, cross-thread patterns
+- **[docs/guide_tools.md](../../../docs/guide_tools.md)**: Hook API if exposing cache stats via API
+
+### Key Integration Points
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/ai_client.py` | ~200-230 | `get_gemini_cache_stats()` function |
+| `src/ai_client.py` | ~60-70 | Cache globals (`_gemini_cache`, `_GEMINI_CACHE_TTL`) |
+| `src/ai_client.py` | ~220 | `cleanup()` function for manual cache clear |
+| `src/gui_2.py` | ~1800-1900 | `_render_token_budget_panel()` - potential location |
+| `src/gui_2.py` | ~150-200 | `App.__init__` state initialization pattern |
+
+## Functional Requirements
+
+### FR1: Cache Status Display
+- Display whether a Gemini cache is currently active (`cache_exists` bool)
+- Show cache age in human-readable format (e.g., "45m 23s old")
+- Only show panel when `current_provider == "gemini"`
+
+### FR2: TTL Countdown
+- Display remaining TTL in seconds and as percentage (e.g., "15:23 remaining (42%)")
+- Visual indicator when TTL is below 20% (warning color)
+- Note: Cache auto-rebuilds at 90% TTL, so this shows time until rebuild trigger
+
+### FR3: Manual Clear Button
+- Button to manually clear cache via `ai_client.cleanup()`
+- Button should have confirmation or be clearly labeled as destructive
+- After clear, display "Cache cleared - will rebuild on next request"
+
+### FR4: Hit/Miss Estimation (Optional Enhancement)
+- Since Gemini API doesn't expose actual hit/miss counts, estimate by:
+  - Counting number of `send()` calls while cache exists
+  - Display as "Cache active for N requests"
+
+## Non-Functional Requirements
+
+| Requirement | Constraint |
+|-------------|------------|
+| Frame Time Impact | <1ms when panel visible |
+| Memory Overhead | <1KB for display state |
+| Thread Safety | Read-only access to ai_client globals |
+
+## Testing Requirements
+
+### Unit Tests
+- Test panel renders without error when provider is Gemini
+- Test panel is hidden when provider is not Gemini
+- Test clear button calls `ai_client.cleanup()`
+
+### Integration Tests (via `live_gui` fixture)
+- Verify cache stats display after actual Gemini API call
+- Verify TTL countdown decrements over time
+
+### Structural Testing Contract
+- **NO mocking** of `ai_client` internals - use real state
+- Test artifacts go to `tests/artifacts/`
+
+## Out of Scope
+- Anthropic prompt caching display (different mechanism - ephemeral breakpoints)
+- DeepSeek caching (not implemented)
+- Actual hit/miss tracking from Gemini API (not exposed)
+- Persisting cache stats across sessions
+
+## Acceptance Criteria
+- [ ] Cache panel displays in GUI when provider is Gemini
+- [ ] Cache age shown in human-readable format
+- [ ] TTL countdown visible with percentage
+- [ ] Warning color when TTL < 20%
+- [ ] Manual clear button works and calls `ai_client.cleanup()`
+- [ ] Panel hidden for non-Gemini providers
+- [ ] Uses existing `get_gemini_cache_stats()` - no new ai_client code
+- [ ] 1-space indentation maintained