llm_cost_tracker 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 547223e1b3bb49e347aee3b92c0734baf563e83c62c64a97356f7b0c0d175e85
-  data.tar.gz: 2d7601383de690b491b65a2aa5c33185dca6a6d7e9aefb53310eff7dc70102e6
+  metadata.gz: a3bb624cf9437e2ab972021128ab552b48b16c9b8d209429fb264062837e8547
+  data.tar.gz: 8785221213ed888a592b312e5a734193637653930ef9652ece73f650cb920eb5
 SHA512:
-  metadata.gz: d88856b8451a27b706c28f153f8e4a68b7ec610a7a8052d6335481754c670785f2e87d970df913369f5c9d8de9a0716e11d7b60bc5f851ae2b617dcb386ecfd9
-  data.tar.gz: d31b56366d4550f7c8ec4786e8029d566dd8742591ddd3ae61def4a0ee571df98338219a7b0d154f413ee345df3b84b28f645f217a64765e20ad98483e87496d
+  metadata.gz: c223c14dbfe3e2ebf61930175ae7607c2a4a05f502962963312c4ec929965242fccab115eda9d1426d6e331d7fb23ad811f73c9ba8a795cb3262c3d49a60eb45
+  data.tar.gz: 6b8e3ef019f41907909bb9f07eb58085dd6355a442699d52440de564c97fb6fb65979ee01271e4741bd9411ce7ef6a3b69102accd764fdf419d42db1bdb2f6e8

data/CHANGELOG.md

@@ -4,6 +4,61 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-06-04
+
+### Added
+
+- `bin/rails llm_cost_tracker:rebuild_rollups` rebuilds the `llm_cost_tracker_call_rollups` cache from the calls ledger — populate it after turning on `config.cache_rollups` for an app with existing calls, or resync it if rollup totals ever drift from the calls.
+
+### 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).
+- `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.
+- The `bin/rails llm_cost_tracker:prices:explain` rake task (and `LlmCostTracker::Pricing.explain`) is removed — the dashboard's Data Quality page surfaces unknown-pricing models and their effective rates instead.
+
+### Changed
+
+- 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: `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).
+
+### Fixed
+
+- RubyLLM streaming chats to Anthropic and Gemini (`chat.ask { |chunk| }`) are now recorded — previously the streamed response's raw body is the SSE text rather than the parsed hash the integration read, so an internal lookup raised and the call was silently dropped from the ledger. Blocking RubyLLM calls were unaffected.
+- A malformed or very long `pricing_mode` (or a provider `service_tier` / `speed` with many underscore-separated tokens) no longer hangs cost calculation — the call lands `cost_status: unknown` instead of pinning a CPU.
+- Gemini preview models dated with a four-digit year (e.g. `gemini-2.5-flash-preview-09-2025`) now fall back to the stable model's price instead of landing `cost_status: unknown`.
+- A typo'd price-key prefix in `pricing_overrides` or a custom `prices_file` (e.g. `bath_input` for `batch_input`, or any unknown `<mode>_<component>`) now logs an `Unknown price keys` warning and is ignored, instead of being silently accepted so the override quietly never applied at the intended mode/tier.
+- Anthropic responses with `service_tier: "priority"` now keep `:priority` as their pricing_mode instead of being silently billed at standard rates — committed-tier customers get `cost_status: unknown` (signaling to add `priority_input`/`priority_output` to `pricing_overrides`) instead of an over-counted USD figure that ignores their commitment discount.
+- OpenAI's `scale` enterprise tier and `priority` tier are now recognized as pricing modes (no more `Logging.warn` about unknown tokens); calls land as `cost_status: unknown` when negotiated rates are absent so you can add them via `pricing_overrides`.
+- Gemini responses echoing `usageMetadata.serviceTier: "unspecified"` (the default) now resolve to standard pricing instead of warning about an unknown token and landing as `cost_status: unknown`.
+- Anthropic SDK batch results (`client.messages.batches.results_streaming(id).each`) land in the ledger with `pricing_mode: :batch` and the per-result `provider_response_id`, with a same-process best-effort dedup against already-ledgered `provider_response_id`s so re-iterating the stream doesn't duplicate rows (concurrent retrieves from multiple processes can still race; async-mode rows in the inbox aren't checked until they drain).
+- OpenAI SDK batch processing auto-captures: `client.batches.retrieve(id)` on a completed batch downloads the output JSONL and emits one ledger event per response with `pricing_mode: :batch` and the per-response `provider_response_id`, with the same best-effort dedup as Anthropic batches.
+- OpenRouter pricing is now scraped via `openrouter.ai/api/v1/models`, so RubyLLM-routed OpenRouter calls (e.g. `openrouter/openai/gpt-4o`) get a real `total_cost` from the next `prices_file` refresh instead of landing as `cost_status: unknown`. The scrape also captures `image` / `audio` per-token rates so OpenRouter calls with multimodal inputs bill against the correct bucket instead of folding image/audio tokens into the text-input rate.
+- Misspelled `pricing_mode:` values now log a `Logging.warn` listing the unrecognized token (e.g. `:bach` for `:batch`) so the resulting `cost_status: unknown` call surfaces a typo instead of silently absorbing it; the warn fires once per unique token.
+- Whisper-style transcriptions whose response carries `usage.type = "duration"` now emit a `transcription_minute` line item (quantity = `ceil(seconds / 60)`) across both the OpenAI Ruby SDK patch and the Faraday / RubyLLM HTTP path; the call previously recorded with zero tokens and no line item, so audio-minute usage was invisible.
+- OpenAI Responses-API `image_generation_call` and `computer_call` output items now emit line items so per-call hosted-tool usage shows up on the dashboard alongside the existing `web_search_call` / `file_search_call` / `code_interpreter_call` coverage.
+- `LlmCostTracker.track(..., enforce_budget: true)` now actually raises `BudgetExceededError` pre-call when the estimated cost (token cost plus priced service line items) overshoots the budget, even when `budget_exceeded_behavior: :notify` is configured — previously the kwarg silently no-op'd unless policy was already `:block_requests`.
+- `Call#pricing_snapshot.rates` now includes per-charge rates for non-token service line items (web search, MCP calls, TTS character billing, etc.) — previously only token rates were captured, so audit/replay of service-charge pricing had no record of the rate that was actually applied.
+- Tags with invalid keys (e.g. containing whitespace or characters outside `[\w.-]`) are now skipped at write with a `Logging.warn` instead of being silently written and then raising `InvalidFilterError` on dashboard read.
+- A raising `default_tags` proc is now captured by `Logging.warn` and falls back to empty default tags, so a broken user callback doesn't take down every tracked call.
+- `LlmCostTracker::Ingestion::Worker.shutdown!(drain: true)` always attempts the final inbox flush even if waking the worker thread raises, so pending inbox rows aren't left when the host process exits.
+- Gemini preview-dated models (e.g. `gemini-2.5-flash-preview-04-17`) now resolve to the stable entry's pricing — previously the `preview-MM-DD` suffix didn't match the dated-snapshot regex so the call landed as `cost_status: unknown`.
+- Gemini parser now reads `usageMetadata.serviceTier` from the response body in addition to the `x-gemini-service-tier` header, so tier-aware pricing applies when only the body carries the tier signal.
+- Line-item and pricing-snapshot `currency` is now stored uppercase regardless of `prices_file` casing, so a `prices_file` with `currency: "eur"` shows up as `EUR` everywhere and service-line items don't get partitioned out of header totals on a case mismatch with cost-data currency.
+- Async-ingestion inbox rows reaching `MAX_ATTEMPTS_BEFORE_QUARANTINE` now log a `Logging.warn` (with row ids) at the moment they quarantine, so production sees the event in `Rails.logger` instead of needing to run `bin/rails llm_cost_tracker:doctor` to discover it.
+- Dashboard "Setup required" page now flags missing `llm_cost_tracker_ingestion_inbox_entries` and `llm_cost_tracker_ingestion_leases` tables when `ingestion: :async` is configured — previously the drift only surfaced as a worker boot crash.
+- Gemini image-generation models (`gemini-2.5-flash-image`, `gemini-3-pro-image-preview`, `gemini-3.1-flash-image-preview`) and stable preview text models (`gemini-3.1-pro-preview`, `gemini-2.5-flash-lite-preview-09-2025`, etc.) are no longer dropped by the price scraper — they flow into the pricing snapshot on the next refresh cycle.
+- Gemini parser splits `IMAGE`-modality tokens from `promptTokensDetails` / `candidatesTokensDetails` (mirroring the existing AUDIO handling), so image-output usage from Gemini calls routes to `image_output` rates instead of falling into the text-output bucket.
+- RubyLLM SDK integration over-subtracted cache-read tokens from recorded `input_tokens` on chat completions, so the figure landed in the ledger short by the cache-read amount; the gem now passes RubyLLM's net `input_tokens` through unchanged.
+- RubyLLM SDK integration captures `service_tier` from response bodies across Anthropic, OpenAI, and Gemini — previously the field was read from the wrong JSON path so batch and flex modes silently priced against standard rates.
+- RubyLLM SDK integration records the provider's response id in `provider_response_id` (previously always nil), so each ledger row carries the upstream id you can cross-reference against provider invoices and logs.
+- RubyLLM Anthropic chat completions split 1-hour and 5-minute cache writes into separate token buckets so 1h writes bill at the 2x extended rate instead of being lumped into the 5m bucket at 1.25x.
+- Async-inbox `total_cost` now round-trips through the JSON payload without losing precision; previously the payload coerced `BigDecimal` to `Float` and dropped digits past ~15 significant figures, so high-volume aggregate billing under `ingestion: :async` came out systematically short. BREAKING for subscribers to the `llm_request.llm_cost_tracker` `ActiveSupport::Notifications` event: `payload[:cost]` numeric values are now decimal strings (was `Float`) — wrap with `BigDecimal(value)` before arithmetic.
+
 ## [0.11.0] - 2026-05-21
 
 ### Added

data/README.md

@@ -32,16 +32,17 @@ gem "openai"
 bin/rails llm_cost_tracker:setup
 ```
 
-Runs the install generator, drops a price snapshot, migrates the database, and verifies via `llm_cost_tracker:doctor`.
+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:
 
 ```ruby
-# config/initializers/llm_cost_tracker.rb
 LlmCostTracker.configure do |config|
   config.default_tags = -> { { environment: Rails.env } }
   config.instrument :openai
 end
 ```
 
+Edit it in place to add tags, switch on async ingestion, etc.
+
 Tag your calls to attribute spend:
 
 ```ruby
@@ -85,7 +86,9 @@ The engine ships without authentication on purpose.
 | Anything else | `LlmCostTracker.track` |
 
 Streams capture when the provider emits final usage. OpenAI Faraday streams
-need `stream_options: { include_usage: true }`.
+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`).
 
 ## What it isn't
 
@@ -102,7 +105,7 @@ For batch jobs, internal gateways, or anything without an SDK/Faraday hook:
 LlmCostTracker.track(
   provider: :anthropic,
   model: "claude-sonnet-4-6",
-  tokens: { input: 1500, output: 320 },
+  tokens: { input_tokens: 1500, output_tokens: 320 },
   tags: { feature: "summarizer", user_id: current_user.id }
 )
 ```

data/app/assets/llm_cost_tracker/application.css

@@ -4,11 +4,12 @@
     --lct-surface-2: #f1f4f9;
     --lct-surface-hover: #eef2f7;
     --lct-panel: #ffffff;
+    --lct-panel-head-bg: #fbfcfe;
     --lct-border: #e3e8ef;
     --lct-border-strong: #cbd2dc;
     --lct-text: #0d1b2a;
-    --lct-muted: #5a6573;
-    --lct-subtle: #8b95a4;
+    --lct-muted: #475467;
+    --lct-subtle: #5a6573;
     --lct-accent: #5b54d8;
     --lct-accent-strong: #4540c4;
     --lct-accent-hover: #4540c4;
@@ -27,7 +28,6 @@
     --lct-danger-copy: #b91c1c;
     --lct-danger-strong: #991b1b;
     --lct-row-hover: #f8fafc;
-    --lct-th-bg: #f1f4f9;
     --lct-toolbar-bg: rgba(255, 255, 255, 0.92);
     --lct-toolbar-border: #e3e8ef;
     --lct-chart-secondary: rgba(13, 27, 42, 0.42);
@@ -80,6 +80,7 @@
       --lct-surface-2: #1c2229;
       --lct-surface-hover: #232a35;
       --lct-panel: #161b22;
+      --lct-panel-head-bg: #1f262e;
       --lct-border: #2a313c;
       --lct-border-strong: #3d4654;
       --lct-text: #e6edf3;
@@ -103,7 +104,6 @@
       --lct-danger-copy: #f85149;
       --lct-danger-strong: #fecaca;
       --lct-row-hover: #1c2229;
-      --lct-th-bg: #1c2229;
       --lct-toolbar-bg: rgba(22, 27, 34, 0.92);
       --lct-toolbar-border: #2a313c;
       --lct-shadow: 0 1px 2px rgba(0, 0, 0, 0.30);
@@ -123,6 +123,7 @@
     --lct-surface-2: #1c2229;
     --lct-surface-hover: #232a35;
     --lct-panel: #161b22;
+    --lct-panel-head-bg: #1f262e;
     --lct-border: #2a313c;
     --lct-border-strong: #3d4654;
     --lct-text: #e6edf3;
@@ -146,7 +147,6 @@
     --lct-danger-copy: #f85149;
     --lct-danger-strong: #fecaca;
     --lct-row-hover: #1c2229;
-    --lct-th-bg: #1c2229;
     --lct-toolbar-bg: rgba(22, 27, 34, 0.92);
     --lct-toolbar-border: #2a313c;
     --lct-shadow: 0 1px 2px rgba(0, 0, 0, 0.30);
@@ -444,6 +444,8 @@
     gap: var(--sp-3);
     padding: 9px var(--sp-4);
     border-bottom: 1px solid var(--lct-border);
+    background: var(--lct-panel-head-bg);
+    border-radius: var(--radius-md) var(--radius-md) 0 0;
   }
   .lct-panel-title {
     font-size: var(--fs-md);
@@ -626,8 +628,7 @@
     color: var(--lct-muted);
     text-align: left;
     padding: 9px var(--sp-4);
-    border-bottom: 1px solid var(--lct-border);
-    background: var(--lct-th-bg);
+    border-bottom: 1px solid var(--lct-border-strong);
     white-space: nowrap;
   }
   .lct-tbl td {

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -26,7 +26,7 @@ module LlmCostTracker
         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.limit).offset(@page.offset).to_a
+          @calls = ordered_scope.includes(:tag_records).limit(@page.per).offset(@page.offset).to_a
         end
         format.csv do
           response.headers["Cache-Control"] = "no-store"
@@ -83,7 +83,7 @@ module LlmCostTracker
 
     def csv_fields
       %i[tracked_at provider model] +
-        TokenUsage.members +
+        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
@@ -93,15 +93,15 @@ module LlmCostTracker
     def csv_value(field, call)
       case field
       when :tracked_at
-        call.tracked_at&.utc&.iso8601
+        call.tracked_at.utc.iso8601
       when :provider_api_key_id, :provider_workspace_id, :provider_project_id
-        csv_safe(LlmCostTracker::Masking.mask_value(field, call[field]))
+        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.parsed_tags.to_json)
+        csv_safe(call.tag_pairs.to_json)
       else
         call[field]
       end

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -13,7 +13,7 @@ module LlmCostTracker
       )
 
       @stats = Dashboard::OverviewStats.call(scope: scope, previous_scope: previous_scope)
-      @monthly_budget_status = Dashboard::OverviewStats.monthly_budget_status
+      @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)
       @spend_anomaly = Dashboard::SpendAnomaly.call(from: @from_date, to: @to_date, scope: scope)

data/app/controllers/llm_cost_tracker/pricing_controller.rb

@@ -4,7 +4,7 @@ module LlmCostTracker
   class PricingController < ApplicationController
     def index
       @overview = Dashboard::PricingOverview.call
-      requested = params[:source].to_s.to_sym
+      requested = params[:source]&.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

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -7,7 +7,6 @@ module LlmCostTracker
     TAG_VALUE_SUMMARY_BYTES = 80
     TAG_TOOLTIP_BYTES = 512
 
-    include DashboardFilterHelper
     include DashboardFilterOptionsHelper
     include DashboardQueryHelper
     include ChartHelper
@@ -22,7 +21,6 @@ module LlmCostTracker
       return :tags if path.start_with?(tags_path)
       return :data_quality if path.start_with?(data_quality_path)
       return :pricing if path.start_with?(pricing_path)
-      return :reconciliation if LlmCostTracker.reconciliation_enabled? && path.start_with?(reconciliation_path)
 
       :overview
     end
@@ -45,26 +43,19 @@ module LlmCostTracker
       value.nil? ? "n/a" : money(value)
     end
 
-    def optional_number(value)
-      value.nil? ? "n/a" : number(value)
-    end
-
-    def number(value)
-      number_with_delimiter(value)
-    end
-
     def format_date(value)
-      value.try(:strftime, "%Y-%m-%d %H:%M") || value.to_s
+      return "" if value.nil?
+
+      value.strftime("%Y-%m-%d %H:%M")
     end
 
     def pricing_status(call)
       return "Unknown" if call.total_cost.nil?
-      return "Estimated" unless call.has_attribute?(:cost_status)
 
       {
-        LlmCostTracker::Billing::CostStatus::COMPLETE => "Estimated",
-        LlmCostTracker::Billing::CostStatus::FREE => "Free",
-        LlmCostTracker::Billing::CostStatus::PARTIAL => "Partial"
+        LlmCostTracker::Charges::CostStatus::COMPLETE => "Estimated",
+        LlmCostTracker::Charges::CostStatus::FREE => "Free",
+        LlmCostTracker::Charges::CostStatus::PARTIAL => "Partial"
       }.fetch(call.cost_status, "Unknown")
     end
 

data/app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb

@@ -4,17 +4,7 @@ module LlmCostTracker
   module DashboardFilterOptionsHelper
     MAX_FILTER_OPTIONS = 100
 
-    def provider_filter_options(filter_params: params)
-      filter_options_for(:provider, filter_params: filter_params)
-    end
-
-    def model_filter_options(filter_params: params)
-      filter_options_for(:model, filter_params: filter_params)
-    end
-
-    private
-
-    def filter_options_for(column, filter_params:)
+    def filter_options_for(column, filter_params: params)
       source = LlmCostTracker::Dashboard::Params.to_hash(filter_params).symbolize_keys
       scope_params = source.merge(
         column => nil, format: nil, page: nil, per: nil, sort: nil

data/app/helpers/llm_cost_tracker/sortable_table_helper.rb

@@ -2,8 +2,8 @@
 
 module LlmCostTracker
   module SortableTableHelper
-    def sortable_header(label, column, num: false)
-      state = sortable_state(column, num: num)
+    def sortable_header(label, column, num: false, default: false)
+      state = sortable_state(column, num: num, default: default)
       classes = ["lct-sortable"]
       classes << "lct-num" if num
       classes << "lct-sorted" if state[:active]
@@ -16,8 +16,8 @@ module LlmCostTracker
 
     private
 
-    def sortable_state(column, num:)
-      current_sort = params[:sort].to_s
+    def sortable_state(column, num:, default: false)
+      current_sort = params[:sort].presence || (default ? column : nil)
       current_dir = Dashboard::Sort::DIRECTIONS.include?(params[:dir].to_s) ? params[:dir].to_s : nil
       natural_dir = num ? "desc" : "asc"
       active = current_sort == column

data/app/helpers/llm_cost_tracker/token_usage_helper.rb

@@ -40,11 +40,9 @@ module LlmCostTracker
 
     def call_line_item_costs_by_component(call)
       call.line_items.each_with_object({}) do |line_item, accumulator|
-        component = LlmCostTracker::Billing::Components::TOKEN_PRICED.find do |item|
-          item.kind.to_s == line_item.kind.to_s &&
-            item.direction.to_s == line_item.direction.to_s &&
-            item.cache_state.to_s == line_item.cache_state.to_s
-        end
+        component = LlmCostTracker::Usage::Catalog.token_priced_for(
+          kind: line_item.kind, direction: line_item.direction, cache_state: line_item.cache_state
+        )
         accumulator[component.key] = line_item.cost if component && line_item.cost
       end
     end
@@ -52,7 +50,7 @@ module LlmCostTracker
     private
 
     def token_usage_display_components(labels:)
-      LlmCostTracker::Billing::Components::TOKEN_PRICED.map do |component|
+      LlmCostTracker::Usage::Catalog.token_priced.map do |component|
         token_key = component.token_key
         {
           token_key: token_key,

data/app/models/llm_cost_tracker/call.rb

@@ -2,43 +2,26 @@
 
 require "securerandom"
 
-require "llm_cost_tracker/billing/cost_status"
-require "llm_cost_tracker/ledger/schema/adapter"
-require "llm_cost_tracker/ledger/tags/sql"
-
 module LlmCostTracker
   class Call < ActiveRecord::Base
     before_validation :assign_event_id
 
-    PERIOD_FORMATS = {
-      day: {
-        postgres: "YYYY-MM-DD",
-        mysql: "%Y-%m-%d"
-      },
-      month: {
-        postgres: "YYYY-MM",
-        mysql: "%Y-%m"
-      }
-    }.freeze
-
-    private_constant :PERIOD_FORMATS
-
     scope :with_cost, -> { where.not(total_cost: nil) }
     scope :without_cost, -> { where(total_cost: nil) }
-    scope :unknown_pricing, lambda {
-      where(total_cost: nil).or(
-        where(cost_status: [Billing::CostStatus::UNKNOWN, Billing::CostStatus::PARTIAL])
-      )
-    }
+    scope :unknown_pricing,
+          lambda {
+            where(Charges::CostStatus.unknown_pricing_sql)
+          }
     scope :with_latency, -> { where.not(latency_ms: nil) }
     scope :streaming,     -> { where(stream: true) }
     scope :non_streaming, -> { where(stream: [false, nil]) }
     scope :by_usage_source, ->(source) { where(usage_source: source.to_s) }
     scope :with_provider_response_id, -> { where.not(provider_response_id: [nil, ""]) }
     scope :missing_provider_response_id, -> { where(provider_response_id: [nil, ""]) }
-    scope :streaming_missing_usage, lambda {
-      where(stream: true).where(usage_source: ["unknown", nil])
-    }
+    scope :streaming_missing_usage,
+          lambda {
+            where(stream: true).where(usage_source: [Usage::Source::UNKNOWN, nil])
+          }
 
     has_many :line_items,
              class_name: "LlmCostTracker::CallLineItem",
@@ -58,6 +41,12 @@ module LlmCostTracker
     scope :between,     ->(from, to) { where(tracked_at: from..to) }
 
     class << self
+      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?
+      end
+
       def by_tag(key, value) = by_tags(key => value)
 
       def by_tags(tags) = Ledger::Tags::Query.apply(tags)
@@ -71,20 +60,20 @@ module LlmCostTracker
       def cost_by_provider(limit: nil) = cost_by_column(:provider, limit: limit)
 
       def group_by_tag(key)
-        Ledger::Tags::Sql.join_relation(self, key).group(Ledger::Tags::Sql.value_arel)
+        Ledger::Tags::Breakdown.join_relation(self, key).group(Ledger::Tags::Breakdown.value_arel)
       end
 
       def cost_by_tag(key, limit: nil)
-        label = Ledger::Tags::Sql.label_sql(connection)
-        raw_value = Ledger::Tags::Sql.raw_value_sql(connection)
-        relation = Ledger::Tags::Sql.join_relation(self, key)
-                                    .select("#{label} AS name", "COALESCE(SUM(total_cost), 0) AS total_cost")
-                                    .group(Arel.sql(label))
-                                    .order(
-                                      Arel.sql("COALESCE(SUM(total_cost), 0) DESC"),
-                                      Arel.sql("MAX(CASE WHEN #{raw_value} IS NULL THEN 1 ELSE 0 END) ASC"),
-                                      Arel.sql("#{label} DESC")
-                                    )
+        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")
+                                          .group(Arel.sql(label))
+                                          .order(
+                                            Arel.sql("COALESCE(SUM(total_cost), 0) DESC"),
+                                            Arel.sql("MAX(CASE WHEN #{raw_value} IS NULL THEN 1 ELSE 0 END) ASC"),
+                                            Arel.sql("#{label} DESC")
+                                          )
         relation = relation.limit(limit) if limit
         relation
       end
@@ -108,8 +97,7 @@ module LlmCostTracker
       private
 
       def cost_by_column(column, limit:)
-        quoted_column = "#{quoted_table_name}.#{connection.quote_column_name(column)}"
-        relation = select("#{quoted_column} AS name, COALESCE(SUM(total_cost), 0) AS total_cost")
+        relation = select(arel_table[column].as("name"), "COALESCE(SUM(total_cost), 0) AS total_cost")
                    .group(column)
                    .order(Arel.sql("COALESCE(SUM(total_cost), 0) DESC"))
         relation = relation.limit(limit) if limit
@@ -117,30 +105,7 @@ module LlmCostTracker
       end
 
       def period_group_expression(period, column:)
-        period = validated_period(period)
-        column = period_column_expression(column)
-        formats = PERIOD_FORMATS.fetch(period)
-
-        if Ledger::Schema::Adapter.postgresql?(connection)
-          postgres_period_expression(period, column, formats)
-        elsif Ledger::Schema::Adapter.mysql?(connection)
-          "DATE_FORMAT(#{column}, #{connection.quote(formats.fetch(:mysql))})"
-        else
-          Ledger::Schema::Adapter.ensure_supported!(connection)
-        end
-      end
-
-      def postgres_period_expression(period, column, formats)
-        "TO_CHAR(" \
-          "DATE_TRUNC(#{connection.quote(period.name)}, #{column}), " \
-          "#{connection.quote(formats.fetch(:postgres))}" \
-          ")"
-      end
-
-      def validated_period(period)
-        return period if PERIOD_FORMATS.key?(period)
-
-        raise ArgumentError, "invalid period: #{period.inspect}"
+        Ledger::Schema::Adapter.period_bucket_sql(connection, period, period_column_expression(column))
       end
 
       def period_column_expression(column)
@@ -151,7 +116,7 @@ module LlmCostTracker
       end
     end
 
-    def parsed_tags
+    def tag_pairs
       tag_records.to_h do |record|
         [record.key, record.value]
       end

data/app/models/llm_cost_tracker/call_line_item.rb

@@ -12,7 +12,7 @@ module LlmCostTracker
     scope :by_direction, ->(direction) { where(direction: direction.to_s) }
     scope :by_modality, ->(modality) { where(modality: modality.to_s) }
     scope :cached, -> { where.not(cache_state: ["none", nil]) }
-    scope :priced, -> { where(cost_status: %w[complete free]) }
-    scope :unpriced, -> { where(cost_status: "unknown") }
+    scope :priced, -> { where(cost_status: [Charges::CostStatus::COMPLETE, Charges::CostStatus::FREE]) }
+    scope :unpriced, -> { where(cost_status: Charges::CostStatus::UNKNOWN) }
   end
 end

data/app/models/llm_cost_tracker/call_rollup.rb

@@ -2,5 +2,43 @@
 
 module LlmCostTracker
   class CallRollup < ActiveRecord::Base
+    class << self
+      def increment_all(rows)
+        upsert_all(rows, on_duplicate: increment_on_duplicate, record_timestamps: true, unique_by: increment_unique_by)
+      end
+
+      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])
+        end
+      end
+
+      private
+
+      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)
+
+        Ledger::Schema::Adapter.ensure_supported!(connection)
+      end
+
+      def postgres_increment_sql
+        total = connection.quote_column_name("total_cost")
+        updated = connection.quote_column_name("updated_at")
+        "#{total} = #{quoted_table_name}.#{total} + excluded.#{total}, #{updated} = excluded.#{updated}"
+      end
+
+      def mysql_increment_sql
+        "total_cost = total_cost + VALUES(total_cost), updated_at = VALUES(updated_at)"
+      end
+
+      def increment_unique_by
+        return unless connection.supports_insert_conflict_target?
+
+        %i[period period_start currency provider]
+      end
+    end
   end
 end

data/app/models/llm_cost_tracker/call_tag.rb

@@ -6,7 +6,5 @@ module LlmCostTracker
                class_name: "LlmCostTracker::Call",
                foreign_key: :llm_cost_tracker_call_id,
                inverse_of: :tag_records
-
-    scope :with_key, ->(key) { where(key: key.to_s) }
   end
 end

data/app/models/llm_cost_tracker/ingestion/inbox_entry.rb

@@ -4,6 +4,8 @@ module LlmCostTracker
   module Ingestion
     class InboxEntry < ActiveRecord::Base
       MAX_ATTEMPTS_BEFORE_QUARANTINE = 5
+
+      scope :pending, -> { where(attempts: ..(MAX_ATTEMPTS_BEFORE_QUARANTINE - 1)) }
     end
   end
 end