llm_cost_tracker 0.5.2 → 0.6.0

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,143 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module LlmCostTracker
+  module Pricing
+    module Lookup
+      Match = Data.define(:source, :key, :prices, :matched_by)
+      MUTEX = Monitor.new
+      CACHE_MISS = Object.new.freeze
+      NO_MATCH = Object.new.freeze
+      MAX_LOOKUP_CACHE_ENTRIES = 512
+
+      class << self
+        def call(provider:, model:)
+          provider_name = provider.to_s
+          model_name = model.to_s
+          generation = LlmCostTracker.configuration_generation
+          cache_key = [generation, provider_name, model_name]
+          cached = cached_lookup(cache_key)
+          return cached unless cached.equal?(CACHE_MISS)
+
+          provider_model = provider_name.empty? ? model_name : "#{provider_name}/#{model_name}"
+          normalized_model = normalize_model_name(model_name)
+          current = current_price_tables(generation)
+
+          match =
+            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)
+          cache_lookup(cache_key, match)
+          match
+        end
+
+        private
+
+        def current_price_tables(generation)
+          cached = @prices_cache
+          return cached[:value] if cached && cached[:generation] == generation
+
+          MUTEX.synchronize do
+            cached = @prices_cache
+            return cached[:value] if cached && cached[:generation] == generation
+
+            config = LlmCostTracker.configuration
+            file_prices = PriceRegistry.file_prices(config.prices_file)
+            overrides = PriceRegistry.normalize_price_table(config.pricing_overrides)
+            value = { pricing_overrides: overrides, file_prices: file_prices }.freeze
+            @prices_cache = { generation: generation, value: value }.freeze
+            value
+          end
+        end
+
+        def cached_lookup(cache_key)
+          cached = @lookup_cache
+          return CACHE_MISS unless cached && cached[:generation] == cache_key.first
+          return CACHE_MISS unless cached[:values].key?(cache_key)
+
+          match = cached[:values].fetch(cache_key)
+          match.equal?(NO_MATCH) ? nil : match
+        end
+
+        def cache_lookup(cache_key, match)
+          MUTEX.synchronize do
+            cached = @lookup_cache
+            values = if cached && cached[:generation] == cache_key.first
+                       cached[:values].dup
+                     else
+                       {}
+                     end
+            values.clear if values.size >= MAX_LOOKUP_CACHE_ENTRIES
+            values[cache_key] = match || NO_MATCH
+            @lookup_cache = { generation: cache_key.first, values: values.freeze }.freeze
+          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/railtie.rb

@@ -3,6 +3,7 @@
 module LlmCostTracker
   class Railtie < Rails::Railtie
     generators do
+      require_relative "generators/llm_cost_tracker/add_ingestion_generator"
       require_relative "generators/llm_cost_tracker/add_period_totals_generator"
       require_relative "generators/llm_cost_tracker/add_latency_ms_generator"
       require_relative "generators/llm_cost_tracker/add_provider_response_id_generator"

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,166 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "registry"
+require_relative "active_record_inbox"
+require_relative "active_record_ingestor"
+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)
+
+          if ActiveRecordInbox.enabled?
+            ActiveRecordInbox.save(event)
+          else
+            ActiveRecordStore.save(event)
+          end
+          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
+          return active_record_inbox_capture_check if ActiveRecordInbox.enabled?
+
+          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 active_record_inbox_capture_check
+          provider, model = sample_priced_identity
+          response_id = "lct_verify_#{SecureRandom.hex(8)}"
+          notifications = []
+          subscription = subscribe_to_verification(response_id, notifications)
+
+          event = LlmCostTracker.track(
+            provider: provider,
+            model: model,
+            input_tokens: 1,
+            output_tokens: 1,
+            provider_response_id: response_id,
+            feature: VERIFY_TAG
+          )
+          LlmCostTracker.flush!
+          persisted = LlmCostTracker::LlmApiCall.where(provider_response_id: response_id).exists?
+
+          if persisted && notifications.any?
+            return active_record_capture_success("manual event emitted and persisted through durable inbox")
+          end
+
+          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
+          cleanup_verification_call(response_id) if response_id
+          LlmCostTracker::InboxEvent.where(event_id: event.event_id).delete_all if event
+          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(message = "manual event emitted and persisted inside rollback")
+          VerificationResult.new(
+            :ok,
+            "active_record capture",
+            message
+          )
+        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 cleanup_verification_call(response_id)
+          relation = LlmCostTracker::LlmApiCall.where(provider_response_id: response_id)
+          rows = relation.pluck(:id, :tracked_at, :total_cost)
+          return if rows.empty?
+
+          relation.delete_all
+          ActiveRecordRollups.decrement!(rows)
+        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_connection_cleanup.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Storage
+    module ActiveRecordConnectionCleanup
+      def self.release!
+        ActiveRecord::Base.connection_handler.clear_active_connections!
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end