llm_cost_tracker 0.13.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec6d42366ce33ab5b2d4847d4ad425dd4d4262a302212427be2a3fc55db53fcc
-  data.tar.gz: 57f6eaa22546be19cc3b17afeed107fb35782ad5de4b6ed9646a4d7955cab589
+  metadata.gz: af338b0d20bfcbdfd9b95a88f903fa2a6b22dab16c72857a48bb2ff6ac0e9ac6
+  data.tar.gz: e2688d3cc3d29795787602ccf79b70dbe541347884644b3d5d234d1635f3f4b9
 SHA512:
-  metadata.gz: 716c326903ac571988211ee34f2ff2a43d6cec3d6b8d00a1682df5d245877e7884f8b3e3b3e9d86e37b0089a73f97f3dc1b4c7cbbf1c40a1365702acef7e5f6b
-  data.tar.gz: ef41e457bafea063396e7ab08d2c7f6c051c1831ec7476071e36b08af7812853c7e1501fc4d7986658de726316c136e562b747eec26316ffd97a7ee6ee7eda2a
+  metadata.gz: d4e06cd0bab7dd941fb958ca5fff5b6844ba17879f04bd3370258864e7ebd390088e091d2e0bd7f6fd839fcf05ecf3bc79f954b918c5b0b1cea471e1d14a413b
+  data.tar.gz: 107d59de744aabfbf946cbc38ce9ad705b4562a516446163dfb4834102ea263065d67e72c302c75f90ac887c12dfe11c404e85256e46300cd5a2ebe73b61b3af

data/CHANGELOG.md

@@ -2,7 +2,100 @@
 
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.14.1] - 2026-09-25
+
+### Added
+
+- `bin/rails llm_cost_tracker:doctor` and the boot log warn when an instrumented SDK is newer than its tested range (RubyLLM 3.0 and later), instead of the integration reporting installed while it records nothing.
+
+### Changed
+
+- Ruby 3.3 is supported; the minimum drops from 3.4.
+- The Faraday middleware adds `stream_options: { include_usage: true }` only for OpenAI, OpenRouter, DeepSeek, Groq, and Azure OpenAI on the v1 API or `api-version` 2024-06-01 and later without On Your Data or image input, since other servers can reject it and fail the request. Hosts you add to `config.capture.openai_compatible_providers` are left untouched: set the flag yourself if they support it, or their streams record `usage_source: unknown` with a warning.
+- `bin/rails llm_cost_tracker:prices:refresh` refuses a snapshot that zeroes an existing price or charges for a free one, drops a model's `input` or `output` rate, moves a price 100-fold or more, or switches currency, and leaves your pricing file untouched, so one bad commit to the snapshot can no longer silence budgets or make `:block_requests` block every call. `PREVIEW=1` and `prices:check` list the changes; re-run with `FORCE=1` (or `force: true`) to accept them. New models and smaller changes are not checked, so keep reviewing the refreshed file.
+- `pricing.unknown_model_behavior = :raise` records the call, with `cost_status: unknown`, before it raises `LlmCostTracker::UnknownPricingError`, so a call the provider already billed is no longer missing from the ledger.
+- A malformed `pricing.file` fails `LlmCostTracker.configure` at boot instead of every LLM call. A missing one is logged at boot and reported as an error by `doctor`, and calls use bundled prices until `prices:refresh` creates it; before, every call raised and nothing was recorded.
+
+### Removed
+
+- An OpenAI or Anthropic SDK stream that your code never iterates is no longer recorded at garbage collection; the finalizer that did it kept every stream alive until process exit.
+
+### Fixed
+
+- Per-tag `:block_requests` budgets check tags passed to the Faraday middleware (`f.use :llm_cost_tracker, tags: ...`) before the call is sent; they saw only `with_tags` tags, so an over-budget tenant still reached the provider.
+- RubyLLM transcriptions are priced at the model's audio input rate when it has one; they were priced as text, at a third to a half of the real cost.
+- `RubyLLM.transcribe` with a Gemini or Vertex AI model on RubyLLM 1.x is recorded; RubyLLM 1.x sent it through its own Gemini method, bypassing the wrapped `RubyLLM::Provider#transcribe`.
+- Calls made through RubyLLM 2.x are recorded. RubyLLM 2.0 moved token counts behind `response.tokens`, so every call was dropped with a warning while `doctor` reported the integration installed. A 2.x `paint(count:)` returning several images is recorded once, as RubyLLM bills it.
+- An automatically captured LLM call no longer fails, losing the provider's response, when the gem cannot record it, such as when the async inbox pool times out. Only `BudgetExceededError`, `UnknownPricingError` under `:raise`, and `TransactionAbortedError` reach your code; other recording failures are logged. `LlmCostTracker.track` and `track_stream` still raise them.
+- A recording error no longer replaces an exception your code raised while iterating an OpenAI or Anthropic SDK stream or inside `track_stream`, such as `Sidekiq::Shutdown`; the stream is still recorded, tagged `stream_errored`, and the recording error is logged. `TransactionAbortedError` still wins, with your exception as its cause.
+- An OpenAI or Anthropic batch with an unpriced model under `:raise`, or one crossing a budget, records every result before raising once; results after the failing one were lost and `batches.retrieve` raised on every poll.
+- With `ingestion.mode = :async`, one inbox row the database rejects no longer fails its whole batch, which after five attempts quarantined up to 99 other calls and dropped them from the ledger and budget totals. A failed batch is retried one row at a time and only rejected rows are marked failed. Rows already quarantined this way can be requeued as described in `docs/operations.md`.
+- A NUL byte in a stored string, which PostgreSQL rejects, or invalid UTF-8 in a tag value no longer loses the call, and `LlmCostTracker.with_tags` no longer raises on invalid UTF-8. NUL bytes are removed on write, including from inbox rows written by earlier releases, and invalid UTF-8 in tag values becomes U+FFFD.
+- An interrupted Gemini or Azure stream records its model from the request URL instead of `unknown`.
+- The async inbox's `last_error` is no longer empty when the 1,000-byte cut splits a multibyte character.
+- An LLM call inside your own database transaction no longer breaks it when the ledger write fails; on PostgreSQL your app's writes were lost with `PG::InFailedSqlTransaction`. Ledger writes, budget reads, and batch de-duplication run in a savepoint inside an open transaction. On MySQL, where a deadlock rolls back your whole transaction, the gem raises `LlmCostTracker::TransactionAbortedError` instead of swallowing it.
+- With `config.budgets.totals_source = :cache`, the rollup increment inside your transaction waits for its commit on Rails 7.2 and later, so an open transaction no longer holds the rollup row lock and stalls every request recording spend for the same provider. On Rails 7.1 and in non-joinable transactions such as transactional fixtures it still runs immediately, and it is never retried inside a transaction.
+- Long streams record their real usage instead of zero tokens and `$0`. Streams were buffered up to 1 MB, dropping the final usage event (past about 3,000 output tokens through Faraday); they are now decoded as they arrive, keeping only the first and last events plus billable tool-call and grounding events, so memory stays flat at any length. Image streams through Faraday keep their final usage too.
+- Streams captured through the OpenAI and Anthropic SDK integrations are released once your code drops them, instead of staying in memory with their buffered events and request for the life of the process.
+- OpenAI Realtime cached audio is no longer billed twice, at the cache-read rate and again at the audio rate ($0.258 instead of $0.106 for a 10,000-token `gpt-realtime` turn with 5,000 cached audio tokens). Cached audio and image tokens are priced at the model's cache-read rate, below OpenAI's published cached-audio price on the mini models. OpenAI-compatible usage whose audio and image buckets exceed the reported input has the overlap taken out of audio input, then image input.
+- Dashboard links and filter forms carry only the dashboard's own query parameters. They copied every parameter, and Rails reads some as link options, so a crafted link such as `?script_name=//evil.example` pointed Export CSV, pagination, filter, and tag links at another site, others rewrote links or caused a 500, and a 50 KB junk parameter grew a tag page to 10 MB. A query string over 16 KB is a bad request.
+- A dashboard page accepts at most 10 `tag[...]` filters, counting a tag value page's own value, and answers more with a bad request. Each filter adds a subquery, so PostgreSQL planning memory grew with the square of their count, and around 700 got the backend killed for running out of memory, restarting the database. Tag breakdowns no longer offer drill-down links past the limit.
+- Dashboard filters handle bad input without a 500. A list or hash in a tag, provider, model, stream, or usage-source filter is a bad request instead of silently matching nothing, and a NUL byte in a filter value matches nothing on PostgreSQL instead of raising. A CSV export with an invalid filter, a missing call, or a database error renders an HTML error page with the right status instead of a 500 or HTML labelled as CSV. A tag value page's value overrides a filter on the same key, and tag pages for keys containing a dot, such as `/tags/team.name`, load instead of returning 404 or 406.
+- The Pricing page shows the active price source instead of a 500 when `source` is a list or hash, as in `/pricing?source[]=bundled`; a list or hash `provider` filter is a bad request, as on other pages.
+
+### Security
+
+- From v0.9.0 through v0.14.0, a provider API key sent as a URL parameter could be stored in call tags. When a middleware after `f.use :llm_cost_tracker`, such as `f.response :raise_error`, raised on a streamed Gemini `?key=` or Azure `?api-key=` request, the `stream_interrupted_error` tag stored Faraday's error message with the full URL, shown on the dashboard, in CSV exports, and in notification payloads. The tag now holds only the error class, and the HTTP status goes into a new `stream_interrupted_status` tag. Rotate any key that may have been exposed, and clear stored messages with `UPDATE llm_cost_tracker_call_tags SET value = split_part(value, ': ', 1) WHERE key = 'stream_interrupted_error'` on PostgreSQL or ``UPDATE llm_cost_tracker_call_tags SET value = SUBSTRING_INDEX(value, ': ', 1) WHERE `key` = 'stream_interrupted_error'`` on MySQL. With async ingestion, run it after the inbox drains, and delete quarantined inbox rows whose `payload` contains `stream_interrupted_error`.
+- Provider keys, tokens, `key=`/`token=`/`sig=` URL parameters, URL user info, and `Authorization` headers inside a longer string are replaced with `[REDACTED]` in tag values, log lines, the async inbox's `last_error`, `TransactionAbortedError` messages, and the `source_url` that `llm_cost_tracker:prices:refresh` writes and prints; before, only a tag value that was entirely a key was caught.
+
+## [0.14.0] - 2026-08-26
+
+### Added
+
+- `config.budgets.per_tag` applies one budget to every distinct value of each declared tag — `{ tenant_id: { monthly: 1000 }, user_id: { daily: 25 } }` gives every tenant its own 1000 a month and every user its own 25 a day, for as many tags as you declare. Windows are `daily`, `weekly`, and `monthly`; a rule can set its own `behavior` and `on_exceeded` or fall back to the global ones, and the payload names the tag and value that crossed. A fresh install is ready for it; an install created before v0.14 runs `bin/rails generate llm_cost_tracker:upgrade_per_tag_budgets`, then `bin/rails llm_cost_tracker:backfill_tag_costs` to count spend recorded before the upgrade.
+- The Data Quality page names any `config.budgets.per_tag` tag that no recorded call carries, so a mistyped tag name shows up as a budget that can never fire instead of silently enforcing nothing. The list clears itself as soon as a call arrives with that tag, and stays hidden until something has been tagged at all.
+- Gemini calls that ground against Google Search are costed. The rate comes from each model's own published `grounding_request` price — $35 per 1,000 on Gemini 2.x, $14 on 3.x — so a grounded call lands `complete` instead of `unknown`. Google's free monthly allowance is account-level and is not modelled, so a project still inside it is over-reported.
+- OpenAI's duration-billed audio models — `gpt-transcribe`, `gpt-live-transcribe`, `gpt-realtime-whisper`, `gpt-realtime-translate` — are priced per minute of audio. They publish no token price, so these calls previously recorded no cost at all.
+- OpenAI gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna are priced, including their cache-write rates across standard, batch, flex, priority, long-context, and data-residency tiers.
+- Cache writes reported in OpenAI usage (`cache_write_tokens`, GPT-5.6 and later) are captured and costed at the model's cache-write rate instead of being counted as regular input.
+- Anthropic thinking tokens are counted as hidden output on the Data Quality page, so reasoning Claude already billed inside `output_tokens` is visible instead of reading as zero. Cost is unchanged — `output_tokens` stays the billable total.
+
+### Changed
+
+- BREAKING: a call the gem never found a rate for records `cost_status: unknown` instead of `free`. `free` covered both "priced at zero" and "never priced", so token-billed endpoints the parser captured no quantities for — `gpt-4o-mini-tts`, Whisper transcription, any unrecognised model — reported as costing nothing. Genuinely unbilled endpoints such as moderations move to `unknown` as well and appear on the Data Quality page.
+- BREAKING: `enforce_budget: true` on `LlmCostTracker.track` records the call before it raises, and the error carries `stage: :post_spend` instead of `:pre_send`. `track` reports a request the provider already served, so the old order threw away real spend — and with the ledger total never advancing, every later call raised and was dropped too. `LlmCostTracker.track_stream` still raises `:pre_send`, before your block runs.
+- BREAKING: `pricing_snapshot["rates"]` is keyed by the rate actually applied, so a batch call reads `batch_input` rather than `input`. The old key named a row whose value in the price table was a different number.
+- `bin/rails llm_cost_tracker:backfill_unknown_pricing` no longer scans the whole ledger on every batch — unpriced calls are found through a partial index. Existing installs pick this up with `bin/rails generate llm_cost_tracker:upgrade_indexes`, which also drops the ingestion inbox lock index the drain never uses.
+- `bin/rails llm_cost_tracker:prune` warns with the count and cost when it deletes inbox rows that never reached the ledger, instead of dropping that spend silently.
+- The unpriced-model warning names the tier as well, so a call at a pricing mode you have no rate for reads `model "gpt-5.5" at pricing_mode "scale"` instead of pointing at the model.
+- The models page caps at 200 rows and an out-of-range `page` no longer renders a database error.
+
+### Deprecated
+
+- Configuration options are grouped into `budgets`, `capture`, `ingestion`, `pricing`, and `tags` — `config.budgets.monthly` replaces `config.monthly_budget`, and so on. Flat names still work and warn with their replacement; they are removed in 1.0. See [docs/upgrading.md](docs/upgrading.md#v013--v014) for the full mapping.
+- `config.log_level` is dropped with no replacement — it never affected any log output.
+
+### Removed
+
+- Bundled prices for OpenAI models past their published shutdown date are dropped, so repricing a call to a retired model reports unknown pricing instead of a stale rate.
+
+### Fixed
+
+- OpenAI responses that break the completion into `text_tokens` are costed on the full billed output again. Reasoning tokens were dropped from the total, so a 1,000-token completion with 800 reasoning tokens recorded $0.011 instead of $0.035 while still reporting `cost_status: complete`.
+- Anthropic calls are priced from the `speed` the response reports rather than the one the request asked for, so a `fast` response no longer records at standard rates — half its real cost on `claude-opus-5`.
+- OpenAI regional calls on gpt-5.6 models are billed at their data-residency rates. Eligibility now comes from the price table instead of a hard-coded model list, which had not caught up with the codename models.
+- Apps that set `config.logger` to a plain `Logger` no longer take a `NoMethodError` from inside the tracker. Every warning went through `Rails.logger.tagged`, which those apps do not have, so a rollup or ingestion failure raised into the request instead of being logged, and the async worker thread died on its first warning.
+- Filtering the dashboard by a tag survives the date, provider, model and stream filters. Submitting any of them flattened `tag[env]=prod` into a single `tag` value, silently dropping the filter and showing a larger total under an unchanged header.
+- A call whose tag value is a large hash or array is recorded instead of failing the whole insert. The encoded value is capped to fit the tag index; the scalar cap alone did not bound a composite.
+- `Call.unknown_pricing` composes with `cost_by_tag` and `group_by_tag` again instead of raising on an ambiguous `total_cost`.
+- A rollup increment that may already have been applied is no longer retried, so a dropped connection cannot leave the cache — and every budget read — above the real spend.
+- The dashboard recovers on its own when the schema catches up. A process that started before `db:migrate` cached "Setup required" until it was restarted.
+- Async inbox writes work after a fork, instead of raising into the request for the life of the child process.
+- A completed OpenAI batch is retried when its result download fails, instead of being marked captured and never recorded.
+- `bin/rails llm_cost_tracker:doctor` reports drift in the async inbox and lease tables, not just their absence.
+- OpenAI gpt-5.4, gpt-5.4-pro, and gpt-5.5 prompts above 272K input tokens are costed at OpenAI's published long-context premium (2x input, 1.5x output on standard, batch, and flex) instead of the flat short-context rate.
+- `bin/rails llm_cost_tracker:backfill_unknown_pricing` no longer aborts on the default configuration; repricing calls with unknown pricing no longer requires opting into `config.budgets.totals_source = :cache`.
+- Setting `config.budgets.totals_source = :cache` without creating `llm_cost_tracker_call_rollups` no longer breaks dashboard and budget reads; totals fall back to aggregating the calls ledger and a log warning names the missing table.
 
 ## [0.13.0] - 2026-06-26
 
@@ -30,7 +123,7 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ### Removed
 
-- BREAKING: the experimental `Reconciliation` subsystem (provider invoice import + diff, the `/reconciliation` dashboard page, `bin/rails llm_cost_tracker:reconcile:*` rake tasks, `config.reconciliation_enabled`, `config.reconciliation_importers`, the `llm_cost_tracker:reconciliation` generator, and the `llm_cost_tracker_provider_invoices` / `_provider_invoice_imports` tables) is gone. It was never finished and never billing-accurate. `calls.provider_response_id` (captured on every call) already covers invoice cross-reference; if invoice-vs-ledger reconciliation ships again it lives in a separate gem. Existing installs can drop the two tables — see [docs/upgrading.md](docs/upgrading.md#v011--v012-unreleased).
+- BREAKING: the experimental `Reconciliation` subsystem (provider invoice import + diff, the `/reconciliation` dashboard page, `bin/rails llm_cost_tracker:reconcile:*` rake tasks, `config.reconciliation_enabled`, `config.reconciliation_importers`, the `llm_cost_tracker:reconciliation` generator, and the `llm_cost_tracker_provider_invoices` / `_provider_invoice_imports` tables) is gone. It was never finished and never billing-accurate. `calls.provider_response_id` (captured on every call) already covers invoice cross-reference; if invoice-vs-ledger reconciliation ships again it lives in a separate gem. Existing installs can drop the two tables — see [docs/upgrading.md](docs/upgrading.md#v011--v012).
 - `config.instrument :gemnii` (or any other typo / unknown integration name) no longer raises at config time — it now logs `Logging.warn("Unknown integration: :gemnii. Known: ...")` once when integrations install, and `bin/rails llm_cost_tracker:doctor` shows the unknown name as a `:warn` row so the typo is visible without crashing boot.
 - Pre-call budget enforcement for Azure-hosted OpenAI calls now keys on `"azure_openai"` (matching the recorded `Call.provider`), so `pricing_overrides` for Azure rates actually gate the call. Previously it always keyed on `"openai"` regardless of the SDK client's `base_url`.
 - BREAKING: removed the `batch:` keyword argument from `LlmCostTracker.track`, `LlmCostTracker.track_stream`, and `stream.usage` (inside `track_stream` blocks). Signal a batch-tier call via `pricing_mode: :batch` (or any pricing_mode containing the `batch` token like `:batch_flex`) — that's the single source of truth now. Previously `batch:` and `pricing_mode:` could disagree, especially after request-side pricing_mode merge inside `Tracker.record` overwrote the parser's mode but left the stored `batch` flag stale, so `calls.batch` could read `true` while `calls.pricing_mode` read `flex` (or vice versa) for the same row.
@@ -40,7 +133,7 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 - The RubyLLM SDK integration now requires `ruby_llm >= 1.15.0` (was `>= 1.14.1`).
 - Engine no longer adds `tag` / `tag_value` to Rails `filter_parameters` — the Symbol filter was substring-matching unrelated host-app params (`tags`, `meta_tag`, etc.) into `[FILTERED]`. `Tags::Sanitizer` continues redacting secret-shaped tag values at storage.
-- BREAKING: the serialized event `cost` (the `llm_request.llm_cost_tracker` notification payload and the async-ingestion inbox payload) is now `{ components: {...}, total:, currency: }` (was flat with a top-level `total_cost:`). Notification subscribers should read `cost[:total]`; `ingestion: :async` rolling deploys should drain the inbox first — see [docs/upgrading.md](docs/upgrading.md#v011--v012-unreleased).
+- BREAKING: the serialized event `cost` (the `llm_request.llm_cost_tracker` notification payload and the async-ingestion inbox payload) is now `{ components: {...}, total:, currency: }` (was flat with a top-level `total_cost:`). Notification subscribers should read `cost[:total]`; `ingestion: :async` rolling deploys should drain the inbox first — see [docs/upgrading.md](docs/upgrading.md#v011--v012).
 - BREAKING: `pricing_mode` in the `llm_request.llm_cost_tracker` notification payload is now a String (e.g. `"batch"`, `"fast_data_residency"`), not a Symbol — subscribers matching it against a Symbol must compare to the String.
 - BREAKING: `LlmCostTracker.track(tokens:)` now takes the same `_tokens`-suffixed keys as `stream.usage` and the stored columns — `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `audio_input_tokens`, etc. (was the short `input`, `output`, `cache_read_input`, …). Update manual `track` calls. Pricing-file / `pricing_overrides` field names are unchanged — they stay `input`, `output`, … (per-component rates, a separate vocabulary).
 
@@ -134,17 +227,11 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [0.9.0] - 2026-05-12
 
-0.9 leans the default install: only `calls`, `call_line_items`, and `call_tags`
-are mandatory. Durable ingestion, rollup-cached budget reads, and provider
-invoice reconciliation are opt-in behind config flags and dedicated generators.
-Plus expanded SDK capture (OpenAI embeddings/audio/images/moderation, RubyLLM
-paint/moderate), correct handling of Anthropic data residency and Priority
-Tier, and a security-hardened dashboard. Existing installs need a migration —
-see [Upgrading](docs/upgrading.md).
+0.9 leans the default install: only `calls`, `call_line_items`, and `call_tags` are mandatory. Durable ingestion, rollup-cached budget reads, and provider invoice reconciliation are opt-in behind config flags and dedicated generators. Plus expanded SDK capture (OpenAI embeddings/audio/images/moderation, RubyLLM paint/moderate), correct handling of Anthropic data residency and Priority Tier, and a security-hardened dashboard. Existing installs need a migration — see [Upgrading](docs/upgrading.md).
 
 ### Added
 
-- **Experimental:** opt-in provider invoice reconciliation. Set `config.reconciliation_enabled = true` and run `bin/rails generate llm_cost_tracker:reconciliation`. Public surface: `LlmCostTracker::Reconciliation.import / .diff`, `config.register_reconciliation_importer(:source) { … }`, rake tasks `llm_cost_tracker:reconcile:import` and `:reconcile:diff`. Doctor warns when drift exceeds 5% or imports go stale past 14 days. See [Configuration](docs/configuration.md#reconciliation-experimental-opt-in).
+- **Experimental:** opt-in provider invoice reconciliation. Set `config.reconciliation_enabled = true` and run `bin/rails generate llm_cost_tracker:reconciliation`. Public surface: `LlmCostTracker::Reconciliation.import / .diff`, `config.register_reconciliation_importer(:source) { … }`, rake tasks `llm_cost_tracker:reconcile:import` and `:reconcile:diff`. Doctor warns when drift exceeds 5% or imports go stale past 14 days.
 - Dashboard Data Quality page now shows a "Streaming health by provider" breakdown (streams, with-usage, unknown, unknown share) so a misconfigured OpenAI-compatible host shipping streams without `stream_options.include_usage` is visible at a glance.
 - Dashboard tag detail page drills into a single value via `?tag_value=…` with total cost, call count, average per call, and a daily spend timeseries.
 - Bundled rates for OpenAI embeddings (`text-embedding-3-small` / `-3-large` / `-ada-002`, including 50% batch discount) and token-priced transcription (`gpt-4o-transcribe`, `gpt-4o-mini-transcribe`). Token-priced transcription splits audio and text inputs at their separate rates. DALL-E and Whisper still record as zero-token visibility events until their per-image / per-minute pricing components land.
@@ -240,11 +327,7 @@ see [Upgrading](docs/upgrading.md).
 
 ## [0.8.0] - 2026-05-07
 
-0.8 is a storage rebuild. Tokens and tool/runtime charges share one shape
-(`Billing::LineItem`) and live in a dedicated line items table. Per-component
-cost columns and the standalone service charges table are gone. Several tables
-were also renamed during the cycle. See [Upgrading](docs/upgrading.md) for the
-migration path — there is no rolling-deploy upgrade.
+0.8 is a storage rebuild. Tokens and tool/runtime charges share one shape (`Billing::LineItem`) and live in a dedicated line items table. Per-component cost columns and the standalone service charges table are gone. Several tables were also renamed during the cycle. See [Upgrading](docs/upgrading.md) for the migration path — there is no rolling-deploy upgrade.
 
 ### Added
 

data/README.md

@@ -2,53 +2,46 @@
 
 Self-hosted LLM cost tracking for Rails.
 
-[![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)
+[![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 your app makes to OpenAI, Anthropic, Gemini, RubyLLM, or any
-OpenAI-compatible API gets logged: tokens, cost, latency, tags. Calls go
-app → provider direct. No proxy.
+Every call your app makes through RubyLLM, the official OpenAI and Anthropic SDKs, Gemini, or any OpenAI-compatible API gets logged: tokens, cost, latency, tags. Calls go app → provider direct. No proxy.
 
-Not Langfuse, Helicone, or LiteLLM. 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.4+, Rails 7.1+, PostgreSQL or MySQL.
+Requires Ruby 3.3+, Rails 7.1+, PostgreSQL or MySQL.
 
-<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>
+<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)).
+
 ```ruby
 # Gemfile
 gem "llm_cost_tracker"
-gem "openai"
+gem "ruby_llm"
 ```
 
 ```bash
 bin/rails llm_cost_tracker:setup
 ```
 
-Runs the install generator, drops a price snapshot, migrates the database, and verifies via `llm_cost_tracker:doctor`. The generated `config/initializers/llm_cost_tracker.rb` looks like:
+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`:
 
 ```ruby
 LlmCostTracker.configure do |config|
-  config.default_tags = -> { { environment: Rails.env } }
-  config.instrument :openai
+  config.tags.default = -> { { environment: Rails.env } }
+  config.instrument :ruby_llm
 end
 ```
 
 Edit it in place to add tags, switch on async ingestion, etc.
 
-Tag your calls to attribute spend:
+Your RubyLLM calls stay unchanged — 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
-  client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
-  client.responses.create(model: "gpt-4o", input: "Hello")
+  RubyLLM.chat.ask("Hello")
 end
 ```
 
@@ -65,30 +58,25 @@ The engine ships without authentication on purpose.
 ## What lands in the ledger
 
 - **Calls.** Provider, model, total tokens, total cost, latency, status.
-- **Line items.** Per-component breakdown — text/audio/cached tokens, tool
-  charges (web search, code execution, grounding, container sessions).
+- **Line items.** Per-component breakdown — text/audio/cached tokens, tool charges (web search, code execution, grounding, container sessions).
 - **Tags.** Whatever attribution you pass — user, feature, tenant, env.
-- **Provider IDs.** Response, project, API key, workspace — for downstream
-  audits.
+- **Provider IDs.** Response, project, API key, workspace — for downstream audits.
 - **Pricing snapshot.** So historical numbers don't drift when prices change.
 
 ## Capture surfaces
 
 | Surface | Path |
 | --- | --- |
+| 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 |
-| RubyLLM | Provider layer |
 | `ruby-openai` | Faraday |
 | OpenRouter, DeepSeek, Groq, LiteLLM-style gateways | OpenAI-compatible Faraday |
 | Anything else | `LlmCostTracker.track` |
 
-Streams capture when the provider emits final usage. OpenAI Faraday streams
-get `stream_options: { include_usage: true }` auto-injected so the final
-usage chunk lands in the ledger (opt out via
-`config.auto_enable_stream_usage = false`).
+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`).
 
 ## What it isn't
 

data/app/controllers/llm_cost_tracker/application_controller.rb

@@ -4,11 +4,14 @@ require "securerandom"
 
 module LlmCostTracker
   class ApplicationController < ActionController::Base
+    MAX_QUERY_BYTES = 16 * 1024
+
     layout "llm_cost_tracker/application"
 
     protect_from_forgery with: :exception
 
     before_action :set_dashboard_security_headers
+    before_action :reject_oversized_query
     before_action :ensure_current_schema
     before_action :assign_dashboard_date_range
 
@@ -22,12 +25,20 @@ module LlmCostTracker
 
     private
 
+    def reject_oversized_query
+      return if request.query_string.bytesize <= MAX_QUERY_BYTES
+
+      raise LlmCostTracker::InvalidFilterError, "query string exceeds #{MAX_QUERY_BYTES / 1024} KB"
+    end
+
     def ensure_current_schema
       drift = LlmCostTracker::Dashboard::SetupState.current
       return unless drift
 
       @setup_message = drift.message
       @setup_details = drift.details
+      return head :service_unavailable unless request.format.html?
+
       render template: "llm_cost_tracker/shared/setup_required"
     end
 
@@ -37,18 +48,21 @@ module LlmCostTracker
       @to_date = range.to
     end
 
-    def render_database_error(error)
-      @error = error
-      render "llm_cost_tracker/errors/database", status: :internal_server_error
+    def render_database_error(_error)
+      render_error_page("database", :internal_server_error)
     end
 
     def render_invalid_filter(error)
       @error_message = error.message
-      render "llm_cost_tracker/errors/invalid_filter", status: :bad_request
+      render_error_page("invalid_filter", :bad_request)
     end
 
     def render_not_found
-      render "llm_cost_tracker/errors/not_found", status: :not_found
+      render_error_page("not_found", :not_found)
+    end
+
+    def render_error_page(name, status)
+      render "llm_cost_tracker/errors/#{name}", status: status, formats: :html, content_type: "text/html"
     end
 
     def set_dashboard_security_headers

data/app/controllers/llm_cost_tracker/data_quality_controller.rb

@@ -21,6 +21,7 @@ module LlmCostTracker
         total_streaming: @summary.streaming_count
       )
       @quarantined_inbox = Dashboard::DataQuality.quarantined_inbox
+      @unseen_budget_tags = Dashboard::DataQuality.unseen_budget_tags
     end
   end
 end

data/app/controllers/llm_cost_tracker/models_controller.rb

@@ -2,12 +2,14 @@
 
 module LlmCostTracker
   class ModelsController < ApplicationController
+    MAX_ROWS = 200
+
     def index
       @sort = params[:sort].to_s
       @dir = params[:dir].to_s
       @rows = Dashboard::TopModels.call(
         scope: Dashboard::Filter.call(params: params),
-        limit: nil,
+        limit: MAX_ROWS,
         sort: @sort,
         direction: @dir
       )

data/app/controllers/llm_cost_tracker/pricing_controller.rb

@@ -4,10 +4,10 @@ module LlmCostTracker
   class PricingController < ApplicationController
     def index
       @overview = Dashboard::PricingOverview.call
-      requested = params[:source]&.to_sym
+      requested = params[:source].to_s.to_sym
       @active_source = @overview.fetch(:sources).key?(requested) ? requested : @overview.fetch(:effective_source)
       @source_data = @overview.fetch(:sources).fetch(@active_source)
-      @provider_filter = params[:provider].to_s.presence
+      @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

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -7,19 +7,20 @@ module LlmCostTracker
     end
 
     def show
-      scope = Dashboard::Filter.call(params: params)
-      @value = params[:tag_value].to_s
+      @value = Dashboard::Params.scalar(params[:tag_value], :tag_value)
 
       if @value.empty?
         @sort = params[:sort].to_s
         @dir = params[:dir].to_s
-        @breakdown = Dashboard::TagBreakdown.call(scope: scope, key: params[:key], sort: @sort, direction: @dir)
+        @breakdown = Dashboard::TagBreakdown.call(
+          scope: Dashboard::Filter.call(params: params), key: params[:key], sort: @sort, direction: @dir
+        )
       else
         @key = LlmCostTracker::Tags::Key.validate!(
           params[:key],
           error_class: LlmCostTracker::InvalidFilterError
         )
-        value_scope = scope.by_tag(@key, @value)
+        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)

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -135,7 +135,7 @@ module LlmCostTracker
     end
 
     def current_query(overrides = {})
-      request.query_parameters.symbolize_keys.merge(overrides)
+      request.query_parameters.symbolize_keys.slice(*LlmCostTracker::Dashboard::Params::QUERY_KEYS).merge(overrides)
     end
 
     def calls_query_for_model(provider:, model:)

data/app/helpers/llm_cost_tracker/dashboard_query_helper.rb

@@ -16,6 +16,22 @@ module LlmCostTracker
       query
     end
 
+    def tag_drilldown_allowed?(key)
+      tags = LlmCostTracker::Dashboard::Params.tag_query(current_query[:tag])
+      tags.except(key.to_s).size < LlmCostTracker::Dashboard::Filter::MAX_TAG_FILTERS
+    end
+
+    def hidden_query_fields(query, prefix: nil)
+      safe_join(query.flat_map do |key, value|
+        name = prefix ? "#{prefix}[#{key}]" : key.to_s
+        case value
+        when Hash then hidden_query_fields(value, prefix: name)
+        when Array then value.map { |item| hidden_field_tag("#{name}[]", item, id: nil) }
+        else hidden_field_tag(name, value, id: nil)
+        end
+      end)
+    end
+
     private
 
     def clean_dashboard_query(value)

data/app/models/llm_cost_tracker/call.rb

@@ -10,7 +10,8 @@ module LlmCostTracker
     scope :without_cost, -> { where(total_cost: nil) }
     scope :unknown_pricing,
           lambda {
-            where(Charges::CostStatus.unknown_pricing_sql)
+            where(Charges::CostStatus.unknown_pricing_sql(total_cost: qualified(:total_cost),
+                                                          cost_status: qualified(:cost_status)))
           }
     scope :with_latency, -> { where.not(latency_ms: nil) }
     scope :streaming,     -> { where(stream: true) }
@@ -44,7 +45,7 @@ module LlmCostTracker
       def already_recorded?(provider:, provider_response_id:)
         return false if provider_response_id.to_s.empty?
 
-        where(provider: provider, provider_response_id: provider_response_id).exists?
+        Ledger::Isolation.guard(self) { where(provider: provider, provider_response_id: provider_response_id).exists? }
       end
 
       def by_tag(key, value) = by_tags(key => value)
@@ -64,13 +65,14 @@ module LlmCostTracker
       end
 
       def cost_by_tag(key, limit: nil)
+        cost = qualified(:total_cost)
         label = Ledger::Tags::Breakdown.label_sql(connection)
         raw_value = Ledger::Tags::Breakdown.raw_value_sql(connection)
         relation = Ledger::Tags::Breakdown.join_relation(self, key)
-                                          .select("#{label} AS name", "COALESCE(SUM(total_cost), 0) AS total_cost")
+                                          .select("#{label} AS name", "COALESCE(SUM(#{cost}), 0) AS total_cost")
                                           .group(Arel.sql(label))
                                           .order(
-                                            Arel.sql("COALESCE(SUM(total_cost), 0) DESC"),
+                                            Arel.sql("COALESCE(SUM(#{cost}), 0) DESC"),
                                             Arel.sql("MAX(CASE WHEN #{raw_value} IS NULL THEN 1 ELSE 0 END) ASC"),
                                             Arel.sql("#{label} DESC")
                                           )
@@ -94,6 +96,10 @@ module LlmCostTracker
           .sum(:total_cost)
       end
 
+      def qualified(column)
+        "#{quoted_table_name}.#{connection.quote_column_name(column)}"
+      end
+
       private
 
       def cost_by_column(column, limit:)

data/app/models/llm_cost_tracker/call_rollup.rb

@@ -7,16 +7,32 @@ module LlmCostTracker
         upsert_all(rows, on_duplicate: increment_on_duplicate, record_timestamps: true, unique_by: increment_unique_by)
       end
 
+      DECREMENT_SLICE = 100
+
       def decrement(buckets)
         now = Time.now.utc
-        buckets.each do |(period, period_start, currency, provider), amount|
-          where(period: period, period_start: period_start, currency: currency, provider: provider)
-            .update_all(["total_cost = GREATEST(0, total_cost - ?), updated_at = ?", amount, now])
+        buckets.each_slice(DECREMENT_SLICE) do |slice|
+          where(decrement_scope(slice)).update_all(decrement_assignment(slice, now))
         end
       end
 
       private
 
+      def decrement_scope(slice)
+        rows = Array.new(slice.size, "(?, ?, ?, ?)").join(", ")
+        binds = slice.flat_map { |bucket, _| bucket }
+        sanitize_sql_array(["(period, period_start, currency, provider) IN (#{rows})", *binds])
+      end
+
+      def decrement_assignment(slice, now)
+        branches = slice.map { "WHEN period = ? AND period_start = ? AND currency = ? AND provider = ? THEN ?" }
+        binds = slice.flat_map { |bucket, amount| [*bucket, amount] }
+        sanitize_sql_array(
+          ["total_cost = GREATEST(0, total_cost - CASE #{branches.join(' ')} ELSE 0 END), updated_at = ?",
+           *binds, now]
+        )
+      end
+
       def increment_on_duplicate
         return Arel.sql(mysql_increment_sql) if Ledger::Schema::Adapter.mysql?(connection)
         return Arel.sql(postgres_increment_sql) if Ledger::Schema::Adapter.postgresql?(connection)

data/app/services/llm_cost_tracker/dashboard/data_quality.rb

@@ -5,6 +5,7 @@ module LlmCostTracker
     module DataQuality
       UnknownPricingRow = ::Data.define(:provider, :model, :calls, :share_percent)
       QuarantinedInbox = ::Data.define(:count, :total_cost)
+      UnseenBudgetTags = ::Data.define(:keys)
       StreamingHealthRow = ::Data.define(:provider, :streams, :with_usage, :unknown, :unknown_share)
       Summary = ::Data.define(:total,
                               :unknown_pricing_count,
@@ -45,6 +46,18 @@ module LlmCostTracker
           QuarantinedInbox.new(count: row.quarantined_count.to_i, total_cost: row.quarantined_cost.to_d)
         end
 
+        def unseen_budget_tags
+          budgeted = Budget::PerTag.configured
+          return nil if budgeted.empty?
+          return nil unless Budget::PerTag.columns?
+          return nil unless LlmCostTracker::CallTag.exists?
+
+          unseen = budgeted.keys.reject { |key| LlmCostTracker::CallTag.exists?(key: key) }
+          return nil if unseen.empty?
+
+          UnseenBudgetTags.new(keys: unseen)
+        end
+
         def summary(stats)
           total = stats.total_calls.to_i
           unknown_pricing_count = stats.unknown_pricing_count.to_i