LLM Usage

Project the cost of a hypothetical workload across providers/models. Returns models ranked by absolute cost ascending, with `relative_cost_pct` measured against the cheapest entry (cheapest = 100%). `models`, if given, restricts the comparison to those model names. Cost is computed from input/output tokens only; `RankedEntry.notes` is always `None` in v1 (the field is retained for future per-row caveats like "tiered pricing approximated"). `include_snapshots=False` (the default) family-dedups the ranked list: rows sharing both a model-family root (`gpt-5-mini` ↔ `gpt-5-mini-2025-08-07`) AND an identical projected cost collapse to one representative, with `RankedEntry.variant_count` recording how many catalog rows the entry stands for. Set `include_snapshots=True` to see every catalog row (each with `variant_count=1`) — useful when comparing snapshot-by-snapshot pricing for production pinning.

Return current pricing for one model, one provider, or all models. Both filters are optional and AND-combined. An unknown (provider, model) returns an empty list rather than an error — the caller can distinguish "model not in our table" from "no model matches your filter" by passing `provider` alone.

List every provider we know about, with their models and OpenAI-compat flag. Sources the provider/model lists from `pricing_snapshot`, so a provider whose pricing hasn't been seeded simply doesn't appear. After `bootstrap()` runs on a fresh install this includes every v1 provider (anthropic, openai, qwen, deepseek). Order is alphabetical by provider, then by model within each provider.

Return spending broken down by a chosen axis over a time window. `start` and `end` are ISO-8601 strings (trailing-`Z`, `+00:00`, or naive — naive is interpreted as UTC). Default window is the last 30 days. `group_by` is one of provider | model | project | tag | day. `filter` AND-combines optional provider/model/project equality predicates. `include_failed` defaults to `False` so failure rows (e.g. streams that died mid-flight with partial counts) are excluded from totals and groups. Pass `True` to fold them back in — useful for debugging capture-layer behavior, not for honest spend numbers. Tag semantics: events with NULL/empty tags are excluded from `group_by="tag"` results entirely; multi-tag events contribute once per tag (so per-group `calls` sums can exceed the window total). Project semantics are symmetric: NULL projects are dropped from `group_by="project"`. Groups are ordered cost-desc with alphabetical ties.

Recommend the cheapest priced model that fits the workload + budget. v1 ranks by cost only. A future release will incorporate quality benchmarks (see `quality_snapshot` — the table is reserved for that purpose) and accept a `quality_priority` axis; for v1 those would rely on data we don't yet have, so the surface stays cost-only and honest. `expected_input_tokens` / `expected_output_tokens` default to a nominal 1k/1k workload when absent; the `reasoning` notes when defaults are in use. `budget_usd`, when set, filters out models that exceed it — if nothing fits, falls back to the cheapest model overall (the result fields are required, so there's no "no match" return shape) and the `reasoning` says so plainly. `providers` / `models` are optional whitelists (AND-combine when both passed). Both are applied before the budget cut, so an over- budget fallback returns the cheapest within the filter set rather than the cheapest priced model overall. A whitelist that matches nothing raises rather than fabricating a result — likely a spelling error in the caller's name list. `task_description` is **optional** and echoed into the reasoning but does not drive selection — the tool isn't an LLM and can't interpret free text. Omit it (or pass `None`) and the reasoning opens with `"Recommending …"` instead of `"For task 'X': …"`.

Record a single LLM API call with token counts. Cost is computed automatically from the pricing table at insert time. `request_id` enables idempotent recording — replaying a log file won't double-count.

Return a one-shot summary of usage over a named calendar period. `period` is one of today | week | month | year (default: "week"). Boundaries are calendar UTC: `today` = since 00:00 UTC today, `week` = since Monday 00:00 UTC, `month` = since the 1st of the month, `year` = since January 1st. Returns totals, the top-3 providers and top-3 models by cost (with `pct` of total), and the single most expensive call in the window — or `largest_call=None` when the window is empty. `include_failed` defaults to `False`: totals, top-N rollups, and `largest_call` all exclude `success=False` rows (partial-stream captures and other failure rows). Pass `True` for symmetric debugging access to the failure population.