llm_cost_tracker 0.13.0 → 0.14.0

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/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
 

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

@@ -4,16 +4,16 @@ LlmCostTracker.configure do |config|
   # Set to false to temporarily disable tracking without removing middleware.
   config.enabled = true
 
-  # LLM Cost Tracker logs warnings through Rails.logger when available.
-  config.log_level = :info
-
   # Tags merged into every event. Use a callable for request/job-time context.
-  config.default_tags = -> { { environment: Rails.env } }
+  config.tags.default = -> { { environment: Rails.env } }
 
   # Tag guardrails keep accidental high-cardinality or sensitive values out of the ledger.
-  # config.max_tag_count = 50
-  # config.max_tag_value_bytesize = 1024
-  # config.redacted_tag_keys = <%= LlmCostTracker::Configuration::DEFAULT_REDACTED_TAG_KEYS.inspect %>
+  # config.tags.max_count = 50
+  # config.tags.max_value_bytesize = 1024
+  # config.tags.redacted_keys = <%= LlmCostTracker::Configuration::Tags::DEFAULT_REDACTED_KEYS.inspect %>
+
+  # Tag keys that get their own cost breakdown in bin/rails llm_cost_tracker:report.
+  # config.tags.report_breakdown_keys = %w[feature user_id]
 
   # Optional SDK integrations. Provider SDK gems are not installed by LLM Cost Tracker.
   # Enabled integrations are checked at boot, so enable only clients your app loads.
@@ -23,35 +23,50 @@ LlmCostTracker.configure do |config|
 
   # Pricing — local file refreshed via bin/rails llm_cost_tracker:prices:refresh
   # plus inline overrides. Rates are per 1M tokens; the snapshot's currency
-  # is read from your prices_file's `metadata.currency` (USD in the bundled
+  # is read from your pricing file's `metadata.currency` (USD in the bundled
   # snapshot — set a different code per file if you maintain non-USD prices).
 <% if options[:prices] -%>
-  config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
+  config.pricing.file = Rails.root.join("config/llm_cost_tracker_prices.yml")
 <% else -%>
-  # config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
+  # config.pricing.file = Rails.root.join("config/llm_cost_tracker_prices.yml")
 <% end -%>
-  # config.pricing_overrides = {
+  # config.pricing.overrides = {
   #   "my-custom-model" => { input: 1.00, output: 2.00 }
   # }
   # :warn (default) records token usage with nil cost when a model has no rate.
-  # Use :raise to require known pricing for every model.
-  config.unknown_pricing_behavior = :warn
+  # Use :raise to reject models that have no rate at all; a model priced with one
+  # component rate missing lands as partial and does not trigger it.
+  config.pricing.unknown_model_behavior = :warn
 
   # Budget guardrails — cumulative monthly/daily and per-call ceilings in USD,
-  # plus behavior on crossing (:notify default fires on_budget_exceeded; :raise
+  # plus behavior on crossing (:notify default fires budgets.on_exceeded; :raise
   # raises after recording; :block_requests preflights supported requests, also
   # estimating the current call's input cost via chars/4 so it can block before
-  # send) and an optional callback. Cap evaluation reads from llm_cost_tracker_calls live;
-  # flip cache_rollups to true at high volume so reads hit the rollups table
-  # instead — generate the table with `bin/rails generate llm_cost_tracker:call_rollups`.
-  # config.monthly_budget = 100.00
-  # config.daily_budget = 10.00
-  # config.per_call_budget = 1.00
-  config.budget_exceeded_behavior = :notify
-  # config.on_budget_exceeded = ->(data) {
+  # send) and an optional callback.
+  # config.budgets.monthly = 100.00
+  # config.budgets.daily = 10.00
+  # config.budgets.per_call = 1.00
+  config.budgets.exceeded_behavior = :notify
+
+  # One budget applied to every distinct value of a tag: each tenant gets its own
+  # 1000 a month, not 1000 shared between them. Declare as many tags as you need; a rule
+  # can set its own behavior and callback instead of following the global ones. Needs the
+  # cost columns from `bin/rails generate llm_cost_tracker:upgrade_per_tag_budgets`.
+  # Budget high-cardinality tags only — a tag with a handful of values covers most of the
+  # ledger, so its check cannot use an index and every call pays for a near-full scan.
+  # config.budgets.per_tag = {
+  #   tenant_id: { monthly: 1000.00, weekly: 300.00 },
+  #   user_id: { daily: 25.00, behavior: :notify }
+  # }
+  # config.budgets.on_exceeded = ->(data) {
   #   Rails.logger.warn("LLM #{data[:budget_type]} budget exceeded: $#{data[:total]} / $#{data[:budget]}")
   # }
-  # config.cache_rollups = true
+
+  # Where budget checks read period spend from. :ledger sums llm_cost_tracker_calls on
+  # every check; :cache keeps running totals in llm_cost_tracker_call_rollups so checks
+  # read one row instead — switch once the live SUM gets slow, and generate the table
+  # first with `bin/rails generate llm_cost_tracker:call_rollups`.
+  # config.budgets.totals_source = :cache
 
   # Ingestion path — :inline (default) writes events synchronously from the request
   # thread. Set to :async for a write-ahead inbox + background worker that batches
@@ -59,13 +74,18 @@ LlmCostTracker.configure do |config|
   # inbox/leases tables created by `bin/rails generate llm_cost_tracker:async_ingestion`.
   # Synchronous inbox writes use a dedicated ActiveRecord pool (defaults to 2 connections)
   # so they don't compete with request threads for the default pool when a tracked call
-  # happens inside an open caller transaction. Bump ingestion_pool_size if your Puma
+  # happens inside an open caller transaction. Bump ingestion.pool_size if your Puma
   # worker count outgrows that.
-  # config.ingestion          = :async
-  # config.ingestion_pool_size = 5
+  # config.ingestion.mode = :async
+  # config.ingestion.pool_size = 5
+
+  # Register OpenAI-compatible gateway hosts so their calls are attributed to a
+  # provider name instead of the generic openai_compatible bucket.
+  # config.capture.openai_compatible_providers["llm.my-company.com"] = "internal_gateway"
+
+  # Streaming calls only report token usage when the request asks for it. Leave this
+  # on and the Faraday middleware adds stream_options: { include_usage: true } to
+  # OpenAI-compatible streaming request bodies that don't already set it.
+  # config.capture.request_stream_usage = false
 
-  # Register OpenAI-compatible gateway hosts and choose extra tag breakdowns
-  # for bin/rails llm_cost_tracker:report.
-  # config.openai_compatible_providers["llm.my-company.com"] = "internal_gateway"
-  # config.report_tag_breakdowns = %w[feature user_id]
 end