learningcircuit--local-deep-research/docs/metrics-dashboard.md

# Metrics & Analytics Dashboard

This guide covers the Metrics Dashboard for monitoring research performance, costs, and usage analytics.

## Table of Contents

- [Overview](#overview)
- [Research Metrics](#research-metrics)
- [Cost Analytics](#cost-analytics)
- [Rate Limiting](#rate-limiting)
- [Link Analytics](#link-analytics)
- [Star Reviews](#star-reviews)
- [API Reference](#api-reference)

---

## Overview

The Metrics Dashboard provides insights into your research activity:
- **Token usage** and LLM costs
- **Search performance** and rate limiting
- **Research quality** ratings
- **Link analytics** and domain classification

Access the dashboard at: `http://localhost:5000/metrics`

---

## Research Metrics

### Overview Page

The main metrics page shows:

| Metric | Description |
|--------|-------------|
| Total Researches | Number of research sessions |
| Total Tokens | Tokens consumed across all research |
| Total Cost | Estimated LLM API costs |
| Average Duration | Mean research completion time |

### Per-Research Metrics

Click on any research to see detailed metrics:

#### Timeline

View the research execution timeline:
- Start and end times
- Iteration progress
- Question generation timing
- Search execution timing

#### Search Metrics

Details about search operations:
- Queries executed
- Results retrieved
- Search engine usage
- Response times

#### Links

All links discovered during research:
- Source URLs
- Domain classification
- Relevance scores

---

## Cost Analytics

### Token Tracking

The system tracks token usage for cost estimation:

| Metric | Description |
|--------|-------------|
| Input Tokens | Tokens sent to LLM |
| Output Tokens | Tokens received from LLM |
| Total Tokens | Combined usage |
| Estimated Cost | Based on model pricing |

### Cost Breakdown

View costs broken down by:
- **Model** - Which LLM models were used
- **Provider** - OpenAI, Anthropic, etc.
- **Time Period** - Daily, weekly, monthly
- **Research** - Per-research costs

### Accessing Cost Analytics

1. Navigate to **Metrics** → **Costs**
2. View summary statistics
3. Filter by date range
4. Export data as needed

### Pricing Information

The system includes pricing data for common models:

```
GET /metrics/api/pricing
GET /metrics/api/pricing/<model_name>
```

---

## Rate Limiting

### Monitoring Rate Limits

View current rate limiting status for search engines:

1. Navigate to **Metrics** → **Rate Limiting**
2. See per-engine statistics

| Column | Description |
|--------|-------------|
| Engine | Search engine name |
| Current Wait | Active wait time |
| Success Rate | Percentage of successful requests |
| Total Requests | Request count |
| Last Updated | Most recent activity |

### Rate Limit Management

From the dashboard you can:
- View current rate limit estimates
- See learned optimal wait times
- Monitor success rates

For CLI management, see [CLI Tools](cli-tools.md#rate-limiting-cli).

---

## Link Analytics

### Domain Classification

The system classifies domains found in research:

| Category | Examples |
|----------|----------|
| Academic | arxiv.org, pubmed.gov |
| News | bbc.com, reuters.com |
| Government | .gov, .edu |
| Commercial | company websites |
| Reference | wikipedia.org |

### Link Statistics

View aggregate statistics:
- Total links discovered
- Unique domains
- Category distribution
- Top domains by frequency

### Accessing Link Analytics

1. Navigate to **Metrics** → **Links**
2. View domain breakdown
3. Filter by category
4. See classification summary

### Classification API

Classify domains programmatically:

```
POST /metrics/api/domain-classifications/classify
{
  "domains": ["example.com", "arxiv.org"]
}
```

---

## Star Reviews

### Rating Research Quality

Rate your research results to track quality over time:

1. Open a completed research
2. Click the star rating (1-5)
3. Optionally add feedback text

### Viewing Ratings

Navigate to **Metrics** → **Star Reviews** to see:
- Average rating across all research
- Rating distribution
- Recent ratings with feedback
- Trends over time

### Rating API

```
# Get ratings for a research
GET /metrics/api/ratings/<research_id>

# Submit a rating
POST /metrics/api/ratings/<research_id>
{
  "rating": 5,
  "feedback": "Excellent results"
}
```

---

## API Reference

### Metrics Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/metrics/api/metrics` | GET | Overview metrics |
| `/metrics/api/metrics/enhanced` | GET | Detailed metrics |
| `/metrics/api/metrics/research/<id>` | GET | Per-research metrics |
| `/metrics/api/metrics/research/<id>/timeline` | GET | Research timeline |
| `/metrics/api/metrics/research/<id>/search` | GET | Search metrics |
| `/metrics/api/metrics/research/<id>/links` | GET | Research links |

### Cost Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/metrics/api/pricing` | GET | Model pricing data |
| `/metrics/api/pricing/<model>` | GET | Specific model pricing |
| `/metrics/api/cost-calculation` | POST | Calculate costs |
| `/metrics/api/research-costs/<id>` | GET | Research cost breakdown |
| `/metrics/api/cost-analytics` | GET | Cost analytics summary |

### Rate Limiting Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/metrics/api/rate-limiting` | GET | Rate limit statistics |
| `/metrics/api/rate-limiting/current` | GET | Current rate limits |

### Rating Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/metrics/api/ratings/<id>` | GET | Get research rating |
| `/metrics/api/ratings/<id>` | POST | Submit rating |
| `/metrics/api/star-reviews` | GET | All ratings summary |

### Domain Classification Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/metrics/api/domain-classifications` | GET | All classifications |
| `/metrics/api/domain-classifications/summary` | GET | Classification summary |
| `/metrics/api/domain-classifications/classify` | POST | Classify domains |
| `/metrics/api/domain-classifications/progress` | GET | Classification progress |
| `/metrics/api/link-analytics` | GET | Link analytics data |

---

## Troubleshooting

### No Metrics Showing

- Ensure you have completed at least one research
- Check that token tracking is enabled
- Refresh the page

### Cost Estimates Incorrect

- Verify model pricing is up to date
- Check provider is correctly identified
- Token counts may vary by model

### Rate Limiting Data Missing

- Run some searches to generate data
- Check the rate limiting CLI for status

---

## See Also

- [CLI Tools](cli-tools.md) - Rate limiting CLI
- [Full Configuration Reference](CONFIGURATION.md) - All settings and environment variables
- [Troubleshooting](troubleshooting.md) - Common issues
- [Architecture Overview](architecture/OVERVIEW.md) - System design