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 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.

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.

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': …".

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.

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.

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.