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.