llm_cost_tracker 0.7.0 → 0.7.2

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

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

@@ -1,124 +1,141 @@
 # frozen_string_literal: true
 
+require "llm_cost_tracker/pricing"
+require "llm_cost_tracker/ledger/schema/adapter"
+
 module LlmCostTracker
   module Dashboard
-    DataQualityStats = Data.define(
-      :total_calls,
-      :unknown_pricing_count,
-      :untagged_calls_count,
-      :missing_latency_count,
-      :latency_column_present,
-      :streaming_count,
-      :streaming_missing_usage_count,
-      :stream_column_present,
-      :missing_provider_response_id_count,
-      :provider_response_id_column_present,
-      :usage_breakdown_column_present,
-      :input_tokens,
-      :cache_read_input_tokens,
-      :cache_write_input_tokens,
-      :output_tokens,
-      :hidden_output_tokens,
-      :input_cost,
-      :cache_read_input_cost,
-      :cache_write_input_cost,
-      :output_cost,
-      :unknown_pricing_by_model
-    )
-
     class DataQuality
       class << self
-        def call(scope: LlmCostTracker::LlmApiCall.all)
+        def call(scope: LlmCostTracker::Ledger::Call.all)
           model = scope.klass
-          aggregates = DataQualityAggregate.call(scope: scope)
-          total = aggregates.fetch(:total_calls).to_i
-
-          DataQualityStats.new(
-            total_calls: total,
-            unknown_pricing_count: aggregates.fetch(:unknown_pricing_count).to_i,
-            untagged_calls_count: total - aggregates.fetch(:tagged_calls_count).to_i,
-            **latency_stats(aggregates, model:),
-            **stream_stats(aggregates, model:),
-            **provider_response_id_stats(aggregates, model:),
-            **usage_stats(aggregates, model:),
-            unknown_pricing_by_model: unknown_pricing_by_model(scope)
-          )
+          scope.unscope(:order).select(aggregate_selects(scope, model:)).take
         end
 
-        private
+        def unknown_pricing_by_model(scope)
+          scope.unknown_pricing
+               .group(:model)
+               .order(Arel.sql("COUNT(*) DESC"))
+               .select("model, COUNT(*) AS calls")
+               .limit(10)
+        end
 
-        def latency_stats(aggregates, model:)
-          latency_present = model.latency_column?
+        def usage_rows(stats)
+          billable_tokens = stats.billable_tokens.to_f
 
-          {
-            missing_latency_count: latency_present ? aggregates.fetch(:missing_latency_count).to_i : nil,
-            latency_column_present: latency_present
-          }
-        end
+          rows = Pricing::COMPONENTS.map do |component|
+            token_key = component.token_key
+            cost_key = component.cost_key
+            token_value = stats[token_key].to_i
+            share_percent = if billable_tokens.positive?
+                              (token_value.to_f / billable_tokens) * 100.0
+                            else
+                              0.0
+                            end
 
-        def stream_stats(aggregates, model:)
-          stream_present = model.stream_column?
-          usage_source_present = model.usage_source_column?
-          streaming_missing_usage_count = nil
-          if stream_present && usage_source_present
-            streaming_missing_usage_count = aggregates.fetch(:streaming_missing_usage_count).to_i
+            {
+              price_key: component.price_key,
+              token_key: token_key,
+              cost_key: cost_key,
+              token_value: token_value,
+              cost_value: stats[cost_key],
+              share_percent: share_percent,
+              share_basis: nil
+            }
           end
 
-          {
-            streaming_count: stream_present ? aggregates.fetch(:streaming_count).to_i : nil,
-            streaming_missing_usage_count: streaming_missing_usage_count,
-            stream_column_present: stream_present
-          }
+          rows + [
+            {
+              price_key: nil,
+              token_key: :hidden_output_tokens,
+              cost_key: nil,
+              token_value: stats.hidden_output_tokens.to_i,
+              cost_value: nil,
+              share_percent: stats.hidden_output_share.to_f,
+              share_basis: :output
+            }
+          ]
         end
 
-        def provider_response_id_stats(aggregates, model:)
-          column_present = model.provider_response_id_column?
-          missing_provider_response_id_count = nil
-          if column_present
-            missing_provider_response_id_count = aggregates.fetch(:missing_provider_response_id_count).to_i
-          end
+        def hidden_output_summary(stats)
+          output_tokens = stats.output_tokens.to_i
+          return unless output_tokens.positive?
 
           {
-            missing_provider_response_id_count: missing_provider_response_id_count,
-            provider_response_id_column_present: column_present
+            hidden_output_tokens: stats.hidden_output_tokens.to_i,
+            output_tokens: output_tokens,
+            share_percent: stats.hidden_output_share.to_f
           }
         end
 
-        def usage_stats(aggregates, model:)
-          usage_breakdown_present = model.usage_breakdown_columns?
-          usage_breakdown_cost_present = model.usage_breakdown_cost_columns?
-          cache_read_input_cost = nil
-          cache_write_input_cost = nil
-          if usage_breakdown_cost_present
-            cache_read_input_cost = decimal_sum(aggregates.fetch(:cache_read_input_cost))
-            cache_write_input_cost = decimal_sum(aggregates.fetch(:cache_write_input_cost))
+        private
+
+        def aggregate_selects(scope, model:)
+          selects = [
+            "COUNT(*) AS total_calls",
+            "#{conditional_count_sql('total_cost IS NULL')} AS unknown_pricing_count",
+            "#{tagged_calls_sql(model)} AS tagged_calls_count",
+            "COUNT(*) - #{tagged_calls_sql(model)} AS untagged_calls_count",
+            "#{conditional_count_sql('latency_ms IS NULL')} AS missing_latency_count",
+            "#{conditional_count_sql('stream')} AS streaming_count",
+            "#{streaming_missing_usage_select} AS streaming_missing_usage_count",
+            "#{provider_response_id_select} AS missing_provider_response_id_count"
+          ]
+
+          usage_sum_columns.each do |column|
+            selects << "#{column_sum(scope, column)} AS #{column}"
           end
 
-          {
-            usage_breakdown_column_present: usage_breakdown_present,
-            input_tokens: aggregates.fetch(:input_tokens).to_i,
-            cache_read_input_tokens: usage_breakdown_present ? aggregates.fetch(:cache_read_input_tokens).to_i : nil,
-            cache_write_input_tokens: usage_breakdown_present ? aggregates.fetch(:cache_write_input_tokens).to_i : nil,
-            output_tokens: aggregates.fetch(:output_tokens).to_i,
-            hidden_output_tokens: usage_breakdown_present ? aggregates.fetch(:hidden_output_tokens).to_i : nil,
-            input_cost: decimal_sum(aggregates.fetch(:input_cost)),
-            cache_read_input_cost: cache_read_input_cost,
-            cache_write_input_cost: cache_write_input_cost,
-            output_cost: decimal_sum(aggregates.fetch(:output_cost))
-          }
+          selects << "#{billable_tokens_select(scope)} AS billable_tokens"
+          selects << "#{hidden_output_share_select(scope)} AS hidden_output_share"
+
+          selects.join(", ")
         end
 
-        def unknown_pricing_by_model(scope)
-          scope.unknown_pricing
-               .group(:model)
-               .order(Arel.sql("COUNT(*) DESC"))
-               .count
-               .first(10)
-               .to_h
+        def usage_sum_columns
+          Pricing::COMPONENTS.map(&:token_key) + [:hidden_output_tokens] + Pricing::COMPONENTS.map(&:cost_key)
+        end
+
+        def billable_tokens_select(scope)
+          Pricing::COMPONENTS
+            .map { |component| column_sum(scope, component.token_key) }
+            .join(" + ")
         end
 
-        def decimal_sum(value)
-          value.to_f.round(8)
+        def hidden_output_share_select(scope)
+          hidden_output = column_sum(scope, :hidden_output_tokens)
+          output = column_sum(scope, :output_tokens)
+
+          "CASE WHEN #{output} > 0 THEN #{hidden_output} * 100.0 / #{output} ELSE 0 END"
+        end
+
+        def column_sum(scope, column)
+          "COALESCE(SUM(#{scope.connection.quote_column_name(column)}), 0)"
+        end
+
+        def conditional_count_sql(predicate)
+          "COALESCE(SUM(CASE WHEN #{predicate} THEN 1 ELSE 0 END), 0)"
+        end
+
+        def streaming_missing_usage_select
+          predicate = "stream AND (usage_source = 'unknown' OR usage_source IS NULL)"
+          conditional_count_sql(predicate)
+        end
+
+        def provider_response_id_select
+          predicate = "provider_response_id IS NULL OR provider_response_id = ''"
+          conditional_count_sql(predicate)
+        end
+
+        def tagged_calls_sql(model)
+          table = model.quoted_table_name
+          column = "#{table}.#{model.connection.quote_column_name('tags')}"
+
+          if Ledger::Schema::Adapter.postgresql?(model.connection)
+            "COALESCE(SUM(CASE WHEN #{column} <> '{}'::jsonb THEN 1 ELSE 0 END), 0)"
+          else
+            "COALESCE(SUM(CASE WHEN JSON_LENGTH(#{column}) > 0 THEN 1 ELSE 0 END), 0)"
+          end
         end
       end
     end

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

@@ -13,8 +13,8 @@ module LlmCostTracker
       end
 
       def self.parse(params, key)
-        value = LlmCostTracker::ParameterHash.with_indifferent_access(params)[key].to_s.strip
-        return nil if value.empty?
+        value = LlmCostTracker::Dashboard::Params.with_indifferent_access(params)[key].to_s.strip.presence
+        return nil unless value
 
         Date.iso8601(value)
       rescue ArgumentError

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

@@ -6,14 +6,14 @@ module LlmCostTracker
   module Dashboard
     class Filter
       class << self
-        def call(scope: LlmCostTracker::LlmApiCall.all, params: {})
+        def call(scope: LlmCostTracker::Ledger::Call.all, params: {})
           new(scope: scope, params: params).relation
         end
       end
 
       def initialize(scope:, params:)
         @scope = scope
-        @params = LlmCostTracker::ParameterHash.with_indifferent_access(params)
+        @params = LlmCostTracker::Dashboard::Params.with_indifferent_access(params)
       end
 
       def relation
@@ -31,8 +31,8 @@ module LlmCostTracker
       attr_reader :scope, :params
 
       def apply_date_filters(relation)
-        from_date = parse_date(:from)
-        to_date = parse_date(:to)
+        from_date = Dashboard::DateRange.parse(params, :from)
+        to_date = Dashboard::DateRange.parse(params, :to)
         Dashboard::DateRange.validate!(from: from_date, to: to_date)
 
         from = from_date&.beginning_of_day
@@ -59,7 +59,6 @@ module LlmCostTracker
       def apply_stream_filter(relation)
         value = normalized_string(params[:stream])
         return relation if value.nil?
-        return relation unless relation.klass.stream_column?
 
         case value.downcase
         when "yes", "true", "1" then relation.where(stream: true)
@@ -71,35 +70,25 @@ module LlmCostTracker
       def apply_usage_source_filter(relation)
         value = normalized_string(params[:usage_source])
         return relation if value.nil?
-        return relation unless relation.klass.usage_source_column?
 
         relation.where(usage_source: value)
       end
 
       def tag_params
-        tags = hash_param(:tag)
+        tags = LlmCostTracker::Dashboard::Params.to_hash(params[:tag])
 
         tags.each_with_object({}) do |(key, value), normalized|
           value = normalized_string(value)
           next if value.nil?
 
-          normalized[LlmCostTracker::TagKey.validate!(key, error_class: LlmCostTracker::InvalidFilterError)] = value
+          normalized[LlmCostTracker::Tags::Key.validate!(key, error_class: LlmCostTracker::InvalidFilterError)] = value
         end
       end
 
-      def hash_param(key)
-        LlmCostTracker::ParameterHash.to_hash(params[key])
-      end
-
-      def parse_date(key)
-        Dashboard::DateRange.parse(params, key)
-      end
-
       def normalized_string(value)
         return nil if value.nil?
 
-        value = value.to_s.strip
-        value.empty? ? nil : value
+        value.to_s.strip.presence
       end
     end
   end

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

@@ -1,85 +1,23 @@
 # frozen_string_literal: true
 
-require "llm_cost_tracker/storage/active_record_store"
+require "llm_cost_tracker/ledger"
 
 module LlmCostTracker
   module Dashboard
-    OverviewStatsData = Data.define(
-      :total_cost,
-      :total_calls,
-      :average_cost_per_call,
-      :average_latency_ms,
-      :unknown_pricing_count,
-      :previous_total_cost,
-      :previous_total_calls,
-      :cost_delta_percent,
-      :calls_delta_percent,
-      :monthly_budget_status
-    )
-
     class OverviewStats
       class << self
-        def call(scope: LlmCostTracker::LlmApiCall.all, previous_scope: nil)
-          current = aggregate(scope)
-          total_calls = current.calls_count.to_i
-          total_cost = current.total_cost_sum.to_f
-
-          previous = previous_scope && aggregate(previous_scope)
-          prev_cost = previous&.total_cost_sum.to_f
-          prev_calls = previous&.calls_count.to_i
-
-          OverviewStatsData.new(
-            total_cost: total_cost,
-            total_calls: total_calls,
-            average_cost_per_call: total_calls.positive? ? total_cost / total_calls : 0.0,
-            average_latency_ms: latency_value(current, scope),
-            unknown_pricing_count: current.unknown_pricing_count.to_i,
-            previous_total_cost: previous ? prev_cost : nil,
-            previous_total_calls: previous ? prev_calls : nil,
-            cost_delta_percent: previous ? delta_percent(total_cost, prev_cost) : nil,
-            calls_delta_percent: previous ? delta_percent(total_calls, prev_calls) : nil,
-            monthly_budget_status: budget_status
-          )
-        end
-
-        private
-
-        def aggregate(scope)
-          scope.select(aggregate_selects(scope)).take
-        end
-
-        def aggregate_selects(scope)
-          selects = [
-            "COUNT(*) AS calls_count",
-            "COALESCE(SUM(total_cost), 0) AS total_cost_sum",
-            "SUM(CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END) AS unknown_pricing_count"
-          ]
-          selects << "AVG(latency_ms) AS average_latency" if scope.klass.latency_column?
-          selects.join(", ")
+        def call(scope: LlmCostTracker::Ledger::Call.all, previous_scope: nil)
+          scope.select(aggregate_selects(previous_scope: previous_scope)).take
         end
 
-        def latency_value(row, scope)
-          return nil unless scope.klass.latency_column?
-
-          row.average_latency&.to_f
-        end
-
-        def delta_percent(current, previous)
-          current = current.to_f
-          previous = previous.to_f
-          return nil if previous.zero?
-
-          ((current - previous) / previous) * 100.0
-        end
-
-        def budget_status
+        def monthly_budget_status
           budget = LlmCostTracker.configuration.monthly_budget
           return nil unless budget
 
           now = Time.now.utc
           month_start = now.beginning_of_month
           month_end = now.end_of_month
-          spent = LlmCostTracker::Storage::ActiveRecordStore.monthly_total(time: now)
+          spent = LlmCostTracker::Ledger::Period::Totals.call(%i[monthly], time: now).fetch(:monthly)
           elapsed_seconds = now - month_start
           total_seconds = month_end - month_start
           projected_spent = if spent.zero? || !elapsed_seconds.positive?
@@ -98,6 +36,59 @@ module LlmCostTracker
             projection_end_label: month_end.strftime("%b %-d")
           }
         end
+
+        private
+
+        def aggregate_selects(previous_scope:)
+          average_cost_sql = <<~SQL.squish
+            CASE WHEN COUNT(*) > 0
+            THEN COALESCE(SUM(total_cost), 0) * 1.0 / COUNT(*)
+            ELSE 0 END
+          SQL
+          selects = [
+            "COUNT(*) AS total_calls",
+            "COALESCE(SUM(total_cost), 0) AS total_cost",
+            "#{average_cost_sql} AS average_cost_per_call",
+            "SUM(CASE WHEN total_cost IS NULL THEN 1 ELSE 0 END) AS unknown_pricing_count",
+            "AVG(latency_ms) AS average_latency_ms"
+          ]
+          selects.concat(previous_selects(previous_scope))
+          selects.join(", ")
+        end
+
+        def previous_selects(previous_scope)
+          unless previous_scope
+            return [
+              "NULL AS previous_total_cost",
+              "NULL AS previous_total_calls",
+              "NULL AS cost_delta_percent",
+              "NULL AS calls_delta_percent"
+            ]
+          end
+
+          previous_cost_sql = aggregate_subquery(previous_scope, "COALESCE(SUM(total_cost), 0)")
+          previous_calls_sql = aggregate_subquery(previous_scope, "COUNT(*)")
+          cost_delta_sql = <<~SQL.squish
+            CASE WHEN (#{previous_cost_sql}) = 0 THEN NULL
+            ELSE ((COALESCE(SUM(total_cost), 0) - (#{previous_cost_sql})) * 100.0 / (#{previous_cost_sql}))
+            END
+          SQL
+          calls_delta_sql = <<~SQL.squish
+            CASE WHEN (#{previous_calls_sql}) = 0 THEN NULL
+            ELSE ((COUNT(*) - (#{previous_calls_sql})) * 100.0 / (#{previous_calls_sql}))
+            END
+          SQL
+          [
+            "(#{previous_cost_sql}) AS previous_total_cost",
+            "(#{previous_calls_sql}) AS previous_total_calls",
+            "#{cost_delta_sql} AS cost_delta_percent",
+            "#{calls_delta_sql} AS calls_delta_percent"
+          ]
+        end
+
+        def aggregate_subquery(scope, expression)
+          scope.unscope(:select, :order).select(expression).to_sql
+        end
       end
     end
   end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Dashboard
+    class Pagination
+      DEFAULT_PER = 50
+      MAX_PER = 200
+      MIN_PAGE = 1
+
+      attr_reader :page, :per
+
+      def self.call(params)
+        params = Params.with_indifferent_access(params)
+        new(
+          page: integer_param(params, :page, default: MIN_PAGE, min: MIN_PAGE),
+          per: integer_param(params, :per, default: DEFAULT_PER, min: 1, max: MAX_PER)
+        )
+      end
+
+      def self.integer_param(params, key, default:, min:, max: nil)
+        value = Integer(params[key], 10)
+        value = [value, min].max
+        value = [value, max].min if max
+        value
+      rescue ArgumentError, TypeError
+        default
+      end
+      private_class_method :integer_param
+
+      def initialize(page:, per:)
+        @page = page
+        @per = per
+        freeze
+      end
+
+      def limit
+        per
+      end
+
+      def offset
+        (page - 1) * per
+      end
+
+      def prev_page?
+        page > MIN_PAGE
+      end
+
+      def next_page?(total_count)
+        offset + per < total_count.to_i
+      end
+
+      def total_pages(total_count)
+        return MIN_PAGE if total_count.to_i <= 0
+
+        [(total_count.to_f / per).ceil, MIN_PAGE].max
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Dashboard
+    module Params
+      class << self
+        def to_hash(value)
+          return {} if value.nil?
+
+          unsafe_hash = value.try(:to_unsafe_h)
+          return unsafe_hash if unsafe_hash.is_a?(Hash)
+          return value if value.is_a?(Hash)
+
+          hash = value.try(:to_h)
+          hash.is_a?(Hash) ? hash : {}
+        rescue ArgumentError, TypeError
+          {}
+        end
+
+        def with_indifferent_access(value)
+          to_hash(value).with_indifferent_access
+        end
+      end
+    end
+  end
+end