# Drama Leaderboard Design

## Overview

Public `/drama-leaderboard` slash command that ranks server members by historical drama levels using a composite score derived from DB data. Configurable time period (7d, 30d, 90d, all-time; default 30d).

## Data Sources

All from existing tables — no schema changes needed:

- **Messages + AnalysisResults** (JOIN on MessageId): per-user avg/peak toxicity, message count
- **Actions**: warning, mute, topic_remind, topic_nudge counts per user

## Composite Score Formula

```
score = (avg_toxicity * 0.4) + (peak_toxicity * 0.2) + (action_rate * 0.4)
```

Where `action_rate = min(1.0, (warnings + mutes*2 + off_topic*0.5) / messages_analyzed * 10)`

Normalizes actions relative to message volume so low-volume high-drama users rank appropriately.

## Embed Format

Top 10 users, ranked by composite score:

```
🥇 0.47 — Username
   Avg: 0.32 | Peak: 0.81 | ⚠️ 3 | 🔇 1 | 📢 5
```

## Files to Modify

- `utils/database.py` — add `get_drama_leaderboard(guild_id, days)` query method
- `cogs/commands.py` — add `/drama-leaderboard` slash command with `period` choice parameter

## Implementation Plan

### Step 1: Database query method

Add `get_drama_leaderboard(guild_id, days=None)` to `Database`:
- Single SQL query joining Messages, AnalysisResults, Actions
- Returns list of dicts with: user_id, username, avg_toxicity, max_toxicity, warnings, mutes, off_topic, messages_analyzed
- `days=None` means all-time (no date filter)
- Filter by GuildId to scope to the server

### Step 2: Slash command

Add `/drama-leaderboard` to `CommandsCog`:
- Public command (no admin restriction)
- `period` parameter with choices: 7d, 30d, 90d, all-time
- Defer response (DB query may take a moment)
- Compute composite score in Python from query results
- Sort by composite score descending, take top 10
- Build embed with ranked list and per-user stat breakdown
- Handle empty results gracefully