llm_cost_tracker 0.8.0 → 0.10.0

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,30 +1,35 @@
 # 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
+  module Pricing # rubocop:disable Metrics/ModuleLength
     extend ServiceCharges
 
     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)
         return nil if value.nil?
 
-        mode = value.is_a?(Symbol) ? value.downcase : normalize_string_mode(value)
+        mode = normalize_string_mode(value.to_s)
         return nil unless mode
 
         STANDARD_MODE_VALUES.include?(mode) ? nil : mode
@@ -42,29 +47,26 @@ module LlmCostTracker
         cost_from(calculation)
       end
 
-      def cost_and_snapshot_for(provider:, model:, tokens:, pricing_mode: nil)
+      def calculate(provider:, model:, tokens:, line_items:, pricing_mode: nil)
         calculation = calculation_for(
           provider: provider,
           model: model,
           tokens: tokens,
           pricing_mode: pricing_mode
         )
-        return [nil, nil] unless calculation
-
-        [cost_from(calculation), snapshot_from(calculation)]
+        cost_data = calculation && cost_from(calculation)
+        snapshot = calculation && snapshot_from(calculation)
+        priced = apply_calculation_to_line_items(line_items, calculation,
+                                                 provider: provider, pricing_mode: pricing_mode)
+        [cost_data, snapshot, priced]
       end
 
       def price_line_items(provider:, model:, line_items:, pricing_mode: nil)
         token_usage = TokenUsage.build_from_tokens(token_attributes_from(line_items))
         calculation = calculation_for(provider: provider, model: model, tokens: token_usage, pricing_mode: pricing_mode)
         snapshot = calculation && snapshot_from(calculation)
-
-        priced = line_items.map do |line_item|
-          next price_token_line_item(line_item, calculation) if line_item.unit == :token
-
-          price_service_charge_line_item(line_item, provider: provider, pricing_mode: pricing_mode)
-        end
-
+        priced = apply_calculation_to_line_items(line_items, calculation,
+                                                 provider: provider, pricing_mode: pricing_mode)
         [priced, snapshot]
       end
 
@@ -91,11 +93,52 @@ module LlmCostTracker
 
       def stored_cost_attributes(attributes)
         value = attributes.to_h[:total_cost]
-        value.nil? ? {} : { total_cost: value }
+        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?
@@ -109,23 +152,19 @@ module LlmCostTracker
           cost = costs[component.key]
           result[component.cost_key] = cost.round(8) unless cost.nil?
         end
-        values[:total_cost] = costs.values.compact.sum.round(8)
+        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
 
         {
@@ -134,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
@@ -144,22 +183,39 @@ 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] }
+      def any_billable_priced?(quantities, effective)
+        any_billable = false
+        quantities.each_pair do |key, quantity|
+          next unless quantity.positive?
+          return true if effective[key]
+
+          any_billable = true
+        end
+        !any_billable
       end
 
-      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])]
+      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:)
+        line_items.map do |line_item|
+          next price_token_line_item(line_item, calculation) if line_item.unit == :token
+
+          price_service_charge_line_item(line_item,
+                                         provider: provider,
+                                         calculation: calculation,
+                                         pricing_mode: pricing_mode)
         end
       end
 
@@ -188,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,
@@ -195,14 +252,33 @@ module LlmCostTracker
         )
       end
 
-      def price_service_charge_line_item(line_item, provider:, pricing_mode:)
+      def price_service_charge_line_item(line_item, provider:, calculation:, pricing_mode:)
         return line_item if line_item.priced?
         return line_item unless line_item.billable?
 
-        rate = charge_rate(provider: provider, component: line_item.kind, pricing_mode: pricing_mode)
+        rate = model_rate_for(line_item, calculation) ||
+               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)
+        return nil unless calculation
+
+        match = calculation[:match]
+        amount = match.prices[line_item.kind] || match.prices[line_item.kind.to_s]
+        return nil unless amount.is_a?(Numeric)
+
+        component = Billing::Components::BY_KEY[line_item.kind]
+        {
+          amount: BigDecimal(amount.to_s),
+          quantity: BigDecimal(Billing::RATE_BASIS_QUANTITIES.fetch(component.rate_basis).to_s),
+          currency: match.currency,
+          source: match.source,
+          source_key: "#{match.key}.#{line_item.kind}",
+          source_version: source_version_for(match.source)
+        }
       end
 
       def component_for_line_item(line_item)
@@ -220,20 +296,17 @@ 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)
-        return 0.0 if tokens.zero?
+        return BigDecimal("0") if tokens.zero?
         return nil if per_million_price.nil?
 
-        (tokens * per_million_price) / RATE_DENOMINATOR_TOKENS
+        (BigDecimal(tokens.to_s) * BigDecimal(per_million_price.to_s)) / RATE_DENOMINATOR_TOKENS
       end
     end
   end

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Providers
+    module Openai
+      module Hosts
+        API_HOSTS = %w[
+          api.openai.com
+          us.api.openai.com
+          eu.api.openai.com
+          au.api.openai.com
+          ca.api.openai.com
+          jp.api.openai.com
+          in.api.openai.com
+          sg.api.openai.com
+          kr.api.openai.com
+          gb.api.openai.com
+          ae.api.openai.com
+        ].freeze
+
+        DATA_RESIDENCY_HOST_PATTERN = /\A[a-z]{2,3}\.api\.openai\.com\z/
+
+        module_function
+
+        def api?(host)
+          API_HOSTS.include?(host.to_s.downcase)
+        end
+
+        def data_residency?(host)
+          host.to_s.downcase.match?(DATA_RESIDENCY_HOST_PATTERN)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Providers
+    module Openai
+      module ModelFamilies
+        DATA_RESIDENCY_MODEL_PATTERN =
+          /\Agpt-5\.(?:4|5)(?:-(?:mini|nano|pro|codex(?:-mini|-max)?))?(?:-\d{4}-\d{2}-\d{2})?\z/
+
+        IMAGE_OUTPUT_MODEL_PATTERN = /\Agpt-image-/i
+
+        CHARACTER_BILLED_TTS_MODEL_PATTERN = /\Atts-1(-hd)?\z/
+
+        REASONING_MODEL_PATTERNS = [
+          /\Agpt-5(\b|[\d.-])/i,
+          /\Ao\d+(\b|[\d.-])/i
+        ].freeze
+
+        NON_REASONING_GPT5_PATTERN = /\Agpt-5(?:\.\d+)?-chat\b/i
+
+        CHAT_COMPLETIONS_SEARCH_MODEL_PATTERN = /-search-(?:preview|api)\b/i
+
+        module_function
+
+        def data_residency?(model)
+          model.to_s.match?(DATA_RESIDENCY_MODEL_PATTERN)
+        end
+
+        def image_output?(model)
+          model.to_s.match?(IMAGE_OUTPUT_MODEL_PATTERN)
+        end
+
+        def character_billed_tts?(model)
+          model.to_s.match?(CHARACTER_BILLED_TTS_MODEL_PATTERN)
+        end
+
+        def chat_completions_search?(model)
+          model.to_s.match?(CHAT_COMPLETIONS_SEARCH_MODEL_PATTERN)
+        end
+
+        def reasoning?(model)
+          name = model.to_s
+          return false if name.empty?
+          return false if NON_REASONING_GPT5_PATTERN.match?(name)
+
+          REASONING_MODEL_PATTERNS.any? { |pattern| pattern.match?(name) }
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/railtie.rb

@@ -11,6 +11,14 @@ module LlmCostTracker
     generators do
       require_relative "generators/llm_cost_tracker/install_generator"
       require_relative "generators/llm_cost_tracker/prices_generator"
+      require_relative "generators/llm_cost_tracker/call_rollups_generator"
+      require_relative "generators/llm_cost_tracker/async_ingestion_generator"
+      require_relative "generators/llm_cost_tracker/reconciliation_generator"
+      require_relative "generators/llm_cost_tracker/upgrade_call_rollups_provider_generator"
+      require_relative "generators/llm_cost_tracker/upgrade_image_tokens_generator"
+      require_relative "generators/llm_cost_tracker/upgrade_call_tags_key_value_index_generator"
+      require_relative "generators/llm_cost_tracker/upgrade_provider_invoice_imports_provider_generator"
+      require_relative "generators/llm_cost_tracker/upgrade_provider_invoices_metadata_index_generator"
     end
 
     rake_tasks do

data/lib/llm_cost_tracker/reconcile_tasks.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "reconciliation"
+
+module LlmCostTracker
+  module ReconcileTasks
+    SOURCE_PARSERS = {
+      "openai" => Reconciliation::Sources::OpenaiUsage,
+      "anthropic" => Reconciliation::Sources::AnthropicUsage
+    }.freeze
+    GENERIC_SOURCES = %w[csv].freeze
+
+    module_function
+
+    def run_import(env: ENV, output: $stdout, error_output: $stderr)
+      result = import_from_env(env: env)
+      output.puts "llm_cost_tracker: imported #{result.total_imported} rows " \
+                  "(inserted=#{result.inserted}, updated=#{result.updated}, skipped=#{result.skipped})"
+      result.errors.each { |error| error_output.puts "  error: #{error}" }
+      raise "llm_cost_tracker: reconcile import had errors" unless result.success?
+
+      result
+    end
+
+    def run_diff(env: ENV, output: $stdout)
+      diff = diff_from_env(env: env)
+      print_diff(diff, output: output)
+      diff
+    end
+
+    def import_from_env(env: ENV)
+      source = required_env(env, "SOURCE")
+      input_path = required_env(env, "INPUT")
+      raise ArgumentError, "INPUT file not found: #{input_path}" unless File.exist?(input_path)
+
+      payload = JSON.parse(File.read(input_path))
+      rows = parse_rows(source: source, payload: payload)
+      Reconciliation.import(source: source.to_sym, rows: rows, provider: env["PROVIDER"])
+    end
+
+    def diff_from_env(env: ENV)
+      source = required_env(env, "SOURCE")
+      period_start = Date.parse(required_env(env, "PERIOD_START"))
+      period_end = Date.parse(required_env(env, "PERIOD_END"))
+      Reconciliation.diff(source: source.to_sym, period_start: period_start, period_end: period_end,
+                          provider: env["PROVIDER"],
+                          drilldown_limit: parse_drilldown_limit(env["DRILLDOWN_LIMIT"]))
+    end
+
+    def parse_drilldown_limit(value)
+      return Reconciliation::Diff::DEFAULT_DRILLDOWN_LIMIT if value.nil? || value.to_s.empty?
+      return nil if value.to_s.downcase == "all"
+
+      Integer(value)
+    end
+
+    def print_diff(diff, output: $stdout)
+      output.puts "llm_cost_tracker: reconciliation diff for #{diff.source} " \
+                  "#{diff.period_start}..#{diff.period_end}"
+      output.puts "  provider_total: #{diff.provider_total.to_s('F')} #{diff.currency}"
+      output.puts "  local_total:    #{diff.local_total.to_s('F')} #{diff.currency} " \
+                  "(from #{diff.local_total_source})"
+      output.puts "  delta:          #{diff.delta_amount.to_s('F')} (#{diff.delta_percent || 'n/a'}%)"
+      print_unmatched_provider_rows(diff, output)
+      print_unmatched_local_calls(diff, output)
+      print_non_cost_rows(diff, output)
+    end
+
+    def parse_rows(source:, payload:)
+      parser = SOURCE_PARSERS[source.to_s]
+      return parser.parse(payload) if parser
+      return Array(payload["rows"]) if GENERIC_SOURCES.include?(source.to_s)
+
+      known = (SOURCE_PARSERS.keys + GENERIC_SOURCES).join(", ")
+      raise ArgumentError, "unknown SOURCE #{source.inspect}; known sources: #{known}"
+    end
+
+    def required_env(env, key)
+      value = env[key].to_s.strip
+      raise ArgumentError, "missing #{key}" if value.empty?
+
+      value
+    end
+
+    def print_unmatched_provider_rows(diff, output)
+      return if diff.unmatched_provider_rows.empty?
+
+      output.puts "  unmatched provider rows#{truncation_suffix(diff.unmatched_provider_rows.size,
+                                                                diff.unmatched_provider_rows_total)}:"
+      diff.unmatched_provider_rows.each do |row|
+        output.puts "    #{row[:external_id]} (#{row[:match_basis]}): " \
+                    "#{format_amount(row[:billed_amount])} #{format_attribution(row[:attribution])}"
+      end
+    end
+
+    def print_unmatched_local_calls(diff, output)
+      return if diff.unmatched_local_calls.empty?
+
+      output.puts "  unmatched local calls#{truncation_suffix(diff.unmatched_local_calls.size,
+                                                              diff.unmatched_local_calls_total)}:"
+      diff.unmatched_local_calls.each do |row|
+        output.puts "    #{row[:count]} calls / #{row[:total_cost].to_s('F')} " \
+                    "#{format_attribution(row[:attribution])}"
+      end
+    end
+
+    def print_non_cost_rows(diff, output)
+      return if diff.non_cost_rows.empty?
+
+      output.puts "  non-cost evidence#{truncation_suffix(diff.non_cost_rows.size,
+                                                          diff.non_cost_rows_total)}:"
+      diff.non_cost_rows.each do |row|
+        output.puts "    [#{row[:row_type]}/#{row[:meter]}] #{format_amount(row[:billed_amount])} " \
+                    "#{format_attribution(row[:attribution])}"
+      end
+    end
+
+    def truncation_suffix(shown, total)
+      return "" if shown >= total
+
+      " (showing #{shown} of #{total} — pass DRILLDOWN_LIMIT=all to see every row)"
+    end
+
+    def format_amount(value)
+      value.nil? ? "n/a" : value.to_s("F")
+    end
+
+    def format_attribution(attribution)
+      LlmCostTracker::Masking.format_attribution(attribution, separator: ",")
+    end
+  end
+end