llm_cost_tracker 0.4.1 → 0.5.0

data/lib/llm_cost_tracker/configuration.rb

@@ -2,9 +2,12 @@
 
 require_relative "errors"
 require_relative "value_helpers"
+require_relative "configuration/instrumentation"
 
 module LlmCostTracker
   class Configuration
+    include ConfigurationInstrumentation
+
     OPENAI_COMPATIBLE_PROVIDERS = {
       "openrouter.ai" => "openrouter",
       "api.deepseek.com" => "deepseek"
@@ -36,6 +39,7 @@ module LlmCostTracker
       :budget_exceeded_behavior,
       :default_tags,
       :pricing_overrides,
+      :instrumented_integrations,
       :report_tag_breakdowns,
       :storage_backend,
       :storage_error_behavior,
@@ -58,6 +62,7 @@ module LlmCostTracker
       @log_level          = :info
       @prices_file        = nil
       @pricing_overrides  = {}
+      @instrumented_integrations = []
       @report_tag_breakdowns = []
       self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
       @finalized = false
@@ -97,13 +102,10 @@ module LlmCostTracker
       end
     end
 
-    def normalize_openai_compatible_providers!
-      self.openai_compatible_providers = openai_compatible_providers
-    end
-
     def finalize!
       @default_tags = ValueHelpers.deep_freeze(@default_tags || {})
       @pricing_overrides = ValueHelpers.deep_freeze(@pricing_overrides || {})
+      @instrumented_integrations = ValueHelpers.deep_freeze(@instrumented_integrations || [])
       @report_tag_breakdowns = ValueHelpers.deep_freeze(Array(@report_tag_breakdowns))
       @openai_compatible_providers = ValueHelpers.deep_freeze(@openai_compatible_providers || {})
       @finalized = true
@@ -116,6 +118,10 @@ module LlmCostTracker
       copy = dup
       copy.instance_variable_set(:@default_tags, ValueHelpers.deep_dup(@default_tags || {}))
       copy.instance_variable_set(:@pricing_overrides, ValueHelpers.deep_dup(@pricing_overrides || {}))
+      copy.instance_variable_set(
+        :@instrumented_integrations,
+        ValueHelpers.deep_dup(@instrumented_integrations || [])
+      )
       copy.instance_variable_set(:@report_tag_breakdowns, ValueHelpers.deep_dup(@report_tag_breakdowns || []))
       copy.instance_variable_set(
         :@openai_compatible_providers,
@@ -126,7 +132,6 @@ module LlmCostTracker
     end
 
     def active_record? = storage_backend == :active_record
-    def log? = storage_backend == :log
 
     private
 

data/lib/llm_cost_tracker/doctor.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "price_freshness"
+
+module LlmCostTracker
+  class Doctor
+    Check = Data.define(:status, :name, :message)
+    CORE_COLUMNS = %w[provider model input_tokens output_tokens total_tokens total_cost tags tracked_at].freeze
+    FEATURE_COLUMNS = {
+      "latency_ms" => "bin/rails generate llm_cost_tracker:add_latency_ms",
+      "stream" => "bin/rails generate llm_cost_tracker:add_streaming",
+      "usage_source" => "bin/rails generate llm_cost_tracker:add_streaming",
+      "provider_response_id" => "bin/rails generate llm_cost_tracker:add_provider_response_id",
+      "cache_read_input_tokens" => "bin/rails generate llm_cost_tracker:add_usage_breakdown",
+      "cache_write_input_tokens" => "bin/rails generate llm_cost_tracker:add_usage_breakdown",
+      "hidden_output_tokens" => "bin/rails generate llm_cost_tracker:add_usage_breakdown",
+      "pricing_mode" => "bin/rails generate llm_cost_tracker:add_usage_breakdown"
+    }.freeze
+
+    class << self
+      def call = new.checks
+
+      def report(checks = call)
+        (["LLM Cost Tracker doctor"] + checks.map { |check| format_check(check) }).join("\n")
+      end
+
+      def healthy?(checks = call)
+        checks.none? { |check| check.status == :error }
+      end
+
+      private
+
+      def format_check(check)
+        "[#{check.status}] #{check.name}: #{check.message}"
+      end
+    end
+
+    def checks
+      [
+        configuration_check,
+        *integration_checks,
+        active_record_check,
+        table_check,
+        column_check,
+        period_totals_check,
+        prices_check,
+        calls_check
+      ].compact
+    end
+
+    private
+
+    def configuration_check
+      Check.new(:ok, "configuration", "storage_backend=#{LlmCostTracker.configuration.storage_backend.inspect}")
+    end
+
+    def integration_checks
+      LlmCostTracker::Integrations.checks.map do |check|
+        Check.new(check.status, check.name.to_s, check.message)
+      end
+    end
+
+    def active_record_check
+      return Check.new(:ok, "storage", "ActiveRecord storage is disabled") unless active_record_storage?
+      return Check.new(:ok, "active_record", "available") if active_record_available?
+
+      Check.new(:error, "active_record", "unavailable; add ActiveRecord/Rails or change storage_backend")
+    end
+
+    def table_check
+      return unless active_record_storage? && active_record_available?
+      return Check.new(:ok, "llm_api_calls", "table exists") if llm_api_calls_table?
+
+      Check.new(
+        :error,
+        "llm_api_calls",
+        "missing; run bin/rails generate llm_cost_tracker:install && bin/rails db:migrate"
+      )
+    end
+
+    def column_check
+      return unless active_record_storage? && llm_api_calls_table?
+
+      columns = column_names("llm_api_calls")
+      missing_core = CORE_COLUMNS - columns
+      missing_features = FEATURE_COLUMNS.keys - columns
+      if missing_core.any?
+        return Check.new(:error, "llm_api_calls columns", "missing core columns: #{missing_core.join(', ')}")
+      end
+      if missing_features.any?
+        return Check.new(
+          :warn,
+          "llm_api_calls columns",
+          "missing optional columns; run #{feature_generators(missing_features).join(' && ')}"
+        )
+      end
+
+      Check.new(:ok, "llm_api_calls columns", "current")
+    end
+
+    def period_totals_check
+      return unless active_record_storage? && llm_api_calls_table?
+      if table_exists?("llm_cost_tracker_period_totals")
+        return Check.new(:ok, "period totals", "llm_cost_tracker_period_totals exists")
+      end
+
+      Check.new(:warn, "period totals", "missing; budget preflight falls back to llm_api_calls sums")
+    end
+
+    def prices_check
+      path = LlmCostTracker.configuration.prices_file
+      unless path
+        return Check.new(
+          :warn,
+          "prices",
+          "using bundled prices updated_at=#{builtin_prices_updated_at}; configure prices_file for production"
+        )
+      end
+
+      count = LlmCostTracker::PriceRegistry.file_prices(path).size
+      metadata = LlmCostTracker::PriceRegistry.file_metadata(path)
+      status, freshness = LlmCostTracker::PriceFreshness.call(metadata)
+      Check.new(status, "prices", "loaded #{count} models from #{path}; #{freshness}")
+    rescue LlmCostTracker::Error => e
+      Check.new(:error, "prices", e.message)
+    end
+
+    def calls_check
+      return unless active_record_storage? && llm_api_calls_table?
+
+      count = LlmCostTracker::LlmApiCall.count
+      return Check.new(:warn, "tracked calls", "none recorded yet") if count.zero?
+
+      latest = LlmCostTracker::LlmApiCall.maximum(:tracked_at)&.utc&.iso8601
+      Check.new(:ok, "tracked calls", "#{count} recorded; latest #{latest}")
+    end
+
+    def active_record_storage? = LlmCostTracker.configuration.storage_backend == :active_record
+
+    def active_record_available?
+      require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+      LlmCostTracker::LlmApiCall.connection
+      true
+    rescue LoadError, StandardError
+      false
+    end
+
+    def llm_api_calls_table?
+      active_record_available? && table_exists?("llm_api_calls")
+    end
+
+    def table_exists?(name)
+      LlmCostTracker::LlmApiCall.connection.data_source_exists?(name)
+    rescue StandardError
+      false
+    end
+
+    def column_names(table) = LlmCostTracker::LlmApiCall.connection.columns(table).map(&:name)
+
+    def feature_generators(columns) = columns.map { |column| FEATURE_COLUMNS.fetch(column) }.uniq
+
+    def builtin_prices_updated_at
+      LlmCostTracker::Pricing.metadata.fetch("updated_at", "unknown")
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb

@@ -11,6 +11,8 @@ module LlmCostTracker
       source_root File.expand_path("templates", __dir__)
 
       desc "Creates the LlmCostTracker migration and initializer"
+      class_option :dashboard, type: :boolean, default: false
+      class_option :prices, type: :boolean, default: false
 
       def create_migration_file
         migration_template(
@@ -26,11 +28,42 @@ module LlmCostTracker
         )
       end
 
+      def create_prices_file
+        return unless options[:prices]
+
+        invoke "llm_cost_tracker:prices"
+      end
+
+      def mount_engine
+        return unless options[:dashboard]
+
+        add_engine_require
+        route %(mount LlmCostTracker::Engine => "/llm-costs")
+      end
+
       private
 
       def migration_version
         "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
       end
+
+      def add_engine_require
+        return unless File.exist?("config/application.rb")
+
+        contents = File.read("config/application.rb")
+        return if contents.include?(%(require "llm_cost_tracker/engine"))
+
+        unless contents.include?(%(require "rails/all"\n))
+          prepend_to_file("config/application.rb", %(require "llm_cost_tracker/engine"\n))
+          return
+        end
+
+        inject_into_file(
+          "config/application.rb",
+          %(require "llm_cost_tracker/engine"\n),
+          after: %(require "rails/all"\n)
+        )
+      end
     end
   end
 end

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