llm_cost_tracker 0.12.0 → 0.14.0

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

data/lib/llm_cost_tracker/doctor/ingestion_check.rb

@@ -11,20 +11,20 @@ module LlmCostTracker
         return unless Probe.table_exists?("llm_cost_tracker_calls")
         return inline_check unless LlmCostTracker::Ingestion.async?
 
-        missing = missing_parts
-        return async_ok if missing.empty?
+        problems = missing_parts + drifted_parts
+        return async_ok if problems.empty?
 
         Check.new(
           :error,
           "async ingestion",
-          "missing #{missing.join(', ')}; see docs/upgrading.md for the recovery steps"
+          "#{problems.join('; ')}; see docs/upgrading.md for the recovery steps"
         )
       end
 
       private
 
       def async_ok
-        Check.new(:ok, "async ingestion", "inbox and ingestion lease tables available")
+        Check.new(:ok, "async ingestion", "inbox and ingestion lease tables are on the current schema")
       end
 
       def inline_check
@@ -32,14 +32,14 @@ module LlmCostTracker
         if leftovers.empty?
           return Check.new(:ok,
                            "inline ingestion",
-                           "config.ingestion = :inline; events write directly to the ledger")
+                           "config.ingestion.mode = :inline; events write directly to the ledger")
         end
 
         Check.new(
           :warn,
           "inline ingestion",
-          "config.ingestion = :inline but found unused async ingestion tables: #{leftovers.join(', ')}. " \
-          "Set config.ingestion = :async to keep the inbox path or drop the tables."
+          "config.ingestion.mode = :inline but found unused async ingestion tables: #{leftovers.join(', ')}. " \
+          "Set config.ingestion.mode = :async to keep the inbox path or drop the tables."
         )
       end
 
@@ -48,7 +48,16 @@ module LlmCostTracker
       end
 
       def missing_parts
-        async_tables.reject { |table| Probe.table_exists?(table) }
+        async_tables.reject { |table| Probe.table_exists?(table) }.map { |table| "missing #{table}" }
+      end
+
+      def drifted_parts
+        LlmCostTracker::Ledger::Schema::ASYNC_SCHEMAS.filter_map do |schema, table|
+          next unless Probe.table_exists?(table)
+
+          errors = schema.current_schema_errors
+          "#{table} #{errors.join(', ')}" unless errors.empty?
+        end
       end
 
       def async_tables

data/lib/llm_cost_tracker/doctor/price_check.rb

@@ -11,7 +11,7 @@ module LlmCostTracker
       REFRESH_COMMAND = "refresh the source-controlled prices file with bin/rails llm_cost_tracker:prices:refresh"
 
       def call
-        path = LlmCostTracker.configuration.prices_file
+        path = LlmCostTracker.configuration.pricing.file
         return bundled_check unless path
 
         count = LlmCostTracker::Pricing::Registry.file_prices(path).size

data/lib/llm_cost_tracker/doctor.rb

@@ -164,7 +164,7 @@ module LlmCostTracker
 
     def call_rollups_check
       return unless llm_cost_tracker_calls_table?
-      return live_rollups_check unless LlmCostTracker.configuration.cache_rollups
+      return live_rollups_check unless LlmCostTracker.configuration.budgets.totals_source == :cache
 
       errors = LlmCostTracker::Ledger::Schema::CallRollups.current_schema_errors
       return Check.new(:ok, "call rollups", "llm_cost_tracker_call_rollups exists") if errors.empty?
@@ -181,14 +181,14 @@ module LlmCostTracker
         Check.new(
           :warn,
           "call rollups",
-          "cache_rollups=false but llm_cost_tracker_call_rollups exists. " \
-          "Set config.cache_rollups = true to keep budget reads on the rollups fast path or drop the table."
+          "budgets.totals_source=:ledger but llm_cost_tracker_call_rollups exists. " \
+          "Set config.budgets.totals_source = :cache to keep budget reads on the rollups fast path or drop the table."
         )
       else
         Check.new(
           :ok,
           "call rollups",
-          "cache_rollups=false; budget reads aggregate from llm_cost_tracker_calls directly"
+          "budgets.totals_source=:ledger; budget reads aggregate from llm_cost_tracker_calls directly"
         )
       end
     end

data/lib/llm_cost_tracker/engine.rb

@@ -9,6 +9,10 @@ module LlmCostTracker
   class Engine < ::Rails::Engine
     isolate_namespace LlmCostTracker
 
+    initializer "llm_cost_tracker.deprecator" do |app|
+      app.deprecators[:llm_cost_tracker] = LlmCostTracker.deprecator
+    end
+
     initializer "llm_cost_tracker.dashboard_setup_state" do |app|
       app.reloader.to_prepare { LlmCostTracker::Dashboard::SetupState.reset! }
     end

data/lib/llm_cost_tracker/errors.rb

@@ -6,20 +6,29 @@ module LlmCostTracker
   class InvalidFilterError < Error; end
 
   class BudgetExceededError < Error
-    attr_reader :total, :budget, :budget_type, :last_event, :stage
+    attr_reader :total, :budget, :budget_type, :last_event, :stage, :scope
 
-    def initialize(budget:, budget_type:, total:, last_event: nil, stage: :post_spend)
+    def initialize(budget:, budget_type:, total:, last_event: nil, stage: :post_spend, scope: nil)
       @total = total
       @budget = budget
       @budget_type = budget_type
       @last_event = last_event
       @stage = stage
+      @scope = scope
 
       super(
-        "LLM #{@budget_type.to_s.tr('_', '-')} budget exceeded: " \
+        "LLM #{@budget_type.to_s.tr('_', '-')} budget exceeded#{scope_suffix}: " \
         "$#{format('%.6f', @total)} / $#{format('%.6f', budget)}"
       )
     end
+
+    private
+
+    def scope_suffix
+      return "" unless @scope
+
+      " for #{@scope[:key]}=#{@scope[:value]}"
+    end
   end
 
   class UnknownPricingError < Error

data/lib/llm_cost_tracker/event.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "pricing/mode"
+
 module LlmCostTracker
   Event = Data.define(
     :event_id,
@@ -48,7 +50,7 @@ module LlmCostTracker
     end
 
     def batch?
-      pricing_mode.to_s.split("_").include?("batch")
+      Pricing::Mode.tokenize(pricing_mode.to_s).include?("batch")
     end
 
     def self.resolve_line_items(service_items)

data/lib/llm_cost_tracker/generators/llm_cost_tracker/async_ingestion_generator.rb

@@ -11,7 +11,7 @@ module LlmCostTracker
       source_root File.expand_path("templates", __dir__)
 
       desc "Creates the async ingestion tables (llm_cost_tracker_ingestion_inbox_entries + _leases). " \
-           "Required when config.ingestion = :async."
+           "Required when config.ingestion.mode = :async."
 
       def create_migration_file
         migration_template(
@@ -25,7 +25,7 @@ module LlmCostTracker
           After migrating, set the following in config/initializers/llm_cost_tracker.rb:
 
             LlmCostTracker.configure do |config|
-              config.ingestion = :async
+              config.ingestion.mode = :async
             end
 
           Without it the async inbox tables stay unused and Tracker keeps writing

data/lib/llm_cost_tracker/generators/llm_cost_tracker/call_rollups_generator.rb

@@ -11,7 +11,7 @@ module LlmCostTracker
       source_root File.expand_path("templates", __dir__)
 
       desc "Creates the optional llm_cost_tracker_call_rollups table for fast budget reads. " \
-           "Required when config.cache_rollups = true."
+           "Required when config.budgets.totals_source = :cache."
 
       def create_migration_file
         migration_template(
@@ -25,7 +25,7 @@ module LlmCostTracker
           After migrating, set the following in config/initializers/llm_cost_tracker.rb:
 
             LlmCostTracker.configure do |config|
-              config.cache_rollups = true
+              config.budgets.totals_source = :cache
             end
 
           Without it Tracker keeps reading budget totals as live SUM aggregates over

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_cost_tracker_async_ingestion.rb.erb

@@ -23,7 +23,6 @@ class CreateLlmCostTrackerAsyncIngestion < ActiveRecord::Migration<%= migration_
 
     add_index :llm_cost_tracker_ingestion_inbox_entries, :event_id, unique: true
     add_index :llm_cost_tracker_ingestion_inbox_entries, [:tracked_at, :attempts]
-    add_index :llm_cost_tracker_ingestion_inbox_entries, [:locked_at, :id]
     add_index :llm_cost_tracker_ingestion_leases, :name, unique: true
   end
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_cost_tracker_calls.rb.erb

@@ -74,20 +74,24 @@ class CreateLlmCostTrackerCalls < ActiveRecord::Migration<%= migration_version %
                    foreign_key: { to_table: :llm_cost_tracker_calls, on_delete: :cascade }
       t.string :key, null: false
       t.text :value, null: false
+      t.decimal :total_cost, precision: 20, scale: 8
+      t.datetime :tracked_at
     end
 
     add_index :llm_cost_tracker_calls, :event_id, unique: true
     add_index :llm_cost_tracker_calls, :tracked_at
-    add_index :llm_cost_tracker_calls, [:provider, :tracked_at]
-    add_index :llm_cost_tracker_calls, [:model, :tracked_at]
+    add_index :llm_cost_tracker_calls, %i[provider tracked_at]
+    add_index :llm_cost_tracker_calls, %i[model tracked_at]
     add_index :llm_cost_tracker_calls, :cost_status
     add_index :llm_cost_tracker_calls, :provider_response_id
+    add_index :llm_cost_tracker_calls, :id, name: :index_llm_cost_tracker_calls_on_unpriced,
+                                          where: "total_cost IS NULL"
     add_index :llm_cost_tracker_call_line_items, [:llm_cost_tracker_call_id, :position]
     add_index :llm_cost_tracker_call_tags, :llm_cost_tracker_call_id
     if postgresql?
-      add_index :llm_cost_tracker_call_tags, [:key, :value]
+      add_index :llm_cost_tracker_call_tags, [:key, :value, :tracked_at]
     elsif mysql?
-      add_index :llm_cost_tracker_call_tags, [:key, :value], length: { value: 191 }
+      add_index :llm_cost_tracker_call_tags, [:key, :value, :tracked_at], length: { value: 191 }
     end
   end