llm_cost_tracker 0.4.0 → 0.5.0

data/lib/llm_cost_tracker/generators/llm_cost_tracker/prices_generator.rb

@@ -2,17 +2,23 @@
 
 require "rails/generators"
 
+require_relative "../../price_registry"
+require_relative "../../price_sync/registry_loader"
+require_relative "../../price_sync/registry_writer"
+
 module LlmCostTracker
   module Generators
     class PricesGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
-      desc "Creates a local LlmCostTracker price override file"
+      desc "Creates a local LLM Cost Tracker price snapshot"
 
       def create_prices_file
-        template(
-          "llm_cost_tracker_prices.yml.erb",
-          "config/llm_cost_tracker_prices.yml"
+        registry = LlmCostTracker::PriceSync::RegistryLoader.new.call(
+          path: LlmCostTracker::PriceRegistry::DEFAULT_PRICES_PATH,
+          seed_path: LlmCostTracker::PriceRegistry::DEFAULT_PRICES_PATH
+        )
+        LlmCostTracker::PriceSync::RegistryWriter.new.call(
+          path: File.join(destination_root, "config/llm_cost_tracker_prices.yml"),
+          registry: registry
         )
       end
     end

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

@@ -8,10 +8,10 @@ class AddPeriodTotalsToLlmCostTracker < ActiveRecord::Migration<%= migration_ver
       t.timestamps
     end unless table_exists?(:llm_cost_tracker_period_totals)
 
+    backfill_period_totals
+
     add_index :llm_cost_tracker_period_totals, [:period, :period_start],
               unique: true unless index_exists?(:llm_cost_tracker_period_totals, [:period, :period_start])
-
-    backfill_period_totals
   end
 
   def down
@@ -22,23 +22,53 @@ class AddPeriodTotalsToLlmCostTracker < ActiveRecord::Migration<%= migration_ver
   private
 
   def backfill_period_totals
+    backfill_legacy_monthly_totals if table_exists?(:llm_cost_tracker_monthly_totals)
     return unless table_exists?(:llm_api_calls)
 
     backfill_period_total("day", day_bucket_sql)
     backfill_period_total("month", month_bucket_sql)
   end
 
+  def backfill_legacy_monthly_totals
+    execute <<~SQL
+      INSERT INTO llm_cost_tracker_period_totals (period, period_start, total_cost, created_at, updated_at)
+      SELECT #{connection.quote("month")} AS period,
+             month AS period_start,
+             total_cost,
+             CURRENT_TIMESTAMP,
+             CURRENT_TIMESTAMP
+      FROM llm_cost_tracker_monthly_totals legacy
+      WHERE NOT EXISTS (
+        SELECT 1
+        FROM llm_cost_tracker_period_totals existing
+        WHERE existing.period = #{connection.quote("month")}
+          AND existing.period_start = legacy.month
+      )
+    SQL
+  end
+
   def backfill_period_total(period, bucket_sql)
     execute <<~SQL
       INSERT INTO llm_cost_tracker_period_totals (period, period_start, total_cost, created_at, updated_at)
-      SELECT #{connection.quote(period)} AS period,
-             #{bucket_sql} AS period_start,
-             SUM(total_cost) AS total_cost,
+      SELECT aggregated.period,
+             aggregated.period_start,
+             aggregated.total_cost,
              CURRENT_TIMESTAMP,
              CURRENT_TIMESTAMP
-      FROM llm_api_calls
-      WHERE total_cost IS NOT NULL
-      GROUP BY #{bucket_sql}
+      FROM (
+        SELECT #{connection.quote(period)} AS period,
+               #{bucket_sql} AS period_start,
+               SUM(total_cost) AS total_cost
+        FROM llm_api_calls
+        WHERE total_cost IS NOT NULL
+        GROUP BY #{bucket_sql}
+      ) aggregated
+      WHERE NOT EXISTS (
+        SELECT 1
+        FROM llm_cost_tracker_period_totals existing
+        WHERE existing.period = aggregated.period
+          AND existing.period_start = aggregated.period_start
+      )
     SQL
   end
 

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

@@ -37,10 +37,9 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
-    add_index :llm_api_calls, :provider
-    add_index :llm_api_calls, :model
     add_index :llm_api_calls, :tracked_at
     add_index :llm_api_calls, [:provider, :tracked_at]
+    add_index :llm_api_calls, [:model, :tracked_at]
     add_index :llm_api_calls, :stream
     add_index :llm_api_calls, :usage_source
     add_index :llm_api_calls, :provider_response_id

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

@@ -1,42 +1,74 @@
 # frozen_string_literal: true
 
 LlmCostTracker.configure do |config|
-  # Enable/disable tracking
+  # Set to false to temporarily disable tracking without removing middleware.
   config.enabled = true
 
-  # Storage backend: :log, :active_record, or :custom
+  # :active_record stores events in llm_api_calls for dashboards, reports, and shared budgets.
+  # Other options: :log for local logging, :custom for your own storage callable.
   config.storage_backend = :active_record
 
-  # Default tags added to every tracked event
-  # config.default_tags = { environment: Rails.env, app: "my_app" }
+  # Tags are merged into every event. Use a callable for request/job-time context.
+  config.default_tags = -> { { environment: Rails.env } }
 
-  # Monthly budget in USD. Set to nil to disable budget alerts.
+  # Optional SDK integrations. Provider SDK gems are not installed by LLM Cost Tracker.
+  # Enable only the SDKs your app already uses.
+  # config.instrument :openai
+  # config.instrument :anthropic
+
+  # Budget behavior: :notify calls on_budget_exceeded, :raise raises after recording,
+  # :block_requests preflights monthly/daily budgets before supported requests.
+  config.budget_exceeded_behavior = :notify
+
+  # Storage failures are non-fatal by default so LLM responses can still return.
+  # Use :raise if failed ledger writes should fail the request/job.
+  config.storage_error_behavior = :warn
+
+  # Unknown pricing records token usage with nil cost by default. Use :raise if
+  # every model must have known pricing before it can be used.
+  config.unknown_pricing_behavior = :warn
+
+  # Used only by the :log storage backend.
+  config.log_level = :info
+<% if options[:prices] -%>
+
+  # Local JSON/YAML pricing file generated by --prices. Keep it in source control
+  # and refresh it with bin/rails llm_cost_tracker:prices:sync.
+  config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
+<% end -%>
+
+  # Cumulative monthly/daily budgets and a single-call ceiling, in USD.
   # config.monthly_budget = 100.00
   # config.daily_budget = 10.00
   # config.per_call_budget = 1.00
-  # config.budget_exceeded_behavior = :notify # :notify, :raise, or :block_requests
 
-  # What to do when storage fails.
-  # config.storage_error_behavior = :warn # :ignore, :warn, or :raise
-
-  # What to do when a model has no built-in price and no pricing_overrides entry.
-  # config.unknown_pricing_behavior = :warn # :ignore, :warn, or :raise
-
-  # Callback when monthly budget is exceeded.
+  # Called when :notify is selected and a monthly, daily, or per-call budget is exceeded.
   # config.on_budget_exceeded = ->(data) {
-  #   Rails.logger.warn "[LlmCostTracker] Budget exceeded! " \
-  #     "#{data[:budget_type]} total: $#{data[:total]}, Budget: $#{data[:budget]}"
-  #   # Or send a Slack notification, email, etc.
+  #   Rails.logger.warn(
+  #     "LLM #{data[:budget_type]} budget exceeded: $#{data[:total]} / $#{data[:budget]}"
+  #   )
   # }
 
-  # Load a local JSON/YAML price table that overrides built-in pricing.
-  # config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.json")
-
-  # Override pricing for specific models in Ruby (per 1M tokens, USD).
+  # Local pricing table and small Ruby-side overrides. Prices are USD per 1M tokens.
+  # config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
   # config.pricing_overrides = {
   #   "my-custom-model" => { input: 1.00, output: 2.00 }
   # }
 
-  # OpenAI-compatible APIs. OpenRouter and DeepSeek are included by default.
+  # 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]
+
+  # Use :custom when you want to send events to your own sink instead of ActiveRecord.
+  # Return false from custom_storage to skip budget checks for that event.
+  # config.storage_backend = :custom
+  # config.custom_storage = ->(event) {
+  #   Rails.logger.info(
+  #     provider: event.provider,
+  #     model: event.model,
+  #     total_cost: event.cost&.total_cost,
+  #     tags: event.tags
+  #   )
+  # }
 end

data/lib/llm_cost_tracker/integrations/anthropic.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module LlmCostTracker
+  module Integrations
+    module Anthropic
+      extend Base
+
+      class << self
+        def integration_name = :anthropic
+
+        def target_patches
+          [
+            [constant("Anthropic::Resources::Messages"), MessagesPatch],
+            [constant("Anthropic::Resources::Beta::Messages"), MessagesPatch]
+          ]
+        end
+
+        def record_message(message, request:, latency_ms:)
+          return unless active?
+
+          record_safely do
+            usage = ObjectReader.first(message, :usage)
+            next unless usage
+
+            input_tokens = ObjectReader.first(usage, :input_tokens)
+            output_tokens = ObjectReader.first(usage, :output_tokens)
+            next if input_tokens.nil? && output_tokens.nil?
+
+            LlmCostTracker::Tracker.record(
+              provider: "anthropic",
+              model: ObjectReader.first(message, :model) || request[:model],
+              input_tokens: ObjectReader.integer(input_tokens),
+              output_tokens: ObjectReader.integer(output_tokens),
+              latency_ms: latency_ms,
+              usage_source: :sdk_response,
+              provider_response_id: ObjectReader.first(message, :id),
+              metadata: usage_metadata(usage)
+            )
+          end
+        end
+
+        def usage_metadata(usage)
+          {
+            cache_read_input_tokens: ObjectReader.integer(ObjectReader.first(usage, :cache_read_input_tokens)),
+            cache_write_input_tokens: ObjectReader.integer(ObjectReader.first(usage, :cache_creation_input_tokens)),
+            hidden_output_tokens: hidden_output_tokens(usage)
+          }
+        end
+
+        def hidden_output_tokens(usage)
+          ObjectReader.integer(
+            ObjectReader.first(usage, :thinking_tokens, :thinking_output_tokens) ||
+            ObjectReader.nested(usage, :output_tokens_details, :reasoning_tokens)
+          )
+        end
+      end
+
+      module MessagesPatch
+        def create(*args, **kwargs)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          LlmCostTracker::Integrations::Anthropic.enforce_budget!
+          message = super
+          LlmCostTracker::Integrations::Anthropic.record_message(
+            message,
+            request: LlmCostTracker::Integrations::Anthropic.request_params(args, kwargs),
+            latency_ms: LlmCostTracker::Integrations::Anthropic.elapsed_ms(started_at)
+          )
+          message
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/integrations/base.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../logging"
+require_relative "object_reader"
+
+module LlmCostTracker
+  module Integrations
+    module Base
+      Result = Data.define(:name, :status, :message)
+
+      def active?
+        LlmCostTracker.configuration.instrumented?(integration_name)
+      end
+
+      def install
+        target_patches.each { |target, patch| install_patch(target, patch) }
+      end
+
+      def status
+        name = integration_name
+        installed = target_patches.count { |target, patch| patch_installed?(target, patch) }
+        available = target_patches.count { |target, _patch| target }
+        return Result.new(name, :ok, "#{name} integration installed") if installed.positive?
+        return Result.new(name, :warn, "#{name} SDK classes are not loaded") if available.zero?
+
+        Result.new(name, :warn, "#{name} integration is enabled but not installed")
+      end
+
+      def elapsed_ms(started_at)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+      end
+
+      def enforce_budget!
+        LlmCostTracker::Tracker.enforce_budget! if active?
+      end
+
+      def record_safely
+        yield
+      rescue LlmCostTracker::Error
+        raise
+      rescue StandardError => e
+        Logging.warn("#{integration_name} integration failed to record usage: #{e.class}: #{e.message}")
+      end
+
+      def request_params(args, kwargs)
+        params = args.first.is_a?(Hash) ? args.first : {}
+        params.merge(kwargs)
+      end
+
+      def constant(path)
+        path.to_s.split("::").reduce(Object) do |scope, const_name|
+          return nil unless scope.const_defined?(const_name, false)
+
+          scope.const_get(const_name, false)
+        end
+      end
+
+      private
+
+      def install_patch(target, patch)
+        return unless target
+        return if patch_installed?(target, patch)
+
+        target.prepend(patch)
+      end
+
+      def patch_installed?(target, patch)
+        target&.ancestors&.include?(patch)
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/integrations/object_reader.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Integrations
+    module ObjectReader
+      module_function
+
+      def first(object, *keys)
+        keys.each do |key|
+          value = read(object, key)
+          return value unless value.nil?
+        end
+        nil
+      end
+
+      def nested(object, *path)
+        path.reduce(object) do |current, key|
+          return nil if current.nil?
+
+          read(current, key)
+        end
+      end
+
+      def read(object, key)
+        return nil if object.nil?
+
+        read_hash(object, key) || read_method(object, key) || read_index(object, key)
+      end
+
+      def integer(value)
+        value.nil? ? 0 : value.to_i
+      end
+
+      def read_hash(object, key)
+        return unless object.respond_to?(:key?)
+
+        return object[key] if object.key?(key)
+
+        string_key = key.to_s
+        object[string_key] if object.key?(string_key)
+      end
+
+      def read_method(object, key)
+        object.public_send(key) if object.respond_to?(key)
+      end
+
+      def read_index(object, key)
+        return unless object.respond_to?(:[])
+
+        object[key]
+      rescue IndexError, TypeError, NoMethodError
+        nil
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/integrations/openai.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module LlmCostTracker
+  module Integrations
+    module Openai
+      extend Base
+
+      class << self
+        def integration_name = :openai
+
+        def target_patches
+          [
+            [constant("OpenAI::Resources::Responses"), ResponsesPatch],
+            [constant("OpenAI::Resources::Chat::Completions"), ChatCompletionsPatch]
+          ]
+        end
+
+        def record_response(response, request:, latency_ms:)
+          return unless active?
+
+          record_safely do
+            usage = ObjectReader.first(response, :usage)
+            next unless usage
+
+            input_tokens = ObjectReader.first(usage, :input_tokens, :prompt_tokens)
+            output_tokens = ObjectReader.first(usage, :output_tokens, :completion_tokens)
+            next if input_tokens.nil? && output_tokens.nil?
+
+            LlmCostTracker::Tracker.record(
+              provider: "openai",
+              model: ObjectReader.first(response, :model) || request[:model],
+              input_tokens: ObjectReader.integer(input_tokens),
+              output_tokens: ObjectReader.integer(output_tokens),
+              latency_ms: latency_ms,
+              usage_source: :sdk_response,
+              provider_response_id: ObjectReader.first(response, :id),
+              metadata: usage_metadata(usage)
+            )
+          end
+        end
+
+        def usage_metadata(usage)
+          {
+            cache_read_input_tokens: cache_read_input_tokens(usage),
+            hidden_output_tokens: hidden_output_tokens(usage)
+          }
+        end
+
+        def cache_read_input_tokens(usage)
+          ObjectReader.integer(
+            ObjectReader.nested(usage, :input_tokens_details, :cached_tokens) ||
+            ObjectReader.nested(usage, :prompt_tokens_details, :cached_tokens)
+          )
+        end
+
+        def hidden_output_tokens(usage)
+          ObjectReader.integer(
+            ObjectReader.nested(usage, :output_tokens_details, :reasoning_tokens) ||
+            ObjectReader.nested(usage, :completion_tokens_details, :reasoning_tokens)
+          )
+        end
+      end
+
+      module ResponsesPatch
+        def create(*args, **kwargs)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          LlmCostTracker::Integrations::Openai.enforce_budget!
+          response = super
+          LlmCostTracker::Integrations::Openai.record_response(
+            response,
+            request: LlmCostTracker::Integrations::Openai.request_params(args, kwargs),
+            latency_ms: LlmCostTracker::Integrations::Openai.elapsed_ms(started_at)
+          )
+          response
+        end
+      end
+
+      module ChatCompletionsPatch
+        def create(*args, **kwargs)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          LlmCostTracker::Integrations::Openai.enforce_budget!
+          response = super
+          LlmCostTracker::Integrations::Openai.record_response(
+            response,
+            request: LlmCostTracker::Integrations::Openai.request_params(args, kwargs),
+            latency_ms: LlmCostTracker::Integrations::Openai.elapsed_ms(started_at)
+          )
+          response
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/integrations/registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "openai"
+require_relative "anthropic"
+
+module LlmCostTracker
+  module Integrations
+    module Registry
+      INTEGRATIONS = {
+        openai: Openai,
+        anthropic: Anthropic
+      }.freeze
+
+      module_function
+
+      def install!(names = LlmCostTracker.configuration.instrumented_integrations)
+        normalize(names).each { |name| fetch(name).install }
+      end
+
+      def checks(names = LlmCostTracker.configuration.instrumented_integrations)
+        return [Base::Result.new(:integrations, :ok, "no SDK integrations enabled")] if names.empty?
+
+        normalize(names).map { |name| fetch(name).status }
+      end
+
+      def normalize(names)
+        Array(names).flatten.map(&:to_sym).uniq
+      end
+
+      def fetch(name)
+        INTEGRATIONS.fetch(name.to_sym) do
+          message = "Unknown integration: #{name.inspect}. Use one of: #{INTEGRATIONS.keys.join(', ')}"
+          raise LlmCostTracker::Error, message
+        end
+      end
+    end
+
+    def self.install! = Registry.install!
+    def self.checks = Registry.checks
+  end
+end

data/lib/llm_cost_tracker/middleware/faraday.rb

@@ -4,6 +4,7 @@ require "faraday"
 require "json"
 
 require_relative "../logging"
+require_relative "../request_url"
 
 module LlmCostTracker
   module Middleware
@@ -76,7 +77,7 @@ module LlmCostTracker
         response_body = read_body(response_env.body)
         unless response_body
           Logging.warn(
-            "Unable to read response body for #{request_url}; " \
+            "Unable to read response body for #{RequestUrl.label(request_url)}; " \
             "streaming responses are captured automatically for OpenAI/Anthropic/Gemini " \
             "or via LlmCostTracker.track_stream for custom clients."
           )
@@ -156,11 +157,11 @@ module LlmCostTracker
 
       def capture_warning(request_url, stream_buffer)
         unless stream_buffer&.dig(:overflowed)
-          return "Unable to capture streaming response for #{request_url}; " \
+          return "Unable to capture streaming response for #{RequestUrl.label(request_url)}; " \
                  "recording usage_source=unknown. Use LlmCostTracker.track_stream for manual capture."
         end
 
-        "Streaming response for #{request_url} exceeded #{STREAM_CAPTURE_LIMIT_BYTES} bytes; " \
+        "Streaming response for #{RequestUrl.label(request_url)} exceeded #{STREAM_CAPTURE_LIMIT_BYTES} bytes; " \
           "recording usage_source=unknown. Use LlmCostTracker.track_stream for manual capture."
       end
     end

data/lib/llm_cost_tracker/parsed_usage.rb

@@ -16,6 +16,7 @@ module LlmCostTracker
   )
 
   class ParsedUsage
+    UNKNOWN_MODEL = "unknown"
     TRACKING_KEYS = %i[
       provider
       model
@@ -30,7 +31,7 @@ module LlmCostTracker
     def self.build(**attributes)
       new(
         provider: attributes.fetch(:provider),
-        model: attributes.fetch(:model),
+        model: normalize_model(attributes.fetch(:model)),
         input_tokens: attributes.fetch(:input_tokens).to_i,
         output_tokens: attributes.fetch(:output_tokens).to_i,
         total_tokens: attributes.fetch(:total_tokens, usage_breakdown(attributes).total_tokens).to_i,
@@ -61,5 +62,11 @@ module LlmCostTracker
       )
     end
     private_class_method :usage_breakdown
+
+    def self.normalize_model(value)
+      model = value.to_s.strip
+      model.empty? ? UNKNOWN_MODEL : model
+    end
+    private_class_method :normalize_model
   end
 end