manual_slop/conductor/tracks/cost_token_analytics_20260306/plan.md

Implementation Plan: Cost & Token Analytics Panel (cost_token_analytics_20260306)

Reference: Spec | Architecture Guide

Phase 1: Foundation & Research

Focus: Verify existing infrastructure

• Task 1.1: Initialize MMA Environment

  • Run activate_skill mma-orchestrator before starting

• Task 1.2: Verify cost_tracker.py implementation

  • WHERE: src/cost_tracker.py
  • WHAT: Confirm MODEL_PRICING dict and estimate_cost() function
  • HOW: Use manual-slop_py_get_definition on estimate_cost
  • OUTPUT: Document exact MODEL_PRICING structure for reference

• Task 1.3: Verify tier_usage in ConductorEngine

  • WHERE: src/multi_agent_conductor.py lines ~50-60
  • WHAT: Confirm tier_usage dict structure and update mechanism
  • HOW: Use manual-slop_py_get_code_outline on ConductorEngine
  • SAFETY: Note thread that updates tier_usage

• Task 1.4: Review existing MMA dashboard

  • WHERE: src/gui_2.py _render_mma_dashboard() method
  • WHAT: Understand existing tier usage table pattern
  • HOW: Read method to identify extension points
  • OUTPUT: Note line numbers for table rendering

Phase 2: State Management

Focus: Add cost tracking state to app

• Task 2.1: Add session cost state

  • WHERE: src/gui_2.py or src/app_controller.py in __init__
  • WHAT: Add session-level cost tracking state
  • HOW:

    self._session_cost_total: float = 0.0
    self._session_cost_by_model: dict[str, float] = {}
    self._session_cost_by_tier: dict[str, float] = {
     "Tier 1": 0.0, "Tier 2": 0.0, "Tier 3": 0.0, "Tier 4": 0.0
    }
    

  • CODE STYLE: 1-space indentation

• Task 2.2: Add cost update logic

  • WHERE: src/gui_2.py in MMA state update handler
  • WHAT: Calculate costs when tier_usage updates
  • HOW:

    def _update_costs_from_tier_usage(self, tier_usage: dict) -> None:
     for tier, usage in tier_usage.items():
      cost = cost_tracker.estimate_cost(
       self.current_model, usage["input"], usage["output"]
      )
      self._session_cost_by_tier[tier] = cost
      self._session_cost_total += cost
    

  • SAFETY: Called from GUI thread via state update

• Task 2.3: Reset costs on session reset

  • WHERE: src/gui_2.py or src/app_controller.py reset handler
  • WHAT: Clear cost state when session resets
  • HOW: Set all cost values to 0.0 in reset function

Phase 3: Panel Implementation

Focus: Create the GUI panel

• Task 3.1: Create _render_cost_panel() method

  • WHERE: src/gui_2.py after other render methods
  • WHAT: New method to display cost information
  • HOW:

    def _render_cost_panel(self) -> None:
     if not imgui.collapsing_header("Cost Analytics"):
      return
    
     # Total session cost
     imgui.text(f"Session Total: ${self._session_cost_total:.4f}")
    
     # Per-tier breakdown
     if imgui.begin_table("tier_costs", 3):
      imgui.table_setup_column("Tier")
      imgui.table_setup_column("Tokens")
      imgui.table_setup_column("Cost")
      imgui.table_headers_row()
      for tier, cost in self._session_cost_by_tier.items():
       imgui.table_next_row()
       imgui.table_set_column_index(0)
       imgui.text(tier)
       imgui.table_set_column_index(2)
       imgui.text(f"${cost:.4f}")
      imgui.end_table()
    
     # Per-model breakdown
     if self._session_cost_by_model:
      imgui.separator()
      imgui.text("By Model:")
      for model, cost in self._session_cost_by_model.items():
       imgui.bullet_text(f"{model}: ${cost:.4f}")
    

  • CODE STYLE: 1-space indentation, no comments

• Task 3.2: Integrate panel into main GUI

  • WHERE: src/gui_2.py in _gui_func() or appropriate panel
  • WHAT: Call _render_cost_panel() in layout
  • HOW: Add near token budget panel or MMA dashboard
  • SAFETY: None

Phase 4: Integration with MMA Dashboard

Focus: Extend existing dashboard with cost column

• Task 4.1: Add cost column to tier usage table

  • WHERE: src/gui_2.py _render_mma_dashboard()
  • WHAT: Add "Est. Cost" column to existing tier usage table
  • HOW:
    • Change imgui.table_setup_column() from 3 to 4 columns
    • Add "Est. Cost" header
    • Calculate cost per tier using current model
    • Display with dollar formatting
  • SAFETY: Handle missing tier_usage gracefully

• Task 4.2: Display model name in table

  • WHERE: src/gui_2.py _render_mma_dashboard()
  • WHAT: Show which model was used for each tier
  • HOW: Add "Model" column with model name
  • SAFETY: May not know per-tier model - use current_model as fallback

Phase 5: Testing

Focus: Verify all functionality

• Task 5.1: Write unit tests for cost calculation

  • WHERE: tests/test_cost_panel.py (new file)
  • WHAT: Test cost accumulation logic
  • HOW: Mock tier_usage, verify costs calculated correctly
  • PATTERN: Follow test_cost_tracker.py as reference

• Task 5.2: Write integration test

  • WHERE: tests/test_cost_panel.py
  • WHAT: Test with live_gui, verify panel displays
  • HOW: Use live_gui fixture, trigger API call, check costs
  • ARTIFACTS: Write to tests/artifacts/

• Task 5.3: Conductor - Phase Verification

  • Run: uv run pytest tests/test_cost_panel.py tests/test_cost_tracker.py -v
  • Manual: Verify panel displays in GUI

Implementation Notes

Thread Safety

• tier_usage is updated on asyncio worker thread
• GUI reads via _process_pending_gui_tasks - already synchronized
• No additional locking needed

Cost Calculation Strategy

• Use current model for all tiers (simplification)
• Future: Track model per tier if needed
• Unknown models return 0.0 cost (safe default)

Files Modified

• src/gui_2.py: Add cost state, render methods
• src/app_controller.py: Possibly add cost state (if using controller)
• tests/test_cost_panel.py: New test file

Code Style Checklist

• 1-space indentation throughout
• CRLF line endings on Windows
• No comments unless requested
• Type hints on new state variables
• Use existing vec4 colors for consistency