polly-usage-report

SKILL.md

---
name: polly-usage-report
description: Generate a Polly customer usage report from the PollyView API. Fetches real-time user data, analyzes spend, engagement, and alerts, saves a historical snapshot, and sends or displays an HTML report. Use when the user asks to run, schedule, or view a Polly usage report, customer usage stats, or daily spend summary.
metadata:
  openclaw:
    requires:
      env:
        - POLLYVIEW_API_KEY
        - POLLYVIEW_HOST
---

# Polly Usage Report Skill

Generates a daily customer usage report from the PollyView API.

## Configuration

Set via `manage_skills config polly-usage-report --env POLLYVIEW_API_KEY=<key> POLLYVIEW_HOST=<host>`:

| Env Var | Description | Example |
|---|---|---|
| `POLLYVIEW_API_KEY` | Bearer token for the API (required) | `b51043db...` |
| `POLLYVIEW_HOST` | Base URL of the PollyView service (required) | `http://your-pollyview-host` |

Additional defaults (set in task description):
- `RECIPIENT` — email to send report to
- `DATA_FILE` — path to historical snapshot JSON

**API reference:** See `references/api.md` for endpoint docs, field descriptions, and example responses.

**Full task instructions:** See `references/task-instructions.md` for the complete step-by-step execution guide to use when creating a scheduled task.

## Workflow Summary

### Step 1: Fetch Customer Data

```
GET {POLLYVIEW_HOST}/api/v1/users
Authorization: Bearer {POLLYVIEW_API_KEY}
```

Use `fetch_url` with the Authorization header. On failure, send a failure email and stop.

**Filter:** Keep only `is_internal == false` users; exclude `@placeholder.local` emails.

### Step 2: Save Snapshot

Load history JSON from `DATA_FILE`, append `{"date", "timestamp", "users": [...]}`, write back. Initialize as `[]` if missing.

### Step 3: Analyze

1. Summary — total customers, today's spend, all-time cost
2. Top Spenders Today — by `or_usage` desc
3. Near Limit Alerts — `or_usage / or_limit >= 0.70`
4. Over Limit — `or_usage > or_limit`
5. All-Time Leaders — top 5 by `total_cost`
6. Engagement — top by `total_conversations` and `total_tool_calls`
7. Inactive — `total_llm_calls == 0`
8. Trends — day-over-day `total_cost` delta; flag >50% increase
9. Anomalies — unusual patterns in real data only

### Step 4: Output

**Email:** Send HTML to RECIPIENT. Subject: `Daily Polly Customer Usage Report — {date}`. See `references/email-template.md` for CSS/dark mode and section layout.

**Chat:** Display clean markdown summary with the same sections.

## Critical Rules

- Never fabricate data. All values must come directly from the API response.
- If the API fails, notify the user/RECIPIENT and stop.