llm_cost_tracker 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eba077a3fb9b0dc146673535769b8be4d34dcbde133ae41e2910652b7833e306
-  data.tar.gz: 3b384ad865a23598566ee46974bedda14af88673bbe4822501fb5eb65980655a
+  metadata.gz: 93ef8bc5c6bc0e850398b7555499a4667d1cc3d8ba2328c1fb926204a794a5a7
+  data.tar.gz: e7208b7bf518332040837498b5de7d1e5e6c761a276d6fb732d14133d38d8c74
 SHA512:
-  metadata.gz: 2c5d72d58222d3b3f66fe7d1511ce69c8a008b45a31351827d59a13a982b5478f24ce7e14afe1417150e51653452ec1cc43c8a9fc8f1f069148da7489e0c2698
-  data.tar.gz: a5a70b59d1622080271d0a1a24259c8630938c132e93cfeb041ef258d3d0a720bb44a1e0b8b5be65c6b9801847f031395f2e1d7adc48d9cf71b83c3f276ae281
+  metadata.gz: 5d19b85e0a4398332a0161f75bc561b79c6ebf12546fe21013b12f2b7f5ff931179fcb8d5610faccd4d84063bf10f4297bd1688df04c24e41ffb63d4ff38b851
+  data.tar.gz: e7b4f3a2164cc9f6e9545e123fe4aeabac356ab66becfc94466f8f25d54329ed5af4056339cfda1c71e20bcba1c4de30a9922ff3b7b5664528bde515834e19f1

data/CHANGELOG.md

@@ -4,6 +4,42 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-04-22
+
+### Added
+
+- `provider_response_id` persistence, parser extraction, and Data Quality coverage for provider-issued response object IDs.
+
+### Changed
+
+- Simplified dashboard helpers, filter normalization, and view templates without changing dashboard behavior.
+- Split `PriceSync` internals into smaller components and removed redundant internal wrapper layers.
+
+### Fixed
+
+- Removed inline dashboard JavaScript to keep the engine server-rendered.
+- Reset ActiveRecord model column information in storage specs to avoid stale schema state across recreated tables.
+
+## [0.3.0] - 2026-04-22
+
+### Added
+
+- Streaming capture across OpenAI, Anthropic, and Gemini, including `LlmCostTracker.track_stream` for non-Faraday clients.
+- `stream` / `usage_source` persistence and dashboard coverage for streamed calls.
+- `llm_cost_tracker:prices:sync` and `llm_cost_tracker:prices:check` for keeping local price snapshots current.
+- `LlmCostTracker.enforce_budget!` and opt-in `enforce_budget:` keyword for `track` / `track_stream`.
+
+### Changed
+
+- Price refresh now uses structured JSON sources (LiteLLM primary, OpenRouter secondary) instead of scraping provider HTML pages.
+- Synced price entries now carry source provenance (`_source`, `_source_version`, `_fetched_at`), while `_source: "manual"` entries remain untouched.
+- Manual stream parsing now resolves parsers through the shared registry, so configured OpenAI-compatible providers work the same way as built-in ones.
+- `LlmCostTracker.configure` now treats configuration as an immutable snapshot after the block returns; mutating or replacing shared fields through `LlmCostTracker.configuration` raises `FrozenError`.
+
+### Removed
+
+- Public `LlmCostTracker.configuration=` writer; use `LlmCostTracker.configure` to replace configuration snapshots.
+
 ## [0.2.0] - 2026-04-20
 
 ### Added

data/README.md

@@ -1,35 +1,17 @@
-# LlmCostTracker
+# LLM Cost Tracker
 
-**Self-hosted LLM cost tracking for Ruby and Rails.** Intercepts Faraday LLM responses, prices them locally, stores events in your database. No proxy, no SaaS.
+**Self-hosted LLM cost tracking for Ruby and Rails.** Intercepts Faraday LLM responses or records usage explicitly, prices events locally, and stores them in your database. No proxy, no SaaS.
 
 [![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)
 
-```text
-LLM Cost Report (last 30 days)
-
-Total cost: $127.420000
-Requests: 4,218
-Avg latency: 812ms
-Unknown pricing: 0
-
-By model:
-  gpt-4o                      $82.100000
-  claude-sonnet-4-6           $31.200000
-  gemini-2.5-flash            $14.120000
-
-By tag key "env":
-  production                  $119.300000
-  staging                     $8.120000
-```
-
 ## Why
 
-Every Rails app with LLM integrations eventually runs into the same question: where did that invoice come from? Full observability platforms like Langfuse and Helicone cover a lot more than cost, and sometimes you just want a small Rails-native ledger that lives in your own database.
+Every Rails app with LLM integrations eventually runs into the same question: where did that invoice come from? Full observability platforms like Langfuse and Helicone solve a broader set of problems; sometimes you just need a small Rails-native ledger in your own database.
 
-`llm_cost_tracker` is scoped to that. It plugs into Faraday, parses provider usage out of the response, looks up pricing locally, and writes an event. You end up with a ledger you can query with plain ActiveRecord, slice by any tag dimension, and optionally surface on a built-in dashboard. No proxy, no SaaS, no separate service to run.
+`llm_cost_tracker` is built for that. It plugs into Faraday or lets you record usage explicitly with `track` / `track_stream`, looks up pricing locally, and writes an event. You end up with a ledger you can query with plain ActiveRecord, slice by any tag dimension, and optionally surface on a built-in dashboard. No proxy, no SaaS, no separate service to run.
 
-It's not a tracing platform, prompt CMS, eval system, or gateway — and doesn't want to be. The goal is answering _"what did this app spend on LLM APIs, and where did that spend come from?"_ well enough that you stop worrying about it.
+It is not a tracing platform, prompt CMS, eval system, or gateway. The goal is to answer _"what did this app spend on LLM APIs, and where did that spend come from?"_ clearly enough to make spend review routine.
 
 ## Installation
 
@@ -44,23 +26,6 @@ bin/rails generate llm_cost_tracker:install
 bin/rails db:migrate
 ```
 
-## Quick try (no database)
-
-```ruby
-require "llm_cost_tracker"
-
-LlmCostTracker.configure { |c| c.storage_backend = :log }
-
-LlmCostTracker.track(
-  provider: :openai,
-  model: "gpt-4o",
-  input_tokens: 1000,
-  output_tokens: 200,
-  feature: "demo"
-)
-# => [LlmCostTracker] openai/gpt-4o tokens=1000+200 cost=$0.004500 tags={:feature=>"demo"}
-```
-
 ## Usage
 
 ### Patch an existing client's Faraday connection
@@ -78,19 +43,7 @@ OpenAI.configure do |config|
 end
 ```
 
-`tags:` can be a callable so `Current` attributes are evaluated per request:
-
-```ruby
-class Current < ActiveSupport::CurrentAttributes
-  attribute :user, :tenant, :workflow
-end
-
-# application_controller.rb
-before_action do
-  Current.user = current_user
-  Current.workflow = "chat"
-end
-```
+`tags:` can be a callable and is evaluated on each request.
 
 ### Raw Faraday
 
@@ -105,7 +58,52 @@ end
 conn.post("/v1/responses", { model: "gpt-5-mini", input: "Hello!" })
 ```
 
-Place `llm_cost_tracker` inside the Faraday stack where it can see the final response body. For streaming APIs, tracking requires the final body to expose provider usage; otherwise the gem warns and skips — use manual tracking there.
+Place `llm_cost_tracker` inside the Faraday stack where it can see the final response body.
+
+### Streaming
+
+Streaming is captured automatically for OpenAI, Anthropic, and Gemini when the request goes through the Faraday middleware. The middleware tees the `on_data` callback, keeps the stream flowing to your code, and records the final usage block once the response completes.
+
+```ruby
+# OpenAI: include usage in the final chunk
+client.chat(parameters: {
+  model: "gpt-4o",
+  messages: [...],
+  stream: proc { |chunk| ... },
+  stream_options: { include_usage: true }
+})
+```
+
+Anthropic emits usage in `message_start` + `message_delta` events. Gemini's `:streamGenerateContent` endpoint includes `usageMetadata`; usage from the final chunk is used.
+
+Streamed calls are stored with `stream: true` and `usage_source: "stream_final"`. If the provider never sends final usage, the call is still recorded with `usage_source: "unknown"` so those calls surface on the Data Quality page.
+
+When the provider emits a stable response object ID, LLM Cost Tracker stores it as `provider_response_id`. OpenAI and Anthropic are covered end-to-end; Gemini is best effort and may vary by endpoint or API version.
+
+For non-Faraday clients (raw `Net::HTTP`, custom SSE code, Azure OpenAI), use the explicit helper:
+
+```ruby
+LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o") do |stream|
+  my_client.stream(...) { |chunk| stream.event(chunk) }
+end
+
+# Or skip the chunk parsing entirely if you already know the totals:
+LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o") do |stream|
+  # ... your streaming loop ...
+  stream.usage(input_tokens: 120, output_tokens: 45)
+end
+```
+
+If your custom streaming client exposes the provider's response object ID after the stream starts, set it explicitly:
+
+```ruby
+LlmCostTracker.track_stream(provider: "anthropic", model: "claude-sonnet-4-6") do |stream|
+  stream.provider_response_id = response.id
+  stream.usage(input_tokens: 120, output_tokens: 45)
+end
+```
+
+Run `bin/rails g llm_cost_tracker:add_streaming` once on existing installs to add the `stream` and `usage_source` columns. Run `bin/rails g llm_cost_tracker:add_provider_response_id` to persist provider-issued response IDs.
 
 ### Manual tracking
 
@@ -115,6 +113,7 @@ LlmCostTracker.track(
   model: "claude-sonnet-4-6",
   input_tokens: 1500,
   output_tokens: 320,
+  provider_response_id: "msg_01XFDUDYJgAACzvnptvVoYEL",
   cache_read_input_tokens: 1200,
   feature: "summarizer",
   user_id: current_user.id
@@ -148,7 +147,7 @@ LlmCostTracker.configure do |config|
 end
 ```
 
-Pricing is best-effort. OpenRouter-style IDs like `openai/gpt-4o-mini` are normalized to built-in names when possible. Use `prices_file` / `pricing_overrides` for fine-tunes, gateway-specific IDs, enterprise discounts, batch pricing, or models the gem doesn't know.
+Pricing is best effort. OpenRouter-style IDs like `openai/gpt-4o-mini` are normalized to built-in names when possible. Use `prices_file` / `pricing_overrides` for fine-tunes, gateway-specific IDs, enterprise discounts, batch pricing, or models the gem does not know.
 
 `storage_error_behavior = :warn` (default) lets LLM responses continue if storage fails; `:raise` exposes `StorageError#original_error`.
 
@@ -160,7 +159,7 @@ LlmCostTracker::LlmApiCall.unknown_pricing.group(:model).count
 
 ### Keeping prices current
 
-Built-in prices are in `lib/llm_cost_tracker/prices.json`. The gem never fetches pricing on boot. For production, generate a local overrides file and point the gem at it:
+Built-in prices live in `lib/llm_cost_tracker/prices.json`. The gem never fetches pricing on boot. For production, keep a local snapshot under `config/` and point the gem at it:
 
 ```bash
 bin/rails generate llm_cost_tracker:prices
@@ -175,7 +174,26 @@ bin/rails generate llm_cost_tracker:prices
 }
 ```
 
-`pricing_overrides` has the highest precedence; use it for small Ruby-only tweaks, `prices_file` for broader tables.
+`pricing_overrides` has the highest precedence. Use it for a handful of Ruby-side overrides; use `prices_file` when you want a local pricing table under source control.
+
+To refresh prices on demand:
+
+```bash
+bin/rails llm_cost_tracker:prices:sync
+```
+
+`llm_cost_tracker:prices:sync` refreshes the current registry from two structured sources: LiteLLM first, OpenRouter second. LiteLLM is the primary source; OpenRouter fills gaps and helps surface discrepancies.
+
+`llm_cost_tracker:prices:sync` / `llm_cost_tracker:prices:check` perform HTTP GET requests to:
+
+- LiteLLM pricing JSON: `https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json`
+- OpenRouter Models API: `https://openrouter.ai/api/v1/models`
+
+If `config.prices_file` is configured, the task syncs that file automatically; otherwise it works from the built-in snapshot. `_source: "manual"` entries are never touched. Models that are still in your file but missing from both upstream sources are left alone and reported as orphaned. For intentional custom entries, mark them as manual so they stop showing up in orphaned warnings.
+
+Use `PREVIEW=1` to see the diff without writing. Use `STRICT=1` to fail instead of applying a partial refresh when a source fails or the validator rejects a price. Use `bin/rails llm_cost_tracker:prices:check` in CI to print the current diff and exit non-zero when the snapshot has drifted or refresh fails.
+
+Large price changes are flagged during sync. If a specific entry is expected to move by more than 3x, add `_validator_override: ["skip_relative_change"]` to that entry in your local price file.
 
 ## Budget enforcement
 
@@ -194,14 +212,31 @@ rescue LlmCostTracker::BudgetExceededError => e
   # e.monthly_total, e.budget, e.last_event
 ```
 
-`:block_requests` is best-effort under concurrency, not a transactional cap. Use provider/gateway-level limits for strict quotas.
+`:block_requests` is a **guardrail, not a hard cap**. The preflight and the spend-recording write are separate statements, so under Puma / Sidekiq concurrency multiple workers can all pass the preflight and then collectively overshoot the budget. The setting reliably *stops new requests after the overshoot is visible* — it does not prevent the overshoot itself. For strict quotas use a provider- or gateway-level limit, or a database-backed counter outside this gem.
+
+Preflight is wired into the Faraday middleware automatically. When you record events via `LlmCostTracker.track` / `track_stream` and also want the same preflight, opt in:
+
+```ruby
+LlmCostTracker.track(
+  provider: "openai",
+  model: "gpt-4o",
+  input_tokens: 120,
+  output_tokens: 45,
+  enforce_budget: true
+)
+
+LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o", enforce_budget: true) do |stream|
+  # raises BudgetExceededError before the block runs when over budget
+end
+
+LlmCostTracker.enforce_budget! # standalone preflight
+```
 
 ## Querying costs
 
 ```bash
 bin/rails llm_cost_tracker:report
 DAYS=7 bin/rails llm_cost_tracker:report
-DAYS=90 bin/rails llm_cost_tracker:prune  # delete calls older than N days in batches
 ```
 
 ```ruby
@@ -230,7 +265,15 @@ LlmCostTracker::LlmApiCall.by_tags(user_id: 42, feature: "chat").this_month.tota
 LlmCostTracker::LlmApiCall.between(1.week.ago, Time.current).cost_by_model
 ```
 
-### Tag storage
+## Retention
+
+Retention is not enforced automatically. Use the rake task below if you need to delete older records in batches.
+
+```bash
+DAYS=90 bin/rails llm_cost_tracker:prune  # delete calls older than N days in batches
+```
+
+## Tag storage
 
 New installs use `jsonb` + GIN on PostgreSQL:
 
@@ -252,7 +295,7 @@ bin/rails db:migrate
 
 ## Dashboard (optional)
 
-Opt-in Rails Engine. Plain ERB, inline CSS, no JS. Requires Rails 7.1+; the core middleware works without Rails.
+Optional Rails Engine. Plain ERB, no JavaScript framework, no asset pipeline required. Requires Rails 7.1+; the core middleware works without Rails.
 
 ```ruby
 # config/application.rb (or an initializer)
@@ -272,7 +315,7 @@ Routes (GET-only; CSV export included):
 - `/llm-costs/tags/:key` — breakdown by values of a given tag key
 - `/llm-costs/data_quality` — unknown pricing share, untagged calls, missing latency
 
-> ⚠️ **No built-in auth.** Tags carry whatever your app puts in them. Protect the mount point with your app's auth.
+> ⚠️ **No built-in auth.** Tags carry whatever your app puts in them. Protect the mount point with your application's authentication.
 
 ### Basic auth
 
@@ -331,7 +374,7 @@ config.custom_storage = ->(event) {
 config.openai_compatible_providers["gateway.example.com"] = "internal_gateway"
 ```
 
-Configured hosts are parsed with the OpenAI-compatible usage shape (`prompt_tokens` / `completion_tokens` / `total_tokens`, `input_tokens` / `output_tokens`, and optional cached-input details). Covers OpenRouter, DeepSeek, and private gateways exposing Chat Completions / Responses / Completions / Embeddings.
+Configured hosts are parsed using the OpenAI-compatible usage shape (`prompt_tokens` / `completion_tokens` / `total_tokens`, `input_tokens` / `output_tokens`, and optional cached-input details). This covers OpenRouter, DeepSeek, and private gateways exposing Chat Completions / Responses / Completions / Embeddings.
 
 ## Custom parser
 
@@ -373,20 +416,33 @@ LlmCostTracker::Parsers::Registry.register(AcmeParser.new)
 | Google Gemini | ✅ | Gemini 2.5 Pro/Flash/Flash-Lite, 2.0 Flash/Flash-Lite, 1.5 Pro/Flash |
 | Any other | 🔧 | Custom parser |
 
-Endpoints: OpenAI Chat Completions / Responses / Completions / Embeddings; OpenAI-compatible equivalents; Anthropic Messages; Gemini `generateContent` with `usageMetadata`.
+Endpoints: OpenAI Chat Completions / Responses / Completions / Embeddings; OpenAI-compatible equivalents; Anthropic Messages; Gemini `generateContent` and `streamGenerateContent`. All endpoints support streaming capture.
 
 ## Safety
 
-- No external HTTP calls.
+- No external HTTP calls at request-tracking time.
 - No prompt or response bodies stored.
 - Faraday responses not modified.
 - Storage failures non-fatal by default (`storage_error_behavior = :warn`).
-- Budget / unknown-pricing errors are raised only when you opt in.
+- Budget and unknown-pricing errors are raised only when you opt in.
+
+## Thread safety (Puma, Sidekiq)
+
+The gem is designed for multi-threaded hosts — Puma with `max_threads > 1` and Sidekiq with `concurrency > 1` are both supported. A few rules:
+
+- **Configure once at boot.** `LlmCostTracker.configure` deep-freezes `default_tags`, `pricing_overrides`, `report_tag_breakdowns`, and `openai_compatible_providers` when the block returns. Mutating or replacing shared fields through `LlmCostTracker.configuration` raises `FrozenError`.
+- **Use `:active_record` storage for shared ledgers.** Puma workers and Sidekiq processes do not share memory; `:log` and `:custom` backends see per-process state only. `:active_record` writes to a single table and is the right choice for dashboards and budget checks across processes.
+- **Size your connection pool.** Each tracked call on the middleware path issues up to three SQL queries (preflight `SUM`, `INSERT`, post-check `SUM`). Make sure the AR pool covers `puma max_threads + sidekiq concurrency` plus your app's own usage.
+- **Don't share a `StreamCollector` across threads you don't own.** The collector itself is thread-safe — `event`, `usage`, and `finish!` synchronize internally and `finish!` is idempotent — but the documented pattern is one collector per stream.
+- **`finish!` is a barrier.** Once a stream is finished, later `event`, `usage`, or `model=` calls raise `FrozenError` instead of mutating a closed collector.
+- **`ActiveSupport::Notifications` subscribers run synchronously** in the caller's thread. Keep them fast or hand off to a background job; otherwise they add latency to every tracked call.
+- **`storage_error_behavior = :raise` inside Sidekiq** will retry the job, which can duplicate an expensive LLM call. Prefer `:warn` plus a Notifications subscriber, or `:ignore`, for worker contexts.
 
 ## Known limitations
 
-- `:block_requests` is best-effort under concurrency; use an external quota system for hard caps.
-- Streaming/SSE tracked only when Faraday exposes a final body with usage.
+- `:block_requests` is a best-effort guardrail, not a hard cap. Concurrent workers can pass preflight simultaneously and collectively overshoot the budget. Use an external quota system if you need a transactional cap.
+- Streaming capture relies on the provider emitting a final-usage event (OpenAI needs `stream_options: { include_usage: true }`); missing events are recorded with `usage_source: "unknown"` so they surface on the Data Quality page.
+- `provider_response_id` is stored only when the provider exposes a stable response object ID. Missing IDs stay `nil` and surface on the Data Quality page.
 - Anthropic cache TTL variants (1h vs 5min writes) not modeled separately.
 - OpenAI reasoning tokens included in output totals; separate reasoning-token attribution not stored.
 

data/Rakefile

@@ -4,6 +4,8 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
 
+Dir[File.expand_path("lib/tasks/**/*.rake", __dir__)].each { |path| load path }
+
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new(:rubocop)
 

data/app/assets/llm_cost_tracker/application.css

@@ -34,7 +34,7 @@
     --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   }
 
-  body:has(> .lct-app) { margin: 0; }
+  .lct-body { margin: 0; }
 
   .lct-app {
     background: var(--lct-bg);
@@ -183,7 +183,6 @@
 
   .lct-stat-sub { color: var(--lct-muted); font-size: var(--fs-xs); margin: 4px 0 0; }
 
-  /* Shared "small uppercase-ish label" recipe */
   .lct-stat-label,
   .lct-field label,
   .lct-dl dt,
@@ -201,7 +200,6 @@
   .lct-chip-label { color: var(--lct-accent); font-weight: 700; }
   .lct-field label { color: var(--lct-text); font-size: var(--fs-md); font-weight: 500; }
 
-  /* Shared "muted body copy" recipe */
   .lct-section-copy,
   .lct-stat-copy,
   .lct-banner-copy,
@@ -285,7 +283,6 @@
   .lct-calls-table td:last-child,
   .lct-calls-table th:last-child { text-align: right; }
 
-  /* Track + fill primitives — shared by bar / budget / stack */
   .lct-bar-track,
   .lct-budget-track,
   .lct-stack-track {

data/app/controllers/llm_cost_tracker/assets_controller.rb

@@ -5,9 +5,8 @@ module LlmCostTracker
     skip_forgery_protection if respond_to?(:skip_forgery_protection)
 
     def stylesheet
-      path = File.join(LlmCostTracker::Assets.root, LlmCostTracker::Assets::STYLESHEET)
       response.set_header("Cache-Control", "public, max-age=31536000, immutable")
-      send_file path, type: "text/css", disposition: "inline"
+      send_file LlmCostTracker::Assets::STYLESHEET_PATH, type: "text/css", disposition: "inline"
     end
   end
 end

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -6,6 +6,7 @@ module LlmCostTracker
   class CallsController < ApplicationController
     CSV_EXPORT_LIMIT = 10_000
     CSV_FORMULA_PREFIXES = ["=", "+", "-", "@", "\t", "\r"].freeze
+    DEFAULT_ORDER = "tracked_at DESC, id DESC"
 
     def index
       @sort = params[:sort].to_s
@@ -30,9 +31,6 @@ module LlmCostTracker
 
     def show
       @call = LlmApiCall.find(params[:id])
-      @tags = @call.parsed_tags
-      @metadata_available = @call.has_attribute?("metadata")
-      @metadata = @call.read_attribute("metadata") if @metadata_available
       @latency_available = LlmApiCall.latency_column?
     end
 
@@ -41,29 +39,26 @@ module LlmCostTracker
     def calls_order(sort)
       case sort
       when "expensive"
-        "CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END ASC, total_cost DESC, #{default_order}"
+        "CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END ASC, total_cost DESC, #{DEFAULT_ORDER}"
       when "input"
-        "input_tokens DESC, #{default_order}"
+        "input_tokens DESC, #{DEFAULT_ORDER}"
       when "output"
-        "output_tokens DESC, #{default_order}"
+        "output_tokens DESC, #{DEFAULT_ORDER}"
       when "slow"
-        return default_order unless LlmApiCall.latency_column?
+        return DEFAULT_ORDER unless LlmApiCall.latency_column?
 
-        "CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC, latency_ms DESC, #{default_order}"
+        "CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC, latency_ms DESC, #{DEFAULT_ORDER}"
       else
-        default_order
+        DEFAULT_ORDER
       end
     end
 
-    def default_order
-      "tracked_at DESC, id DESC"
-    end
-
     def render_csv(relation)
       latency = LlmApiCall.latency_column?
       CSV.generate do |csv|
         headers = %w[tracked_at provider model input_tokens output_tokens total_tokens total_cost]
         headers << "latency_ms" if latency
+        headers << "provider_response_id" if LlmApiCall.provider_response_id_column?
         headers << "tags"
         csv << headers
 
@@ -78,6 +73,7 @@ module LlmCostTracker
             call.total_cost
           ]
           row << call.latency_ms if latency
+          row << csv_safe(call.provider_response_id) if LlmApiCall.provider_response_id_column?
           row << csv_safe(call.parsed_tags.to_json)
           csv << row
         end

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -5,15 +5,19 @@ module LlmCostTracker
     def index
       @from_date, @to_date = overview_range
       prev_from, prev_to = previous_range
-      scope = Dashboard::Filter.call(params: overview_filter_params)
-      previous_scope = Dashboard::Filter.call(params: previous_filter_params)
-      model_rows = Dashboard::TopModels.call(scope: scope, limit: 10)
+      filter_params = LlmCostTracker::ParameterHash.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)
+      )
 
       @stats = Dashboard::OverviewStats.call(scope: scope, previous_scope: previous_scope)
       @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)
-      @top_models = model_rows.first(5)
+      @top_models = Dashboard::TopModels.call(scope: scope)
       @providers = Dashboard::ProviderBreakdown.call(scope: scope)
     end
 
@@ -32,21 +36,6 @@ module LlmCostTracker
       [prev_from, prev_to]
     end
 
-    def overview_filter_params
-      params.to_unsafe_h.merge(
-        "from" => @from_date.iso8601,
-        "to" => @to_date.iso8601
-      )
-    end
-
-    def previous_filter_params
-      prev_from, prev_to = previous_range
-      params.to_unsafe_h.merge(
-        "from" => prev_from.iso8601,
-        "to" => prev_to.iso8601
-      )
-    end
-
     def parsed_date(value)
       return nil if value.to_s.strip.empty?
 

data/app/controllers/llm_cost_tracker/data_quality_controller.rb

@@ -3,8 +3,7 @@
 module LlmCostTracker
   class DataQualityController < ApplicationController
     def index
-      scope = Dashboard::Filter.call(params: params)
-      @stats = Dashboard::DataQuality.call(scope: scope)
+      @stats = Dashboard::DataQuality.call(scope: Dashboard::Filter.call(params: params))
     end
   end
 end

data/app/controllers/llm_cost_tracker/models_controller.rb

@@ -3,9 +3,12 @@
 module LlmCostTracker
   class ModelsController < ApplicationController
     def index
-      scope = Dashboard::Filter.call(params: params)
       @sort = params[:sort].to_s
-      @rows = Dashboard::TopModels.call(scope: scope, limit: nil, sort: @sort)
+      @rows = Dashboard::TopModels.call(
+        scope: Dashboard::Filter.call(params: params),
+        limit: nil,
+        sort: @sort
+      )
       @latency_available = LlmApiCall.latency_column?
     end
   end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -3,14 +3,12 @@
 module LlmCostTracker
   class TagsController < ApplicationController
     def index
-      scope = Dashboard::Filter.call(params: params)
-      @rows = Dashboard::TagKeyExplorer.call(scope: scope)
+      @rows = Dashboard::TagKeyExplorer.call(scope: Dashboard::Filter.call(params: params))
     end
 
     def show
       @tag_key = params[:key]
-      scope = Dashboard::Filter.call(params: params)
-      @rows = Dashboard::TagBreakdown.call(scope: scope, key: @tag_key)
+      @rows = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: @tag_key)
       @total_calls = @rows.sum(&:calls)
 
       tagged_rows = @rows.reject { |r| r.value == "(untagged)" }

data/app/helpers/llm_cost_tracker/dashboard_filter_helper.rb

@@ -2,7 +2,12 @@
 
 module LlmCostTracker
   module DashboardFilterHelper
-    FILTER_PARAM_KEYS = %i[from to provider model tag sort page per].freeze
+    FILTER_PARAM_KEYS = %i[from to provider model stream usage_source tag sort page per].freeze
+
+    STREAM_FILTER_OPTIONS = [
+      ["Streaming only", "yes"],
+      ["Non-streaming only", "no"]
+    ].freeze
 
     def any_filter_applied?
       FILTER_PARAM_KEYS.any? { |key| params[key].present? }

data/app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb

@@ -13,7 +13,7 @@ module LlmCostTracker
     private
 
     def filter_options_for(column, filter_params:)
-      source = filter_source_hash(filter_params)
+      source = LlmCostTracker::ParameterHash.to_hash(filter_params)
       scope_params = source.stringify_keys.merge(
         column.to_s => nil, "format" => nil, "page" => nil, "per" => nil, "sort" => nil
       )
@@ -24,11 +24,5 @@ module LlmCostTracker
       values.unshift(current) if current && !values.include?(current)
       values
     end
-
-    def filter_source_hash(filter_params)
-      return filter_params.to_unsafe_h if filter_params.respond_to?(:to_unsafe_h)
-
-      filter_params.to_h
-    end
   end
 end

data/app/helpers/llm_cost_tracker/dashboard_query_helper.rb

@@ -19,18 +19,14 @@ module LlmCostTracker
     private
 
     def normalized_query_tags(tags)
-      return {} unless tags
-
-      tags = tags.to_unsafe_h if tags.respond_to?(:to_unsafe_h)
-      tags = tags.to_h if tags.respond_to?(:to_h)
-      return {} unless tags.is_a?(Hash)
-
-      tags.transform_keys(&:to_s).transform_values(&:to_s)
+      LlmCostTracker::ParameterHash.to_hash(tags).transform_keys(&:to_s).transform_values(&:to_s)
     end
 
     def clean_dashboard_query(value)
-      return clean_dashboard_hash(value.to_unsafe_h) if value.is_a?(ActionController::Parameters)
-      return clean_dashboard_hash(value) if value.is_a?(Hash)
+      if LlmCostTracker::ParameterHash.hash_like?(value)
+        return clean_dashboard_hash(LlmCostTracker::ParameterHash.to_hash(value))
+      end
+
       return clean_dashboard_array(value) if value.is_a?(Array)
       return clean_dashboard_string(value) if value.is_a?(String)