llm_cost_tracker 0.14.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c1f13f9f919518298bf4aa5bb9bf33f6fb48851a963d132d48000c2c9ab2477
-  data.tar.gz: 1de730cdb5061df2588c74dd0c56ec29aa59ec0fe812188e2ae30df4e206c682
+  metadata.gz: 3fbd251f06208de2aaeb887d9e8603fe7614e365c1d5d5e9aef0c27dba5f54d2
+  data.tar.gz: 78600f3f5844d367c4dd9030c3af8b024937f90f501b9bab51a792df085ab9a7
 SHA512:
-  metadata.gz: ee3ac1c8844c4bc478f85899d9e74734d67040d4b4f124c1751a970924a6d4ccf6fd2d680a2ed2a0d0e51ea79d7e985ad623ff49ed88148129df0276ba6c0925
-  data.tar.gz: 2aaa9cad0cd45a6e7df0920f054c258d12f03b2edc99c1c3bcf846d4ba33f4ce62972419cc92c5014711e417cb5f12eee63df2ac2f3c3e691acf47c8c620fdb8
+  metadata.gz: 11e337b545c34c40b5ce468278a3a7d15f562bd016269b1dd59c41053fd0eb7602b2025aaa286c9dd603dd2740502b37afca51689ba843d5d039e1d8385490f7
+  data.tar.gz: b918914d2b8b7671d02597d8f08000818f38d890609ae2a81286fa279da5ab3efaec230690c31ec5e060d2b02dcab6d4bc93bf129804233158c8681cf4575aa8

data/CHANGELOG.md

@@ -2,6 +2,122 @@
 
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.0] - 2026-10-10
+
+### Added
+
+- `budgets.per_tag` `total` window: a lifetime limit per tag value, such as one agent run's `run_id`.
+- `budgets.per_tag` `calls` limit: the number of recorded calls per tag value, unpriced calls included.
+- RubyLLM calls inside `RubyLLM.workflow` are tagged `run_id` with the workflow's id, also from tools RubyLLM runs concurrently and batch results collected inside it, unless the app sets `run_id`.
+- RubyLLM 2.x speech, OCR, rerank, judgments and operations added in later RubyLLM releases are recorded, with unknown cost where no rate applies; video generation and research jobs are not.
+- RubyLLM 2.x `RubyLLM.batch` results are recorded once each at batch rates when `Batch#messages` or `#results` returns them.
+- `RubyLLM.workflow` names and steps become `workflow_name` and `workflow_step_name` tags.
+- Perplexity, xAI and Mistral hosts, regional ones included, are built into `capture.openai_compatible_providers`, so Faraday, the official openai gem and `track_stream` capture them without registration.
+- Perplexity Sonar and Agent API calls, background polls included, are recorded at their billed `usage.cost.total_cost`.
+- Faraday captures image generation and edits, transcriptions, translations, speech and Mistral OCR on OpenAI-compatible hosts, and moderations on OpenAI and OpenAI-compatible hosts, `free` on a $0-priced model.
+- `off_peak` pricing mode: a call made inside a price entry's `_off_peak_windows` (ISO weekdays, UTC hours) is priced at its `off_peak_*` rates, also when backfilled or repriced.
+- `ocr_page` and `rerank_search_unit` dimensions, per 1,000 pages and search units, recorded for Mistral OCR and RubyLLM 2.x Cohere Parse and rerank.
+- `_minimum_billed_seconds` price-entry field: a shorter transcription is billed for that many seconds.
+- `gpt-4o-mini-tts` speech requested with `stream_format: "sse"` is priced from its usage, text input at `input` and audio at `audio_output`; binary responses carry no usage and stay unknown.
+- Bundled DeepSeek prices, peak and off-peak, under its current and legacy model names; Chinese public holidays are priced at peak.
+- Bundled Mistral prices for Voxtral transcription (per minute), Voxtral TTS (per character), OCR (per 1,000 pages), Codestral Embed and Mistral Moderation 2 ($0).
+- Bundled Groq prices for Whisper, per minute of a `verbose_json` response's `duration` with Groq's 10-second minimum, and Orpheus, per character.
+- Bundled Cohere prices from its pricing page: Command R and R7B, legacy Command models, Aya Expanse, Embed 5, Rerank 4 per 1,000 search units and Parse per 1,000 pages.
+- RubyLLM 2.x Cohere chats and embeddings record billed image tokens at `image_input`, so a call with images is `partial` or `unknown` until a price has that rate.
+- Bundled prices for Mistral Embed and Cohere Command A, which their providers' pages omit, taken from LiteLLM and marked `"_source": "litellm"`.
+- `LICENSE.txt` carries LiteLLM's MIT notice for the bundled prices taken from its data.
+- OpenAI Responses WebSocket mode (`responses.connect`, `OpenAI::Responses::Session` included) is recorded, one call per response that reports usage, and `:block_requests` checks each `response.create` before it is sent.
+
+### Changed
+
+- RubyLLM 2.x is captured from its instrumentation events and documented protocol methods instead of patches to its internals; RubyLLM 1.x keeps the previous integration.
+- RubyLLM 2.x records one row per provider attempt: retries, fallbacks and `pause_turn` segments each get a row, refused or unsent attempts are skipped, and a failed attempt that may have been billed is recorded with unknown cost unless its usage was read.
+- RubyLLM 2.x responses in OpenAI, Anthropic or Gemini format are priced on any host, Vertex AI included.
+- Under `:block_requests`, a RubyLLM 2.x call is blocked when its RubyLLM event starts; the event's other subscribers then see no finish.
+- On RubyLLM 2.x, an unset `RubyLLM.config.instrumenter` is set to `ActiveSupport::Notifications`; `doctor` warns when it is anything else or a protocol method the integration reads is missing.
+- RubyLLM 2.x Cohere chats record Cohere's billed units instead of token counts that include its unbilled preamble; rows recorded earlier keep the larger counts, so backfilling them overstates their cost.
+- xAI calls are recorded at their billed `usage.cost_in_usd_ticks`, tool calls included, instead of a list-price estimate.
+- Faraday asks xAI and Mistral streams for their usage with `stream_options.include_usage`; they report it only when asked.
+- A model priced only per minute, character, page or search unit is billed by that unit when the call reports it; the token counts its response also reports stay unbilled.
+- A Mistral chat with audio input gets a `transcription_minute` line item for its audio, so a model priced only per token is recorded `partial`.
+- A transcription or translation without `usage` is priced by its `verbose_json` `duration`, rounded up to whole seconds, through Faraday and the official openai gem, Azure OpenAI Whisper included.
+- `bin/rails llm_cost_tracker:prices:refresh` runs `backfill_unknown_pricing` after writing a new `config.pricing.file`, or prints that command when the calls ledger is not reachable.
+- `backfill_unknown_pricing` and `reprice` store the pricing mode they apply, so a Bedrock regional-profile call recorded before 0.14.2 gets `data_residency`.
+- Bundled prices drop the models Mistral lists as retired, with their aliases such as `magistral-medium-latest`, and any model its provider has stopped listing for 90 days.
+- Vertex AI calls through RubyLLM are priced at the tier their `usageMetadata.trafficType` reports, and Bedrock Converse calls at their `serviceTier`, instead of at standard rates; Provisioned Throughput, Bedrock `reserved` and tiers no bundled price lists become `unknown`, so they no longer count toward money budgets but still count toward `calls` limits, and `provisioned_throughput_*` or `reserved_*` rates in `pricing.overrides` price them.
+- Calls through the official OpenAI SDK's Bedrock provider (`OpenAI::Providers.bedrock`) are recorded as `bedrock` instead of `openai`.
+- `with_tags` tags reach fibers started inside its block, and on RubyLLM 2.1 the tool threads RubyLLM starts, until the block ends; an `ActionController::Live` action's thread keeps them for the whole action, and other threads, such as a thread pool's, get none.
+- The maintained price snapshot requires 0.15.0, so `prices:refresh` and `prices:check` on 0.14.x stop with "remote pricing snapshot requires llm_cost_tracker >= 0.15.0".
+
+### Fixed
+
+- Anthropic compaction, advisor, fallback and refusal pricing applies to RubyLLM 2.x chats, and each blocking `pause_turn` segment is priced from its own response.
+- RubyLLM 2.x Vertex AI `gemini-embedding-2` embeddings price image, audio and video tokens at their own rates instead of as text.
+- RubyLLM 2.x Bedrock Converse streams price cache writes at the cache lifetimes Bedrock reports instead of the one `with_caching` requested.
+- RubyLLM 1.x and 2.x images returned without usage are recorded with unknown cost instead of $0.
+- Gemini Omni Flash, 3.5 Transcribe (Live included) and 2.5 Computer Use calls are priced instead of recorded with unknown cost; Omni video output uses the new `video_output` rate.
+- OpenAI Ultrafast calls (`service_tier: "ultrafast"`) are priced at GPT-6 Astra's Ultrafast rates, US data residency included, instead of recorded with unknown cost.
+- GPT-Realtime-2, 2.1 and 2.1 mini get `data_residency` rates.
+- OpenAI `text-embedding-ada-002` embeddings, reported as `text-embedding-ada-002-v2`, and Mistral Embed called as `mistral-embed-2312` are priced instead of recorded with unknown cost.
+- A Chat Completions or Responses stream is recorded under the model its last event names, so a Perplexity Agent API preset such as `fast` is recorded as the model that served it.
+- Concurrent `backfill_unknown_pricing` or `reprice` runs no longer add a call's cost to the `:cache` rollups twice.
+- An empty, `0` or non-numeric `BATCH_SIZE` stops `backfill_unknown_pricing`, `reprice`, `prune` and `backfill_tag_costs` with an error.
+- JSON price files keep floats in their shortest form on json 2.11 and later (`0.951432`, not `0.9514320000000001`).
+- The Calls CSV export sorts the matching calls once instead of re-querying each 500-row batch with `OFFSET`, which was slow on large ledgers.
+- Gemini calls on a Vertex AI regional or multi-region endpoint through RubyLLM, or through the official openai gem on its OpenAI-compatible API, are priced at the non-global rates Google's Vertex AI pricing page lists from July 1, 2026, instead of its global rates.
+- Claude 4.5 and later calls on a Vertex AI regional or multi-region endpoint through RubyLLM 2.x or the Anthropic SDK's Vertex client are priced at their `data_residency` rates, Anthropic's 10% premium, instead of their global rates.
+- Claude Opus 4.1, Opus 4, Sonnet 4 and Haiku 3.5, retired on Anthropic's API but still served on Bedrock or Google Cloud, are priced at Anthropic's list prices instead of being recorded with unknown cost; Haiku 3.5 is priced under its API id `claude-3-5-haiku`.
+- RubyLLM 2.x Vertex AI batch results from a regional or multi-region job are priced at their non-global batch rates instead of their global ones.
+- Gemini models that only Google's Vertex AI pricing page prices, such as Gemini 3.8 Flash Cyber, are priced from it instead of recorded with unknown cost.
+- Claude Haiku 5.5 calls are priced instead of recorded with unknown cost, prompts over 100,000 tokens at Anthropic's higher rates for them.
+- Claude Sonnet 4.5 prompts over 200K tokens, which Bedrock and Vertex AI still serve, are priced at the long-context rates on Google's Vertex AI pricing page instead of standard rates.
+- Mistral models on sale, such as Mistral Large 4, are priced at the sale price on Mistral's pricing page instead of recorded with unknown cost.
+- Mistral Voxtral Small (`voxtral-small-2507`) chats are priced, audio input per minute at its model card's rate, instead of recorded with unknown cost.
+- OpenAI Responses streams whose hosted-tool items, such as file search results, outgrow the 1 MB capture limit are recorded with their usage and tool fees instead of with unknown cost.
+- OpenAI `responses.compact` calls are recorded, through the official openai gem and Faraday.
+- The official openai gem's `client.beta.responses` and legacy `client.completions.create` calls are recorded.
+- Azure OpenAI calls on a `*.cognitiveservices.azure.com` host are recorded as `azure_openai` instead of missed by Faraday and recorded as `openai` by the official openai gem.
+- An image edit with cached input through the official openai gem counts the cached tokens once, as Faraday does, instead of billing them again as image input.
+- RubyLLM 2.1 calls are priced at the `service_tier`, `speed` and `inference_geo` set with `with_provider_options`, which RubyLLM 2.1 no longer keeps on its raw responses.
+- `:block_requests` stops RubyLLM 2.x batch submissions, video and research jobs, RubyLLM 2.1 judgments and `RubyLLM.cache` before they are sent, and recording a cache's storage no longer raises a budget error after the cache is created.
+- `RubyLLM.cache` on Vertex AI records the cache's storage, as on the Gemini API.
+- `with_tags` in fibers sharing a thread, such as RubyLLM tools under `concurrency: :fibers`, no longer tags other fibers' calls or leaves its tags on the thread.
+- `:block_requests` checks batch submissions before they are sent: `batches.create` through the openai gem, `messages.batches.create` through the anthropic gem and `POST /v1/batches` through Faraday.
+- Faraday no longer checks the budget before Anthropic token counting or batch cancellation, which are free.
+- On MySQL, per-tag budgets read each tag value's own spend instead of merging values that differ only by case, accents or trailing spaces.
+- A budget pushed over its limit by `backfill_unknown_pricing` or `reprice`, the backfill after `prices:refresh` included, fires `on_exceeded` once.
+- A host app whose inflections define an `LLM` acronym boots and serves the dashboard instead of failing to load the engine.
+- A tag value page for a whitespace-only value, linked from the tag breakdown, renders instead of returning a 500.
+- RubyLLM 2.x Cohere embeddings record the response id, as chats do.
+- Claude calls on Vertex AI under a versioned model id, such as `claude-sonnet-4-5@20250929`, are priced instead of recorded with unknown cost.
+- Calls made under a read-only database role, such as a GET request with Rails' automatic role switching, are recorded through the writing role instead of lost, and the async inbox no longer binds to a replica; budget reads use the writing role too.
+- A stream event spanning many network reads, such as a streamed image through Faraday, is parsed in linear instead of quadratic time.
+- Recording an openai SDK response no longer walks its embedding vectors, which added up to 60% to a large `embeddings.create` call.
+- Recording a call from a thread outside the Rails executor, such as a thread pool's, no longer keeps a database connection checked out until the thread exits, and the gem no longer calls `ActiveRecord::Base.connection`, so it works with `permanent_connection_checkout = :disallowed`.
+- `close` on an official openai or anthropic SDK stream closes its HTTP response and records the call, instead of leaving the openai connection open and unrecorded.
+- `track_stream` records the call when its block leaves with `return`, `break` or `throw`; it was not recorded.
+- `doctor` reports an error when `budgets.per_tag` is set but `llm_cost_tracker_call_tags` lacks the cost columns, which leaves every per-tag budget unenforced.
+- `Ingestion::Worker.flush!` returns `false` while quarantined inbox rows keep spend out of the ledger and logs when it times out, and `doctor` warns about quarantined rows and, in inline mode, inbox rows that never reached the ledger.
+- On PostgreSQL, re-running an upgrade generator's migration after its concurrent index build was cancelled rebuilds the invalid index instead of keeping it and dropping the working one.
+- The async ingestor treats a statement timeout, a cancelled query or a dropped connection as transient, so a slow or locked ledger no longer quarantines good inbox rows.
+- On MySQL, concurrent calls for different providers under `totals_source: :cache` no longer deadlock on the rollup upsert and lose increments.
+- The Faraday middleware reads a multipart request's model only from a part starting at the request's boundary, so an uploaded file that contains a `model` field can no longer change the recorded model.
+- `prices:refresh` and a re-run of the prices generator keep `pricing.file` entries for models the bundled prices do not list, such as fine-tuned models, instead of deleting them unless marked `"_source": "manual"`, and the refresh change list no longer shows kept entries as removed.
+- `budgets.monthly`, `daily` and `per_call` given as a numeric string, such as an `ENV` value, are used as numbers instead of failing every call or never firing; a non-numeric or negative value, or an `on_exceeded` that cannot be called, raises at `configure`.
+- The Faraday middleware keeps `with_tags` and `tags.default` tags on a call when its own `tags:` proc raises; it dropped them all.
+- A `tags.default` proc that returns `nil` or `false` adds no tags; `false` failed SDK streams before the request and dropped blocking calls.
+- Usage that reports only `total_tokens`, with no input or output split, is recorded as `cost_status: unknown` on a priced model instead of `free` at $0.
+- `prices:check` and `prices:refresh` print changed rates as plain decimals instead of forms like `0.375e1`.
+- `prices:refresh` and `prices:check` write and print the snapshot URL without its credentials, query string or fragment; only known secret parameter names were masked.
+- `Ingestion::Worker.flush!` inside a request, a job or `rails runner` notices inbox rows another process drained, instead of reading a cached answer until it times out.
+- `llm_cost_tracker:backfill_tag_costs` no longer rescans the rows it already filled, which slowed it down on large tables.
+- On MySQL, the install and `upgrade_indexes` migrations no longer create `index_llm_cost_tracker_calls_on_unpriced`, which MySQL built as a plain index on `id` that no query uses.
+- The Calls page shows the CSV export's 10,000-call cap on its export link when more calls match; the cut was silent.
+- `doctor` warns when an enabled SDK integration cannot find one of the SDK classes it patches, such as a renamed resource in a newer SDK, instead of reporting it installed while those calls go unrecorded.
+- The Faraday middleware reads a request body only on LLM URLs, so a Hash body that is not valid JSON, such as binary form data, no longer fails requests to other hosts; an LLM request whose body cannot be read is recorded from its response.
+- A dashboard query that fails, such as on a statement timeout, shows a query failure page, logs the error and reports it through `Rails.error`, instead of asking you to run the install generator; the Tags page no longer shows an empty list when its query fails.
+- The warning for a response the Faraday middleware cannot process names the provider, the model and the failing line, and the async ingestor's warning names the failing line.
+
 ## [0.14.2] - 2026-09-28
 
 ### Added

data/LICENSE.txt

@@ -19,3 +19,31 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+Third-party data
+
+lib/llm_cost_tracker/prices.json includes prices derived from LiteLLM's
+model_prices_and_context_window.json (https://github.com/BerriAI/litellm),
+distributed under the following license:
+
+MIT License
+
+Copyright (c) 2023 Berri AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,20 +1,18 @@
 # LLM Cost Tracker
 
-Per-tenant LLM spend attribution and budgets for Rails — in your database, no proxy.
+LLM spend tracking and budgets for Rails: by user, feature, or any tag, in your own database, no proxy.
 
 [![Gem Version](https://img.shields.io/gem/v/llm_cost_tracker.svg)](https://rubygems.org/gems/llm_cost_tracker) [![CI](https://github.com/sergey-homenko/llm_cost_tracker/actions/workflows/ruby.yml/badge.svg)](https://github.com/sergey-homenko/llm_cost_tracker/actions) [![codecov](https://codecov.io/gh/sergey-homenko/llm_cost_tracker/branch/main/graph/badge.svg)](https://codecov.io/gh/sergey-homenko/llm_cost_tracker)
 
-Every call through RubyLLM, the official OpenAI and Anthropic SDKs, Gemini, or any OpenAI-compatible API is logged with tokens, cost, and your tags. Budgets can block a tenant's next call before it is sent.
+No prompts, no traces, no replay. Spend attribution only.
 
-Not Langfuse, Helicone, or LiteLLM. No prompts, no traces, no replay. Spend attribution only.
-
-Requires Ruby 3.3+, Rails 8.0+, PostgreSQL or MySQL.
+Requires Ruby 3.3+, Rails 8.0+, PostgreSQL or MySQL. Built for a Rails monolith, not multiple services.
 
 <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/dashboard-overview-dark.png"> <img alt="LLM Cost Tracker dashboard" src="docs/dashboard-overview-light.png"> </picture>
 
 ## Quickstart
 
-Shown with RubyLLM; the flow is identical for the official OpenAI and Anthropic SDKs — swap the gem and the `instrument` name (see the [cookbook](docs/cookbook.md)).
+Shown with RubyLLM; the flow is identical for the official OpenAI and Anthropic SDKs: swap the gem and the `instrument` name (see the [cookbook](docs/cookbook.md)).
 
 ```ruby
 # Gemfile
@@ -26,7 +24,7 @@ gem "ruby_llm"
 bin/rails llm_cost_tracker:setup
 ```
 
-Runs the install generator, drops a price snapshot, migrates the database, and verifies via `llm_cost_tracker:doctor`. Then enable the integration in the generated `config/initializers/llm_cost_tracker.rb`:
+Runs the install generator, writes a local price file, migrates the database, and verifies via `llm_cost_tracker:doctor`. Then enable the integration in the generated `config/initializers/llm_cost_tracker.rb`:
 
 ```ruby
 LlmCostTracker.configure do |config|
@@ -35,9 +33,7 @@ LlmCostTracker.configure do |config|
 end
 ```
 
-Edit it in place to add tags, switch on async ingestion, etc.
-
-Your RubyLLM calls stay unchanged — every chat, embedding, transcription, image, and moderation call now lands in the ledger. Tag them to attribute spend:
+Your RubyLLM calls stay unchanged, and every chat, embedding, transcription, image, and moderation call now lands in the ledger. Tag them to attribute spend:
 
 ```ruby
 LlmCostTracker.with_tags(user_id: Current.user&.id, feature: "chat") do
@@ -45,7 +41,7 @@ LlmCostTracker.with_tags(user_id: Current.user&.id, feature: "chat") do
 end
 ```
 
-Mount the dashboard in `config/routes.rb`, behind your auth:
+Mount the dashboard in `config/routes.rb`. The engine ships without authentication, so put it behind yours:
 
 ```ruby
 authenticate :admin do
@@ -53,52 +49,48 @@ authenticate :admin do
 end
 ```
 
-The engine ships without authentication on purpose.
-
-## What lands in the ledger
+## What it records
 
 - **Calls.** Provider, model, total tokens, total cost, latency, status.
-- **Line items.** Per-component breakdown — text/audio/cached tokens, tool charges (web search, grounding, container sessions).
-- **Tags.** Whatever attribution you pass — user, feature, tenant, env.
-- **Provider IDs.** Response, project, API key, workspace — for downstream audits.
+- **Line items.** Per-component breakdown: text/audio/cached tokens, tool charges (web search, grounding, container sessions).
+- **Tags.** Whatever attribution you pass: user, feature, tenant, env.
+- **Provider IDs.** Response, plus project, API key and workspace when you pass them to `track` or `track_stream`, for downstream audits.
 - **Pricing snapshot.** So historical numbers don't drift when prices change.
 
-## Capture surfaces
+## Budgets
+
+Daily, monthly, and per-call limits, plus per-tag limits such as one monthly budget per `tenant_id`, or a lifetime cap in dollars or calls per agent run (`run_id`, which `RubyLLM.workflow` sets on its calls). A crossed limit calls your `on_exceeded` hook, raises, or blocks the next call before it is sent. See [Budgets](docs/budgets.md).
 
-| Surface | Path |
+## Supported clients
+
+| Client | Captured through |
 | --- | --- |
-| RubyLLM | Provider layer |
-| OpenAI | Official SDK or Faraday |
-| Anthropic | Official SDK or Faraday |
-| Azure OpenAI | Faraday or official SDK (auto-detected on `*.openai.azure.com` and Foundry `*.services.ai.azure.com`, both deployments and `/openai/v1/...`) |
-| Google Gemini | Faraday |
-| `ruby-openai` | Faraday |
-| OpenRouter, DeepSeek, Groq; xAI, Mistral, and other gateways (LiteLLM etc.) once their host is added to `config.capture.openai_compatible_providers` | OpenAI-compatible Faraday, or the official OpenAI SDK with `base_url` on that host |
-| Anything else | `LlmCostTracker.track` |
+| RubyLLM | Instrumentation events (2.x) or the provider layer (1.x) |
+| OpenAI, Anthropic | Official SDK or Faraday |
+| Azure OpenAI | Official SDK or Faraday, on `*.openai.azure.com`, and Foundry `*.services.ai.azure.com` or `*.cognitiveservices.azure.com` |
+| Google Gemini, `ruby-openai` | Faraday |
+| OpenRouter, DeepSeek, Groq, xAI, Mistral, Perplexity | Faraday, or the official OpenAI SDK with `base_url` on that host |
+| Other OpenAI-compatible gateways | The same, once the host is added to `config.capture.openai_compatible_providers` |
+| Anything else | [`LlmCostTracker.track`](#manual-tracking) |
+
+Streams are recorded from the provider's final usage; see [Streaming](docs/streaming.md).
 
-Streams capture when the provider emits final usage. OpenAI Faraday streams to `/chat/completions` get `stream_options: { include_usage: true }` auto-injected so the final usage chunk lands in the ledger (opt out via `config.capture.request_stream_usage = false`).
+## Pricing
 
 Captured does not always mean priced:
 
 | Cost comes from | Calls |
 | --- | --- |
-| The amount billed, from `usage.cost` in the response or final stream chunk | OpenRouter through Faraday, the official OpenAI SDK, or `track_stream`, and any OpenAI-compatible gateway that returns `usage.cost`; bundled prices apply when it is missing or the call comes through RubyLLM, other than an OpenRouter chat |
-| Bundled [`prices.json`](lib/llm_cost_tracker/prices.json) | The OpenAI, Anthropic, Gemini, Groq, OpenRouter, xAI, and Mistral models it lists, and the same Claude models on Bedrock through RubyLLM |
+| The billed amount in the response or final stream chunk: `usage.cost`, xAI's `usage.cost_in_usd_ticks`, or Perplexity's `usage.cost.total_cost` | OpenRouter, xAI, Perplexity, and other OpenAI-compatible gateways that return one (through RubyLLM 1.x, OpenRouter, xAI, and Perplexity chats only) |
+| Bundled [`prices.json`](lib/llm_cost_tracker/prices.json), read from each provider's own pricing page or API | The OpenAI, Anthropic, Gemini, Groq, OpenRouter, xAI, Mistral, DeepSeek, and Cohere models it lists, DeepSeek at its off-peak rates in its off-peak hours, and the same Claude models on Bedrock through RubyLLM |
 | The OpenAI, Anthropic, or Gemini price for the same model name | Azure OpenAI (by the model in the response, not the deployment name), Vertex AI through RubyLLM, gateways that pass a listed model name through |
-| Nothing: recorded with `cost_status: unknown` | DeepSeek, and through RubyLLM also Perplexity, Ollama, other Bedrock models, and Claude on GovCloud (`us-gov.` profiles) |
-
-Add missing prices to `config.pricing.file` or `config.pricing.overrides` ([Pricing](docs/pricing.md)), then run `bin/rails llm_cost_tracker:backfill_unknown_pricing` to price the calls already recorded.
-
-## What it isn't
+| Nothing: recorded with `cost_status: unknown` | Perplexity without a billed amount (its Router) when no price lists its model, calls through the official OpenAI SDK's Bedrock provider, and through RubyLLM also Ollama, Cohere models without a bundled price (such as Command A+, Embed 4, and Rerank 3.5), other Bedrock models, and Claude on GovCloud (`us-gov.` profiles) |
 
-- No proxy. Direct calls only.
-- No prompts. Token counts and metadata only.
-- No traces, evals, or prompt management. Different product, different gem.
-- Not multi-service. Built for a Rails monolith.
+Add missing prices to `config.pricing.file` or `config.pricing.overrides` ([Pricing](docs/pricing.md)), then run `bin/rails llm_cost_tracker:backfill_unknown_pricing` to price the calls already recorded. `bin/rails llm_cost_tracker:prices:refresh` runs it after writing a new `config.pricing.file` if the database is reachable.
 
 ## Manual tracking
 
-For batch jobs, internal gateways, or anything without an SDK/Faraday hook:
+For batch jobs, internal gateways, or anything without an SDK or Faraday hook:
 
 ```ruby
 LlmCostTracker.track(
@@ -135,4 +127,4 @@ bin/check
 
 ## License
 
-MIT — see [LICENSE.txt](LICENSE.txt).
+MIT. See [LICENSE.txt](LICENSE.txt).

data/app/controllers/llm_cost_tracker/application_controller.rb

@@ -20,7 +20,7 @@ module LlmCostTracker
     rescue_from ActiveRecord::ConnectionNotEstablished, with: :render_database_error
     rescue_from ActiveRecord::AdapterNotSpecified, with: :render_database_error
     rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
-    rescue_from ActiveRecord::StatementInvalid, with: :render_database_error
+    rescue_from ActiveRecord::StatementInvalid, with: :render_query_error
     rescue_from LlmCostTracker::InvalidFilterError, with: :render_invalid_filter
 
     private
@@ -52,6 +52,12 @@ module LlmCostTracker
       render_error_page("database", :internal_server_error)
     end
 
+    def render_query_error(error)
+      Logging.warn("Dashboard query failed: #{error.class}: #{error.message}")
+      Rails.error.report(error, handled: true)
+      render_error_page("query", :internal_server_error)
+    end
+
     def render_invalid_filter(error)
       @error_message = error.message
       render_error_page("invalid_filter", :bad_request)

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -1,37 +1,18 @@
 # frozen_string_literal: true
 
-require "csv"
-require "json"
-
 module LlmCostTracker
   class CallsController < ApplicationController
     CSV_EXPORT_LIMIT = 10_000
     CSV_EXPORT_BATCH_SIZE = 500
-    CSV_FORMULA_PREFIXES = ["=", "+", "-", "@", "\t", "\r"].freeze
-    DEFAULT_TIEBREAKER = { tracked_at: :desc, id: :desc }.freeze
-    SORT_OPTIONS = %w[tracked_at provider model input output cost latency].freeze
-    NULLS_LAST_GUARD = {
-      total_cost: Arel.sql("CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END ASC"),
-      latency_ms: Arel.sql("CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC")
-    }.freeze
 
     def index
       scope = Dashboard::Filter.call(params: params)
       scope = scope.unknown_pricing if params[:cost_status].to_s == "incomplete"
-      ordered_scope = scope.order(*calls_order(params[:sort].to_s, params[:dir].to_s))
+      ordered_scope = Dashboard::CallOrder.call(scope, sort: params[:sort], direction: params[:dir])
 
       respond_to do |format|
-        format.html do
-          @page = Dashboard::Pagination.call(params)
-          @calls_count, @calls_total_cost = scope.pick(Arel.sql("COUNT(*), COALESCE(SUM(total_cost), 0)"))
-          @calls = ordered_scope.includes(:tag_records).limit(@page.per).offset(@page.offset).to_a
-        end
-        format.csv do
-          response.headers["Cache-Control"] = "no-store"
-          send_data render_csv(ordered_scope),
-                    type: "text/csv",
-                    disposition: %(attachment; filename="llm_calls_#{Time.now.utc.strftime('%Y%m%d_%H%M%S')}.csv")
-        end
+        format.html { assign_page(scope, ordered_scope) }
+        format.csv { send_csv(ordered_scope) }
       end
     end
 
@@ -41,80 +22,17 @@ module LlmCostTracker
 
     private
 
-    def calls_order(sort, dir)
-      column = SORT_OPTIONS.include?(sort) ? sort.to_sym : :tracked_at
-      natural = %i[provider model].include?(column) ? :asc : :desc
-      direction = Dashboard::Sort::DIRECTIONS.include?(dir.downcase) ? dir.downcase.to_sym : natural
-
-      case column
-      when :tracked_at then [{ tracked_at: direction, id: direction }]
-      when :provider   then [{ provider: direction, model: :asc, **DEFAULT_TIEBREAKER }]
-      when :model      then [{ model: direction, **DEFAULT_TIEBREAKER }]
-      when :input      then [{ input_tokens: direction, **DEFAULT_TIEBREAKER }]
-      when :output     then [{ output_tokens: direction, **DEFAULT_TIEBREAKER }]
-      when :cost       then [NULLS_LAST_GUARD[:total_cost], { total_cost: direction, **DEFAULT_TIEBREAKER }]
-      when :latency    then [NULLS_LAST_GUARD[:latency_ms], { latency_ms: direction, **DEFAULT_TIEBREAKER }]
-      end
-    end
-
-    def render_csv(relation)
-      fields = csv_fields
-      CSV.generate do |csv|
-        csv << fields.map(&:to_s)
-        each_export_batch(relation) do |call|
-          csv << fields.map { |field| csv_value(field, call) }
-        end
-      end
-    end
-
-    def each_export_batch(relation, &)
-      offset = 0
-      while offset < CSV_EXPORT_LIMIT
-        batch_size = [CSV_EXPORT_BATCH_SIZE, CSV_EXPORT_LIMIT - offset].min
-        batch = relation.limit(batch_size).offset(offset).preload(:tag_records).to_a
-        break if batch.empty?
-
-        batch.each(&)
-        offset += batch.size
-      end
-    end
-
-    def csv_fields
-      %i[tracked_at provider model] +
-        Usage::TokenUsage.members +
-        %i[
-          total_cost cost_status pricing_snapshot latency_ms provider_response_id provider_project_id
-          provider_api_key_id provider_workspace_id batch tags
-        ]
+    def assign_page(scope, ordered_scope)
+      @page = Dashboard::Pagination.call(params)
+      @calls_count, @calls_total_cost = scope.pick(Arel.sql("COUNT(*), COALESCE(SUM(total_cost), 0)"))
+      @calls = ordered_scope.includes(:tag_records).limit(@page.per).offset(@page.offset).to_a
     end
 
-    def csv_value(field, call)
-      case field
-      when :tracked_at
-        call.tracked_at.utc.iso8601
-      when :provider_api_key_id, :provider_workspace_id, :provider_project_id
-        csv_safe(LlmCostTracker::Dashboard::Masking.mask_value(field, call[field]))
-      when :provider, :model, :provider_response_id, :cost_status
-        csv_safe(call[field])
-      when :pricing_snapshot
-        csv_safe(csv_json(call.pricing_snapshot))
-      when :tags
-        csv_safe(call.tag_pairs.to_json)
-      else
-        call[field]
-      end
-    end
-
-    def csv_json(value)
-      Hash(value).deep_stringify_keys.to_json
-    end
-
-    def csv_safe(value)
-      return value if value.nil?
-
-      string = value.to_s
-      stripped = string.lstrip
-      CSV_FORMULA_PREFIXES.include?(stripped[0]) ? "'#{string}" : string
+    def send_csv(relation)
+      response.headers["Cache-Control"] = "no-store"
+      send_data Dashboard::CallsExport.call(relation, limit: CSV_EXPORT_LIMIT, batch_size: CSV_EXPORT_BATCH_SIZE),
+                type: "text/csv",
+                disposition: %(attachment; filename="llm_calls_#{Time.now.utc.strftime('%Y%m%d_%H%M%S')}.csv")
     end
   end
 end

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -3,19 +3,14 @@
 module LlmCostTracker
   class DashboardController < ApplicationController
     def index
-      prev_from, prev_to = previous_range
-      filter_params = LlmCostTracker::Dashboard::Params.to_hash(params)
-      scope = Dashboard::Filter.call(
-        params: filter_params.merge("from" => @from_date.iso8601, "to" => @to_date.iso8601)
-      )
-      previous_scope = Dashboard::Filter.call(
-        params: filter_params.merge("from" => prev_from.iso8601, "to" => prev_to.iso8601)
-      )
+      previous_from, previous_to = previous_range
+      scope = scope_between(@from_date, @to_date)
+      previous_scope = scope_between(previous_from, previous_to)
 
       @stats = Dashboard::OverviewStats.call(scope: scope, previous_scope: previous_scope)
       @monthly_budget_status = Dashboard::MonthlyBudget.status
       @time_series = Dashboard::TimeSeries.call(scope: scope, from: @from_date, to: @to_date)
-      @comparison_series = Dashboard::TimeSeries.call(scope: previous_scope, from: prev_from, to: prev_to)
+      @comparison_series = Dashboard::TimeSeries.call(scope: previous_scope, from: previous_from, to: previous_to)
       @spend_anomaly = Dashboard::SpendAnomaly.call(from: @from_date, to: @to_date, scope: scope)
       @top_models = Dashboard::TopModels.call(scope: scope)
       @providers = Dashboard::ProviderBreakdown.call(scope: scope)
@@ -23,11 +18,15 @@ module LlmCostTracker
 
     private
 
+    def scope_between(from, to)
+      filter_params = Dashboard::Params.to_hash(params).merge("from" => from.iso8601, "to" => to.iso8601)
+      Dashboard::Filter.call(params: filter_params)
+    end
+
     def previous_range
       span_days = (@to_date - @from_date).to_i + 1
-      prev_to = @from_date - 1
-      prev_from = prev_to - (span_days - 1)
-      [prev_from, prev_to]
+      previous_to = @from_date - 1
+      [previous_to - (span_days - 1), previous_to]
     end
   end
 end

data/app/controllers/llm_cost_tracker/pricing_controller.rb

@@ -4,13 +4,24 @@ module LlmCostTracker
   class PricingController < ApplicationController
     def index
       @overview = Dashboard::PricingOverview.call
-      requested = params[:source].to_s.to_sym
-      @active_source = @overview.fetch(:sources).key?(requested) ? requested : @overview.fetch(:effective_source)
+      @active_source = requested_source || @overview.fetch(:effective_source)
       @source_data = @overview.fetch(:sources).fetch(@active_source)
       @provider_filter = Dashboard::Params.scalar(params[:provider], :provider).presence
-      @rows = @source_data.fetch(:rows)
-      @rows = @rows.select { |row| row.provider == @provider_filter } if @provider_filter
       @providers = @source_data.fetch(:rows).map(&:provider).compact.uniq.sort
+      @rows = provider_rows(@source_data.fetch(:rows))
+    end
+
+    private
+
+    def requested_source
+      source = params[:source].to_s.to_sym
+      source if @overview.fetch(:sources).key?(source)
+    end
+
+    def provider_rows(rows)
+      return rows unless @provider_filter
+
+      rows.select { |row| row.provider == @provider_filter }
     end
   end
 end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -10,22 +10,29 @@ module LlmCostTracker
       @value = Dashboard::Params.scalar(params[:tag_value], :tag_value)
 
       if @value.empty?
-        @breakdown = Dashboard::TagBreakdown.call(
-          scope: Dashboard::Filter.call(params: params),
-          key: params[:key],
-          sort: params[:sort].to_s,
-          direction: params[:dir].to_s
-        )
+        assign_breakdown
       else
-        @key = LlmCostTracker::Tags::Key.validate!(
-          params[:key],
-          error_class: LlmCostTracker::InvalidFilterError
-        )
-        value_scope = Dashboard::Filter.call(params: params, tags: { @key => @value })
-        @value_total_cost = value_scope.sum(:total_cost).to_f
-        @value_calls = value_scope.count
-        @value_points = Dashboard::TimeSeries.call(scope: value_scope, from: @from_date, to: @to_date)
+        assign_value_trend
       end
     end
+
+    private
+
+    def assign_breakdown
+      @breakdown = Dashboard::TagBreakdown.call(
+        scope: Dashboard::Filter.call(params: params),
+        key: params[:key],
+        sort: params[:sort].to_s,
+        direction: params[:dir].to_s
+      )
+    end
+
+    def assign_value_trend
+      @key = LlmCostTracker::Tags::Key.validate!(params[:key], error_class: LlmCostTracker::InvalidFilterError)
+      value_scope = Dashboard::Filter.call(params: params, tags: { @key => @value })
+      @value_total_cost = value_scope.sum(:total_cost).to_f
+      @value_calls = value_scope.count
+      @value_points = Dashboard::TimeSeries.call(scope: value_scope, from: @from_date, to: @to_date)
+    end
   end
 end