cost-report

Files (1)

• SKILL.md

SKILL.md (first lines)

# Usage Cost Reporting

Query the API usage ledger and produce clear, actionable cost reports broken down by provider, model, and time period.

## When to Use

- When the user asks "how much have I spent" or "show me my usage"
- During heartbeats to check if spending is approaching a configured budget threshold
- When evaluating whether to switch models or providers based on cost efficiency
- As part of a daily or weekly briefing that includes operational metrics
- After a heavy ingestion or research session to assess the cost impact

## Step-by-Step Methodology

1. **Determine the time window**: Default to the current billing period (calendar month) unless the user specifies a range. Common windows: today, this week, this month, last 30 days, custom range.
2. **Query the ledger**: Use `query_usage` with the appropriate date range. The tool returns rows from the `api_usage` table with provider, model, token counts (input/output), and computed cost.
3. **Aggregate by dimension**: Break down the raw data into useful summaries:
   - **By provider**: Total cost per provider (OpenAI, Anthropic, local inference, etc.)
   - **By model**: Cost per model to identify which models consume the most budget
   - **By category**: Separate LLM inference costs from embedding costs from tool API costs
   - **By day**: Daily trend to spot spikes or patterns
4. **Compute key metrics**: Calculate:
   - Total spend for the period
   - Average daily cost
   - Cost per conversation (if trackable)
   - Projected monthly cost at current burn rate
5. **Compare to budget**: If a budget threshold is configured, compare current spend and projection against it. Flag if on track to exceed.
6. **Present the report**: Format as a clean table or summary. Lead with the headline number (total spend), then break down by the most useful dimension.

## Quality Guidelines

- Always show actual numbers, not vague descriptions. "You have spent $4.32 this month" is useful; "you have moderate usage" is not.
- Round costs to two decimal places for readability.
- When projecting monthly cost, note that it is an extrapolation and actual spend may vary.
- If the usage ledger is empty or the query returns no data, say so plainly rather than reporting zeros that could be misleading.
- In heartbeat context, only generate a cost report if spend is approaching a threshold or if a goal explicitly asks for cost monitoring. Do not waste energy on routine cost checks every heartbeat.
- Protect cost data as operational metadata. Do not expose it to external services.

From rajacsp/hexnostic, MIT.