llm_cost_tracker 0.5.2 → 0.5.3

data/lib/llm_cost_tracker/pricing/effective_prices.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Pricing
+    EffectivePriceSet = Data.define(:input, :cache_read_input, :cache_write_input, :output) do
+      def to_h
+        {
+          input: input,
+          cache_read_input: cache_read_input,
+          cache_write_input: cache_write_input,
+          output: output
+        }
+      end
+
+      def complete?
+        missing_keys.empty?
+      end
+
+      def missing_keys
+        to_h.filter_map { |key, value| key if value.nil? }
+      end
+    end
+
+    module EffectivePrices
+      class << self
+        def call(usage:, prices:, pricing_mode:)
+          EffectivePriceSet.new(
+            input: price_for_usage(usage.input_tokens, prices, :input, pricing_mode),
+            cache_read_input: price_for_cache_usage(
+              usage.cache_read_input_tokens,
+              prices,
+              :cache_read_input,
+              pricing_mode
+            ),
+            cache_write_input: price_for_cache_usage(
+              usage.cache_write_input_tokens,
+              prices,
+              :cache_write_input,
+              pricing_mode
+            ),
+            output: price_for_usage(usage.output_tokens, prices, :output, pricing_mode)
+          )
+        end
+
+        private
+
+        def price_for_cache_usage(tokens, prices, key, pricing_mode)
+          return 0.0 unless tokens.positive?
+
+          price_for(prices, key, pricing_mode) || price_for(prices, :input, pricing_mode)
+        end
+
+        def price_for_usage(tokens, prices, key, pricing_mode)
+          tokens.positive? ? price_for(prices, key, pricing_mode) : 0.0
+        end
+
+        def price_for(prices, key, pricing_mode)
+          mode = normalized_pricing_mode(pricing_mode)
+          return prices[key] unless mode
+
+          prices[:"#{mode}_#{key}"] || prices[key]
+        end
+
+        def normalized_pricing_mode(value)
+          return nil if value.nil?
+
+          mode = value.to_s.strip
+          return nil if mode.empty? || mode == "standard"
+
+          mode
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/explainer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "effective_prices"
+
+module LlmCostTracker
+  module Pricing
+    Explanation = Data.define(
+      :provider,
+      :model,
+      :pricing_mode,
+      :source,
+      :matched_key,
+      :matched_by,
+      :prices,
+      :effective_prices,
+      :missing_price_keys
+    ) do
+      def matched? = !prices.nil?
+
+      def complete? = matched? && missing_price_keys.empty?
+
+      def message
+        return "No price entry matched #{provider}/#{model}" unless matched?
+        return "Matched #{matched_key} from #{source} via #{matched_by}" if complete?
+
+        "Matched #{matched_key} from #{source} via #{matched_by}, but missing #{missing_price_keys.join(', ')}"
+      end
+    end
+
+    module Explainer
+      class << self
+        def call(provider:, model:, input_tokens: 1, output_tokens: 1, cache_read_input_tokens: 0,
+                 cache_write_input_tokens: 0, pricing_mode: nil)
+          match = Lookup.call(provider: provider, model: model)
+          usage = match && UsageBreakdown.build(
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            cache_read_input_tokens: cache_read_input_tokens,
+            cache_write_input_tokens: cache_write_input_tokens
+          )
+
+          explanation(provider, model, pricing_mode, match, usage)
+        end
+
+        private
+
+        def explanation(provider, model, pricing_mode, match, usage)
+          prices = match&.prices
+          effective = if prices && usage
+                        EffectivePrices.call(usage: usage, prices: prices, pricing_mode: pricing_mode)
+                      end
+
+          Explanation.new(
+            provider.to_s,
+            model.to_s,
+            normalized_pricing_mode(pricing_mode),
+            match&.source,
+            match&.key,
+            match&.matched_by,
+            prices,
+            effective ? effective.to_h : {},
+            effective ? effective.missing_keys : []
+          )
+        end
+
+        def normalized_pricing_mode(value)
+          return nil if value.nil?
+
+          mode = value.to_s.strip
+          return nil if mode.empty? || mode == "standard"
+
+          mode
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/lookup.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module LlmCostTracker
+  module Pricing
+    module Lookup
+      Match = Data.define(:source, :key, :prices, :matched_by)
+      MUTEX = Monitor.new
+
+      class << self
+        def call(provider:, model:)
+          provider_name = provider.to_s
+          model_name = model.to_s
+          provider_model = provider_name.empty? ? model_name : "#{provider_name}/#{model_name}"
+          normalized_model = normalize_model_name(model_name)
+          current = current_price_tables
+
+          explain_table(current.fetch(:pricing_overrides), :pricing_overrides, provider_model, model_name,
+                        normalized_model) ||
+            explain_table(current.fetch(:file_prices), :prices_file, provider_model, model_name, normalized_model) ||
+            explain_table(Pricing::PRICES, :bundled, provider_model, model_name, normalized_model)
+        end
+
+        private
+
+        def current_price_tables
+          file_prices = PriceRegistry.file_prices(LlmCostTracker.configuration.prices_file)
+          overrides = PriceRegistry.normalize_price_table(LlmCostTracker.configuration.pricing_overrides)
+          cache_key = [file_prices.object_id, LlmCostTracker.configuration.pricing_overrides.hash]
+
+          cached = @prices_cache
+          return cached[:value] if cached && cached[:key] == cache_key
+
+          MUTEX.synchronize do
+            cached = @prices_cache
+            return cached[:value] if cached && cached[:key] == cache_key
+
+            value = { pricing_overrides: overrides, file_prices: file_prices }.freeze
+            @prices_cache = { key: cache_key, value: value }.freeze
+            value
+          end
+        end
+
+        def explain_table(table, source, provider_model, model_name, normalized_model)
+          return nil if table.empty?
+
+          direct_match(table, source, provider_model, :provider_model) ||
+            direct_match(table, source, model_name, :model) ||
+            direct_match(table, source, normalized_model, :normalized_model) ||
+            unique_providerless_lookup(normalized_model, table, source) ||
+            fuzzy_match(provider_model, normalized_model, table, source) ||
+            unique_providerless_fuzzy_match(normalized_model, table, source)
+        end
+
+        def normalize_model_name(model)
+          model.to_s.split("/").last
+        end
+
+        def unique_providerless_lookup(model, table, source)
+          matches = sorted_price_keys(table).select { |key| normalize_model_name(key) == model }
+          match(table, source, matches.first, :unique_providerless_model) if matches.one?
+        end
+
+        def fuzzy_match(model, normalized_model, table, source)
+          sorted_price_keys(table).each do |key|
+            return match(table, source, key, :dated_snapshot) if snapshot_variant?(model, key) ||
+                                                                 snapshot_variant?(normalized_model, key)
+          end
+
+          nil
+        end
+
+        def unique_providerless_fuzzy_match(model, table, source)
+          matches = sorted_price_keys(table).select { |key| snapshot_variant?(model, normalize_model_name(key)) }
+          match(table, source, matches.first, :unique_providerless_dated_snapshot) if matches.one?
+        end
+
+        def direct_match(table, source, key, matched_by)
+          match(table, source, key, matched_by) if table.key?(key)
+        end
+
+        def match(table, source, key, matched_by)
+          Match.new(source.to_s, key, table[key], matched_by.to_s)
+        end
+
+        def snapshot_variant?(model, key)
+          suffix = model.delete_prefix("#{key}-")
+          return false if suffix == model
+
+          suffix.match?(/\A(?:\d{4}-\d{2}-\d{2}|\d{8})\z/)
+        end
+
+        def sorted_price_keys(table)
+          cached = @sorted_price_keys_cache
+          return cached[:keys] if cached && cached[:table].equal?(table)
+
+          MUTEX.synchronize do
+            cached = @sorted_price_keys_cache
+            return cached[:keys] if cached && cached[:table].equal?(table)
+
+            keys = table.keys.sort_by { |key| -key.length }
+            @sorted_price_keys_cache = { table: table, keys: keys }.freeze
+            keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-require "monitor"
+require_relative "pricing/lookup"
+require_relative "pricing/effective_prices"
+require_relative "pricing/explainer"
 
 module LlmCostTracker
   module Pricing
     PRICES = PriceRegistry.builtin_prices
-    MUTEX = Monitor.new
 
     class << self
       def cost_for(provider:, model:, input_tokens:, output_tokens:, cache_read_input_tokens: 0,
@@ -20,6 +21,7 @@ module LlmCostTracker
           cache_write_input_tokens: cache_write_input_tokens
         )
         costs = calculate_costs(usage, prices, pricing_mode: pricing_mode)
+        return nil unless costs
 
         Cost.new(
           input_cost: costs[:input].round(8),
@@ -32,127 +34,42 @@ module LlmCostTracker
       end
 
       def lookup(provider:, model:)
-        provider_name = provider.to_s
-        model_name = model.to_s
-        provider_model = provider_name.empty? ? model_name : "#{provider_name}/#{model_name}"
-        normalized_model = normalize_model_name(model_name)
-        current = current_price_tables
-
-        lookup_in_table(current.fetch(:pricing_overrides), provider_model, model_name, normalized_model) ||
-          lookup_in_table(current.fetch(:file_prices), provider_model, model_name, normalized_model) ||
-          lookup_in_table(PRICES, provider_model, model_name, normalized_model)
+        Lookup.call(provider: provider, model: model)&.prices
       end
 
-      private
-
-      def current_price_tables
-        file_prices = PriceRegistry.file_prices(LlmCostTracker.configuration.prices_file)
-        overrides = PriceRegistry.normalize_price_table(LlmCostTracker.configuration.pricing_overrides)
-        cache_key = [file_prices.object_id, LlmCostTracker.configuration.pricing_overrides.hash]
-
-        cached = @prices_cache
-        return cached[:value] if cached && cached[:key] == cache_key
-
-        MUTEX.synchronize do
-          cached = @prices_cache
-          return cached[:value] if cached && cached[:key] == cache_key
-
-          value = { pricing_overrides: overrides, file_prices: file_prices }.freeze
-          @prices_cache = { key: cache_key, value: value }.freeze
-          value
-        end
+      def explain(provider:, model:, input_tokens: 1, output_tokens: 1, cache_read_input_tokens: 0,
+                  cache_write_input_tokens: 0, pricing_mode: nil)
+        Explainer.call(
+          provider: provider,
+          model: model,
+          input_tokens: input_tokens,
+          output_tokens: output_tokens,
+          cache_read_input_tokens: cache_read_input_tokens,
+          cache_write_input_tokens: cache_write_input_tokens,
+          pricing_mode: pricing_mode
+        )
       end
 
-      def lookup_in_table(table, provider_model, model_name, normalized_model)
-        return nil if table.empty?
-
-        table[provider_model] ||
-          table[model_name] ||
-          table[normalized_model] ||
-          unique_providerless_lookup(normalized_model, table) ||
-          fuzzy_match(provider_model, normalized_model, table) ||
-          unique_providerless_fuzzy_match(normalized_model, table)
-      end
+      private
 
       def calculate_costs(usage, prices, pricing_mode:)
+        effective = EffectivePrices.call(usage: usage, prices: prices, pricing_mode: pricing_mode)
+        return nil unless effective.complete?
+
         {
-          input: token_cost(usage.input_tokens, price_for(prices, :input, pricing_mode)),
-          cache_read_input: token_cost(
-            usage.cache_read_input_tokens,
-            price_for(prices, :cache_read_input, pricing_mode) || price_for(prices, :input, pricing_mode)
-          ),
-          cache_write_input: token_cost(
-            usage.cache_write_input_tokens,
-            price_for(prices, :cache_write_input, pricing_mode) || price_for(prices, :input, pricing_mode)
-          ),
-          output: token_cost(usage.output_tokens, price_for(prices, :output, pricing_mode))
+          input: token_cost(usage.input_tokens, effective.input),
+          cache_read_input: token_cost(usage.cache_read_input_tokens, effective.cache_read_input),
+          cache_write_input: token_cost(usage.cache_write_input_tokens, effective.cache_write_input),
+          output: token_cost(usage.output_tokens, effective.output)
         }
       end
 
-      def price_for(prices, key, pricing_mode)
-        mode = normalized_pricing_mode(pricing_mode)
-        return prices[key] unless mode
-
-        prices[:"#{mode}_#{key}"] || prices[key]
-      end
-
-      def normalized_pricing_mode(value)
-        return nil if value.nil?
-
-        mode = value.to_s.strip
-        return nil if mode.empty? || mode == "standard"
-
-        mode
-      end
-
       def token_cost(tokens, per_million_price)
         return 0.0 if tokens.to_i.zero?
+        return nil if per_million_price.nil?
 
         (tokens.to_f / 1_000_000) * per_million_price
       end
-
-      def normalize_model_name(model)
-        model.to_s.split("/").last
-      end
-
-      def unique_providerless_lookup(model, table)
-        matches = sorted_price_keys(table).select { |key| normalize_model_name(key) == model }
-        table[matches.first] if matches.one?
-      end
-
-      def fuzzy_match(model, normalized_model, table)
-        sorted_price_keys(table).each do |key|
-          return table[key] if snapshot_variant?(model, key) || snapshot_variant?(normalized_model, key)
-        end
-
-        nil
-      end
-
-      def unique_providerless_fuzzy_match(model, table)
-        matches = sorted_price_keys(table).select { |key| snapshot_variant?(model, normalize_model_name(key)) }
-        table[matches.first] if matches.one?
-      end
-
-      def snapshot_variant?(model, key)
-        suffix = model.delete_prefix("#{key}-")
-        return false if suffix == model
-
-        suffix.match?(/\A(?:\d{4}-\d{2}-\d{2}|\d{8})\z/)
-      end
-
-      def sorted_price_keys(table)
-        cached = @sorted_price_keys_cache
-        return cached[:keys] if cached && cached[:table].equal?(table)
-
-        MUTEX.synchronize do
-          cached = @sorted_price_keys_cache
-          return cached[:keys] if cached && cached[:table].equal?(table)
-
-          keys = table.keys.sort_by { |key| -key.length }
-          @sorted_price_keys_cache = { table: table, keys: keys }.freeze
-          keys
-        end
-      end
     end
   end
 end

data/lib/llm_cost_tracker/retention.rb

@@ -8,15 +8,9 @@ module LlmCostTracker
       def prune(older_than:, batch_size: DEFAULT_BATCH_SIZE, now: Time.now.utc)
         batch_size = normalized_batch_size(batch_size)
         cutoff = resolve_cutoff(older_than, now)
-        require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
-
-        deleted = 0
-        loop do
-          batch = LlmCostTracker::LlmApiCall.where(tracked_at: ...cutoff).limit(batch_size).delete_all
-          deleted += batch
-          break if batch < batch_size
-        end
-        deleted
+        require_relative "storage/active_record_backend"
+
+        Storage::ActiveRecordBackend.prune(cutoff: cutoff, batch_size: batch_size)
       end
 
       private

data/lib/llm_cost_tracker/storage/active_record_backend.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "registry"
+require_relative "active_record_store"
+
+module LlmCostTracker
+  module Storage
+    class ActiveRecordBackend
+      VERIFY_TAG = "llm_cost_tracker_verify"
+
+      class << self
+        def save(event)
+          require_relative "../llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+
+          ActiveRecordStore.save(event)
+          event
+        rescue LoadError => e
+          raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
+        end
+
+        def verify
+          require_relative "../llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+
+          unless LlmCostTracker::LlmApiCall.table_exists?
+            return [
+              VerificationResult.new(
+                :error,
+                "active_record",
+                "llm_api_calls table is missing; run install generator and migrate"
+              )
+            ]
+          end
+
+          [active_record_capture_check]
+        rescue LoadError => e
+          [VerificationResult.new(:error, "active_record", "unavailable: #{e.message}")]
+        rescue StandardError => e
+          [VerificationResult.new(:error, "active_record", "#{e.class}: #{e.message}")]
+        end
+
+        def prune(cutoff:, batch_size:)
+          require_relative "../llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+
+          ActiveRecordStore.prune(cutoff: cutoff, batch_size: batch_size)
+        end
+
+        private
+
+        def active_record_capture_check
+          provider, model = sample_priced_identity
+          response_id = "lct_verify_#{SecureRandom.hex(8)}"
+          notifications = []
+          persisted = false
+          subscription = subscribe_to_verification(response_id, notifications)
+
+          LlmCostTracker::LlmApiCall.transaction do
+            LlmCostTracker.track(
+              provider: provider,
+              model: model,
+              input_tokens: 1,
+              output_tokens: 1,
+              provider_response_id: response_id,
+              feature: VERIFY_TAG
+            )
+            persisted = LlmCostTracker::LlmApiCall.where(provider_response_id: response_id).exists?
+            raise ActiveRecord::Rollback
+          end
+
+          return active_record_capture_success if persisted && notifications.any?
+
+          VerificationResult.new(:error, "active_record capture", capture_failure_message(persisted, notifications))
+        rescue LlmCostTracker::BudgetExceededError => e
+          VerificationResult.new(:error, "active_record capture", "blocked by budget guardrail: #{e.message}")
+        rescue LlmCostTracker::Error => e
+          VerificationResult.new(:error, "active_record capture", e.message)
+        rescue StandardError => e
+          VerificationResult.new(:error, "active_record capture", "#{e.class}: #{e.message}")
+        ensure
+          ActiveSupport::Notifications.unsubscribe(subscription) if subscription
+        end
+
+        def subscribe_to_verification(response_id, notifications)
+          ActiveSupport::Notifications.subscribe(LlmCostTracker::Tracker::EVENT_NAME) do |*, payload|
+            notifications << payload if payload[:provider_response_id] == response_id
+          end
+        end
+
+        def active_record_capture_success
+          VerificationResult.new(
+            :ok,
+            "active_record capture",
+            "manual event emitted and persisted inside rollback"
+          )
+        end
+
+        def capture_failure_message(persisted, notifications)
+          missing = []
+          missing << "notification" if notifications.empty?
+          missing << "persisted row" unless persisted
+          "missing #{missing.join(' and ')} for synthetic manual event"
+        end
+
+        def sample_priced_identity
+          key = LlmCostTracker::PriceRegistry.builtin_prices.find do |model_id, prices|
+            model_id.include?("/") && prices[:input] && prices[:output]
+          end&.first
+          provider, model = key.to_s.split("/", 2)
+          [provider || "openai", model || "gpt-4o-mini"]
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/storage/active_record_rollups.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "bigdecimal"
+
 module LlmCostTracker
   module Storage
     class ActiveRecordRollups
@@ -26,6 +28,15 @@ module LlmCostTracker
           )
         end
 
+        def decrement!(call_rows)
+          return unless period_totals_enabled?
+
+          totals = period_decrement_totals(call_rows)
+          return if totals.empty?
+
+          apply_decrements(totals)
+        end
+
         def monthly_total(time: Time.now.utc)
           period_totals(%i[monthly], time: time).fetch(:monthly)
         end
@@ -57,6 +68,37 @@ module LlmCostTracker
           end
         end
 
+        def period_decrement_totals(call_rows)
+          call_rows.each_with_object(Hash.new { |totals, key| totals[key] = BigDecimal("0") }) do |row, totals|
+            _id, tracked_at, total_cost = row
+            next unless total_cost
+
+            PERIODS.each_key do |period|
+              totals[[period, bucket_for(period, tracked_at)]] += decimal(total_cost)
+            end
+          end
+        end
+
+        def apply_decrements(totals)
+          model = period_total_model
+          now = Time.now.utc
+
+          totals.each do |(period, period_start), amount|
+            row = model.lock.find_by(period: PERIODS.fetch(period), period_start: period_start)
+            next unless row
+
+            row.update_columns(total_cost: decremented_total(row.total_cost, amount), updated_at: now)
+          end
+        end
+
+        def decremented_total(current, amount)
+          [decimal(current) - amount, BigDecimal("0")].max
+        end
+
+        def decimal(value)
+          BigDecimal(value.to_s)
+        end
+
         def rollup_period_totals(periods, time)
           buckets = periods.to_h { |period| [period, bucket_for(period, time)] }
           index = buckets.to_h { |period, bucket| [[PERIODS.fetch(period), bucket], period] }

data/lib/llm_cost_tracker/storage/active_record_store.rb

@@ -54,8 +54,34 @@ module LlmCostTracker
           ActiveRecordRollups.period_totals(periods, time: time)
         end
 
+        def prune(cutoff:, batch_size:)
+          deleted = 0
+          loop do
+            batch = prune_batch(cutoff, batch_size)
+            deleted += batch
+            break if batch < batch_size
+          end
+          deleted
+        end
+
         private
 
+        def prune_batch(cutoff, batch_size)
+          LlmCostTracker::LlmApiCall.transaction do
+            rows = LlmCostTracker::LlmApiCall
+                   .where(tracked_at: ...cutoff)
+                   .order(:id)
+                   .limit(batch_size)
+                   .lock
+                   .pluck(:id, :tracked_at, :total_cost)
+            next 0 if rows.empty?
+
+            deleted = LlmCostTracker::LlmApiCall.where(id: rows.map(&:first)).delete_all
+            ActiveRecordRollups.decrement!(rows) if deleted.positive?
+            deleted
+          end
+        end
+
         def stringify_tags(tags)
           tags.transform_keys(&:to_s).transform_values { |value| stringify_tag_value(value) }
         end