llm_cost_tracker 0.9.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

@@ -7,13 +7,11 @@ 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,

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,7 +3,8 @@
 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
@@ -35,6 +36,24 @@ module LlmCostTracker
           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!
@@ -62,6 +81,7 @@ module LlmCostTracker
           @prices_cache = nil
           @lookup_cache = nil
           @sorted_price_keys_cache = nil
+          @prices_file_iso_cache = nil
           @prices_file_signature = signature
         end
 
@@ -168,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/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

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: {} }
@@ -198,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

@@ -13,7 +13,7 @@ module LlmCostTracker
 
         def call(path:, registry:)
           FileUtils.mkdir_p(File.dirname(path))
-          merged = merge_with_existing(path: path, registry: registry)
+          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)
@@ -24,6 +24,17 @@ 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)
@@ -51,8 +62,9 @@ module LlmCostTracker
           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.merge(merged.fetch(provider, {}))
+            merged[provider] = charges
           end
         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", {})

data/lib/llm_cost_tracker/pricing/unknown.rb

@@ -6,10 +6,11 @@ module LlmCostTracker
   module Pricing
     class Unknown
       MUTEX = Mutex.new
+      WARN_CACHE_LIMIT = 1024
 
       class << self
-        def handle!(model)
-          model = model.to_s.presence || "unknown"
+        def process(model)
+          model = model.to_s.presence || Event::UNKNOWN_MODEL
 
           case LlmCostTracker.configuration.unknown_pricing_behavior
           when :ignore
@@ -30,6 +31,8 @@ module LlmCostTracker
         def warn_missing(model)
           should_warn = MUTEX.synchronize do
             @warned_models ||= Set.new
+            next false if @warned_models.size >= WARN_CACHE_LIMIT && !@warned_models.include?(model)
+
             @warned_models.add?(model)
           end
           return unless should_warn

data/lib/llm_cost_tracker/pricing.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/object/blank"
+require "bigdecimal"
 require "time"
 
 require_relative "version"
+require_relative "logging"
 require_relative "token_usage"
 require_relative "billing/components"
+require_relative "billing/line_item"
 require_relative "pricing/mode"
 require_relative "pricing/registry"
 require_relative "pricing/lookup"
 require_relative "pricing/effective_prices"
 require_relative "pricing/explainer"
 require_relative "pricing/service_charges"
+require_relative "pricing/estimator"
 
 module LlmCostTracker
   module Pricing # rubocop:disable Metrics/ModuleLength
@@ -19,7 +23,7 @@ module LlmCostTracker
 
     STANDARD_MODE_VALUES = %i[auto default standard standard_only].freeze
     RATE_DENOMINATOR_TOKENS = 1_000_000
-    private_constant :STANDARD_MODE_VALUES, :RATE_DENOMINATOR_TOKENS
+    private_constant :RATE_DENOMINATOR_TOKENS
 
     class << self
       def normalize_mode(value)
@@ -92,8 +96,49 @@ module LlmCostTracker
         value ? { total_cost: value } : {}
       end
 
+      def combine_with_service_lines(cost_data, line_items)
+        priced_services = line_items.reject(&:token?).select(&:priced?)
+        return cost_data if priced_services.empty?
+
+        base_currency = base_currency_for(cost_data, priced_services)
+        matching, mismatched = priced_services.partition { |line| line.currency.to_s == base_currency.to_s }
+        warn_currency_mismatch(mismatched, base_currency) if mismatched.any?
+
+        cost = cost_data ? cost_data.dup : {}
+        cost[:currency] ||= base_currency.to_s
+        return cost if matching.empty?
+
+        service_total = matching.sum(BigDecimal("0"), &:cost_value)
+        base_total = BigDecimal(cost.fetch(:total_cost, 0).to_s)
+        cost[:total_cost] = (base_total + service_total).round(8)
+        cost
+      end
+
+      def token_pricing_partial?(token_usage, cost_data)
+        return false unless cost_data
+
+        token_usage.priced_quantities.any? do |key, quantity|
+          next false unless quantity.positive?
+
+          cost_data[Billing::Components::BY_KEY.fetch(key).cost_key].nil?
+        end
+      end
+
       private
 
+      def base_currency_for(cost_data, priced_services)
+        (cost_data && cost_data[:currency]) || priced_services.first.currency || Billing::LineItem::USD
+      end
+
+      def warn_currency_mismatch(lines, base_currency)
+        currencies = lines.map { |line| line.currency.to_s }.uniq.sort
+        Logging.warn(
+          "Service line currency mismatch: header is #{base_currency}, dropping " \
+          "#{lines.size} priced line(s) in #{currencies.join(', ')} from header total. " \
+          "Per-line costs are still recorded; header total reflects #{base_currency} only."
+        )
+      end
+
       def normalize_string_mode(value)
         normalized = value.strip
         return nil if normalized.empty?
@@ -108,22 +153,18 @@ module LlmCostTracker
           result[component.cost_key] = cost.round(8) unless cost.nil?
         end
         values[:total_cost] = costs.values.compact.sum(BigDecimal("0")).round(8)
+        values[:currency] = calculation[:match].currency
         values
       end
 
       def snapshot_from(calculation)
         match = calculation[:match]
         effective = calculation[:effective]
-        token_usage = calculation[:token_usage]
-        rates = Billing::Components::TOKEN_PRICED.each_with_object({}) do |component, values|
-          quantity = token_usage.public_send(component.token_key)
-          price = effective[component.key]
+        rates = calculation[:quantities].each_with_object({}) do |(key, quantity), values|
+          price = effective[key]
           next if quantity.zero? || price.nil?
 
-          values[component.key] = {
-            amount: price,
-            quantity: RATE_DENOMINATOR_TOKENS
-          }
+          values[key] = { amount: price, quantity: RATE_DENOMINATOR_TOKENS }
         end
 
         {
@@ -132,7 +173,7 @@ module LlmCostTracker
           source_key: match.key,
           source_version: source_version_for(match.source),
           matched_by: match.matched_by,
-          currency: "USD",
+          currency: match.currency,
           rates: rates
         }
       end
@@ -142,23 +183,29 @@ module LlmCostTracker
         return nil unless match
 
         token_usage = TokenUsage.build_from_tokens(tokens)
+        quantities = token_usage.priced_quantities
         mode = normalize_mode(pricing_mode)
-        effective = EffectivePrices.call(usage: token_usage, prices: match.prices, pricing_mode: mode)
-        return nil unless any_billable_priced?(token_usage, effective)
+        effective = EffectivePrices.call(usage: token_usage, quantities: quantities, prices: match.prices,
+                                         pricing_mode: mode)
+        return nil unless any_billable_priced?(quantities, effective)
 
-        { match: match, effective: effective, token_usage: token_usage, costs: costs_for(token_usage, effective) }
+        { match: match, effective: effective, token_usage: token_usage, quantities: quantities,
+          costs: costs_for(quantities, effective) }
       end
 
-      def any_billable_priced?(token_usage, effective)
-        billable = Billing::Components::TOKEN_PRICED.select { |c| token_usage.public_send(c.token_key).positive? }
-        billable.empty? || billable.any? { |c| effective[c.key] }
-      end
+      def any_billable_priced?(quantities, effective)
+        any_billable = false
+        quantities.each_pair do |key, quantity|
+          next unless quantity.positive?
+          return true if effective[key]
 
-      def costs_for(usage, effective)
-        Billing::Components::TOKEN_PRICED.to_h do |component|
-          tokens = usage.public_send(component.token_key)
-          [component.key, token_cost(tokens, effective[component.key])]
+          any_billable = true
         end
+        !any_billable
+      end
+
+      def costs_for(quantities, effective)
+        quantities.to_h { |key, tokens| [key, token_cost(tokens, effective[key])] }
       end
 
       def apply_calculation_to_line_items(line_items, calculation, provider:, pricing_mode:)
@@ -197,6 +244,7 @@ module LlmCostTracker
           rate_amount: BigDecimal(effective_price.to_s),
           rate_quantity: BigDecimal(RATE_DENOMINATOR_TOKENS),
           cost: cost,
+          currency: match.currency,
           cost_status: cost.zero? ? Billing::CostStatus::FREE : Billing::CostStatus::COMPLETE,
           price_key: component.key,
           price_source: match.source,
@@ -212,7 +260,7 @@ module LlmCostTracker
                charge_rate(provider: provider, component: line_item.kind, pricing_mode: pricing_mode)
         return line_item unless rate
 
-        line_item.apply_rate(rate)
+        line_item.with_rate(rate)
       end
 
       def model_rate_for(line_item, calculation)
@@ -226,7 +274,7 @@ module LlmCostTracker
         {
           amount: BigDecimal(amount.to_s),
           quantity: BigDecimal(Billing::RATE_BASIS_QUANTITIES.fetch(component.rate_basis).to_s),
-          currency: "USD",
+          currency: match.currency,
           source: match.source,
           source_key: "#{match.key}.#{line_item.kind}",
           source_version: source_version_for(match.source)
@@ -248,13 +296,10 @@ module LlmCostTracker
         when :bundled
           LlmCostTracker::VERSION
         when :prices_file
-          path = LlmCostTracker.configuration.prices_file
-          path ? File.mtime(path).utc.iso8601 : nil
+          Lookup.prices_file_mtime_iso
         when :pricing_overrides
           "configuration"
         end
-      rescue Errno::ENOENT
-        nil
       end
 
       def token_cost(tokens, per_million_price)

data/lib/llm_cost_tracker/providers/anthropic/tier_classification.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Providers
+    module Anthropic
+      module TierClassification
+        DATA_RESIDENCY_GEOS = %w[us].freeze
+        STANDARD_EQUIVALENT_SERVICE_TIERS = %w[standard standard_only priority].freeze
+
+        module_function
+
+        def data_residency_geo?(geo)
+          DATA_RESIDENCY_GEOS.include?(geo.to_s.downcase)
+        end
+
+        def standard_equivalent_tier?(service_tier)
+          STANDARD_EQUIVALENT_SERVICE_TIERS.include?(service_tier.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/providers/azure/hosts.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Providers
+    module Azure
+      module Hosts
+        OPENAI_HOST_PATTERN = /\A[a-z0-9][a-z0-9-]*\.(?:openai\.azure\.com|services\.ai\.azure\.com)\z/i
+
+        module_function
+
+        def openai?(host)
+          host.to_s.match?(OPENAI_HOST_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/providers/gemini/model_families.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Providers
+    module Gemini
+      module ModelFamilies
+        PER_QUERY_GROUNDING_MODEL_PATTERN = /\bgemini-(?:[3-9]|[1-9]\d)\b/i
+
+        module_function
+
+        def per_query_grounding?(model)
+          model.to_s.match?(PER_QUERY_GROUNDING_MODEL_PATTERN)
+        end
+      end
+    end
+  end
+end