llm_cost_tracker 0.13.0 → 0.14.1

data/lib/llm_cost_tracker/capture/stream_tracker.rb

@@ -13,8 +13,7 @@ module LlmCostTracker
         @collector = collector
         @active = active
         @finish = finish || proc { |errored| collector.finish!(errored: errored) }
-        @finished_ref = [false]
-        @attempted_ref = [false]
+        @finished = false
         @capture_failed = false
         @mutex = Mutex.new
       end
@@ -45,7 +44,6 @@ module LlmCostTracker
           )
         end
 
-        register_orphan_finalizer
         @stream
       rescue StandardError => e
         Logging.warn("stream integration failed to install wrapper: #{e.class}: #{e.message}")
@@ -77,7 +75,7 @@ module LlmCostTracker
             yield event
           end
         end
-      rescue StandardError
+      rescue Exception # rubocop:disable Lint/RescueException -- mark Interrupt/shutdown too, so it is not masked
         errored = true
         raise
       ensure
@@ -107,10 +105,9 @@ module LlmCostTracker
 
       def finish!(errored:)
         should_finish = @mutex.synchronize do
-          @attempted_ref[0] = true
-          next false if @finished_ref[0]
+          next false if @finished
 
-          @finished_ref[0] = true
+          @finished = true
           true
         end
         return unless should_finish && @active.call
@@ -118,37 +115,10 @@ module LlmCostTracker
         begin
           @finish.call(errored)
         rescue StandardError
-          @mutex.synchronize { @finished_ref[0] = false }
+          @mutex.synchronize { @finished = false }
           raise
         end
       end
-
-      def register_orphan_finalizer
-        finished_ref = @finished_ref
-        attempted_ref = @attempted_ref
-        finish_proc = @finish
-        active_proc = @active
-        mutex = @mutex
-        finalizer = lambda do |_object_id|
-          should_finish = mutex.synchronize do
-            next false if finished_ref[0] || attempted_ref[0]
-
-            finished_ref[0] = true
-            attempted_ref[0] = true
-            true
-          end
-          next unless should_finish && active_proc.call
-
-          begin
-            Rails.application.executor.wrap { finish_proc.call(false) }
-          rescue StandardError
-            nil
-          end
-        end
-        ObjectSpace.define_finalizer(@stream, finalizer)
-      rescue TypeError, ArgumentError
-        nil
-      end
     end
   end
 end

data/lib/llm_cost_tracker/charges/cost_status.rb

@@ -16,7 +16,7 @@ module LlmCostTracker
         "#{total_cost} IS NULL OR #{cost_status} IN (#{statuses})"
       end
 
-      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def self.call(token_usage:,
                     usage_source:,
                     token_cost:,
@@ -43,9 +43,10 @@ module LlmCostTracker
         return UNKNOWN if unpriced && !priced
         return PARTIAL if unpriced
 
-        total_cost.nil? || total_cost.zero? ? FREE : COMPLETE
+        return UNKNOWN if total_cost.nil?
+
+        total_cost.zero? ? FREE : COMPLETE
       end
-      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     end
   end
 end

data/lib/llm_cost_tracker/configuration/budgets.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+require_relative "section"
+
+module LlmCostTracker
+  class Configuration
+    class Budgets < Section
+      EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
+      TOTALS_SOURCES = %i[ledger cache].freeze
+      PER_TAG_WINDOWS = %i[daily weekly monthly].freeze
+      PER_TAG_OPTIONS = %i[behavior on_exceeded].freeze
+
+      attributes :monthly, :daily, :per_call, :on_exceeded
+      enum_attribute :exceeded_behavior, allowed: EXCEEDED_BEHAVIORS, default: :notify
+      enum_attribute :totals_source, allowed: TOTALS_SOURCES, default: :ledger
+
+      attr_reader :per_tag
+
+      def initialize(owner)
+        super
+        @monthly = nil
+        @daily = nil
+        @per_call = nil
+        @on_exceeded = nil
+        @per_tag = {}
+        self.exceeded_behavior = :notify
+        self.totals_source = :ledger
+      end
+
+      def per_tag=(value)
+        ensure_mutable!
+        @per_tag = (value || {}).to_h.to_h { |key, entry| [validated_key(key), validated_entry(key, entry)] }
+      end
+
+      def finalize!
+        @per_tag = deep_freeze(@per_tag || {})
+      end
+
+      private
+
+      def validated_key(key)
+        LlmCostTracker::Tags::Key.validate!(key, error_class: Error)
+      end
+
+      def validated_entry(key, entry)
+        raise Error, "budgets.per_tag[#{key.inspect}] must be a hash" unless entry.is_a?(Hash)
+
+        normalized = entry.to_h.transform_keys(&:to_sym)
+        windows, options = normalized.partition { |name, _| !PER_TAG_OPTIONS.include?(name) }.map(&:to_h)
+        if windows.empty?
+          raise Error,
+                "budgets.per_tag[#{key.inspect}] needs at least one of: #{PER_TAG_WINDOWS.join(', ')}"
+        end
+
+        {
+          windows: windows.to_h do |window, limit|
+                     [validated_window(key, window), validated_limit(key, window, limit)]
+                   end,
+          behavior: validated_behavior(key, options[:behavior]),
+          on_exceeded: options[:on_exceeded]
+        }
+      end
+
+      def validated_behavior(key, behavior)
+        return nil if behavior.nil?
+        return behavior.to_sym if EXCEEDED_BEHAVIORS.include?(behavior.to_sym)
+
+        raise Error,
+              "Unknown budgets.per_tag[#{key.inspect}] behavior: #{behavior.inspect}. " \
+              "Use one of: #{EXCEEDED_BEHAVIORS.join(', ')}"
+      end
+
+      def validated_window(key, window)
+        return window.to_sym if PER_TAG_WINDOWS.include?(window.to_sym)
+
+        raise Error,
+              "Unknown budgets.per_tag[#{key.inspect}] window: #{window.inspect}. " \
+              "Use one of: #{PER_TAG_WINDOWS.join(', ')}"
+      end
+
+      def validated_limit(key, window, limit)
+        numeric = Float(limit, exception: false)
+        return BigDecimal(limit.to_s) if numeric&.positive?
+
+        raise Error,
+              "budgets.per_tag[#{key.inspect}][#{window.inspect}] must be a positive number, " \
+              "got #{limit.inspect}"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/capture.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "section"
+
+module LlmCostTracker
+  class Configuration
+    class Capture < Section
+      OPENAI_COMPATIBLE_PROVIDERS = {
+        "openrouter.ai" => "openrouter",
+        "api.deepseek.com" => "deepseek",
+        "api.groq.com" => "groq"
+      }.freeze
+
+      attributes :request_stream_usage
+
+      attr_reader :openai_compatible_providers
+
+      def initialize(owner)
+        super
+        @request_stream_usage = true
+        self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
+      end
+
+      def openai_compatible_providers=(providers)
+        ensure_mutable!
+        @openai_compatible_providers = normalize_providers(providers)
+      end
+
+      def finalize!
+        @openai_compatible_providers = deep_freeze(normalize_providers(@openai_compatible_providers))
+      end
+
+      private
+
+      def normalize_providers(providers)
+        (providers || {}).each_with_object({}) do |(host, provider), normalized|
+          normalized[host.to_s.downcase] = provider.to_s
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/ingestion.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "section"
+
+module LlmCostTracker
+  class Configuration
+    class Ingestion < Section
+      MODES = %i[inline async].freeze
+
+      attributes :pool_size
+      enum_attribute :mode, allowed: MODES, default: :inline
+
+      def initialize(owner)
+        super
+        @pool_size = nil
+        self.mode = :inline
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/mutability.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class Configuration
+    module Mutability
+      private
+
+      def ensure_mutable!
+        return unless finalized?
+
+        raise FrozenError, "can't modify frozen LlmCostTracker::Configuration"
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each do |key, nested_value|
+            deep_freeze(key)
+            deep_freeze(nested_value)
+          end
+          value.frozen? ? value : value.freeze
+        when Array, Set
+          value.each { |nested_value| deep_freeze(nested_value) }
+          value.frozen? ? value : value.freeze
+        when String
+          value.frozen? ? value : value.freeze
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/pricing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "section"
+
+module LlmCostTracker
+  class Configuration
+    class Pricing < Section
+      UNKNOWN_BEHAVIORS = %i[ignore warn raise].freeze
+
+      attributes :file
+      enum_attribute :unknown_model_behavior, allowed: UNKNOWN_BEHAVIORS, default: :warn
+
+      attr_reader :overrides
+
+      def initialize(owner)
+        super
+        @file = nil
+        self.overrides = {}
+        self.unknown_model_behavior = :warn
+      end
+
+      def overrides=(value)
+        ensure_mutable!
+        @overrides = LlmCostTracker::Pricing::Registry.normalize_price_entries(
+          value || {}, context: "pricing_overrides"
+        )
+      rescue ArgumentError, TypeError => e
+        raise Error, "invalid pricing.overrides: #{e.message}"
+      end
+
+      def finalize!
+        @overrides = deep_freeze(@overrides || {})
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/section.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/string/inflections"
+
+require_relative "mutability"
+
+module LlmCostTracker
+  class Configuration
+    class Section
+      include Mutability
+
+      class << self
+        def attributes(*names)
+          names.each do |name|
+            attr_reader name
+
+            define_method(:"#{name}=") do |value|
+              ensure_mutable!
+              instance_variable_set(:"@#{name}", value)
+            end
+          end
+        end
+
+        def enum_attribute(name, allowed:, default:)
+          attr_reader name
+
+          define_method(:"#{name}=") do |value|
+            ensure_mutable!
+            instance_variable_set(:"@#{name}", normalize_enum(name, value, allowed, default))
+          end
+        end
+      end
+
+      private attr_reader :owner
+
+      delegate :finalized?, to: :owner
+
+      def initialize(owner)
+        @owner = owner
+      end
+
+      def finalize!; end
+
+      private
+
+      def section_name
+        self.class.name.split("::").last.underscore
+      end
+
+      def normalize_enum(name, value, allowed, default)
+        value = default if value.nil?
+        return value if allowed.include?(value)
+
+        raise Error, "Unknown #{section_name}.#{name}: #{value.inspect}. Use one of: #{allowed.join(', ')}"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration/tags.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "section"
+
+module LlmCostTracker
+  class Configuration
+    class Tags < Section
+      DEFAULT_REDACTED_KEYS = %w[api_key access_token authorization credential password refresh_token secret].freeze
+
+      attributes :default, :max_count, :max_value_bytesize
+
+      attr_reader :redacted_keys, :report_breakdown_keys
+
+      def initialize(owner)
+        super
+        @default = {}
+        @max_count = 50
+        @max_value_bytesize = 1024
+        @redacted_keys = DEFAULT_REDACTED_KEYS.dup
+        @report_breakdown_keys = []
+      end
+
+      def redacted_keys=(value)
+        ensure_mutable!
+        @redacted_keys = Array(value).map(&:to_s)
+      end
+
+      def report_breakdown_keys=(value)
+        ensure_mutable!
+        @report_breakdown_keys = Array(value).map { |key| LlmCostTracker::Tags::Key.validate!(key, error_class: Error) }
+      end
+
+      def normalized_redacted_keys
+        @normalized_redacted_keys ||=
+          Array(@redacted_keys).map { |key| LlmCostTracker::Tags::Sanitizer.normalized_key(key) }.freeze
+      end
+
+      def static_sanitized_default
+        return nil if @default.respond_to?(:call)
+
+        @static_sanitized_default ||=
+          LlmCostTracker::Tags::Sanitizer.call((@default || {}).to_h, config: owner).freeze
+      end
+
+      def finalize!
+        @default = deep_freeze(@default || {})
+        @redacted_keys = deep_freeze(Array(@redacted_keys))
+        @report_breakdown_keys = deep_freeze(Array(@report_breakdown_keys))
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/configuration.rb

@@ -1,89 +1,61 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "deprecator"
 require_relative "pricing/registry"
 require_relative "tags/key"
+require_relative "configuration/budgets"
+require_relative "configuration/capture"
+require_relative "configuration/ingestion"
+require_relative "configuration/pricing"
+require_relative "configuration/tags"
 
 module LlmCostTracker
   class Configuration
-    OPENAI_COMPATIBLE_PROVIDERS = {
-      "openrouter.ai" => "openrouter",
-      "api.deepseek.com" => "deepseek",
-      "api.groq.com" => "groq"
+    include Mutability
+
+    SECTIONS = {
+      budgets: Budgets, capture: Capture, ingestion: Ingestion, pricing: Pricing, tags: Tags
     }.freeze
 
-    BUDGET_EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
-    UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
-    INGESTION_MODES = %i[inline async].freeze
-    SCALAR_ATTRIBUTES = %i[enabled default_tags on_budget_exceeded monthly_budget daily_budget per_call_budget
-                           log_level prices_file max_tag_count max_tag_value_bytesize
-                           ingestion_pool_size auto_enable_stream_usage cache_rollups].freeze
-    ENUM_ATTRIBUTES = {
-      budget_exceeded_behavior: [BUDGET_EXCEEDED_BEHAVIORS, :notify],
-      unknown_pricing_behavior: [UNKNOWN_PRICING_BEHAVIORS, :warn],
-      ingestion: [INGESTION_MODES, :inline]
+    SCALAR_ATTRIBUTES = %i[enabled].freeze
+
+    DEPRECATED_OPTIONS = {
+      monthly_budget: { to: %i[budgets monthly] },
+      daily_budget: { to: %i[budgets daily] },
+      per_call_budget: { to: %i[budgets per_call] },
+      budget_exceeded_behavior: { to: %i[budgets exceeded_behavior] },
+      on_budget_exceeded: { to: %i[budgets on_exceeded] },
+      default_tags: { to: %i[tags default] },
+      max_tag_count: { to: %i[tags max_count] },
+      max_tag_value_bytesize: { to: %i[tags max_value_bytesize] },
+      redacted_tag_keys: { to: %i[tags redacted_keys] },
+      report_tag_breakdowns: { to: %i[tags report_breakdown_keys] },
+      prices_file: { to: %i[pricing file] },
+      pricing_overrides: { to: %i[pricing overrides] },
+      unknown_pricing_behavior: { to: %i[pricing unknown_model_behavior] },
+      ingestion_pool_size: { to: %i[ingestion pool_size] },
+      auto_enable_stream_usage: { to: %i[capture request_stream_usage] },
+      openai_compatible_providers: { to: %i[capture openai_compatible_providers] },
+      cache_rollups: {
+        to: %i[budgets totals_source],
+        cast: ->(value) { value ? :cache : :ledger },
+        uncast: ->(value) { value == :cache }
+      },
+      ingestion: { to: %i[ingestion mode], writer_only: true },
+      log_level: { to: nil, note: "LlmCostTracker logs through Rails.logger, which owns the level" }
     }.freeze
-    DEFAULT_REDACTED_TAG_KEYS = %w[api_key access_token authorization credential password refresh_token secret].freeze
-
-    attr_reader(
-      *SCALAR_ATTRIBUTES,
-      :budget_exceeded_behavior,
-      :ingestion,
-      :instrumented_integrations,
-      :pricing_overrides,
-      :report_tag_breakdowns,
-      :redacted_tag_keys,
-      :unknown_pricing_behavior,
-      :openai_compatible_providers
-    )
+
+    attr_reader(*SCALAR_ATTRIBUTES, *SECTIONS.keys, :instrumented_integrations)
 
     def initialize
+      SECTIONS.each { |name, klass| instance_variable_set(:"@#{name}", klass.new(self)) }
       @enabled = true
-      @default_tags       = {}
-      @on_budget_exceeded = nil
-      @monthly_budget     = nil
-      @daily_budget       = nil
-      @per_call_budget    = nil
-      self.budget_exceeded_behavior = :notify
-      self.unknown_pricing_behavior = :warn
-      @log_level          = :info
-      @prices_file        = nil
-      @max_tag_count      = 50
-      @max_tag_value_bytesize = 1024
-      @ingestion_pool_size = nil
-      self.pricing_overrides = {}
+      @log_level = :info
       @instrumented_integrations = Set.new
-      @report_tag_breakdowns = []
-      @redacted_tag_keys = DEFAULT_REDACTED_TAG_KEYS.dup
-      self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
-      @auto_enable_stream_usage = true
-      self.ingestion = :inline
-      @cache_rollups = false
       @finalized = false
     end
 
-    def openai_compatible_providers=(providers)
-      ensure_mutable!
-      @openai_compatible_providers = normalize_openai_compatible_providers(providers)
-    end
-
-    def pricing_overrides=(value)
-      ensure_mutable!
-      @pricing_overrides = Pricing::Registry.normalize_price_entries(value || {}, context: "pricing_overrides")
-    rescue ArgumentError, TypeError => e
-      raise Error, "invalid pricing_overrides: #{e.message}"
-    end
-
-    def report_tag_breakdowns=(value)
-      ensure_mutable!
-      @report_tag_breakdowns = Array(value).map { |key| Tags::Key.validate!(key, error_class: Error) }
-    end
-
-    def redacted_tag_keys=(value)
-      ensure_mutable!
-      @redacted_tag_keys = Array(value).map(&:to_s)
-    end
-
     def instrument(*names)
       ensure_mutable!
       names = names.flatten
@@ -96,83 +68,55 @@ module LlmCostTracker
     end
 
     SCALAR_ATTRIBUTES.each do |name|
-      define_method("#{name}=") do |value|
+      define_method(:"#{name}=") do |value|
         ensure_mutable!
         instance_variable_set(:"@#{name}", value)
       end
     end
 
-    ENUM_ATTRIBUTES.each do |name, (allowed, default)|
-      define_method("#{name}=") do |value|
-        ensure_mutable!
-        instance_variable_set(:"@#{name}", normalize_enum(name, value, allowed, default: default))
+    DEPRECATED_OPTIONS.each do |old_name, spec|
+      path = spec[:to]
+      replacement = path ? "config.#{path.join('.')}" : nil
+
+      define_method(:"#{old_name}=") do |value|
+        LlmCostTracker.deprecator.warn(deprecation_message(old_name, replacement, spec[:note], writer: true))
+        ensure_mutable! unless path
+        next instance_variable_set(:"@#{old_name}", value) unless path
+
+        value = spec[:cast].call(value) if spec[:cast]
+        target = path[0..-2].inject(self) { |object, step| object.public_send(step) }
+        target.public_send(:"#{path.last}=", value)
+      end
+
+      next if spec[:writer_only]
+
+      define_method(old_name) do
+        LlmCostTracker.deprecator.warn(deprecation_message(old_name, replacement, spec[:note], writer: false))
+        next instance_variable_get(:"@#{old_name}") unless path
+
+        current = path.inject(self) { |object, step| object.public_send(step) }
+        spec[:uncast] ? spec[:uncast].call(current) : current
       end
     end
 
     def finalize!
-      @default_tags = deep_freeze(@default_tags || {})
-      @pricing_overrides = deep_freeze(@pricing_overrides || {})
+      SECTIONS.each_key { |name| public_send(name).finalize! }
       @instrumented_integrations = deep_freeze(@instrumented_integrations || Set.new)
-      @report_tag_breakdowns = deep_freeze(Array(@report_tag_breakdowns))
-      @redacted_tag_keys = deep_freeze(Array(@redacted_tag_keys))
-      @openai_compatible_providers = deep_freeze(
-        normalize_openai_compatible_providers(@openai_compatible_providers)
-      )
       @finalized = true
     end
 
-    def normalized_redacted_tag_keys
-      @normalized_redacted_tag_keys ||=
-        Array(@redacted_tag_keys).map { |key| Tags::Sanitizer.normalized_key(key) }.freeze
-    end
-
-    def static_sanitized_default_tags
-      return nil if @default_tags.respond_to?(:call)
-
-      @static_sanitized_default_tags ||= Tags::Sanitizer.call((@default_tags || {}).to_h).freeze
-    end
-
     def finalized?
       @finalized
     end
 
     private
 
-    def normalize_enum(name, value, allowed, default:)
-      value = default if value.nil?
-      return value if allowed.include?(value)
+    def deprecation_message(old_name, replacement, note, writer:)
+      suffix = writer ? "=" : ""
+      name = "config.#{old_name}#{suffix}"
+      return "#{name} is deprecated; use #{replacement}#{suffix}" if replacement
 
-      raise Error, "Unknown #{name}: #{value.inspect}. Use one of: #{allowed.join(', ')}"
-    end
-
-    def normalize_openai_compatible_providers(providers)
-      (providers || {}).each_with_object({}) do |(host, provider), normalized|
-        normalized[host.to_s.downcase] = provider.to_s
-      end
-    end
-
-    def ensure_mutable!
-      return unless finalized?
-
-      raise FrozenError, "can't modify frozen LlmCostTracker::Configuration"
-    end
-
-    def deep_freeze(value)
-      case value
-      when Hash
-        value.each do |key, nested_value|
-          deep_freeze(key)
-          deep_freeze(nested_value)
-        end
-        value.frozen? ? value : value.freeze
-      when Array, Set
-        value.each { |nested_value| deep_freeze(nested_value) }
-        value.frozen? ? value : value.freeze
-      when String
-        value.frozen? ? value : value.freeze
-      else
-        value
-      end
+      "#{name} is deprecated and has no effect; #{note}"
     end
   end
 end

data/lib/llm_cost_tracker/deprecator.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "active_support/deprecation"
+
+module LlmCostTracker
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("1.0", "LlmCostTracker")
+  end
+end