cost_tracking_llm v1.0.0

name: "cost_tracking_llm" description: "Track LLM API spend per task, model, and feature: log every call to a cost ledger, get per-feature and per-task spend reports, fire budget alerts at 70/90/100%, and evaluate whether routing-by-difficulty or prompt caching will pay off. Use when an app or agent needs cost attribution, monthly budget guardrails, or a measured plan to cut token spend."

Purpose

Turn "the LLM bill went up" into an answerable question. This skill gives an agent a working cost ledger, spend reports sliced by task/model/feature, budget alerts, and a playbook for the two levers that cut spend: routing by difficulty and prompt caching.

Workflow

1. Set up the pricing table. Copy assets/prices.example.json to assets/prices.json and fill in the current per-million-token prices for the models you use: input, cached-input, output, and reasoning. Prices change constantly, so treat this file as the single source of truth and update it when providers reprice.
2. Log every call. After each LLM call, run:

bin/llm-cost-tracker.py log --model <id> --input <n> --output <n> --task <task-id> --feature <feature>

Add --cached-input, --reasoning, --provider, and --outcome failed when applicable. The task tag is what makes per-task attribution work, so never leave it unset.

1. Read the report weekly. bin/llm-cost-tracker.py report --month YYYY-MM shows spend by feature, by model, top tasks, and waste flags (high failure rates, one model dominating spend). The expensive feature is usually obvious; start there.
2. Guard the budget. Put bin/llm-cost-tracker.py check-budget --budget <usd> --month YYYY-MM on a cron schedule. Exit 0 is fine, 1 means warning (70%+), 2 means critical (90%+): throttle or reroute to cheaper models.
3. Decide on routing or caching with numbers. For a candidate task, run bin/llm-cost-tracker.py estimate-route with your own volume and difficulty mix to see whether a cascade saves money. For caching, check the task's cache hit rate from the report and follow references/routing-and-caching-playbook.md: Anthropic needs reuse twice within the TTL to beat the write premium, OpenAI caching is automatic, misroutes and stale routers are the failure modes.

Output Contract

• log writes one JSON record per call to the ledger (default ~/.llm-cost/ledger.jsonl) and prints the call's cost in USD.
• report prints: total calls and spend, spend by feature, spend by model, the 8 most expensive tasks with per-call cost, and waste flags.
• check-budget prints spend, budget, percentage used, and status (ok / warning / critical / CRITICAL exhausted), exiting 0/1/2.
• estimate-route prints projected daily cost for cascade vs always-large routing and the estimated savings.

Operating Rules

1. Every factual claim about a provider's pricing or caching behavior must come from the provider's docs or pricing page, verified before use. Unverifiable numbers get cut, never stated confidently.
2. Log token counts, models, tags, and cost. Never log prompt or response text into the cost pipeline.
3. task is required on every logged call. "(unset)" features are allowed but should stay rare.
4. A model missing from the pricing table is logged with a warning and blank cost, not silently dropped. Add the price, then move on.
5. A routing or caching change ships only after a measured quality check against a baseline (always-small, always-large), not on vibes.
6. When the budget check hits critical, throttle or route cheaper first. A hard stop on a production path needs a human decision.