llm_cost_tracker 0.14.2 → 0.15.0

data/lib/llm_cost_tracker/pricing/calculation.rb

@@ -5,14 +5,17 @@ require "bigdecimal/util"
 require_relative "../usage/catalog"
 require_relative "../charges/line_item"
 require_relative "rate"
+require_relative "calculation/iterations"
+require_relative "calculation/quantities"
+require_relative "calculation/snapshot"
+require_relative "calculation/totals"
 
 module LlmCostTracker
   module Pricing
     class Calculation
       RATE_DENOMINATOR_TOKENS = Pricing::RATE_BASIS_QUANTITIES.fetch("per_million_tokens")
-      SNAPSHOT_SCHEMA_VERSION = 1
       CACHE_INPUT_KEYS = %w[cache_read_input cache_write_input].freeze
-      private_constant :RATE_DENOMINATOR_TOKENS, :SNAPSHOT_SCHEMA_VERSION, :CACHE_INPUT_KEYS
+      private_constant :RATE_DENOMINATOR_TOKENS, :CACHE_INPUT_KEYS
 
       def self.for(provider:, model:, tokens:, pricing_mode:, line_items: [], usage_source: nil, at: Time.now)
         new(provider: provider,
@@ -29,12 +32,18 @@ module LlmCostTracker
         @model = model
         @token_usage = token_usage
         @line_items = line_items
-        @mode = mode
+        @requested_mode = mode
         @usage_source = usage_source
         @at = at
       end
 
-      attr_reader :mode
+      def mode
+        return @mode if defined?(@mode)
+
+        tokens = Mode.tokenize(@requested_mode) - ["off_peak"]
+        tokens << "off_peak" if off_peak?
+        @mode = Mode.compose(tokens)
+      end
 
       def match
         return @match if defined?(@match)
@@ -49,7 +58,7 @@ module LlmCostTracker
           usage: @token_usage,
           quantities: quantities,
           prices: match.prices,
-          pricing_mode: @mode,
+          pricing_mode: mode,
           cache_at_input_rate: cache_keys_at_input_rate
         )
       end
@@ -57,8 +66,8 @@ module LlmCostTracker
       def token_cost
         return @token_cost if defined?(@token_cost)
 
-        known = priceable? && @usage_source != Usage::Source::UNKNOWN && !only_unpriced_lines?
-        @token_cost = known ? build_token_cost : nil
+        known = priceable? && @usage_source != Usage::Source::UNKNOWN && !only_unpriced_lines? && !unsplit_total?
+        @token_cost = known ? Totals.token_cost(priced_token_line_items, match.source.currency) : nil
       end
 
       def priced_line_items
@@ -72,34 +81,39 @@ module LlmCostTracker
 
         @snapshot =
           if priceable?
-            build_snapshot
-          elsif kept_service_lines.any?
-            build_service_snapshot
+            Snapshot.for_match(match, counted_service_lines, priced_token_line_items)
+          elsif counted_service_lines.any?
+            Snapshot.for_service_charges(counted_service_lines, cost.currency)
           end
       end
 
       def cost
         return @cost if defined?(@cost)
 
-        @cost = combine_service_lines
+        @cost = Totals.with_service_lines(token_cost, counted_service_lines)
       end
 
       def cost_status
         @cost_status ||= begin
-          status = billed_status || Charges::CostStatus.call(
-            token_usage: @token_usage,
-            usage_source: @usage_source,
-            token_cost: token_cost,
-            token_pricing_partial: token_pricing_partial?,
-            service_line_items: priced_line_items.reject(&:token?),
-            total_cost: cost&.total
-          )
-          @partial_iteration && status != Charges::CostStatus::UNKNOWN ? Charges::CostStatus::PARTIAL : status
+          status = billed_status || priced_status
+          @iterations&.partial? && status != Charges::CostStatus::UNKNOWN ? Charges::CostStatus::PARTIAL : status
         end
       end
 
+      def unsplit_total?
+        return false unless match && @token_usage.total_tokens.to_i.positive?
+
+        @token_usage.priced_quantities.values.none?(&:positive?) &&
+          match.prices.values_at("input", "output").any? { |rate| rate.to_f.positive? }
+      end
+
       private
 
+      def off_peak?
+        windows = match&.prices&.[](Registry::OFF_PEAK_WINDOWS_KEY)
+        windows && OffPeak.cover?(windows, @at)
+      end
+
       def cache_keys_at_input_rate
         return [] if match.source.name == "pricing_overrides" || !match.key.start_with?("openai/")
 
@@ -113,14 +127,7 @@ module LlmCostTracker
       end
 
       def quantities
-        @quantities ||= @line_items.each_with_object(@token_usage.priced_quantities) do |line_item, result|
-          dimension = line_item.dimension
-          next unless dimension&.parent
-
-          quantity = [line_item.quantity.to_i, result.fetch(dimension.parent)].min
-          result[dimension.parent] -= quantity
-          result[dimension.key] = result.fetch(dimension.key, 0) + quantity
-        end
+        @quantities ||= Quantities.new(@token_usage, @line_items, match&.prices || {}).to_h
       end
 
       def unpriced_line_items
@@ -135,188 +142,90 @@ module LlmCostTracker
         @line_items.find { |line_item| line_item.kind == "billed_request" }
       end
 
-      def billed_status
-        return unless billed_line
-
-        unpriced_attempt = priced_line_items.any? { |item| item.kind == "model_iteration" && item.unpriced? }
-        return Charges::CostStatus::PARTIAL if unpriced_attempt
-
-        billed_line.priced? && cost.total.positive? ? Charges::CostStatus::COMPLETE : billed_line.cost_status
-      end
-
-      def only_unpriced_lines?
-        billable = priced_line_items.select(&:billable?)
-        billable.any? && billable.none?(&:priced?)
-      end
-
       def all_billable_unpriced?
         billable = quantities.select { |_key, quantity| quantity.positive? }.keys
         billable.any? && billable.none? { |key| effective[key] }
       end
 
-      def priced_token_line_items
-        @priced_token_line_items ||= priced_line_items.select(&:token?)
-      end
-
-      def build_token_cost
-        by_component = priced_token_line_items.group_by { |item| item.dimension.parent || item.dimension.key }
-        components = Usage::Catalog.token_priced.each_with_object({}) do |dimension, result|
-          line_items = by_component.fetch(dimension.key, [])
-          next if line_items.any?(&:unpriced?)
-
-          result[dimension.cost_key] = line_items.sum(BigDecimal("0")) { |line_item| line_item.cost_value.round(8) }
-        end
-        Charges::Cost.new(
-          components: components.freeze,
-          total: priced_token_line_items.sum(BigDecimal("0")) { |line_item| line_item.cost_value.round(8) },
-          currency: match.source.currency
-        )
-      end
-
-      def build_snapshot
-        {
-          "schema_version" => SNAPSHOT_SCHEMA_VERSION,
-          "source" => match.source.name,
-          "source_key" => match.key,
-          "source_version" => match.source.version,
-          "matched_by" => match.matched_by.to_s,
-          "currency" => match.source.currency,
-          "rates" => charge_rates(kept_service_lines).merge(charge_rates(priced_token_line_items))
-        }
-      end
-
-      def build_service_snapshot
-        primary = kept_service_lines.first
-        {
-          "schema_version" => SNAPSHOT_SCHEMA_VERSION,
-          "source" => primary.price_source,
-          "source_version" => primary.price_source_version,
-          "matched_by" => "service_charges",
-          "currency" => cost.currency,
-          "rates" => charge_rates(kept_service_lines)
-        }
-      end
-
-      def charge_rates(line_items)
-        line_items.each_with_object({}) do |line_item, rates|
-          next if line_item.price_key.nil? || line_item.rate_amount.nil?
-
-          rates[line_item.price_key] ||= rate_entry(line_item.rate_amount, line_item.rate_quantity)
-        end
-      end
-
-      def rate_entry(amount, quantity)
-        { "amount" => amount.to_d.to_s("F"), "quantity" => Integer(quantity) }
+      def only_unpriced_lines?
+        billable = priced_line_items.select(&:billable?)
+        billable.any? && billable.none?(&:priced?)
       end
 
       def price_token(line_item)
         price = priceable? && effective[line_item.dimension.key]
-        price ? line_item.with_rate(token_rate(price)) : line_item
-      end
+        return line_item unless price
 
-      def token_rate(price)
-        Pricing::Rate.new(
-          amount: price.amount.to_d,
-          quantity: RATE_DENOMINATOR_TOKENS.to_d,
-          currency: match.source.currency,
-          source: match.source.name,
-          source_key: price.key,
-          source_version: match.source.version
-        )
+        line_item.with_rate(match.rate(price.amount.to_d, RATE_DENOMINATOR_TOKENS.to_d, price.key))
       end
 
       def price_service(line_item)
-        return price_iteration(line_item) if line_item.kind == "model_iteration"
+        return iterations.price(line_item) if line_item.kind == "model_iteration"
         return line_item if line_item.priced? || !line_item.billable? || billed_line
 
         rate = model_rate(line_item) ||
-               ServiceRates.charge_rate(provider: @provider, dimension: line_item.kind, pricing_mode: @mode)
+               ServiceRates.charge_rate(provider: @provider, dimension: line_item.kind, pricing_mode: mode)
         return line_item unless rate
 
-        line_item.with_rate(rate)
+        billed_minimum(line_item).with_rate(rate)
       end
 
-      def price_iteration(line_item)
-        details = line_item.details.to_h.transform_keys(&:to_sym)
-        model = details[:model].to_s
-        calculation = Calculation.for(
-          provider: @provider,
-          model: model,
-          tokens: details.slice(*Usage::TokenUsage.members),
-          pricing_mode: iteration_mode(model),
-          at: @at
-        )
-        cost = calculation.token_cost
-        return line_item unless cost
+      def model_rate(line_item)
+        return unless priceable?
 
-        @partial_iteration ||= calculation.cost_status == Charges::CostStatus::PARTIAL
-        status = cost.total.zero? ? Charges::CostStatus::FREE : Charges::CostStatus::COMPLETE
-        line_item.with(rate_amount: cost.total, cost: cost.total, currency: cost.currency, cost_status: status)
+        key = model_price_key(line_item.kind)
+        return unless key
+
+        quantity = Pricing::RATE_BASIS_QUANTITIES.fetch(Usage::Catalog[line_item.kind].rate_basis)
+        match.rate(match.prices[key].to_d, quantity.to_d, "#{match.key}.#{key}")
       end
 
-      def iteration_mode(model)
-        return @mode if Matcher.modifier_priced?(provider: @provider, model: model, modifier: "fast")
+      def model_price_key(kind)
+        modes = mode ? Mode.permutations_for(mode) : []
+        [*modes.map { |permutation| PriceKey.build(kind, mode: permutation) }, kind]
+          .find { |key| match.prices[key].is_a?(Numeric) }
+      end
 
-        Mode.compose(Mode.tokenize(@mode) - ["fast"])
+      def billed_minimum(line_item)
+        seconds = match&.prices&.[](Registry::MINIMUM_BILLED_SECONDS_KEY) if line_item.kind == "transcription_minute"
+        seconds ? line_item.with(quantity: [line_item.quantity, BigDecimal(seconds) / 60].max) : line_item
       end
 
-      def model_rate(line_item)
-        return nil unless priceable?
-
-        modes = @mode ? Mode.permutations_for(@mode) : []
-        key = [*modes.map { |mode| PriceKey.build(line_item.kind, mode: mode) }, line_item.kind]
-              .find { |candidate| match.prices[candidate].is_a?(Numeric) }
-        return nil unless key
-
-        dimension = Usage::Catalog[line_item.kind]
-        Pricing::Rate.new(
-          amount: match.prices[key].to_d,
-          quantity: Pricing::RATE_BASIS_QUANTITIES.fetch(dimension.rate_basis).to_d,
-          currency: match.source.currency,
-          source: match.source.name,
-          source_key: "#{match.key}.#{key}",
-          source_version: match.source.version
-        )
+      def iterations
+        @iterations ||= Iterations.new(provider: @provider, requested_mode: @requested_mode, at: @at)
       end
 
-      def kept_service_lines
-        return @kept_service_lines if defined?(@kept_service_lines)
+      def priced_token_line_items
+        @priced_token_line_items ||= priced_line_items.select(&:token?)
+      end
 
-        priced_services = priced_line_items.reject(&:token?).select(&:priced?)
-        return @kept_service_lines = [] if priced_services.empty?
+      def priced_service_line_items
+        @priced_service_line_items ||= priced_line_items.reject(&:token?)
+      end
 
-        base_currency = token_cost&.currency || priced_services.first.currency || LlmCostTracker::DEFAULT_CURRENCY
-        matching, mismatched = priced_services.partition { |line| line.currency.to_s == base_currency.to_s }
-        warn_currency_mismatch(mismatched, base_currency) if mismatched.any?
-        @kept_service_lines = matching
+      def counted_service_lines
+        @counted_service_lines ||= Totals.in_call_currency(priced_service_line_items.select(&:priced?), token_cost)
       end
 
-      def combine_service_lines
-        cost = token_cost
-        return cost if kept_service_lines.empty?
+      def billed_status
+        return unless billed_line
+
+        unpriced_attempt = priced_line_items.any? { |item| item.kind == "model_iteration" && item.unpriced? }
+        return Charges::CostStatus::PARTIAL if unpriced_attempt
 
-        service_total = kept_service_lines.sum(BigDecimal("0")) { |line| line.cost_value.round(8) }
-        Charges::Cost.new(
-          components: cost ? cost.components : {}.freeze,
-          total: (cost&.total || BigDecimal("0")) + service_total,
-          currency: (cost&.currency || kept_service_lines.first.currency).to_s
-        )
+        billed_line.priced? && cost.total.positive? ? Charges::CostStatus::COMPLETE : billed_line.cost_status
       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."
+      def priced_status
+        Charges::CostStatus.call(
+          token_usage: @token_usage,
+          usage_source: @usage_source,
+          token_cost: token_cost,
+          token_pricing_partial: !token_cost.nil? && priced_token_line_items.any?(&:unpriced?),
+          service_line_items: priced_service_line_items,
+          total_cost: cost&.total
         )
       end
-
-      def token_pricing_partial?
-        return false unless token_cost
-
-        priced_token_line_items.any?(&:unpriced?)
-      end
     end
   end
 end

data/lib/llm_cost_tracker/pricing/matcher.rb

@@ -8,11 +8,23 @@ require_relative "registry"
 module LlmCostTracker
   module Pricing
     module Matcher
-      Match = Data.define(:source, :key, :prices, :matched_by)
+      Match = Data.define(:source, :key, :prices, :matched_by) do
+        def rate(amount, quantity, source_key)
+          Rate.new(
+            amount: amount,
+            quantity: quantity,
+            currency: source.currency,
+            source: source.name,
+            source_key: source_key,
+            source_version: source.version
+          )
+        end
+      end
 
       CACHE_LIMIT = 2048
       BEDROCK_ANTHROPIC_ID = /\A(?:[a-z]+\.)?anthropic\.(claude-.+?)(?:-v\d+(?::\d+)?)?\z/
-      private_constant :CACHE_LIMIT, :BEDROCK_ANTHROPIC_ID
+      VERTEX_VERSION = /@(?=\d{8}\z)/
+      private_constant :CACHE_LIMIT, :BEDROCK_ANTHROPIC_ID, :VERTEX_VERSION
 
       class << self
         def lookup(provider:, model:, at: Time.now)
@@ -21,14 +33,11 @@ module LlmCostTracker
           return nil if model_name.empty?
 
           sources = Registry.sources
-          reset_cache(sources) unless @cache_sources.equal?(sources)
           date = at.getutc.to_date.iso8601
-          key = [provider_name, model_name, date].freeze
-          return @cache[key] if @cache.key?(key)
-
-          @cache.clear if @cache.size >= CACHE_LIMIT
-          @cache[key] = lookup_match(sources, provider_name, model_name)&.then do |match|
-            match.with(prices: prices_on(match.prices, date))
+          cached(sources, [provider_name, model_name, date].freeze) do
+            lookup_match(sources, provider_name, model_name)&.then do |match|
+              match.with(prices: prices_on(match.prices, date))
+            end
           end
         end
 
@@ -44,15 +53,23 @@ module LlmCostTracker
           current.freeze
         end
 
-        def modifier_priced?(provider:, model:, modifier:)
-          prices = lookup(provider: provider, model: model)&.prices
-          return false unless prices
+        def modifier_priced?(provider:, model:, modifier:, owners: nil)
+          match = lookup(provider: provider, model: model)
+          return false unless match && (owners.nil? || match.key.start_with?(*owners))
 
-          prices.any? { |key, _| key.to_s.include?(modifier) }
+          match.prices.any? { |key, _| key.to_s.match?(/(?:\A|_)#{modifier}_/) }
         end
 
         private
 
+        def cached(sources, key)
+          reset_cache(sources) unless @cache_sources.equal?(sources)
+          return @cache[key] if @cache.key?(key)
+
+          @cache.clear if @cache.size >= CACHE_LIMIT
+          @cache[key] = yield
+        end
+
         def reset_cache(sources)
           @cache_sources = sources
           @cache = {}
@@ -95,7 +112,7 @@ module LlmCostTracker
         end
 
         def normalize_model_name(model)
-          name = model.to_s.split("/").last
+          name = model.to_s.split("/").last.sub(VERTEX_VERSION, "-")
           name.match(BEDROCK_ANTHROPIC_ID)&.[](1) || name
         end
 

data/lib/llm_cost_tracker/pricing/mode.rb

@@ -4,9 +4,13 @@ module LlmCostTracker
   module Pricing
     module Mode
       STANDARD_MODE_VALUES = %w[auto default standard standard_only unspecified].freeze
-      KNOWN_MODIFIERS = %w[batch flex priority scale fast on_demand data_residency].freeze
+      KNOWN_MODIFIERS = %w[
+        batch flex priority scale fast ultrafast on_demand data_residency off_peak reserved provisioned_throughput
+      ].freeze
       HOST_DERIVED_MODIFIERS = %w[data_residency].freeze
       MAX_PERMUTED_MODIFIERS = 6
+      TOKEN = /#{Regexp.union(KNOWN_MODIFIERS)}(?=_|\z)|[^_]+/
+      private_constant :TOKEN
 
       def self.normalize(value)
         mode = value.to_s.strip.downcase.tr("-", "_")
@@ -33,24 +37,7 @@ module LlmCostTracker
       end
 
       def self.tokenize(value)
-        remaining = value.to_s.downcase.tr("-", "_")
-        tokens = []
-        loop do
-          break if remaining.empty?
-
-          known = KNOWN_MODIFIERS.find do |modifier|
-            remaining == modifier || remaining.start_with?("#{modifier}_")
-          end
-          if known
-            tokens << known
-            remaining = remaining.delete_prefix(known).delete_prefix("_")
-          else
-            first, _, rest = remaining.partition("_")
-            tokens << first unless first.empty?
-            remaining = rest
-          end
-        end
-        tokens
+        value.to_s.downcase.tr("-", "_").scan(TOKEN)
       end
 
       def self.permutations_for(value)

data/lib/llm_cost_tracker/pricing/off_peak.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Pricing
+    module OffPeak
+      HOURS = /\A((?:[01]\d|2[0-3]):[0-5]\d)-((?:[01]\d|2[0-3]):[0-5]\d|24:00)\z/
+      KEYS = %w[hours_utc weekdays].freeze
+
+      class << self
+        def windows(value, label:)
+          windows = Array(value).map { |window| window.is_a?(Hash) ? window.transform_keys(&:to_s) : {} }
+          unless value.is_a?(Array) && list?(windows) { |window| window?(window) }
+            raise ArgumentError,
+                  "#{label} must be a list of windows like " \
+                  '{"weekdays" => [1, 2, 3, 4, 5], "hours_utc" => ["00:00-01:00", "10:00-24:00"]} ' \
+                  "(ISO weekdays, UTC hours, start inclusive, end exclusive), got #{value.inspect}"
+          end
+
+          windows.map(&:freeze).freeze
+        end
+
+        def cover?(windows, at)
+          time = at.getutc
+          weekday = time.wday.zero? ? 7 : time.wday
+          minute = (time.hour * 60) + time.min
+          windows.any? do |window|
+            window["weekdays"].include?(weekday) &&
+              window["hours_utc"].any? { |hours| minutes(hours).then { |from, to| minute >= from && minute < to } }
+          end
+        end
+
+        private
+
+        def window?(window)
+          weekdays, hours = window.values_at("weekdays", "hours_utc")
+          window.keys.sort == KEYS && list?(weekdays) { |day| day.is_a?(Integer) && day.between?(1, 7) } &&
+            list?(hours) { |range| minutes(range)&.then { |from, to| from < to } }
+        end
+
+        def list?(value, &)
+          value.is_a?(Array) && value.any? && value.all?(&)
+        end
+
+        def minutes(range)
+          range.to_s.match(HOURS)&.captures&.map { |clock| (clock[0, 2].to_i * 60) + clock[3, 2].to_i }
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/pricing/rate.rb

@@ -8,6 +8,7 @@ module LlmCostTracker
       "per_million_token_hours" => 1_000_000,
       "per_request" => 1,
       "per_1k_requests" => 1_000,
+      "per_1k_pages" => 1_000,
       "per_session" => 1,
       "per_hour" => 1,
       "per_minute" => 1

data/lib/llm_cost_tracker/pricing/registry/normalizer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "bigdecimal/util"
+
+require_relative "../../logging"
+require_relative "../off_peak"
+require_relative "../price_key"
+require_relative "../rate"
+
+module LlmCostTracker
+  module Pricing
+    module Registry
+      class Normalizer
+        def initialize(context)
+          @context = context
+        end
+
+        def prices(table)
+          table = {} if table.nil?
+          raise ArgumentError, "#{@context} must be a hash of models" unless table.is_a?(Hash)
+
+          table.each_with_object({}) { |(model, entry), prices| prices[model.to_s] = price_entry(model, entry) }
+        end
+
+        def rates(registry)
+          charges = registry.fetch("service_charges", {})
+          raise ArgumentError, "#{@context} service_charges must be a hash" unless charges.is_a?(Hash)
+
+          currency = (registry.dig("metadata", "currency") || LlmCostTracker::DEFAULT_CURRENCY).upcase
+          charges.to_h do |provider, entries|
+            [provider, provider_rates(entries, currency, "#{@context} service_charges.#{provider}")]
+          end
+        end
+
+        private
+
+        def price_entry(model, entry)
+          fields = hash_entry(model, entry).map { |key, value| [key, price_field(model, key, value)] }
+          unknown = fields.reject { |key, field| field || METADATA_KEYS.include?(key) }.map(&:first)
+          warn_unknown_keys(model, unknown) unless unknown.empty?
+          fields.filter_map(&:last).to_h
+        end
+
+        def hash_entry(model, entry)
+          return {} if entry.nil?
+          return entry if entry.is_a?(Hash)
+
+          raise ArgumentError, "price entry for #{model.inspect} in #{@context} must be a hash"
+        end
+
+        def price_field(model, key, value)
+          name = key.to_s
+          case name
+          when CONTEXT_THRESHOLD_KEY, MINIMUM_BILLED_SECONDS_KEY then [name, Integer(value)]
+          when OFF_PEAK_WINDOWS_KEY then [name, OffPeak.windows(value, label: "#{name} for #{model.inspect}")]
+          else
+            price_key = PriceKey.price_key_for(name)
+            [price_key, amount(value, "price for #{price_key.inspect}")] if price_key
+          end
+        end
+
+        def warn_unknown_keys(model, keys)
+          Logging.warn(
+            "Unknown price keys #{keys.inspect} for #{model.inspect} in #{@context}; " \
+            "ignored. Known keys: #{(PRICE_KEYS + METADATA_KEYS).inspect}; mode-specific keys use mode_input"
+          )
+        end
+
+        def provider_rates(entries, currency, context)
+          raise ArgumentError, "#{context} must be a hash" unless entries.is_a?(Hash)
+
+          entries.each_with_object({}) do |(key, value), rates|
+            dimension, tier = dimension_and_tier(key.to_s, context)
+            rate = service_rate(key.to_s, value, dimension, currency, context)
+            dimension_rates = rates[dimension.key] ||= { tiers: {} }
+            if tier
+              dimension_rates[:tiers][tier] = rate
+            else
+              dimension_rates[:default] = rate
+            end
+          end
+        end
+
+        def dimension_and_tier(key, context)
+          dimension, tier = PriceKey.parse_dimension_key(key)
+          return [dimension, tier] if dimension && dimension.token_key.nil?
+
+          raise ArgumentError, "service charge price key #{key.inspect} in #{context} uses unknown billing dimension"
+        end
+
+        def service_rate(key, value, dimension, currency, context)
+          {
+            amount: amount(value, "service charge price amount for #{key.inspect} in #{context}"),
+            quantity: Pricing::RATE_BASIS_QUANTITIES.fetch(dimension.rate_basis).to_d,
+            currency: currency,
+            source_key: key
+          }
+        end
+
+        def amount(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
+      end
+    end
+  end
+end