Add SSDL-style docstrings to cache, usage, tool analytics, token budget, and log management panels

project_history.toml

@@ -9,5 +9,5 @@ active = "main"
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-06-12T21:52:14"
+last_updated = "2026-06-12T21:52:43"
 history = []

src/gui_2.py

@@ -340,9 +340,9 @@ class App:
     delegation_targets=['_render_main_interface', '_render_discussion_hub', '_render_files_and_media', '_render_ai_settings_hub', '_render_operations_hub', '_render_mma_dashboard']
    ))
   with startup_profiler.phase("app_init_workspace"):
-   self.workspace_manager = workspace_manager.WorkspaceManager(project_root=self.controller.active_project_root)
-   self.disc_entries = self.controller.disc_entries
-   self.disc_roles = self.controller.disc_roles
+   self.workspace_manager  = workspace_manager.WorkspaceManager(project_root=self.controller.active_project_root)
+   self.disc_entries       = self.controller.disc_entries
+   self.disc_roles         = self.controller.disc_roles
    self.workspace_profiles = self.workspace_manager.load_all_profiles()
   with startup_profiler.phase("app_init_start_services"):
    self.controller.start_services(self)
@@ -1763,6 +1763,16 @@ def render_custom_title_bar(app: App) -> None:
 #region: Diagnostics & Analytics
 
 def render_usage_analytics_panel(app: App) -> None:
+ """
+ Renders the aggregate dashboard panel for usage, budgeting, cache analytics,
+ tool performance metrics, and session insights.
+
+ State Mutations:
+   None directly (delegated to sub-panels).
+
+ SSDL Shape:
+   `[I] -> [B:token_budget] -> [B:cache_panel] -> [B:tool_analytics] -> [B:session_insights]`
+ """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_usage_analytics_panel")
  render_token_budget_panel(app)
  imgui.separator()
@@ -1903,6 +1913,16 @@ def render_diagnostics_panel(app: App) -> None:
  if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_diagnostics_panel")
 
 def render_cache_panel(app: App) -> None:
+ """
+ Renders caching analytics and a clear cache utility for providers that support caching (Gemini).
+
+ State Mutations:
+   app.controller (clears cached files)
+   app._cache_cleared_timestamp (updates trigger timestamp)
+
+ SSDL Shape:
+   `[I:cache_stats] -> [B:progress_bar] => [B:clear_cache]`
+ """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_cache_panel")
  if app.current_provider != "gemini":
   if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_cache_panel")
@@ -1935,6 +1955,15 @@ def render_cache_panel(app: App) -> None:
  if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_cache_panel")
 
 def render_tool_analytics_panel(app: App) -> None:
+ """
+ Renders a breakdown of tool execution telemetry, including calls, average latency, and failure rates.
+
+ State Mutations:
+   app._cached_tool_stats, app._tool_stats_cache_time (throttled caching of tool telemetry)
+
+ SSDL Shape:
+   `[I:tool_stats] -> [B:stats_table]`
+ """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_tool_analytics_panel")
  imgui.text_colored(C_LBL(), 'Tool Usage')
  imgui.separator()
@@ -1973,6 +2002,15 @@ def render_tool_analytics_panel(app: App) -> None:
  if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_tool_analytics_panel")
 
 def render_token_budget_panel(app: App) -> None:
+ """
+ Renders prompt token utilization breakdown, system/tools/history usage, and estimated pricing/costs.
+
+ State Mutations:
+   app._token_stats_dirty, app._token_stats (requests API metrics calculations via background worker)
+
+ SSDL Shape:
+   `[I:session_tokens] -> [B:utilization_bar] -> [B:breakdown_table] -> [B:tier_costs_table]`
+ """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_token_budget_panel")
  imgui.text_colored(C_LBL(), 'Prompt Utilization')
  usage = app.session_usage
@@ -2090,7 +2128,16 @@ def render_token_budget_panel(app: App) -> None:
 
 def render_log_management(app: App) -> None:
  """
-   [C: tests/test_log_management_ui.py:test_render_log_management_logic]
+ Renders log management window, enabling browsing, starring/whitelisting, and loading of prior log sessions.
+
+ State Mutations:
+   app.show_windows["Log Management"]
+   app._log_registry (creates and loads session logs registry toml)
+
+ SSDL Shape:
+   `[I:sessions] -> [B:registry_actions] -> [B:sessions_table]`
+
+ [C: tests/test_log_management_ui.py:test_render_log_management_logic]
  """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_log_management")
  with imscope.window("Log Management", app.show_windows["Log Management"]) as (exp, opened):