llm_cost_tracker 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b20da957651521f022866af9d4735a4ef53d52a2dc3c278b8b2a90e1d7a7f98
-  data.tar.gz: ea98b2a7505d99c5f78d7756d0adc50224c4fdc88000fa5ec81be4450c9200f1
+  metadata.gz: 6952282e6f93b4e5658ef9d2b9527d2a332cb2d6f483da25540c3a0d6672ed9b
+  data.tar.gz: e66eaaeb99698abf9c0ff9e3f1305e6bb27a8b6c25355e94bce4baec5f5d3a50
 SHA512:
-  metadata.gz: 9ca709080d46395ac32b9a2931b4b3cb7d4df6016b73bad3579cb1decdd046be21a2fb67c06e96876013a754a113e9ce5987ed0e27792b312716324bdb5f9adb
-  data.tar.gz: 445b77222180802f208246a2e25b30e5e0a5679d2d5b84a2ba00d1e2fc97a5cf3127521be13f415c6d76bbcc056dd0bdfe6ade937eb9d67d737ce6b6548665fa
+  metadata.gz: '078d695498ed6f254a700ccb3381ace3feaa1f4880691a1a69be4bb435097202ecf28f2cbf065202a543186bdd3894aaedcc44bfacc2d2ffa25a54ddf6d1cc76'
+  data.tar.gz: 2638ae3c579bd2c0f71a73b06719eb0a35d7b82e8614a74c5100f41b69693babfd3b613ecf18e7f6e7ea33210222432efa5a7ca718325c4c8fd12be9b8ab806e

data/CHANGELOG.md

@@ -4,6 +4,29 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-04-22
+
+### Added
+
+- Test coverage reporting via SimpleCov with LCOV upload to Codecov from CI.
+- Repository governance files: `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CONTRIBUTING.md`, and GitHub issue templates.
+
+## [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

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, as its code of conduct. The full text is available at:
+
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+## Our pledge
+
+We as contributors and maintainers pledge to make participation in this project a welcoming, respectful, and inclusive experience for everyone.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (issues, pull requests, discussions, commit messages, review comments) and in public spaces when an individual is representing the project.
+
+## Reporting
+
+Instances of unacceptable behavior may be reported to the project maintainer at **sergey@mm.st**. All reports will be reviewed and investigated promptly and fairly. The maintainer is obligated to respect the privacy and safety of the reporter of any incident.
+
+## Enforcement
+
+Maintainers are responsible for clarifying and enforcing the standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, or harmful. This may include warnings, temporary bans, or permanent removal from project participation.
+
+For the full set of community standards, enforcement guidelines, and attribution, see the canonical document linked above.

data/README.md

@@ -4,14 +4,70 @@
 
 [![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)
+
+Requires Ruby 3.3+, Rails/ActiveRecord 7.1+, and Faraday 2.0+.
+Core tracking works without Rails; the mounted dashboard requires Rails 7.1+.
 
 ## 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 solve a broader set of problems; sometimes you just need a small Rails-native ledger in your own database.
 
-`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.
+## What You Get
+
+- A local ActiveRecord ledger of provider, model, tokens, cost, latency, tags, streaming usage, and provider response IDs
+- Faraday middleware plus explicit `track` / `track_stream` helpers for non-Faraday clients
+- Server-rendered Rails dashboard with overview, calls, tags, CSV export, and data-quality pages
+- Local pricing snapshots, price sync tasks, and budget guardrails
+- Prompt and response bodies are never persisted
+
+## Dashboard
+
+LLM Cost Tracker ships with an optional server-rendered Rails Engine dashboard for spend review, attribution, and data quality checks.
+
+![LLM Cost Tracker dashboard](docs/dashboard-overview.png)
+
+The overview page includes spend trend, budget status, provider breakdown, top models, and filterable slices. The engine also includes Calls, Tags, and Data Quality pages. Plain ERB, no JavaScript bundle.
+
+## Quickstart
+
+```ruby
+gem "llm_cost_tracker"
+```
+
+```bash
+bin/rails generate llm_cost_tracker:install
+bin/rails db:migrate
+```
 
-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.
+```ruby
+LlmCostTracker.configure do |config|
+  config.storage_backend = :active_record
+  config.default_tags = { app: "my_app", environment: Rails.env }
+end
+
+OpenAI.configure do |config|
+  config.access_token = ENV["OPENAI_API_KEY"]
+  config.faraday do |f|
+    f.use :llm_cost_tracker, tags: -> { { user_id: Current.user&.id, feature: "chat" } }
+  end
+end
+```
+
+```ruby
+mount LlmCostTracker::Engine => "/llm-costs"
+```
+
+After that, LLM Cost Tracker starts recording calls into `llm_api_calls` and the dashboard becomes available at `/llm-costs`.
+Protect the mounted engine with your application's authentication before exposing it outside development.
+
+## Tradeoffs
+
+- Self-hosted ledger first: no proxy, no SaaS, no separate service to operate
+- Best-effort pricing for spend review and attribution, not invoice-grade billing
+- No prompt or response body storage
+- No built-in auth on the mounted dashboard
+- Use `:active_record` when you want shared dashboards and budget checks across Puma workers and Sidekiq processes
 
 ## Installation
 
@@ -78,6 +134,8 @@ Anthropic emits usage in `message_start` + `message_delta` events. Gemini's `:st
 
 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
@@ -92,7 +150,16 @@ LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o") do |stream|
 end
 ```
 
-Run `bin/rails g llm_cost_tracker:add_streaming` once on existing installs to add the `stream` and `usage_source` columns.
+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
 
@@ -102,6 +169,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
@@ -281,7 +349,7 @@ bin/rails generate llm_cost_tracker:add_latency_ms
 bin/rails db:migrate
 ```
 
-## Dashboard (optional)
+## Mounting the dashboard
 
 Optional Rails Engine. Plain ERB, no JavaScript framework, no asset pipeline required. Requires Rails 7.1+; the core middleware works without Rails.
 
@@ -303,7 +371,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 application's authentication.
+No built-in auth is included. Tags carry whatever your app puts in them, so protect the mount point with your application's authentication.
 
 ### Basic auth
 
@@ -369,20 +437,26 @@ Configured hosts are parsed using the OpenAI-compatible usage shape (`prompt_tok
 For providers with a non-OpenAI usage shape:
 
 ```ruby
+require "uri"
+
 class AcmeParser < LlmCostTracker::Parsers::Base
   def match?(url)
-    url.to_s.include?("api.acme-llm.example")
+    uri = URI.parse(url.to_s)
+    uri.host == "api.acme-llm.example" && uri.path == "/v1/generate"
+  rescue URI::InvalidURIError
+    false
   end
 
   def parse(request_url, request_body, response_status, response_body)
     return nil unless response_status == 200
 
-    usage = safe_json_parse(response_body)&.dig("usage")
+    payload = safe_json_parse(response_body)
+    usage = payload&.dig("usage")
     return nil unless usage
 
     LlmCostTracker::ParsedUsage.build(
       provider: "acme",
-      model: safe_json_parse(response_body)["model"],
+      model: payload["model"],
       input_tokens: usage["input"] || 0,
       output_tokens: usage["output"] || 0
     )
@@ -408,9 +482,12 @@ Endpoints: OpenAI Chat Completions / Responses / Completions / Embeddings; OpenA
 
 ## Safety
 
+**By design, `llm_cost_tracker` never persists prompt or response content.** The only data stored per call is the metadata needed for a cost ledger (provider, model, token counts, cost, latency, tags, provider response ID, HTTP status, and a timestamp). Tags carry whatever your application passes in — treat them as user-controlled input and avoid putting request bodies, completions, or secrets into them.
+
 - No external HTTP calls at request-tracking time.
 - No prompt or response bodies stored.
 - Faraday responses not modified.
+- Authorization headers and API keys are never stored or logged.
 - Storage failures non-fatal by default (`storage_error_behavior = :warn`).
 - Budget and unknown-pricing errors are raised only when you opt in.
 
@@ -430,6 +507,7 @@ The gem is designed for multi-threaded hosts — Puma with `max_threads > 1` and
 
 - `: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/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Supported versions
+
+The gem is pre-1.0. Only the latest released version receives security fixes — please upgrade rather than expecting backports to older releases.
+
+## Reporting a vulnerability
+
+Please **do not open a public GitHub issue** for security reports.
+
+Email **sergey@mm.st** with:
+
+- A description of the issue and its potential impact
+- Steps to reproduce (a minimal proof-of-concept is ideal)
+- The affected version(s)
+- Any suggested mitigation or fix
+
+You will receive an acknowledgment within **72 hours**. I will work with you on a disclosure timeline — typically a fix plus a coordinated release within 14 days for confirmed vulnerabilities, longer if the issue is complex.
+
+## Scope
+
+In scope:
+
+- Vulnerabilities in the gem's middleware, parsers, storage adapters, dashboard controllers, or generators
+- Data-exposure issues (unintended persistence of prompt content, API keys, or response bodies)
+- Injection, auth-bypass, or privilege-escalation in the mounted dashboard
+
+Out of scope:
+
+- Issues in third-party dependencies (report those upstream; mention them here only if this gem's usage pattern creates the vulnerability)
+- Missing security hardening recommendations that are not vulnerabilities (open a regular issue instead)
+- Social engineering or physical attacks
+
+## Credit
+
+Reporters who follow this policy will be credited in the release notes for the fix unless they request anonymity.

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

@@ -2,8 +2,6 @@
 
 module LlmCostTracker
   class AssetsController < ActionController::Base
-    skip_forgery_protection if respond_to?(:skip_forgery_protection)
-
     def stylesheet
       response.set_header("Cache-Control", "public, max-age=31536000, immutable")
       send_file LlmCostTracker::Assets::STYLESHEET_PATH, type: "text/css", disposition: "inline"

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_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)
 

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

@@ -11,6 +11,8 @@ module LlmCostTracker
       :streaming_count,
       :streaming_missing_usage_count,
       :stream_column_present,
+      :missing_provider_response_id_count,
+      :provider_response_id_column_present,
       :unknown_pricing_by_model
     )
 
@@ -20,6 +22,7 @@ module LlmCostTracker
           total = scope.count
           latency_present = LlmCostTracker::LlmApiCall.latency_column?
           stream_present = LlmCostTracker::LlmApiCall.stream_column?
+          provider_response_id_present = LlmCostTracker::LlmApiCall.provider_response_id_column?
 
           DataQualityStats.new(
             total_calls: total,
@@ -28,8 +31,14 @@ module LlmCostTracker
             missing_latency_count: latency_present ? scope.where(latency_ms: nil).count : nil,
             latency_column_present: latency_present,
             streaming_count: stream_present ? scope.streaming.count : nil,
-            streaming_missing_usage_count: streaming_missing_usage_count(scope, stream_present),
+            streaming_missing_usage_count: if stream_present && LlmCostTracker::LlmApiCall.usage_source_column?
+                                             scope.streaming_missing_usage.count
+                                           end,
             stream_column_present: stream_present,
+            missing_provider_response_id_count: (
+              provider_response_id_present ? scope.missing_provider_response_id.count : nil
+            ),
+            provider_response_id_column_present: provider_response_id_present,
             unknown_pricing_by_model: scope.unknown_pricing
                                       .group(:model)
                                       .order(Arel.sql("COUNT(*) DESC"))
@@ -38,15 +47,6 @@ module LlmCostTracker
                                       .to_h
           )
         end
-
-        private
-
-        def streaming_missing_usage_count(scope, stream_present)
-          return nil unless stream_present
-          return nil unless LlmCostTracker::LlmApiCall.usage_source_column?
-
-          scope.streaming_missing_usage.count
-        end
       end
     end
   end

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

@@ -4,10 +4,6 @@ require "date"
 
 module LlmCostTracker
   module Dashboard
-    # Parses dashboard params into an ActiveRecord relation.
-    #
-    # Invalid dates are ignored, pagination is handled elsewhere, and invalid
-    # tag keys raise InvalidFilterError so controllers can fail closed with HTTP 400.
     class Filter
       class << self
         def call(scope: LlmCostTracker::LlmApiCall.all, params: {})
@@ -17,7 +13,7 @@ module LlmCostTracker
 
       def initialize(scope:, params:)
         @scope = scope
-        @params = normalize_params(params)
+        @params = LlmCostTracker::ParameterHash.with_indifferent_access(params)
       end
 
       def relation
@@ -34,15 +30,6 @@ module LlmCostTracker
 
       attr_reader :scope, :params
 
-      def normalize_params(params)
-        return {}.with_indifferent_access if params.nil?
-
-        raw = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
-        raw.with_indifferent_access
-      rescue NoMethodError
-        {}.with_indifferent_access
-      end
-
       def apply_date_filters(relation)
         from = parse_date(:from)&.beginning_of_day
         to = parse_date(:to)&.end_of_day
@@ -53,7 +40,7 @@ module LlmCostTracker
       end
 
       def apply_exact_filter(relation, key)
-        value = string_param(key)
+        value = normalized_string(params[key])
         return relation if value.nil?
 
         relation.where(key => value)
@@ -67,7 +54,7 @@ module LlmCostTracker
       end
 
       def apply_stream_filter(relation)
-        value = string_param(:stream)
+        value = normalized_string(params[:stream])
         return relation if value.nil?
         return relation unless relation.klass.stream_column?
 
@@ -79,7 +66,7 @@ module LlmCostTracker
       end
 
       def apply_usage_source_filter(relation)
-        value = string_param(:usage_source)
+        value = normalized_string(params[:usage_source])
         return relation if value.nil?
         return relation unless relation.klass.usage_source_column?
 
@@ -98,14 +85,11 @@ module LlmCostTracker
       end
 
       def hash_param(key)
-        raw = params[key]
-        raw = raw.to_unsafe_h if raw.respond_to?(:to_unsafe_h)
-        raw = raw.to_h if raw.respond_to?(:to_h)
-        raw.is_a?(Hash) ? raw : {}
+        LlmCostTracker::ParameterHash.to_hash(params[key])
       end
 
       def parse_date(key)
-        value = string_param(key)
+        value = normalized_string(params[key])
         return nil if value.nil?
 
         Date.iso8601(value)
@@ -113,10 +97,6 @@ module LlmCostTracker
         nil
       end
 
-      def string_param(key)
-        normalized_string(params[key])
-      end
-
       def normalized_string(value)
         return nil if value.nil?