llm_cost_tracker 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6942269ea8e3ce5f22bb30a1dc6f6c73ee056b33f4f5d7697d1749ce5742ca93
-  data.tar.gz: 1b0712cfcbea56ee0e03dd1cb6c400969fc485c5648f75616140a62f6e82fc02
+  metadata.gz: fbf918d9a4886e24ba99f93dc1125e016e50b45208437dd3254adda76f58033a
+  data.tar.gz: 8a22ccfa517549f55d2a302287660a8a5d7faf03568e80c253e6024ad4988743
 SHA512:
-  metadata.gz: 9793cc211dd08669deecf4a1d6a242ec4f2fff3fc41922472d158002731f4db40d618163d6fb054eeb36cae4e8aa708a0055a0fe1820faf88081b26de407107a
-  data.tar.gz: 05ed21f8309b16475b4ca7a0a938c999336f0ebb09baf897225422c69dd8e7e81f73ef01e69ff2d4c80d392f49230c212a87ec5c925c6e242b24942c5369f37f
+  metadata.gz: 4ef6bc278f6f98ce37a91e515e8b4a004aaff5f573fc8580e312e53b903d1e7700b2cd58b9bea72fc0ec904010cba43fb0209e7993c31bb69205b42564554884
+  data.tar.gz: 4c9a193d16bb5e8bfa58aaefb6fb9b7d98a632a8e19203927c3fd29b957da6088af71caf5c14f5f2b7452660f78001d7898745f8d7611a4fd6e94311b723bc71

data/CHANGELOG.md

@@ -4,6 +4,30 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-04-30
+
+### Changed
+
+- BREAKING: ActiveRecord ledger write failures now raise directly; removed `storage_error_behavior` and `StorageError`.
+- BREAKING: Removed custom parser and SDK integration registration APIs; use built-in capture or explicit `track` / `track_stream`.
+- BREAKING: Usage and pricing APIs now use `TokenUsage`; removed `UsageBreakdown`, `add_usage_breakdown`, direct `Pricing` token arguments, and `Pricing::Cost`.
+- BREAKING: `Tracker.record` now accepts `UsageCapture`, and notification payloads nest `token_usage`.
+- BREAKING: Moved price registry and refresh APIs under `LlmCostTracker::Pricing`.
+- BREAKING: ActiveRecord installs must run the current ledger and period-total migrations; doctor, dashboard setup, and flush now fail on stale schema.
+- BREAKING: `cache_write_input_tokens` now stores only standard cache writes; 1-hour cache writes use `cache_write_1h_input_tokens` and `cache_write_1h_input_cost`.
+- Dashboard model and data-quality pages now use canonical `TokenUsage` totals.
+- OpenAI, Anthropic, and RubyLLM capture now populate `pricing_mode` from provider tier data.
+- Pricing now handles Anthropic 1-hour cache-write TTLs, Gemini context-cache reads, stackable batch cache rates, and long-context tiers.
+- Missing positive-token pricing-mode rates now return unknown pricing instead of falling back to standard prices.
+
+## [0.7.0] - 2026-04-29
+
+### Changed
+
+- BREAKING: ActiveRecord is now the only storage path; removed `storage_backend`, `custom_storage`, `Storage.register`, `:log`, and `:custom`.
+- BREAKING: PostgreSQL and MySQL are now the only supported database adapters; SQLite support was removed.
+- Runtime dependencies now include Rails and ActiveRecord.
+
 ## [0.6.1] - 2026-04-29
 
 ### Fixed

data/README.md

@@ -10,7 +10,7 @@ If you have OpenAI, Anthropic, or Gemini in production and someone keeps asking
 
 It is not Langfuse, Helicone, or LiteLLM. It does not capture prompts, score completions, or replay traces. It does one thing: tells you which provider, which model, which feature, and which user burned how much money. That's the entire pitch.
 
-Requires Ruby 3.3+, ActiveSupport 7.1+, Faraday 2.0+. ActiveRecord storage and the dashboard need Rails 7.1+.
+Requires Ruby 3.3+, Rails 7.1+, PostgreSQL or MySQL, and Faraday 2.0+.
 
 ![Dashboard overview](docs/dashboard-overview.png)
 
@@ -35,7 +35,6 @@ Drop this into `config/initializers/llm_cost_tracker.rb`:
 
 ```ruby
 LlmCostTracker.configure do |config|
-  config.storage_backend = :active_record
   config.default_tags    = -> { { environment: Rails.env } }
   config.instrument :openai
 end
@@ -91,7 +90,7 @@ LlmCostTracker.with_tags(feature: "support_chat") do
 end
 ```
 
-Captures usage, model, latency, response ID, cache tokens, and reasoning tokens whenever the SDK exposes them. Provider SDKs are not added as gem dependencies — you install whichever you actually use.
+Captures usage, model, latency, response ID, pricing mode, cache tokens, Anthropic cache-write TTLs, and reasoning tokens whenever the SDK exposes them. Provider SDKs are not added as gem dependencies — you install whichever you actually use.
 
 Enabled integrations are checked at boot: the client gem must be loaded, meet the minimum supported version, and expose the expected classes and methods. If the contract check fails, boot raises instead of silently missing spend.
 
@@ -135,7 +134,7 @@ For streaming the same way, `track_stream` accepts a block, parses provider even
 
 ## Tags: who burned this money
 
-Tags answer the only question that matters in attribution: which feature, which user, which job, which tenant. They're free-form strings, indexed (JSONB on Postgres, fallback elsewhere), and queryable from both Ruby and the dashboard.
+Tags answer the only question that matters in attribution: which feature, which user, which job, which tenant. They're free-form strings, stored as JSONB on PostgreSQL or JSON on MySQL, and queryable from both Ruby and the dashboard.
 
 ```ruby
 LlmCostTracker.with_tags(user_id: current_user.id, feature: "support_chat", trace_id: request.uuid) do
@@ -173,7 +172,9 @@ Explain why a model is priced or unknown:
 PROVIDER=openai MODEL=gpt-4o bin/rails llm_cost_tracker:prices:explain
 ```
 
-Precedence is `pricing_overrides` → `prices_file` → bundled. Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys. Full pricing reference: [`docs/pricing.md`](docs/pricing.md).
+Precedence is `pricing_overrides` → `prices_file` → bundled. Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys.
+
+`pricing_mode` selects mode-prefixed rates such as `batch_input` or `priority_output`. Built-in capture fills it from provider tier fields when available; explicit `track` calls can pass it directly for batch jobs or gateway-specific modes. Full pricing reference: [`docs/pricing.md`](docs/pricing.md).
 
 ## Budgets
 
@@ -196,10 +197,10 @@ Full behavior, error class, and preflight details: [`docs/budgets.md`](docs/budg
 When you want to slice spend from a console, scheduled job, or your own admin page:
 
 ```ruby
-LlmCostTracker::LlmApiCall.this_month.cost_by_model
-LlmCostTracker::LlmApiCall.this_month.cost_by_tag("feature")
-LlmCostTracker::LlmApiCall.daily_costs(days: 7)
-LlmCostTracker::LlmApiCall.by_tags(user_id: 42, feature: "chat").this_month.total_cost
+LlmCostTracker::Ledger::Call.this_month.cost_by_model
+LlmCostTracker::Ledger::Call.this_month.cost_by_tag("feature")
+LlmCostTracker::Ledger::Call.daily_costs(days: 7)
+LlmCostTracker::Ledger::Call.by_tags(user_id: 42, feature: "chat").this_month.total_cost
 ```
 
 A text report is also one rake task away:
@@ -219,7 +220,7 @@ Mount the engine wherever you want — it's plain ERB, no JavaScript bundle, no
 mount LlmCostTracker::Engine => "/llm-costs"
 ```
 
-Pages: overview (spend trend, budget status, anomaly banner), models, calls (filterable, paginated, CSV export), tags, data quality. Reads `llm_api_calls`, so use `:active_record` storage if you want to mount it.
+Pages: overview (spend trend, budget status, anomaly banner), models, calls (filterable, paginated, CSV export), tags, data quality. Reads the ActiveRecord ledger in `llm_api_calls`.
 
 Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs/dashboard.md).
 
@@ -233,7 +234,7 @@ Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs
 | OpenRouter | Yes | OpenAI-compatible usage; provider-prefixed model IDs are normalized |
 | DeepSeek | Yes | OpenAI-compatible usage; add `pricing_overrides` for DeepSeek-specific rates |
 | Other OpenAI-compatible hosts | Configurable | Register the host via `config.openai_compatible_providers` |
-| Anything else | Configurable | Custom parser — see [`docs/extending.md`](docs/extending.md) |
+| Anything else | Manual | Use `LlmCostTracker.track` / `track_stream` |
 
 RubyLLM chat, embedding, and transcription calls are captured through RubyLLM's provider layer when `config.instrument :ruby_llm` is enabled.
 
@@ -267,8 +268,8 @@ is still brief.
 
 - `:block_requests` is best-effort under concurrency, not a transactional cap.
 - Streaming usage capture relies on the provider emitting a final-usage event. Missing events are stored with `usage_source: "unknown"` so they appear on the data-quality page rather than vanishing.
+- Non-token line items such as Gemini explicit-cache storage duration, provider tool calls, and modality-specific surcharges are not folded into token cost.
 - `provider_response_id` is stored only when the provider exposes a stable ID. Gemini is best-effort and varies by endpoint.
-- Cache write TTL variants on Anthropic (1h vs 5min writes) are not modeled separately yet.
 
 ## Development
 

data/app/assets/llm_cost_tracker/application.css

@@ -302,6 +302,9 @@
   .lct-budget-fill--warn { background: linear-gradient(90deg, #f59e0b, #d97706); }
   .lct-budget-fill--over { background: linear-gradient(90deg, #ef4444, #b91c1c); }
   .lct-stack-fill-input  { background: var(--lct-accent); }
+  .lct-stack-fill-cache-read { background: #22c55e; }
+  .lct-stack-fill-cache-write { background: #f59e0b; }
+  .lct-stack-fill-cache-write-1h { background: #a855f7; }
   .lct-stack-fill-output { background: #0ea5e9; }
 
   .lct-budget { display: grid; gap: 10px; }

data/app/controllers/llm_cost_tracker/application_controller.rb

@@ -4,7 +4,7 @@ module LlmCostTracker
   class ApplicationController < ActionController::Base
     layout "llm_cost_tracker/application"
 
-    before_action :ensure_llm_api_calls_table
+    before_action :ensure_current_schema
 
     rescue_from ActiveRecord::ConnectionNotEstablished, with: :render_database_error
     rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
@@ -13,9 +13,27 @@ module LlmCostTracker
 
     private
 
-    def ensure_llm_api_calls_table
-      return if LlmCostTracker::LlmApiCall.table_exists?
-
+    def ensure_current_schema
+      unless LlmCostTracker::Ledger::Call.table_exists?
+        @setup_message = "The llm_api_calls table is not available yet."
+        return render template: "llm_cost_tracker/shared/setup_required"
+      end
+
+      schema_errors = LlmCostTracker::Ledger::Schema::Calls.current_schema_errors
+      if schema_errors.any?
+        @setup_message = "The llm_api_calls table does not match the current LLM Cost Tracker schema."
+        @setup_details = schema_errors
+        render template: "llm_cost_tracker/shared/setup_required"
+        return
+      end
+
+      period_total_errors = LlmCostTracker::Ledger::Schema::PeriodTotals.current_schema_errors
+      return if period_total_errors.empty?
+
+      @setup_message = "The llm_cost_tracker_period_totals table does not match the current LLM Cost Tracker schema."
+      @setup_details = period_total_errors + [
+        "run bin/rails generate llm_cost_tracker:add_period_totals && bin/rails db:migrate"
+      ]
       render template: "llm_cost_tracker/shared/setup_required"
     end
 

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -14,11 +14,10 @@ module LlmCostTracker
       scope = Dashboard::Filter.call(params: params)
       scope = scope.unknown_pricing if @sort == "unknown_pricing"
       ordered_scope = scope.order(Arel.sql(calls_order(@sort)))
-      @latency_available = LlmApiCall.latency_column?
 
       respond_to do |format|
         format.html do
-          @page = Pagination.call(params)
+          @page = Dashboard::Pagination.call(params)
           @calls_count = scope.count
           @calls = ordered_scope.limit(@page.limit).offset(@page.offset).to_a
         end
@@ -31,8 +30,7 @@ module LlmCostTracker
     end
 
     def show
-      @call = LlmApiCall.find(params[:id])
-      @latency_available = LlmApiCall.latency_column?
+      @call = Ledger::Call.find(params[:id])
     end
 
     private
@@ -46,8 +44,6 @@ module LlmCostTracker
       when "output"
         "output_tokens DESC, #{DEFAULT_ORDER}"
       when "slow"
-        return DEFAULT_ORDER unless LlmApiCall.latency_column?
-
         "CASE WHEN latency_ms IS NULL THEN 1 ELSE 0 END ASC, latency_ms DESC, #{DEFAULT_ORDER}"
       else
         DEFAULT_ORDER
@@ -66,11 +62,10 @@ module LlmCostTracker
     end
 
     def csv_fields
-      fields = %i[tracked_at provider model input_tokens output_tokens total_tokens total_cost]
-      fields << :latency_ms if LlmApiCall.latency_column?
-      fields << :provider_response_id if LlmApiCall.provider_response_id_column?
-      fields << :tags
-      fields
+      %i[tracked_at provider model] +
+        TokenUsage::STORED_KEYS +
+        Pricing::COST_KEYS +
+        %i[latency_ms provider_response_id tags]
     end
 
     def csv_value(field, value)

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -7,7 +7,7 @@ module LlmCostTracker
       @from_date = range.from
       @to_date = range.to
       prev_from, prev_to = previous_range
-      filter_params = LlmCostTracker::ParameterHash.to_hash(params)
+      filter_params = LlmCostTracker::Dashboard::Params.to_hash(params)
       scope = Dashboard::Filter.call(
         params: filter_params.merge("from" => @from_date.iso8601, "to" => @to_date.iso8601)
       )
@@ -16,6 +16,7 @@ module LlmCostTracker
       )
 
       @stats = Dashboard::OverviewStats.call(scope: scope, previous_scope: previous_scope)
+      @monthly_budget_status = Dashboard::OverviewStats.monthly_budget_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/data_quality_controller.rb

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

data/app/controllers/llm_cost_tracker/models_controller.rb

@@ -9,7 +9,6 @@ module LlmCostTracker
         limit: nil,
         sort: @sort
       )
-      @latency_available = LlmApiCall.latency_column?
     end
   end
 end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -7,14 +7,7 @@ module LlmCostTracker
     end
 
     def show
-      @tag_key = params[:key]
-      breakdown = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: @tag_key)
-      @rows = breakdown.rows
-      @total_calls = breakdown.total_calls
-      @tagged_calls = breakdown.tagged_calls
-      @distinct_values = breakdown.distinct_values
-      @tag_value_limit = breakdown.limit
-      @tag_values_limited = breakdown.limited?
+      @breakdown = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: params[:key])
     end
   end
 end

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -12,6 +12,7 @@ module LlmCostTracker
     include DashboardQueryHelper
     include ChartHelper
     include PaginationHelper
+    include TokenUsageHelper
 
     def coverage_percent(numerator, denominator)
       return 0.0 unless denominator.to_i.positive?
@@ -43,7 +44,7 @@ module LlmCostTracker
     end
 
     def format_date(value)
-      value.respond_to?(:strftime) ? value.strftime("%Y-%m-%d %H:%M") : value.to_s
+      value.try(:strftime, "%Y-%m-%d %H:%M") || value.to_s
     end
 
     def pricing_status(call)

data/app/helpers/llm_cost_tracker/dashboard_filter_helper.rb

@@ -14,8 +14,7 @@ module LlmCostTracker
     end
 
     def active_tag_filters
-      tag_params = normalized_query_tags(params[:tag])
-      return [] unless tag_params.is_a?(Hash)
+      tag_params = LlmCostTracker::Dashboard::Params.to_hash(params[:tag]).transform_keys(&:to_s).transform_values(&:to_s)
 
       tag_params.filter_map do |key, value|
         next if key.blank? || value.blank?

data/app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb

@@ -15,7 +15,7 @@ module LlmCostTracker
     private
 
     def filter_options_for(column, filter_params:)
-      source = LlmCostTracker::ParameterHash.to_hash(filter_params)
+      source = LlmCostTracker::Dashboard::Params.to_hash(filter_params)
       scope_params = source.stringify_keys.merge(
         column.to_s => nil, "format" => nil, "page" => nil, "per" => nil, "sort" => nil
       )

data/app/helpers/llm_cost_tracker/dashboard_query_helper.rb

@@ -11,44 +11,27 @@ module LlmCostTracker
 
     def calls_query_for_tag(key:, value:)
       query = current_query(page: nil, per: nil, format: nil)
-      tags = normalized_query_tags(query[:tag])
+      tags = LlmCostTracker::Dashboard::Params.to_hash(query[:tag]).transform_keys(&:to_s).transform_values(&:to_s)
       query[:tag] = tags.merge(key.to_s => value.to_s)
       query
     end
 
     private
 
-    def normalized_query_tags(tags)
-      LlmCostTracker::ParameterHash.to_hash(tags).transform_keys(&:to_s).transform_values(&:to_s)
-    end
-
     def clean_dashboard_query(value)
-      if LlmCostTracker::ParameterHash.hash_like?(value)
-        return clean_dashboard_hash(LlmCostTracker::ParameterHash.to_hash(value))
-      end
+      if value.is_a?(Hash) || value.try(:to_unsafe_h).is_a?(Hash)
+        return LlmCostTracker::Dashboard::Params.to_hash(value).each_with_object({}) do |(key, nested), cleaned|
+          nested = clean_dashboard_query(nested)
+          next if nested.nil? || nested == {} || nested == []
 
-      return clean_dashboard_array(value) if value.is_a?(Array)
-      return clean_dashboard_string(value) if value.is_a?(String)
-
-      value
-    end
-
-    def clean_dashboard_hash(hash)
-      hash.each_with_object({}) do |(key, nested), cleaned|
-        nested = clean_dashboard_query(nested)
-        next if nested.nil? || nested == {} || nested == []
-
-        cleaned[key] = nested
+          cleaned[key] = nested
+        end
       end
-    end
 
-    def clean_dashboard_array(array)
-      array.filter_map { |item| clean_dashboard_query(item) }.presence
-    end
+      return value.filter_map { |item| clean_dashboard_query(item) }.presence if value.is_a?(Array)
+      return value.strip.presence if value.is_a?(String)
 
-    def clean_dashboard_string(string)
-      stripped = string.strip
-      stripped.empty? ? nil : stripped
+      value
     end
   end
 end

data/app/helpers/llm_cost_tracker/token_usage_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module TokenUsageHelper
+    COMPONENT_LABELS = {
+      input_tokens: "Input",
+      cache_read_input_tokens: "Cache read",
+      cache_write_input_tokens: "Cache write",
+      cache_write_1h_input_tokens: "1h cache write",
+      output_tokens: "Output",
+      hidden_output_tokens: "Hidden output"
+    }.freeze
+    QUALITY_LABELS = COMPONENT_LABELS.merge(
+      input_tokens: "Regular input",
+      cache_read_input_tokens: "Cache read input",
+      cache_write_input_tokens: "Cache write input",
+      cache_write_1h_input_tokens: "1h cache write input"
+    ).freeze
+    STACK_CLASSES = {
+      input_tokens: "lct-stack-fill-input",
+      cache_read_input_tokens: "lct-stack-fill-cache-read",
+      cache_write_input_tokens: "lct-stack-fill-cache-write",
+      cache_write_1h_input_tokens: "lct-stack-fill-cache-write-1h",
+      output_tokens: "lct-stack-fill-output"
+    }.freeze
+
+    def token_usage_stack_components
+      token_usage_display_components(labels: COMPONENT_LABELS).select do |component|
+        component.fetch(:cost_key)
+      end
+    end
+
+    def token_usage_quality_label(token_key)
+      QUALITY_LABELS.fetch(token_key.to_sym)
+    end
+
+    private
+
+    def token_usage_display_components(labels:)
+      LlmCostTracker::Pricing::COMPONENTS.map do |component|
+        token_key = component.token_key
+        {
+          token_key: token_key,
+          cost_key: component.cost_key,
+          label: labels.fetch(token_key),
+          css_class: STACK_CLASSES[token_key]
+        }
+      end + [
+        {
+          token_key: :hidden_output_tokens,
+          cost_key: nil,
+          label: labels.fetch(:hidden_output_tokens),
+          css_class: nil
+        }
+      ]
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module LlmCostTracker
+  module Ingestion
+    class Event < ActiveRecord::Base
+      MAX_ATTEMPTS = 5
+
+      self.table_name = "llm_cost_tracker_inbox_events"
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module LlmCostTracker
+  module Ingestion
+    class Lease < ActiveRecord::Base
+      self.table_name = "llm_cost_tracker_ingestor_leases"
+    end
+  end
+end

data/app/models/llm_cost_tracker/ledger/call.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module LlmCostTracker
+  module Ledger
+    class Call < ActiveRecord::Base
+      extend Period::Grouping
+      extend Ledger::CallMetrics
+      include Ledger::Tags::Accessors
+
+      self.table_name = "llm_api_calls"
+
+      scope :with_cost, -> { where.not(total_cost: nil) }
+      scope :without_cost, -> { where(total_cost: nil) }
+      scope :unknown_pricing, -> { without_cost }
+      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 :with_json_tags, lambda {
+        where.not(tags: {})
+      }
+
+      scope :today,       -> { where(tracked_at: Time.now.utc.beginning_of_day..) }
+      scope :this_week,   -> { where(tracked_at: Time.now.utc.beginning_of_week..) }
+      scope :this_month,  -> { where(tracked_at: Time.now.utc.beginning_of_month..) }
+      scope :between,     ->(from, to) { where(tracked_at: from..to) }
+
+      def self.by_tag(key, value)
+        by_tags(key => value)
+      end
+
+      def self.by_tags(tags)
+        Ledger::Tags::Query.apply(self, tags)
+      end
+    end
+  end
+end

data/app/models/llm_cost_tracker/ledger/call_metrics.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "llm_cost_tracker/ledger/tags/sql"
+
+module LlmCostTracker
+  module Ledger
+    module CallMetrics
+      def total_cost
+        sum(:total_cost).to_f
+      end
+
+      def total_tokens
+        sum(:total_tokens).to_i
+      end
+
+      def cost_by_model(limit: nil)
+        cost_by_column(:model, limit: limit)
+      end
+
+      def cost_by_provider(limit: nil)
+        cost_by_column(:provider, limit: limit)
+      end
+
+      def group_by_tag(key)
+        group(Arel.sql(tag_value_expression(key)))
+      end
+
+      def cost_by_tag(key, limit: nil)
+        expression = tag_value_expression(key)
+        label_expression = "COALESCE(NULLIF(#{expression}, ''), #{connection.quote('(untagged)')})"
+        relation = select("#{label_expression} AS name, COALESCE(SUM(total_cost), 0) AS total_cost")
+                   .group(Arel.sql(label_expression))
+                   .order(Arel.sql("COALESCE(SUM(total_cost), 0) DESC"))
+        relation = relation.limit(limit) if limit
+        relation
+      end
+
+      def average_latency_ms
+        average(:latency_ms)&.to_f
+      end
+
+      def latency_by_model
+        group(:model).average(:latency_ms).transform_values(&:to_f)
+      end
+
+      def latency_by_provider
+        group(:provider).average(:latency_ms).transform_values(&:to_f)
+      end
+
+      def tag_value_expression(key, table_name: quoted_table_name)
+        Ledger::Tags::Sql.value_expression(self, key, table_name: table_name)
+      end
+
+      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")
+                   .group(column)
+                   .order(Arel.sql("COALESCE(SUM(total_cost), 0) DESC"))
+        relation = relation.limit(limit) if limit
+        relation
+      end
+    end
+  end
+end

data/app/models/llm_cost_tracker/ledger/period/grouping.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "llm_cost_tracker/ledger/schema/adapter"
+
+module LlmCostTracker
+  module Ledger
+    module Period
+      module Grouping
+        PERIOD_FORMATS = {
+          day: {
+            postgres: "YYYY-MM-DD",
+            mysql: "%Y-%m-%d"
+          },
+          month: {
+            postgres: "YYYY-MM",
+            mysql: "%Y-%m"
+          }
+        }.freeze
+
+        private_constant :PERIOD_FORMATS
+
+        def group_by_period(period, column: :tracked_at)
+          group(Arel.sql(period_group_expression(period, column: column)))
+        end
+
+        def daily_costs(days: 30)
+          where(tracked_at: days.days.ago..)
+            .group_by_period(:day)
+            .sum(:total_cost)
+        end
+
+        private
+
+        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.to_s)}, #{column}), " \
+            "#{connection.quote(formats.fetch(:postgres))}" \
+            ")"
+        end
+
+        def validated_period(period)
+          normalized_period = period.try(:to_sym)
+          return normalized_period if PERIOD_FORMATS.key?(normalized_period)
+
+          raise ArgumentError, "invalid period: #{period.inspect}"
+        end
+
+        def period_column_expression(column)
+          column = column.to_s
+          return "#{quoted_table_name}.#{connection.quote_column_name(column)}" if column_names.include?(column)
+
+          raise ArgumentError, "invalid period column: #{column.inspect}"
+        end
+      end
+    end
+  end
+end