Implement token usage visualization charts

[manavgup]

Priority

🔴 High

Description

Visual charts/graphs for token consumption over time.

Current State

No token visualization

Files to Create

• frontend/src/components/analytics/TokenChart.tsx
• frontend/src/components/analytics/TokenDashboard.tsx

Acceptance Criteria

• Line chart for token usage over time
• Bar chart by conversation
• Pie chart by model/provider
• Cost estimation display
• Export data as CSV

Effort

1 week

[manavgup]

@claude again how can we implement this along with other UI features yet keep the Ui clean?

[claude]

Claude finished @manavgup's task —— View job

---

Token Visualization Architecture Recommendations

I've analyzed the current codebase and here's a comprehensive approach to implement token visualization charts while keeping the UI clean:

---

Current State Analysis

✅ What You Already Have:

• Token tracking backend infrastructure (TokenTrackingService, LLMUsage, TokenUsageStats)
• Existing API endpoints at /api/token-warnings/ with usage stats
• Carbon Design System v1.65 integrated
• Clean navigation pattern with tabs (see ConfigurationPage.js)
• Dashboard tile-based layout

❌ What's Missing:

• Charting library (Carbon doesn't include charts)
• Frontend API calls for token data
• Token visualization components

---

Recommended Architecture

1. Keep UI Clean with Strategic Placement

Option A: Analytics Section in Existing Dashboard (Recommended)

• Add a new tile to Dashboard.js called "Token Usage Overview"
• Show mini-charts or summary stats
• Click tile to navigate to full analytics page
• Pros: Discoverable, integrates with existing flow, low friction
• Cons: Dashboard might get crowded if you add more features

Option B: Dedicated Analytics Page with Tabs

• Create /analytics route with tabbed interface (like Configuration)
• Tabs: "Token Usage", "Conversations", "Performance", etc.
• Pros: Scalable for future analytics features, keeps dashboard clean
• Cons: Requires navigation away from main dashboard

Option C: Analytics Menu Item with Dropdown

• Add "Analytics" to SideNav with sub-items
• Sub-items: "Token Usage", "Usage Reports", "Cost Estimation"
• Pros: Most scalable, follows existing Configuration pattern
• Cons: Adds another top-level nav item

My Recommendation: Use Option B for immediate needs (dedicated /analytics page with tabs), positioned between "Search Documents" and "Configuration" in the SideNav. This provides:

• Clean separation of concerns
• Room for future analytics features (performance metrics, usage reports, etc.)
• Follows the established tabbed pattern from Configuration page

---

2. Charting Library Recommendation

Carbon Design System doesn't include charts, so you'll need to add one:

Best Options:

1. Carbon Charts (IBM official) ⭐ RECOMMENDED

   npm install @carbon/charts @carbon/charts-react d3

   • Pros: Official Carbon integration, matches design system perfectly, responsive
   • Cons: Additional dependency
   • Provides: Line, Bar, Pie, Area, Scatter, and more

2. Recharts (Alternative)

   npm install recharts

   • Pros: Lightweight, React-native, composable
   • Cons: Styling needs manual Carbon theming

3. Chart.js with react-chartjs-2 (Alternative)

   npm install chart.js react-chartjs-2

   • Pros: Well-established, lots of examples
   • Cons: Not React-native, harder to theme

I recommend Carbon Charts since it's IBM's official solution and will look consistent with your existing Carbon components.

---

3. Component Structure

webui/src/components/analytics/
├── AnalyticsPage.js            # Main page with tabs
├── AnalyticsPage.css           # Styling
├── TokenDashboard.js           # Overview tab (all charts together)
├── TokenUsageChart.js          # Line chart for usage over time
├── ConversationTokenChart.js   # Bar chart by conversation
├── ModelDistributionChart.js   # Pie chart by model/provider
├── CostEstimation.js           # Cost display component
└── ExportData.js               # CSV export functionality

Data Flow:

AnalyticsPage (tabs)
  └─ TokenDashboard (tab 1)
      ├─ TokenUsageChart (line chart)
      ├─ ConversationTokenChart (bar chart)  
      ├─ ModelDistributionChart (pie chart)
      └─ CostEstimation (cost display)
      └─ ExportData (CSV button)

---

4. API Integration Strategy

Backend endpoints needed (may need to create):

// Already exists:
GET /api/token-warnings/user/{user_id}/stats
  → Returns TokenUsageStats

// May need to add:
GET /api/token-warnings/user/{user_id}/usage-history?start_date={}&end_date={}
  → Returns time-series data for line chart

GET /api/token-warnings/user/{user_id}/by-conversation?limit=10
  → Returns token usage grouped by conversation

GET /api/token-warnings/user/{user_id}/by-model
  → Returns token usage grouped by model/provider

Frontend API service:

// webui/src/api/analytics.js
export const getTokenUsageStats = async (userId) => {
  return api.get(`/api/token-warnings/user/${userId}/stats`);
};

export const getTokenUsageHistory = async (userId, startDate, endDate) => {
  return api.get(`/api/token-warnings/user/${userId}/usage-history`, {
    params: { start_date: startDate, end_date: endDate }
  });
};

// ... more API calls

---

5. UI/UX Patterns to Keep Clean

Progressive Disclosure:

• Show summary on dashboard (1 tile with key metrics)
• Full details on analytics page
• Drill-down capabilities (click chart to see details)

Responsive Layout:

• Use Carbon's Grid and Column components
• Stack charts vertically on mobile
• Side-by-side on desktop (2 columns)

Loading States:

• Use Carbon's Loading component
• Skeleton loaders for charts
• Error boundaries for failed data loads

Date Range Filtering:

• Use Carbon's DatePicker for time range selection
• Default to "Last 30 days"
• Presets: Today, Last 7 days, Last 30 days, Last 90 days, All time

Export Functionality:

• Use Carbon's Button with Download icon
• Generate CSV client-side from chart data
• Include metadata (date range, user, export time)

---

6. Sample Implementation Sketch

// AnalyticsPage.js
import { Tabs, TabList, Tab, TabPanels, TabPanel, Grid, Column } from '@carbon/react';
import { ChartLine, ChartBar, ChartPie } from '@carbon/icons-react';
import TokenDashboard from './TokenDashboard';
import UsageReports from './UsageReports'; // Future feature

const AnalyticsPage = () => {
  return (
    <div className="analytics-page">
      <Grid>
        <Column lg={16} md={8} sm={4}>
          <h1>Analytics & Insights</h1>
          
          <Tabs>
            <TabList>
              <Tab renderIcon={() => <ChartLine size={16} />}>Token Usage</Tab>
              <Tab renderIcon={() => <ChartBar size={16} />}>Usage Reports</Tab>
              {/* Future tabs: Performance, Costs, etc. */}
            </TabList>

            <TabPanels>
              <TabPanel>
                <TokenDashboard />
              </TabPanel>
              <TabPanel>
                <UsageReports />
              </TabPanel>
            </TabPanels>
          </Tabs>
        </Column>
      </Grid>
    </div>
  );
};

// TokenDashboard.js (main analytics view)
import { Grid, Column, Tile, Button, DatePicker, DatePickerInput } from '@carbon/react';
import { Download } from '@carbon/icons-react';
import TokenUsageChart from './TokenUsageChart';
import ConversationTokenChart from './ConversationTokenChart';
import ModelDistributionChart from './ModelDistributionChart';
import CostEstimation from './CostEstimation';

const TokenDashboard = () => {
  const [dateRange, setDateRange] = useState({ start: ..., end: ... });
  const [data, setData] = useState(null);
  
  // Fetch data based on date range
  useEffect(() => { /* ... */ }, [dateRange]);

  const handleExport = () => {
    // Generate CSV from data
  };

  return (
    <div className="token-dashboard">
      <Grid>
        {/* Controls row */}
        <Column lg={16}>
          <div className="dashboard-controls">
            <DatePicker datePickerType="range" onChange={setDateRange}>
              <DatePickerInput labelText="Start date" />
              <DatePickerInput labelText="End date" />
            </DatePicker>
            <Button renderIcon={Download} onClick={handleExport}>
              Export CSV
            </Button>
          </div>
        </Column>

        {/* Charts row 1 */}
        <Column lg={8} md={8} sm={4}>
          <Tile>
            <h3>Token Usage Over Time</h3>
            <TokenUsageChart data={data?.timeSeries} />
          </Tile>
        </Column>
        <Column lg={8} md={8} sm={4}>
          <Tile>
            <h3>Cost Estimation</h3>
            <CostEstimation data={data?.stats} />
          </Tile>
        </Column>

        {/* Charts row 2 */}
        <Column lg={8} md={8} sm={4}>
          <Tile>
            <h3>Usage by Conversation</h3>
            <ConversationTokenChart data={data?.byConversation} />
          </Tile>
        </Column>
        <Column lg={8} md={8} sm={4}>
          <Tile>
            <h3>Usage by Model</h3>
            <ModelDistributionChart data={data?.byModel} />
          </Tile>
        </Column>
      </Grid>
    </div>
  );
};

---

7. Keeping the UI Clean - Best Practices

1. Consistent Spacing: Use Carbon's spacing tokens ($spacing-05, $spacing-06, etc.)
2. Tile-Based Layout: Wrap each chart in a Tile component (consistent with Dashboard)
3. Responsive Grids: Use Carbon's Grid/Column with proper breakpoints
4. Icon Usage: Use Carbon icons consistently (ChartLine, ChartBar, ChartPie)
5. Typography: Follow Carbon type scale (h1, h2, h3 for hierarchy)
6. Loading States: Always show loading indicators during data fetch
7. Empty States: Handle "no data" gracefully with illustrations/messages
8. Color Palette: Use Carbon's color tokens (don't hardcode colors)

---

8. Implementation Roadmap

Phase 1: Foundation

• Install @carbon/charts and dependencies
• Create /analytics route in App.js
• Add Analytics nav item to SideNav.js
• Create AnalyticsPage.js with tab structure

Phase 2: Backend API (if needed)

• Add usage history endpoint
• Add conversation grouping endpoint
• Add model grouping endpoint

Phase 3: Components

• TokenUsageChart.js (line chart)
• ConversationTokenChart.js (bar chart)
• ModelDistributionChart.js (pie chart)
• CostEstimation.js (display component)

Phase 4: Features

• Date range filtering
• CSV export
• Responsive design testing
• Error handling & loading states

---

Next Steps

Would you like me to:

1. Start implementing this architecture (create the Analytics page with charts)?
2. First add backend endpoints if they're missing (check what API endpoints exist)?
3. Create a proof-of-concept with one chart to validate the approach?

Let me know how you'd like to proceed!

---

Job Run • Branch: claude/issue-283-20251005-1030