llm_cost_tracker 0.10.0 → 0.12.0

data/lib/llm_cost_tracker/pricing/mode.rb

@@ -2,16 +2,37 @@
 
 module LlmCostTracker
   module Pricing
-    class Mode
+    module Mode
+      STANDARD_MODE_VALUES = %w[auto default standard standard_only unspecified].freeze
       COMPOUND_MODIFIERS = %w[data_residency].freeze
+      KNOWN_MODIFIERS = %w[batch flex priority scale fast on_demand data_residency].freeze
+      MAX_PERMUTED_MODIFIERS = 6
 
-      attr_reader :modifiers
+      def self.normalize(value)
+        return nil if value.nil?
 
-      def self.parse(value)
-        return value if value.is_a?(self)
-        return new([]) if value.nil?
+        mode = normalize_string(value.to_s)
+        return nil unless mode
+        return nil if STANDARD_MODE_VALUES.include?(mode)
 
-        new(tokenize(value.to_s))
+        warn_unknown_tokens(mode)
+        mode
+      end
+
+      def self.merge(provider_mode, request_mode)
+        return normalize(request_mode) if provider_mode.to_s.strip.empty?
+
+        provider_tokens = tokenize(provider_mode) - STANDARD_MODE_VALUES
+        request_host_tokens = tokenize(request_mode || "") & COMPOUND_MODIFIERS
+        combined = provider_tokens | request_host_tokens
+        return nil if combined.empty?
+
+        normalize(combined.join("_"))
+      end
+
+      def self.compose(tokens)
+        tokens = Array(tokens).compact.uniq
+        tokens.empty? ? nil : tokens.join("_")
       end
 
       def self.tokenize(value)
@@ -24,53 +45,50 @@ module LlmCostTracker
             remaining == token || remaining.start_with?("#{token}_")
           end
           if compound
-            tokens << compound.to_sym
+            tokens << compound
             remaining = remaining.delete_prefix(compound).delete_prefix("_")
           else
             first, _, rest = remaining.partition("_")
-            tokens << first.to_sym unless first.empty?
+            tokens << first unless first.empty?
             remaining = rest
           end
         end
         tokens
       end
 
-      def initialize(modifiers)
-        @modifiers = Array(modifiers).map(&:to_sym).uniq.sort
-        freeze
-      end
+      def self.permutations_for(value)
+        modifiers = tokenize(value).uniq.sort
+        return [""] if modifiers.empty?
+        return [modifiers.first] if modifiers.size == 1
+        return [modifiers.join("_")] if modifiers.size > MAX_PERMUTED_MODIFIERS
 
-      def empty?
-        modifiers.empty?
-      end
-
-      def include?(modifier)
-        modifiers.include?(modifier.to_sym)
+        modifiers.permutation.map { |permutation| permutation.join("_") }.uniq
       end
 
-      def canonical
-        modifiers.join("_")
-      end
-      alias to_s canonical
+      def self.normalize_string(value)
+        normalized = value.strip
+        return nil if normalized.empty?
 
-      def to_sym
-        empty? ? nil : canonical.to_sym
+        normalized.downcase.tr("-", "_")
       end
+      private_class_method :normalize_string
 
-      def permutations
-        return [canonical] if modifiers.size <= 1
+      def self.warn_unknown_tokens(mode)
+        unknown = tokenize(mode) - KNOWN_MODIFIERS - STANDARD_MODE_VALUES
+        return if unknown.empty?
 
-        modifiers.permutation.map { |permutation| permutation.join("_") }.uniq
-      end
-
-      def ==(other)
-        other.is_a?(self.class) && modifiers == other.modifiers
-      end
-      alias eql? ==
+        @warned_tokens ||= Set.new
+        fresh = unknown.uniq.reject { |token| @warned_tokens.include?(token) }
+        return if fresh.empty?
 
-      def hash
-        modifiers.hash
+        @warned_tokens.merge(fresh)
+        Logging.warn(
+          "Unrecognized pricing_mode token(s) #{fresh.inspect} in #{mode.inspect}; " \
+          "the call will land with cost_status: unknown. " \
+          "Known pricing_mode tokens: #{KNOWN_MODIFIERS.inspect}"
+        )
       end
+      private_class_method :warn_unknown_tokens
     end
   end
 end

data/lib/llm_cost_tracker/pricing/price_key.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../usage/catalog"
+require_relative "mode"
+
+module LlmCostTracker
+  module Pricing
+    module PriceKey
+      ABOVE_CONTEXT_PREFIX = "above_context_"
+
+      class << self
+        def build(dimension_key, mode: nil, above_context: false)
+          key = mode ? "#{mode}_#{dimension_key}" : dimension_key.to_s
+          above_context ? "#{ABOVE_CONTEXT_PREFIX}#{key}" : key
+        end
+
+        def price_key_for(key)
+          key = key.to_s
+          dimension_key = strip_mode_prefix(key.delete_prefix(ABOVE_CONTEXT_PREFIX))
+          dimension = Usage::Catalog[dimension_key]
+          return nil unless dimension
+          return key if key == dimension_key
+
+          dimension.token_key ? key : nil
+        end
+
+        def parse_dimension_key(key)
+          name = key.to_s
+          exact = Usage::Catalog.all.find { |dimension| dimension.key == name }
+          return [exact, nil] if exact
+
+          Usage::Catalog.all.sort_by { |dimension| -dimension.key.length }.each do |dimension|
+            suffix = "_#{dimension.key}"
+            next unless name.end_with?(suffix)
+
+            tier = name.delete_suffix(suffix)
+            return [dimension, tier] unless tier.empty?
+          end
+          nil
+        end
+
+        private
+
+        def strip_mode_prefix(key)
+          loop do
+            modifier = Mode::KNOWN_MODIFIERS.find { |m| key.start_with?("#{m}_") }
+            break unless modifier
+
+            key = key.delete_prefix("#{modifier}_")
+          end
+          key
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/rate.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Pricing
+    RATE_BASIS_QUANTITIES = {
+      "per_million_tokens" => 1_000_000,
+      "per_million_characters" => 1_000_000,
+      "per_request" => 1,
+      "per_1k_requests" => 1_000,
+      "per_session" => 1,
+      "per_hour" => 1,
+      "per_minute" => 1,
+      "per_image" => 1
+    }.freeze
+
+    Rate = Data.define(:amount, :quantity, :currency, :source, :source_key, :source_version)
+  end
+end

data/lib/llm_cost_tracker/pricing/registry.rb

@@ -1,162 +1,211 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/object/blank"
+require "bigdecimal/util"
 require "yaml"
 
-require_relative "../billing/components"
+require_relative "../usage/catalog"
+require_relative "../pricing/rate"
 require_relative "../logging"
+require_relative "mode"
+require_relative "price_key"
+require_relative "source"
 
 module LlmCostTracker
   module Pricing
     module Registry
       DEFAULT_PRICES_PATH = File.expand_path("../prices.json", __dir__)
-      EMPTY_PRICES = {}.freeze
-      CONTEXT_THRESHOLD_KEY = :_context_price_threshold_tokens
-      PRICE_KEYS = Billing::Components::TOKEN_PRICED.map { |component| component.key.name }.freeze
-      METADATA_KEYS = [
-        "_source", "_source_version", "_fetched_at", "_updated", "_notes", "_validator_override",
-        CONTEXT_THRESHOLD_KEY.name
-      ].freeze
-      MUTEX = Mutex.new
+      CONTEXT_THRESHOLD_KEY = "_context_price_threshold_tokens"
+      PRICE_KEYS = Usage::Catalog.token_priced.map(&:key).freeze
+      METADATA_KEYS = ["_source", CONTEXT_THRESHOLD_KEY].freeze
 
       class << self
         def reset!
-          MUTEX.synchronize do
-            @builtin_prices = nil
-            @metadata = nil
-            @raw_registry = nil
-            @file_prices_cache = nil
-          end
+          @builtin_prices = nil
+          @metadata = nil
+          @raw_registry = nil
+          @raw_file_registries = nil
+          @file_prices = nil
+          @builtin_rates = nil
+          @file_rates = nil
+          @sources = nil
+          @sorted_price_keys_cache = nil
+          @prices_file_mtime_iso = nil
         end
 
         def builtin_prices
-          cached = @builtin_prices
-          return cached if cached
-
-          MUTEX.synchronize do
-            @builtin_prices ||= begin
-              registry = @raw_registry ||= load_raw_registry
-              normalize_price_table(registry.fetch("models", {})).freeze
-            end
-          end
+          @builtin_prices ||= normalize_price_entries(
+            raw_registry.fetch("models", {}), context: "bundled prices"
+          ).freeze
         end
 
         def metadata
-          cached = @metadata
-          return cached if cached
-
-          MUTEX.synchronize do
-            @metadata ||= begin
-              registry = @raw_registry ||= load_raw_registry
-              registry.fetch("metadata", {}).freeze
-            end
-          end
+          @metadata ||= raw_registry.fetch("metadata", {}).freeze
         end
 
         def file_metadata(path)
           return {} unless path
 
-          registry = YAML.safe_load_file(path, aliases: false) || {}
+          meta = raw_file_registry(path).fetch("metadata", {})
+          return meta if meta.is_a?(Hash)
 
-          metadata = registry.fetch("metadata", {})
-          raise ArgumentError, "prices_file metadata must be a hash" unless metadata.is_a?(Hash)
+          raise Error, "Unable to load prices_file #{path.inspect}: prices_file metadata must be a hash"
+        end
 
-          metadata
-        rescue Errno::ENOENT, Psych::Exception, ArgumentError, TypeError => e
-          raise Error, "Unable to load prices_file #{path.inspect}: #{e.message}"
+        def file_prices(path)
+          return {} unless path
+
+          prices, @file_prices = memoize_in(@file_prices, path) { load_file_prices(path) }
+          prices
+        end
+
+        def normalize_price_entries(table, context:)
+          table = {} if table.nil?
+          raise ArgumentError, "#{context} must be a hash of models" unless table.is_a?(Hash)
+
+          table.each_with_object({}) do |(model, price), normalized|
+            price = validate_price_entry(price, model: model, context: context)
+            normalized[model.to_s] = normalize_price_entry(model, price, context)
+          end
         end
 
-        def normalize_price_table(table)
-          normalize_price_entries(table, context: "price table")
+        def raw_registry
+          @raw_registry ||= YAML.safe_load_file(DEFAULT_PRICES_PATH, aliases: false).freeze
         end
 
-        def file_prices(path)
-          return EMPTY_PRICES unless path
+        def raw_file_registry(path)
+          registry, @raw_file_registries = memoize_in(@raw_file_registries, path) { load_raw_file_registry(path) }
+          registry
+        end
+
+        def builtin_rates
+          @builtin_rates ||= rates_from_registry(raw_registry, context: DEFAULT_PRICES_PATH).freeze
+        end
+
+        def file_rates(path)
+          return {} unless path
 
-          cache_key = [path, File.mtime(path)]
-          cached = @file_prices_cache
-          return cached[:value] if cached && cached[:key] == cache_key
+          rates, @file_rates = memoize_in(@file_rates, path) { load_file_rates(path) }
+          rates
+        end
 
-          MUTEX.synchronize do
-            cached = @file_prices_cache
-            return cached[:value] if cached && cached[:key] == cache_key
+        def rates_from_registry(registry, context:)
+          data = registry.fetch("service_charges", {})
+          raise ArgumentError, "#{context} service_charges must be a hash" unless data.is_a?(Hash)
 
-            registry = YAML.safe_load_file(path, aliases: false) || {}
-            value = normalize_price_entries(registry.fetch("models", registry), context: path).freeze
-            @file_prices_cache = { key: cache_key, value: value }.freeze
-            value
+          currency = upcased_currency(registry.dig("metadata", "currency"))
+          data.each_with_object({}) do |(provider, entries), rates|
+            section_context = "#{context} service_charges.#{provider}"
+            rates[provider] = rates_from_section(entries, currency: currency, context: section_context)
           end
-        rescue Errno::ENOENT, Psych::Exception, ArgumentError, TypeError => e
-          raise Error, "Unable to load prices_file #{path.inspect}: #{e.message}"
         end
 
-        private
+        def prices_file_mtime_iso
+          path = LlmCostTracker.configuration.prices_file
+          return nil unless path && File.exist?(path)
 
-        def load_raw_registry
-          YAML.safe_load_file(DEFAULT_PRICES_PATH, aliases: false).freeze
+          @prices_file_mtime_iso ||= File.mtime(path).utc.iso8601
         end
 
-        def normalize_price_entry(price)
-          price.each_with_object({}) do |(key, value), normalized|
-            key = registry_key_for(key)
-            if key == CONTEXT_THRESHOLD_KEY
-              normalized[key] = Integer(value)
-            elsif key
-              normalized[key] = non_negative_float(key, value)
-            end
+        def sources
+          @sources ||= begin
+            config = LlmCostTracker.configuration
+            [
+              Source.new(
+                name: "pricing_overrides",
+                prices: config.pricing_overrides,
+                rates: {},
+                currency: upcased_currency(nil),
+                version: "configuration"
+              ),
+              Source.new(
+                name: "prices_file",
+                prices: file_prices(config.prices_file),
+                rates: file_rates(config.prices_file),
+                currency: upcased_currency(file_metadata(config.prices_file)["currency"]),
+                version: prices_file_mtime_iso
+              ),
+              Source.new(
+                name: "bundled",
+                prices: builtin_prices,
+                rates: builtin_rates,
+                currency: upcased_currency(metadata["currency"]),
+                version: LlmCostTracker::VERSION
+              )
+            ].freeze
           end
         end
 
-        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?
+        def sorted_price_keys(table)
+          keys, @sorted_price_keys_cache =
+            memoize_in(@sorted_price_keys_cache, table, identity: true) { table.keys.sort_by { |key| -key.length } }
+          keys
+        end
+
+        private
 
-          rate
+        def memoize_in(cache, key, identity: false)
+          existing = cache && cache[key]
+          return [existing, cache] if existing
+
+          value = yield
+          next_cache = cache&.dup || (identity ? {}.compare_by_identity : {})
+          next_cache[key] = value
+          [value, next_cache.freeze]
         end
 
-        def normalize_price_entries(table, context:)
-          table = {} if table.nil?
-          raise ArgumentError, "#{context} must be a hash of models" unless table.is_a?(Hash)
+        def loading(path)
+          yield
+        rescue Errno::ENOENT, Psych::Exception, ArgumentError, TypeError => e
+          raise Error, "Unable to load prices_file #{path.inspect}: #{e.message}"
+        end
 
-          table.each_with_object({}) do |(model, price), normalized|
-            price = validate_price_entry(price, model: model, context: context)
-            warn_unknown_keys(model, price, context)
-            normalized[model.to_s] = normalize_price_entry(price)
+        def load_raw_file_registry(path)
+          loading(path) { (YAML.safe_load_file(path, aliases: false) || {}).freeze }
+        end
+
+        def load_file_prices(path)
+          loading(path) do
+            doc = raw_file_registry(path)
+            normalize_price_entries(doc.fetch("models", doc), context: path).freeze
           end
         end
 
-        def warn_unknown_keys(model, price, path)
-          unknown_keys = price.keys.reject do |key|
-            registry_key_for(key) || METADATA_KEYS.include?(key)
+        def normalize_price_entry(model, price, context)
+          unknown = []
+          normalized = price.each_with_object({}) do |(key, value), acc|
+            registry_key = registry_key_for(key)
+            if registry_key == CONTEXT_THRESHOLD_KEY
+              acc[registry_key] = Integer(value)
+            elsif registry_key
+              acc[registry_key] = non_negative_decimal(value, label: "price for #{registry_key.inspect}")
+            elsif !METADATA_KEYS.include?(key)
+              unknown << key
+            end
           end
-          return if unknown_keys.empty?
+          warn_unknown_keys(model, unknown, context) unless unknown.empty?
+          normalized
+        end
+
+        def non_negative_decimal(value, label:)
+          decimal = BigDecimal(value.to_s)
+          raise ArgumentError, "#{label} must be finite (got #{value})" unless decimal.finite?
+          raise ArgumentError, "#{label} must be non-negative (got #{value})" if decimal.negative?
 
+          decimal
+        end
+
+        def warn_unknown_keys(model, unknown_keys, path)
           Logging.warn(
             "Unknown price keys #{unknown_keys.inspect} for #{model.inspect} in #{path}; " \
             "ignored. Known keys: #{(PRICE_KEYS + METADATA_KEYS).inspect}; mode-specific keys use mode_input"
           )
         end
 
-        def price_key_for(key)
-          name = key.is_a?(Symbol) ? key.name : key
-          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)
-
-            prefix = name.delete_suffix(suffix)
-            return :"#{prefix}_#{candidate.key.name}" unless prefix.empty?
-          end
-
-          nil
-        end
-
         def registry_key_for(key)
-          return CONTEXT_THRESHOLD_KEY if key == CONTEXT_THRESHOLD_KEY || key == CONTEXT_THRESHOLD_KEY.name
+          return CONTEXT_THRESHOLD_KEY if key.to_s == CONTEXT_THRESHOLD_KEY
 
-          price_key_for(key)
+          PriceKey.price_key_for(key)
         end
 
         def validate_price_entry(price, model:, context:)
@@ -165,6 +214,46 @@ module LlmCostTracker
 
           raise ArgumentError, "price entry for #{model.inspect} in #{context} must be a hash"
         end
+
+        def load_file_rates(path)
+          loading(path) { rates_from_registry(raw_file_registry(path), context: path).freeze }
+        end
+
+        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|
+            key = key.to_s
+            dimension, tier = dimension_and_tier_for(key, context: context)
+            amount = non_negative_decimal(amount, label: "service charge price amount for #{key.inspect} in #{context}")
+
+            rate = {
+              amount: amount,
+              quantity: rate_quantity(dimension),
+              currency: currency,
+              source_key: key
+            }
+            dimension_rates = rates[dimension.key] ||= { tiers: {} }
+            (tier ? dimension_rates[:tiers] : dimension_rates)[tier || :default] = rate
+          end
+        end
+
+        def dimension_and_tier_for(key, context:)
+          dimension, tier = PriceKey.parse_dimension_key(key)
+          unless dimension && dimension.token_key.nil?
+            raise ArgumentError, "service charge price key #{key.inspect} in #{context} uses unknown billing dimension"
+          end
+
+          [dimension, tier]
+        end
+
+        def rate_quantity(dimension)
+          Pricing::RATE_BASIS_QUANTITIES.fetch(dimension.rate_basis).to_d
+        end
+
+        def upcased_currency(value)
+          (value || LlmCostTracker::DEFAULT_CURRENCY).upcase
+        end
       end
     end
   end

data/lib/llm_cost_tracker/pricing/service_rates.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+
+require_relative "../usage/catalog"
+require_relative "registry"
+require_relative "rate"
+require_relative "mode"
+
+module LlmCostTracker
+  module Pricing
+    module ServiceRates
+      class << self
+        def charge_rate(provider:, dimension:, pricing_mode:)
+          pricing_mode = Mode.normalize(pricing_mode)
+          provider_name = provider.to_s.presence
+          return nil unless provider_name
+
+          dimension_key = charge_dimension_key(dimension)
+          Registry.sources.each do |source|
+            provider_rates = source.rates.fetch(provider_name, {})
+            rate = rate_for(provider_rates, dimension_key: dimension_key, pricing_mode: pricing_mode)
+            next unless rate
+
+            return Pricing::Rate.new(
+              amount: rate.fetch(:amount),
+              quantity: rate.fetch(:quantity),
+              currency: rate.fetch(:currency),
+              source: source.name,
+              source_key: "service_charges.#{provider_name}.#{rate.fetch(:source_key)}",
+              source_version: source.version
+            )
+          end
+          nil
+        end
+
+        private
+
+        def rate_for(provider_table, dimension_key:, pricing_mode:)
+          dimension_rates = provider_table.fetch(dimension_key, {})
+          tier_rates = dimension_rates.fetch(:tiers, {})
+          if pricing_mode
+            rate = tier_rates[pricing_mode]
+            return rate if rate
+
+            tier_rates.each do |candidate, candidate_rate|
+              return candidate_rate if tier_includes?(pricing_mode, candidate)
+            end
+          end
+          dimension_rates[:default]
+        end
+
+        def tier_includes?(tier_name, candidate_name)
+          tier_name == candidate_name ||
+            tier_name.start_with?("#{candidate_name}_") ||
+            tier_name.end_with?("_#{candidate_name}") ||
+            tier_name.include?("_#{candidate_name}_")
+        end
+
+        def charge_dimension_key(dimension)
+          billing_dimension = Usage::Catalog[dimension]
+          return billing_dimension.key if billing_dimension && billing_dimension.token_key.nil?
+
+          raise Error, "Unknown billing dimension: #{dimension.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/source.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Pricing
+    Source = Data.define(:name, :prices, :rates, :currency, :version)
+  end
+end

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

@@ -13,7 +13,7 @@ module LlmCostTracker
   module Pricing
     module Sync
       class Fetcher
-        Response = Data.define(:body, :etag, :last_modified, :not_modified, :fetched_at) do
+        Response = Data.define(:body, :etag, :last_modified, :not_modified) do
           def source_version
             etag || last_modified || Digest::SHA256.hexdigest(body.to_s)
           end
@@ -106,8 +106,7 @@ module LlmCostTracker
             body: body,
             etag: response["etag"],
             last_modified: response["last-modified"],
-            not_modified: not_modified,
-            fetched_at: Time.now.utc.iso8601
+            not_modified: not_modified
           )
         end
       end