llm_cost_tracker 0.8.0 → 0.10.0

data/lib/llm_cost_tracker/pricing/backfill.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "../pricing"
+require_relative "../billing/cost_status"
+require_relative "../billing/line_item"
+require_relative "../ledger/rollups"
+require_relative "../token_usage"
+
+module LlmCostTracker
+  module Pricing
+    class Backfill
+      Result = Data.define(:examined, :recomputed, :still_unknown)
+      RollupEvent = Data.define(:provider, :tracked_at, :pricing_snapshot, :total_cost)
+
+      DEFAULT_BATCH_SIZE = 500
+
+      class << self
+        def call(scope: default_scope, batch_size: DEFAULT_BATCH_SIZE)
+          examined = 0
+          recomputed = 0
+
+          scope.includes(:line_items).find_in_batches(batch_size: batch_size) do |batch|
+            rollup_events = []
+            LlmCostTracker::Call.transaction do
+              batch.each do |call|
+                examined += 1
+                outcome = recompute_for(call)
+                next unless outcome
+
+                persist!(call, outcome)
+                rollup_events << rollup_event_for(call, outcome)
+                recomputed += 1
+              end
+              Ledger::Rollups.increment_many!(rollup_events) if rollup_events.any?
+            end
+          end
+
+          Result.new(examined: examined, recomputed: recomputed, still_unknown: examined - recomputed)
+        end
+
+        def default_scope
+          LlmCostTracker::Call.where(total_cost: nil)
+        end
+
+        private
+
+        def recompute_for(call)
+          token_usage = token_usage_from(call)
+          billing_items = billing_line_items_from(call)
+          cost_data, snapshot, priced = Pricing.calculate(
+            provider: call.provider, model: call.model,
+            tokens: token_usage, line_items: billing_items,
+            pricing_mode: call.pricing_mode
+          )
+          return nil unless cost_data
+
+          full_cost = Pricing.combine_with_service_lines(cost_data, priced)
+          total_cost = full_cost[:total_cost]
+          return nil if total_cost.nil?
+
+          {
+            snapshot: snapshot,
+            priced_line_items: priced,
+            total_cost: total_cost,
+            cost_status: Billing::CostStatus.call(
+              token_usage: token_usage,
+              usage_source: call.usage_source&.to_sym,
+              token_cost: cost_data,
+              token_pricing_partial: Pricing.token_pricing_partial?(token_usage, cost_data),
+              service_line_items: priced.reject(&:token?),
+              total_cost: total_cost
+            )
+          }
+        end
+
+        def persist!(call, outcome)
+          call.update!(
+            total_cost: outcome[:total_cost],
+            pricing_snapshot: outcome[:snapshot],
+            cost_status: outcome[:cost_status]
+          )
+          call.line_items.to_a.zip(outcome[:priced_line_items]).each do |record, priced|
+            next if priced.nil?
+
+            record.update!(
+              rate_amount: priced.rate_amount,
+              rate_quantity: priced.rate_quantity,
+              cost: priced.cost,
+              currency: priced.currency,
+              cost_status: priced.cost_status,
+              price_key: priced.price_key,
+              price_source: priced.price_source&.to_s,
+              price_source_version: priced.price_source_version
+            )
+          end
+        end
+
+        def rollup_event_for(call, outcome)
+          RollupEvent.new(
+            provider: call.provider,
+            tracked_at: call.tracked_at,
+            pricing_snapshot: outcome[:snapshot],
+            total_cost: outcome[:total_cost]
+          )
+        end
+
+        def token_usage_from(call)
+          TokenUsage.build(
+            input_tokens: call.input_tokens,
+            output_tokens: call.output_tokens,
+            cache_read_input_tokens: call.cache_read_input_tokens,
+            cache_write_input_tokens: call.cache_write_input_tokens,
+            cache_write_extended_input_tokens: call.cache_write_extended_input_tokens,
+            audio_input_tokens: call.audio_input_tokens,
+            audio_output_tokens: call.audio_output_tokens,
+            image_input_tokens: call.image_input_tokens,
+            image_output_tokens: call.image_output_tokens,
+            hidden_output_tokens: call.hidden_output_tokens,
+            total_tokens: call.total_tokens
+          )
+        end
+
+        def billing_line_items_from(call)
+          call.line_items.map do |record|
+            Billing::LineItem.build(
+              kind: record.kind, direction: record.direction, modality: record.modality,
+              cache_state: record.cache_state, quantity: record.quantity, unit: record.unit,
+              rate_amount: record.rate_amount, rate_quantity: record.rate_quantity,
+              cost: record.cost, currency: record.currency, cost_status: record.cost_status,
+              pricing_basis: record.pricing_basis, price_key: record.price_key,
+              price_source: record.price_source, price_source_version: record.price_source_version,
+              provider_field: record.provider_field, provider_item_id: record.provider_item_id,
+              details: record.details
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/effective_prices.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 require_relative "../billing/components"
+require_relative "mode"
 
 module LlmCostTracker
   module Pricing
     module EffectivePrices
       class << self
-        def call(usage:, prices:, pricing_mode:)
+        def call(usage:, quantities:, prices:, pricing_mode:)
           context_tier = context_tier?(usage: usage, prices: prices)
+          orderings = pricing_mode && Mode.parse(pricing_mode).permutations
 
-          Billing::Components::TOKEN_PRICED.to_h do |component|
-            price_key = component.key
-            tokens = usage.public_send(component.token_key)
+          quantities.to_h do |price_key, tokens|
             price = if tokens.positive?
                       price_for(
                         prices: prices,
                         key: price_key,
-                        pricing_mode: pricing_mode,
+                        orderings: orderings,
                         context_tier: context_tier
                       )
                     else
@@ -28,10 +28,9 @@ module LlmCostTracker
 
         private
 
-        def price_for(prices:, key:, pricing_mode:, context_tier:)
-          return contextual_price(prices: prices, key: key, context_tier: context_tier) unless pricing_mode
+        def price_for(prices:, key:, orderings:, context_tier:)
+          return contextual_price(prices: prices, key: key, context_tier: context_tier) unless orderings
 
-          orderings = mode_orderings_for(pricing_mode)
           orderings.each do |mode|
             direct = contextual_price(prices: prices, key: :"#{mode}_#{key}", context_tier: context_tier)
             return direct if direct
@@ -41,38 +40,6 @@ module LlmCostTracker
           derived_mode_price(prices: prices, key: key, modes: orderings, context_tier: context_tier)
         end
 
-        def mode_orderings_for(pricing_mode)
-          mode_string = pricing_mode.to_s
-          return [mode_string] unless mode_string.include?("_")
-
-          tokens = tokenize_mode(mode_string)
-          return [mode_string] if tokens.size <= 1
-
-          [mode_string, *tokens.permutation.map { |permutation| permutation.join("_") }].uniq
-        end
-
-        def tokenize_mode(mode_string)
-          remaining = mode_string.dup
-          tokens = []
-          loop do
-            break if remaining.empty?
-
-            compound = COMPOUND_MODE_TOKENS.find { |token| remaining == token || remaining.start_with?("#{token}_") }
-            if compound
-              tokens << compound
-              remaining = remaining.delete_prefix(compound).delete_prefix("_")
-            else
-              first, _, rest = remaining.partition("_")
-              tokens << first
-              remaining = rest
-            end
-          end
-          tokens
-        end
-
-        COMPOUND_MODE_TOKENS = %w[data_residency].freeze
-        private_constant :COMPOUND_MODE_TOKENS
-
         def contextual_price(prices:, key:, context_tier:)
           return prices[key] unless context_tier
 

data/lib/llm_cost_tracker/pricing/estimator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module LlmCostTracker
+  module Pricing
+    module Estimator
+      CHARS_PER_TOKEN = 4
+
+      def self.call(provider:, model:, request:)
+        chars = char_count(request)
+        return BigDecimal("0") if chars.zero?
+
+        estimated_tokens = (chars.to_f / CHARS_PER_TOKEN).ceil
+        cost_data = Pricing.cost_for(
+          provider: provider,
+          model: model,
+          tokens: { input: estimated_tokens }
+        )
+        cost_data && BigDecimal(cost_data[:total_cost].to_s)
+      end
+
+      def self.char_count(value)
+        case value
+        when String then value.length
+        when Hash then value.values.sum { |nested| char_count(nested) }
+        when Array then value.sum { |nested| char_count(nested) }
+        else 0
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/explainer.rb

@@ -51,7 +51,10 @@ module LlmCostTracker
         def explanation(provider:, model:, pricing_mode:, match:, usage:)
           prices = match&.prices
           pricing_mode = Pricing.normalize_mode(pricing_mode)
-          effective = EffectivePrices.call(usage: usage, prices: prices, pricing_mode: pricing_mode) if prices
+          effective = if prices
+                        EffectivePrices.call(usage: usage, quantities: usage.priced_quantities,
+                                             prices: prices, pricing_mode: pricing_mode)
+                      end
 
           Explanation.new(
             provider: provider.to_s,

data/lib/llm_cost_tracker/pricing/lookup.rb

@@ -3,10 +3,14 @@
 module LlmCostTracker
   module Pricing
     module Lookup
-      Match = Data.define(:source, :key, :prices, :matched_by)
+      Match = Data.define(:source, :key, :prices, :matched_by, :currency)
+      DEFAULT_CURRENCY = "USD"
       MUTEX = Mutex.new
       CACHE_MISS = Object.new.freeze
       NO_MATCH = Object.new.freeze
+      LOOKUP_CACHE_LIMIT = 2_048
+      PRICE_FILE_RECHECK_INTERVAL = 1.0
+      private_constant :PRICE_FILE_RECHECK_INTERVAL
 
       class << self
         def call(provider:, model:)
@@ -14,6 +18,8 @@ module LlmCostTracker
           model_name = model.to_s
           return nil if model_name.empty?
 
+          invalidate_cache_if_prices_file_changed!
+
           cache_key = [provider_name, model_name]
           cached = cached_lookup(cache_key)
           return cached unless cached.equal?(CACHE_MISS)
@@ -25,14 +31,60 @@ module LlmCostTracker
 
         def reset!
           MUTEX.synchronize do
-            @prices_cache = nil
-            @lookup_cache = nil
-            @sorted_price_keys_cache = nil
+            reset_prices_caches!(signature: nil)
+            @prices_file_last_check_at = nil
+          end
+        end
+
+        def prices_file_mtime_iso
+          invalidate_cache_if_prices_file_changed!
+          signature = @prices_file_signature
+          return nil unless signature
+
+          cached = @prices_file_iso_cache
+          return cached[:value] if cached && cached[:mtime] == signature
+
+          MUTEX.synchronize do
+            cached = @prices_file_iso_cache
+            return cached[:value] if cached && cached[:mtime] == signature
+
+            iso = signature.utc.iso8601
+            @prices_file_iso_cache = { mtime: signature, value: iso }.freeze
+            iso
           end
         end
 
         private
 
+        def invalidate_cache_if_prices_file_changed!
+          path = LlmCostTracker.configuration.prices_file
+
+          unless path
+            return if @prices_file_signature.nil?
+
+            MUTEX.synchronize { reset_prices_caches!(signature: nil) unless @prices_file_signature.nil? }
+            return
+          end
+
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          last_check = @prices_file_last_check_at
+          return if last_check && (now - last_check) < PRICE_FILE_RECHECK_INTERVAL
+
+          signature = File.exist?(path) ? File.mtime(path) : nil
+          MUTEX.synchronize do
+            @prices_file_last_check_at = now
+            reset_prices_caches!(signature: signature) if @prices_file_signature != signature
+          end
+        end
+
+        def reset_prices_caches!(signature:)
+          @prices_cache = nil
+          @lookup_cache = nil
+          @sorted_price_keys_cache = nil
+          @prices_file_iso_cache = nil
+          @prices_file_signature = signature
+        end
+
         def lookup_match(provider_name:, model_name:)
           provider_model = provider_name ? "#{provider_name}/#{model_name}" : model_name
           normalized_model = normalize_model_name(model_name)
@@ -86,6 +138,7 @@ module LlmCostTracker
         def cache_lookup(cache_key, match)
           MUTEX.synchronize do
             values = (@lookup_cache || {}).dup
+            values.shift while values.size >= LOOKUP_CACHE_LIMIT
             values[cache_key] = match || NO_MATCH
             @lookup_cache = values.freeze
           end
@@ -135,7 +188,22 @@ module LlmCostTracker
         end
 
         def match(table:, source:, key:, matched_by:)
-          Match.new(source: source, key: key, prices: table[key], matched_by: matched_by)
+          Match.new(
+            source: source,
+            key: key,
+            prices: table[key],
+            matched_by: matched_by,
+            currency: source_currency(source)
+          )
+        end
+
+        def source_currency(source)
+          case source
+          when :bundled then Registry.metadata["currency"] || DEFAULT_CURRENCY
+          when :prices_file
+            Registry.file_metadata(LlmCostTracker.configuration.prices_file)["currency"] || DEFAULT_CURRENCY
+          else DEFAULT_CURRENCY
+          end
         end
 
         def snapshot_variant?(model, key)

data/lib/llm_cost_tracker/pricing/mode.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Pricing
+    class Mode
+      COMPOUND_MODIFIERS = %w[data_residency].freeze
+
+      attr_reader :modifiers
+
+      def self.parse(value)
+        return value if value.is_a?(self)
+        return new([]) if value.nil?
+
+        new(tokenize(value.to_s))
+      end
+
+      def self.tokenize(value)
+        remaining = value.to_s.downcase.tr("-", "_")
+        tokens = []
+        loop do
+          break if remaining.empty?
+
+          compound = COMPOUND_MODIFIERS.find do |token|
+            remaining == token || remaining.start_with?("#{token}_")
+          end
+          if compound
+            tokens << compound.to_sym
+            remaining = remaining.delete_prefix(compound).delete_prefix("_")
+          else
+            first, _, rest = remaining.partition("_")
+            tokens << first.to_sym unless first.empty?
+            remaining = rest
+          end
+        end
+        tokens
+      end
+
+      def initialize(modifiers)
+        @modifiers = Array(modifiers).map(&:to_sym).uniq.sort
+        freeze
+      end
+
+      def empty?
+        modifiers.empty?
+      end
+
+      def include?(modifier)
+        modifiers.include?(modifier.to_sym)
+      end
+
+      def canonical
+        modifiers.join("_")
+      end
+      alias to_s canonical
+
+      def to_sym
+        empty? ? nil : canonical.to_sym
+      end
+
+      def permutations
+        return [canonical] if modifiers.size <= 1
+
+        modifiers.permutation.map { |permutation| permutation.join("_") }.uniq
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && modifiers == other.modifiers
+      end
+      alias eql? ==
+
+      def hash
+        modifiers.hash
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/registry.rb

@@ -91,13 +91,6 @@ module LlmCostTracker
 
         private
 
-        def raw_registry
-          cached = @raw_registry
-          return cached if cached
-
-          MUTEX.synchronize { @raw_registry ||= load_raw_registry }
-        end
-
         def load_raw_registry
           YAML.safe_load_file(DEFAULT_PRICES_PATH, aliases: false).freeze
         end
@@ -115,6 +108,7 @@ module LlmCostTracker
 
         def non_negative_float(key, value)
           rate = Float(value)
+          raise ArgumentError, "price for #{key.inspect} must be finite (got #{rate})" unless rate.finite?
           raise ArgumentError, "price for #{key.inspect} must be non-negative (got #{rate})" if rate.negative?
 
           rate
@@ -145,8 +139,9 @@ module LlmCostTracker
 
         def price_key_for(key)
           name = key.is_a?(Symbol) ? key.name : key
-          Billing::Components::TOKEN_PRICED.each do |candidate|
+          Billing::Components::REGISTRY.each do |candidate|
             return candidate.key if candidate.key.name == name
+            next unless candidate.token_key
 
             suffix = "_#{candidate.key.name}"
             next unless name.end_with?(suffix)

data/lib/llm_cost_tracker/pricing/service_charges.rb

@@ -60,9 +60,10 @@ module LlmCostTracker
         data = registry.fetch("service_charges", EMPTY_RATES)
         raise ArgumentError, "#{context} service_charges must be a hash" unless data.is_a?(Hash)
 
+        currency = registry.dig("metadata", "currency") || DEFAULT_CURRENCY
         data.each_with_object({}) do |(provider, entries), rates|
           section_context = "#{context} service_charges.#{provider}"
-          rates[provider] = rates_from_section(entries, context: section_context)
+          rates[provider] = rates_from_section(entries, currency: currency, context: section_context)
         end
       end
 
@@ -84,7 +85,7 @@ module LlmCostTracker
 
       private
 
-      def rates_from_section(entries, context:)
+      def rates_from_section(entries, currency:, context:)
         raise ArgumentError, "#{context} must be a hash" unless entries.is_a?(Hash)
 
         entries.each_with_object({}) do |(key, amount), rates|
@@ -95,7 +96,7 @@ module LlmCostTracker
           rate = {
             amount: amount,
             quantity: rate_quantity(component),
-            currency: DEFAULT_CURRENCY,
+            currency: currency,
             source_key: key
           }
           component_rates = rates[component.key] ||= { tiers: {} }
@@ -121,14 +122,20 @@ module LlmCostTracker
 
       def amount_for(key, amount, context:)
         value = BigDecimal(amount.to_s)
-        message = "service charge price amount for #{key.inspect} in #{context} must be non-negative"
-        raise ArgumentError, message if value.negative?
+        if value.infinite? || value.nan?
+          raise ArgumentError,
+                "service charge price amount for #{key.inspect} in #{context} must be finite"
+        end
+        if value.negative?
+          raise ArgumentError,
+                "service charge price amount for #{key.inspect} in #{context} must be non-negative"
+        end
 
         value
       end
 
       def rate_quantity(component)
-        component.unit == :request ? BigDecimal("1000") : BigDecimal("1")
+        BigDecimal(Billing::RATE_BASIS_QUANTITIES.fetch(component.rate_basis, 1).to_s)
       end
 
       def charge_rate_match(provider:, component:, pricing_mode:)
@@ -192,12 +199,7 @@ module LlmCostTracker
       def rate_source_version_for(source)
         return LlmCostTracker::VERSION if source == :bundled
 
-        path = LlmCostTracker.configuration.prices_file
-        return nil unless path
-
-        File.mtime(path).utc.iso8601
-      rescue Errno::ENOENT
-        nil
+        Lookup.prices_file_mtime_iso
       end
     end
   end

data/lib/llm_cost_tracker/pricing/{sync_change_printer.rb → sync/change_printer.rb}

@@ -2,9 +2,9 @@
 
 module LlmCostTracker
   module Pricing
-    module SyncChangePrinter
-      class << self
-        def call(changes, output: $stdout)
+    module Sync
+      module ChangePrinter
+        def self.call(changes, output: $stdout)
           service_changes = changes["service_charges"]
           model_changes = changes.except("service_charges")
 

data/lib/llm_cost_tracker/pricing/sync/registry_writer.rb

@@ -9,10 +9,12 @@ module LlmCostTracker
     module Sync
       class RegistryWriter
         YAML_EXTENSIONS = %w[.yml .yaml].freeze
+        MANUAL_SOURCE = "manual"
 
         def call(path:, registry:)
           FileUtils.mkdir_p(File.dirname(path))
-          payload = yaml_file?(path) ? YAML.dump(registry) : "#{JSON.pretty_generate(registry)}\n"
+          merged = canonicalize(merge_with_existing(path: path, registry: registry))
+          payload = yaml_file?(path) ? YAML.dump(merged) : "#{JSON.pretty_generate(merged)}\n"
           temp_path = "#{path}.tmp-#{Process.pid}-#{Thread.current.object_id}"
           File.write(temp_path, payload)
           File.rename(temp_path, path)
@@ -22,6 +24,65 @@ module LlmCostTracker
 
         private
 
+        def canonicalize(value)
+          case value
+          when Hash
+            value.sort_by { |key, _| key.to_s }.to_h { |key, nested| [key, canonicalize(nested)] }
+          when Array
+            value.map { |element| canonicalize(element) }
+          else
+            value
+          end
+        end
+
+        def merge_with_existing(path:, registry:)
+          existing = read_existing(path)
+          return registry unless existing.is_a?(Hash)
+
+          merged = registry.dup
+          merged["models"] = merged_models(registry, existing) if existing["models"].is_a?(Hash)
+          if existing["service_charges"].is_a?(Hash)
+            merged["service_charges"] = merged_service_charges(registry, existing)
+          end
+          merged
+        end
+
+        def merged_models(registry, existing)
+          merged = registry.fetch("models", {}).dup
+          existing.fetch("models", {}).each do |model, attrs|
+            next unless attrs.is_a?(Hash) && attrs["_source"].to_s == MANUAL_SOURCE
+            next if merged.key?(model)
+
+            merged[model] = attrs
+          end
+          merged
+        end
+
+        def merged_service_charges(registry, existing)
+          remote = registry.fetch("service_charges", {})
+          existing.fetch("service_charges", {}).each_with_object(remote.dup) do |(provider, charges), merged|
+            next unless charges.is_a?(Hash)
+            next if merged.key?(provider)
+
+            merged[provider] = charges
+          end
+        end
+
+        def read_existing(path)
+          return nil unless File.exist?(path)
+
+          contents = File.read(path)
+          return nil if contents.strip.empty?
+
+          if yaml_file?(path)
+            YAML.safe_load(contents, permitted_classes: [Symbol, Date, Time])
+          else
+            JSON.parse(contents)
+          end
+        rescue StandardError
+          nil
+        end
+
         def yaml_file?(path)
           YAML_EXTENSIONS.include?(File.extname(path).downcase)
         end

data/lib/llm_cost_tracker/pricing/sync.rb

@@ -29,7 +29,7 @@ module LlmCostTracker
           prices_file = config.prices_file
           return prices_file.to_s if prices_file
 
-          default_output_path
+          Rails.root.join(DEFAULT_OUTPUT_PATH).to_s
         end
 
         def configured_remote_url(env: ENV)
@@ -103,14 +103,6 @@ module LlmCostTracker
 
         private
 
-        def default_output_path
-          if Rails.root
-            Rails.root.join(DEFAULT_OUTPUT_PATH).to_s
-          else
-            DEFAULT_OUTPUT_PATH
-          end
-        end
-
         def normalize_remote_registry(body, url:, response:, today:)
           registry = parse_registry(body)
           metadata = registry.fetch("metadata", {})
@@ -150,8 +142,10 @@ module LlmCostTracker
         end
 
         def load_registry(path)
+          return {} unless File.exist?(path)
+
           YAML.safe_load_file(path, aliases: false) || {}
-        rescue Errno::ENOENT, Psych::Exception, ArgumentError, TypeError => e
+        rescue Psych::Exception, ArgumentError, TypeError => e
           raise Error, "Unable to load pricing registry #{path.inspect}: #{e.message}"
         end