llm_cost_tracker 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de844d3302fda39c5a8b32736d8abff488a5cd6cfd00932f492a1ec701f308d
-  data.tar.gz: a8f942605f9cfbcc77f7e998e3e504150fa820e44829156e901cb06bdcc6d0cf
+  metadata.gz: fbf918d9a4886e24ba99f93dc1125e016e50b45208437dd3254adda76f58033a
+  data.tar.gz: 8a22ccfa517549f55d2a302287660a8a5d7faf03568e80c253e6024ad4988743
 SHA512:
-  metadata.gz: 4c7d9869224101f85298dab0b4395b0c2b96634f46f24e76487412f0f8418e4270fb15124f6f238499c3205f4ad2ebae6e8bcba1b265f7496e3509b7da7c5ea9
-  data.tar.gz: f07e91cf62de94d7e7c76eff7ec4b798208724df5722374d6a72884445a70a64ef83421b90aa8be51b887e277f3e8bcb7eec3ad14987eec25609483bc11f0667
+  metadata.gz: 4ef6bc278f6f98ce37a91e515e8b4a004aaff5f573fc8580e312e53b903d1e7700b2cd58b9bea72fc0ec904010cba43fb0209e7993c31bb69205b42564554884
+  data.tar.gz: 4c9a193d16bb5e8bfa58aaefb6fb9b7d98a632a8e19203927c3fd29b957da6088af71caf5c14f5f2b7452660f78001d7898745f8d7611a4fd6e94311b723bc71

data/CHANGELOG.md

@@ -4,6 +4,22 @@ 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

data/README.md

@@ -90,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.
 
@@ -134,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
@@ -172,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
 
@@ -195,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:
@@ -232,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.
 
@@ -266,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

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module LlmCostTracker
+  module Ledger
+    module Period
+      class Total < ActiveRecord::Base
+        self.table_name = "llm_cost_tracker_period_totals"
+      end
+    end
+  end
+end

data/app/models/llm_cost_tracker/ledger/tags/accessors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LlmCostTracker
+  module Ledger
+    module Tags
+      module Accessors
+        def parsed_tags
+          return tags.transform_keys(&:to_s) if tags.is_a?(Hash)
+
+          JSON.parse(tags || "{}")
+        rescue JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end