ai-reports/README.md

# AI Tool Usage Reporting Dashboard

A comprehensive suite of HTML dashboards for reporting on AI tool usage and conversation data via webhook APIs.

Total cost: $6.36
Total duration (API): 17m 17.1s
Total duration (wall): 3h 40m 1.3s

## Overview

This repository contains several connected reporting tools:

1. **Main Navigation Dashboard** (`main-index.html`): Central hub for accessing all reports
2. **Conversation Reports**:
   - **Latam Report** (`index-Latam.html`): Latin America conversation metrics
   - **SBII Report** (`index-SBII.html`): SBII platform conversation metrics
   - **Sidekick Report** (`index-sidekick.html`): Sidekick assistant conversation metrics
3. **AI Tool Usage Report** (`SANDBOX-ai-tools-report.html`): Monitors usage of AI tools like Text-to-Voice and Text-to-Image services

## Main Navigation Dashboard

A clean, card-based interface for navigating between all available reports. Each report is represented by a color-coded card with a description of its purpose and a direct link to open it.

## Conversation Reports

### Features

- **Simple Interface**: Clean, compact design using Montserrat font
- **Data Selection**: Dropdown menu to select different conversation datasets
- **Assistant Name Resolution**: 
  - Automatically looks up friendly names for assistant IDs
  - Displays both name and ID in reports for easy identification
  - Handles multiple assistant databases for Latam report
- **Pivot Table View**: 
  - Groups data by Assistant
  - Shows conversation count per user
  - Includes subtotals per Assistant
  - Displays grand total of all conversations
- **Usage Graph**:
  - Interactive line chart showing usage over time
  - Filter data by time period (Today, 7 days, 30 days, 3 months, All time)
  - Color-coded lines for different assistants
  - Assistants labeled by name instead of ID for readability
- **CSV Export**: 
  - Export all raw data in CSV format
  - Includes both assistant IDs and names in separate columns
  - Timestamp included in filename for version tracking

### How to Use Conversation Reports

1. Open `main-index.html` in a web browser to access the navigation dashboard
2. Select the desired report from the available options
3. In each report, select the desired dataset from the dropdown (if applicable)
4. Click "Send Request" to fetch the data
5. View the usage graph showing trends over time, and use time filters to focus on specific periods
6. Explore the detailed pivot table showing conversation metrics
7. Use the "Export CSV" button to download the raw data as a CSV file

## AI Tool Usage Report

### Features

- **Multi-view Dashboard**: Comprehensive analytics with multiple views and interactive visualizations
- **Enhanced Date Filtering**: Filter by date range including Today, Yesterday, 7 days, 30 days, **90 days**, and All time
- **Multi-Select Filtering**: 
  - **Checkbox-based filtering** for Users, Models, and Sub-Tools
  - **Select multiple items** simultaneously instead of single selections
  - **Select All/Deselect All** buttons for quick bulk operations
  - **Real-time filtering** with instant updates across all views
- **Interactive Pie Chart**: 
  - **Tool usage distribution** visualization on Summary tab
  - **Hover tooltips** showing counts and percentages
  - **Dynamic updates** when filters change
  - **Chart.js powered** interactive charts
- **Summary Cards**: Quick overview of usage metrics with visual enhancements
- **Multiple Pivot Tables**:
  - By User: See which users are using which tools
  - By Model: Track usage across different AI models
  - By Sub-Tool: Analyze which sub-tools are most popular
- **Detailed View**: See all usage entries with full details
- **CSV Export**: Download filtered data as CSV file with timestamp

### How to Use AI Tools Report

1. Open the AI Tools Report from the main dashboard
2. Select report type from dropdown (All Tools, Text-to-Voice, Text-to-Image)
3. Click "Send Request" to fetch the data
4. **Apply Filters**:
   - Choose date range (now includes 90-day option)
   - **Select multiple users** by checking/unchecking boxes (or use "Select All")
   - **Select multiple models** using checkbox interface
   - **Select multiple sub-tools** for granular analysis
5. **View Results**:
   - **Summary tab**: Overview cards + interactive pie chart showing tool distribution
   - **Pivot tables**: Analyze data by User, Model, or Sub-Tool
   - **Detailed View**: Complete data table with all entries
6. **Export**: Download filtered results as CSV file for external analysis

## Technical Details

- **Pure HTML/CSS/JavaScript**: Uses native web technologies with enhanced UI components
- **Chart.js Integration**: 
  - Interactive pie charts with hover effects and percentage tooltips
  - Responsive charts that update dynamically with filter changes
  - Memory-efficient chart cleanup and recreation
- **Advanced Filtering System**:
  - Multi-select checkbox interfaces with scrollable containers
  - Real-time filtering without server requests
  - Client-side data processing for instant results
  - Bulk selection controls (Select All/Deselect All)
- **Multiple API Endpoints**: 
  - Each report connects to appropriate data webhooks
  - Assistant name lookup uses separate assistant database webhooks 
  - Backend provides all-time data, frontend applies date/user/model filtering
- **Parallel API Calls**: Makes simultaneous requests to improve loading performance
- **Authentication**: Includes secure auth_code token with each request
- **Error Handling**: Gracefully handles API errors and displays user-friendly messages
- **Responsive Design**: Works on desktop and tablet devices with optimized layouts

## Data Structures

### Conversation Data

```json
[
  {
    "data": {
      "User_ID": "example@domain.com",
      "StartTime": "2024-10-21T21:29:47.470Z",
      "Brand Voice Setting": "standard",
      "Title": "Example Title",
      "EndTime": "2024-10-21T21:29:57.203Z",
      "Assistant_ID": "asst_identifier",
      "Assistant_Key": "key_value",
      "Conversation_ID": "conversation_id",
      "Vision_Images": ""
    }
  }
]
```

### Assistant Data

```json
[
  {
    "data": {
      "Name": "Friendly Assistant Name",
      "Assistant ID": "asst_identifier",
      "Instructions": "Assistant instructions...",
      "Model": "claude-3-sonnet-20240229"
    }
  }
]
```

### AI Tool Usage Data

```json
[
  {
    "data": {
      "Date": "2024-05-15T23:00:00.000Z",
      "TOOL": "TEXT2VOICE",
      "USER": "user@example.com",
      "MODEL": "eleven_multilingual_v2",
      "PROMPT": "Example prompt text",
      "SUB_TOOL": "Elevenlabs",
      "SETTINGS": "Voice settings",
      "BOX_FILE_ID": "123456"
    }
  }
]
```