llm_cost_tracker 0.1.1 → 0.1.3

data/lib/llm_cost_tracker/configuration.rb

@@ -1,25 +1,88 @@
 # frozen_string_literal: true
 
+require_relative "errors"
+
 module LlmCostTracker
   class Configuration
+    # Hostname => provider name for OpenAI-compatible APIs.
+    OPENAI_COMPATIBLE_PROVIDERS = {
+      "openrouter.ai" => "openrouter",
+      "api.deepseek.com" => "deepseek"
+    }.freeze
+
+    BUDGET_EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
+    STORAGE_ERROR_BEHAVIORS = %i[ignore warn raise].freeze
+    STORAGE_BACKENDS = %i[log active_record custom].freeze
+    UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
+
     attr_accessor :enabled,
-                  :storage_backend,    # :log, :active_record, :custom
                   :custom_storage,     # callable object for :custom backend
                   :default_tags,       # Hash of default tags added to every event
                   :on_budget_exceeded, # callable, receives event hash
                   :monthly_budget,     # Float, in USD — nil means no limit
                   :log_level,          # :debug, :info, :warn
+                  :prices_file,        # JSON/YAML file that overrides built-in prices
                   :pricing_overrides   # Hash to override built-in pricing
 
+    attr_reader :budget_exceeded_behavior, # :notify, :raise, :block_requests
+                :storage_backend, # :log, :active_record, :custom
+                :storage_error_behavior, # :ignore, :warn, :raise
+                :unknown_pricing_behavior, # :ignore, :warn, :raise
+                :openai_compatible_providers
+
     def initialize
-      @enabled            = true
-      @storage_backend    = :log
+      @enabled = true
+      self.storage_backend = :log
       @custom_storage     = nil
       @default_tags       = {}
       @on_budget_exceeded = nil
       @monthly_budget     = nil
+      self.budget_exceeded_behavior = :notify
+      self.storage_error_behavior = :warn
+      self.unknown_pricing_behavior = :warn
       @log_level          = :info
+      @prices_file        = nil
       @pricing_overrides  = {}
+      self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
+    end
+
+    def openai_compatible_providers=(providers)
+      @openai_compatible_providers = normalize_openai_compatible_providers(providers)
+    end
+
+    def storage_backend=(value)
+      @storage_backend = normalize_enum(:storage_backend, value, STORAGE_BACKENDS, default: :log)
+    end
+
+    def budget_exceeded_behavior=(value)
+      @budget_exceeded_behavior = normalize_enum(
+        :budget_exceeded_behavior,
+        value,
+        BUDGET_EXCEEDED_BEHAVIORS,
+        default: :notify
+      )
+    end
+
+    def storage_error_behavior=(value)
+      @storage_error_behavior = normalize_enum(
+        :storage_error_behavior,
+        value,
+        STORAGE_ERROR_BEHAVIORS,
+        default: :warn
+      )
+    end
+
+    def unknown_pricing_behavior=(value)
+      @unknown_pricing_behavior = normalize_enum(
+        :unknown_pricing_behavior,
+        value,
+        UNKNOWN_PRICING_BEHAVIORS,
+        default: :warn
+      )
+    end
+
+    def normalize_openai_compatible_providers!
+      self.openai_compatible_providers = openai_compatible_providers
     end
 
     def active_record?
@@ -29,5 +92,21 @@ module LlmCostTracker
     def log?
       storage_backend == :log
     end
+
+    private
+
+    def normalize_enum(name, value, allowed, default:)
+      value = default if value.nil?
+      value = value.to_sym
+      return value if allowed.include?(value)
+
+      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
   end
 end

data/lib/llm_cost_tracker/cost.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "value_object"
+
+module LlmCostTracker
+  Cost = ValueObject.define(
+    :input_cost,
+    :cached_input_cost,
+    :cache_read_input_cost,
+    :cache_creation_input_cost,
+    :output_cost,
+    :total_cost,
+    :currency
+  )
+end

data/lib/llm_cost_tracker/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class Error < StandardError; end
+
+  class BudgetExceededError < Error
+    attr_reader :monthly_total, :budget, :last_event
+
+    def initialize(monthly_total:, budget:, last_event: nil)
+      @monthly_total = monthly_total
+      @budget = budget
+      @last_event = last_event
+
+      super("LLM monthly budget exceeded: $#{format('%.6f', monthly_total)} / $#{format('%.6f', budget)}")
+    end
+  end
+
+  class UnknownPricingError < Error
+    attr_reader :model
+
+    def initialize(model:)
+      @model = model
+
+      super("No pricing configured for LLM model: #{model.inspect}")
+    end
+  end
+
+  class StorageError < Error
+    attr_reader :original_error
+
+    def initialize(original_error)
+      @original_error = original_error
+
+      super("Failed to store LLM cost event: #{original_error.class}: #{original_error.message}")
+    end
+  end
+end

data/lib/llm_cost_tracker/event.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "value_object"
+
+module LlmCostTracker
+  Event = ValueObject.define(
+    :provider,
+    :model,
+    :input_tokens,
+    :output_tokens,
+    :total_tokens,
+    :cost,
+    :tags,
+    :latency_ms,
+    :tracked_at
+  ) do
+    def to_h
+      super.merge(
+        cost: cost&.to_h,
+        tags: tags ? tags.to_h : {}
+      )
+    end
+  end
+end

data/lib/llm_cost_tracker/event_metadata.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module EventMetadata
+    INTERNAL_TAG_KEYS = %w[
+      cache_creation_input_tokens
+      cache_creation_tokens
+      cache_read_input_tokens
+      cache_read_tokens
+      cached_input_tokens
+      input_tokens
+      output_tokens
+      reasoning_tokens
+      total_tokens
+    ].freeze
+
+    class << self
+      def usage_data(input_tokens, output_tokens, metadata)
+        cache_read_input_tokens = integer_metadata(metadata, :cache_read_input_tokens, :cache_read_tokens)
+        cache_creation_input_tokens = integer_metadata(
+          metadata,
+          :cache_creation_input_tokens,
+          :cache_creation_tokens
+        )
+        cached_input_tokens = integer_metadata(metadata, :cached_input_tokens)
+
+        {
+          input_tokens: input_tokens.to_i,
+          output_tokens: output_tokens.to_i,
+          cached_input_tokens: cached_input_tokens,
+          cache_read_input_tokens: cache_read_input_tokens,
+          cache_creation_input_tokens: cache_creation_input_tokens,
+          total_tokens: input_tokens.to_i + output_tokens.to_i +
+            cache_read_input_tokens + cache_creation_input_tokens
+        }
+      end
+
+      def tags(metadata)
+        metadata.reject { |key, _value| INTERNAL_TAG_KEYS.include?(key.to_s) }
+      end
+
+      private
+
+      def integer_metadata(metadata, *keys)
+        keys.each do |key|
+          value = metadata[key] || metadata[key.to_s]
+          return value.to_i unless value.nil?
+        end
+
+        0
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class AddLatencyMsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add llm_api_calls.latency_ms"
+
+      def create_migration_file
+        migration_template(
+          "add_latency_ms_to_llm_api_calls.rb.erb",
+          "db/migrate/add_latency_ms_to_llm_api_calls.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module LlmCostTracker
+  module Generators
+    class PricesGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a local LlmCostTracker price override file"
+
+      def create_prices_file
+        template(
+          "llm_cost_tracker_prices.yml.erb",
+          "config/llm_cost_tracker_prices.yml"
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+class AddLatencyMsToLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_column :llm_api_calls, :latency_ms, :integer unless column_exists?(:llm_api_calls, :latency_ms)
+  end
+
+  def down
+    remove_column :llm_api_calls, :latency_ms if column_exists?(:llm_api_calls, :latency_ms)
+  end
+end

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

@@ -6,10 +6,15 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
       t.integer :input_tokens,  null: false, default: 0
       t.integer :output_tokens, null: false, default: 0
       t.integer :total_tokens,  null: false, default: 0
-      t.decimal :input_cost,    precision: 12, scale: 8
-      t.decimal :output_cost,   precision: 12, scale: 8
-      t.decimal :total_cost,    precision: 12, scale: 8
-      t.text    :tags
+      t.decimal :input_cost,    precision: 20, scale: 8
+      t.decimal :output_cost,   precision: 20, scale: 8
+      t.decimal :total_cost,    precision: 20, scale: 8
+      t.integer :latency_ms
+      if postgresql?
+        t.jsonb :tags, null: false, default: {}
+      else
+        t.text :tags
+      end
       t.datetime :tracked_at,   null: false
 
       t.timestamps
@@ -19,5 +24,12 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
     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, :tags, using: :gin if postgresql?
+  end
+
+  private
+
+  def postgresql?
+    connection.adapter_name.downcase.include?("postgres")
   end
 end

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

@@ -12,6 +12,13 @@ LlmCostTracker.configure do |config|
 
   # Monthly budget in USD. Set to nil to disable budget alerts.
   # config.monthly_budget = 100.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.
   # config.on_budget_exceeded = ->(data) {
@@ -20,8 +27,14 @@ LlmCostTracker.configure do |config|
   #   # Or send a Slack notification, email, etc.
   # }
 
-  # Override built-in pricing for specific models (per 1M tokens, USD)
+  # 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).
   # config.pricing_overrides = {
   #   "my-custom-model" => { input: 1.00, output: 2.00 }
   # }
+
+  # OpenAI-compatible APIs. OpenRouter and DeepSeek are included by default.
+  # config.openai_compatible_providers["llm.my-company.com"] = "internal_gateway"
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/llm_cost_tracker_prices.yml.erb

@@ -0,0 +1,36 @@
+# Local LlmCostTracker price overrides.
+#
+# Add only the models you want to override or add. Built-in prices still come
+# from the gem's prices.json, and Ruby pricing_overrides still take precedence.
+#
+# Units: USD per 1M tokens.
+#
+# Supported price keys:
+# - input
+# - output
+# - cached_input
+# - cache_read_input
+# - cache_creation_input
+#
+# Optional metadata keys, ignored by cost calculation:
+# - _source
+# - _updated
+# - _notes
+#
+# Example: custom fine-tune
+# models:
+#   "ft:gpt-4o-mini:my-org":
+#     input: 0.30
+#     cached_input: 0.15
+#     output: 1.20
+#     _notes: "Internal fine-tune rate"
+#
+# Example: negotiated provider discount
+# models:
+#   "gpt-4o":
+#     input: 2.00
+#     output: 8.00
+#     _source: "Enterprise agreement"
+#     _updated: "2026-04-18"
+
+models:

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

@@ -0,0 +1,15 @@
+class UpgradeLlmApiCallCostPrecision < ActiveRecord::Migration<%= migration_version %>
+  COST_COLUMNS = %i[input_cost output_cost total_cost].freeze
+
+  def up
+    COST_COLUMNS.each do |column|
+      change_column :llm_api_calls, column, :decimal, precision: 20, scale: 8
+    end
+  end
+
+  def down
+    COST_COLUMNS.each do |column|
+      change_column :llm_api_calls, column, :decimal, precision: 12, scale: 8
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+class UpgradeLlmApiCallTagsToJsonb < ActiveRecord::Migration<%= migration_version %>
+  def up
+    unless postgresql?
+      say "Skipping llm_api_calls.tags JSONB upgrade: database adapter is #{connection.adapter_name}."
+      return
+    end
+
+    return if tags_jsonb?
+
+    remove_index :llm_api_calls, :tags if index_exists?(:llm_api_calls, :tags)
+
+    change_column(
+      :llm_api_calls,
+      :tags,
+      :jsonb,
+      using: "CASE WHEN tags IS NULL OR tags = '' THEN '{}'::jsonb ELSE tags::jsonb END",
+      default: {},
+      null: false
+    )
+
+    add_index :llm_api_calls, :tags, using: :gin unless index_exists?(:llm_api_calls, :tags)
+  end
+
+  def down
+    return unless postgresql?
+
+    remove_index :llm_api_calls, :tags if index_exists?(:llm_api_calls, :tags)
+    change_column :llm_api_calls, :tags, :text, using: "tags::text"
+  end
+
+  private
+
+  def postgresql?
+    connection.adapter_name.downcase.include?("postgres")
+  end
+
+  def tags_jsonb?
+    column = connection.columns(:llm_api_calls).find { |candidate| candidate.name == "tags" }
+    column&.sql_type.to_s.downcase == "jsonb"
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_cost_precision_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class UpgradeCostPrecisionGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to widen llm_api_calls cost decimal precision"
+
+      def create_migration_file
+        migration_template(
+          "upgrade_llm_api_call_cost_precision.rb.erb",
+          "db/migrate/upgrade_llm_api_call_cost_precision.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_tags_to_jsonb_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class UpgradeTagsToJsonbGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to upgrade llm_api_calls.tags to PostgreSQL JSONB"
+
+      def create_migration_file
+        migration_template(
+          "upgrade_llm_api_call_tags_to_jsonb.rb.erb",
+          "db/migrate/upgrade_llm_api_call_tags_to_jsonb.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/llm_api_call.rb

@@ -2,15 +2,33 @@
 
 require "active_record"
 
+require_relative "tag_accessors"
+require_relative "tag_query"
+require_relative "tags_column"
+
 module LlmCostTracker
   class LlmApiCall < ActiveRecord::Base
+    extend TagsColumn
+    include TagAccessors
+
     self.table_name = "llm_api_calls"
 
     # Scopes for querying
     scope :by_provider, ->(provider) { where(provider: provider) }
     scope :by_model,    ->(model)    { where(model: model) }
-    scope :by_tag, lambda { |key, value|
-      where("tags LIKE ?", "%\"#{key}\":\"#{value}\"%")
+    scope :by_user,    ->(user_id) { by_tag("user_id", user_id) }
+    scope :by_feature, ->(feature) { by_tag("feature", feature) }
+    scope :with_cost, -> { where.not(total_cost: nil) }
+    scope :without_cost, -> { where(total_cost: nil) }
+    scope :unknown_pricing, -> { without_cost }
+    scope :with_latency, -> { latency_column? ? where.not(latency_ms: nil) : none }
+
+    scope :with_json_tags, lambda {
+      if tags_json_column?
+        where.not(tags: {})
+      else
+        where.not(tags: [nil, "", "{}"])
+      end
     }
 
     scope :today,       -> { where(tracked_at: Time.now.utc.beginning_of_day..) }
@@ -18,6 +36,14 @@ module LlmCostTracker
     scope :this_month,  -> { where(tracked_at: Time.now.utc.beginning_of_month..) }
     scope :between,     ->(from, to) { where(tracked_at: from..to) }
 
+    def self.by_tag(key, value)
+      by_tags(key => value)
+    end
+
+    def self.by_tags(tags)
+      TagQuery.apply(self, tags)
+    end
+
     # Aggregations
     def self.total_cost
       sum(:total_cost).to_f
@@ -35,24 +61,29 @@ module LlmCostTracker
       group(:provider).sum(:total_cost)
     end
 
-    def self.daily_costs(days: 30)
-      where(tracked_at: days.days.ago..)
-        .group("DATE(tracked_at)")
-        .sum(:total_cost)
+    def self.average_latency_ms
+      return nil unless latency_column?
+
+      average(:latency_ms)&.to_f
     end
 
-    def parsed_tags
-      JSON.parse(tags || "{}")
-    rescue JSON::ParserError
-      {}
+    def self.latency_by_model
+      return {} unless latency_column?
+
+      group(:model).average(:latency_ms).transform_values(&:to_f)
     end
 
-    def feature
-      parsed_tags["feature"]
+    def self.latency_by_provider
+      return {} unless latency_column?
+
+      group(:provider).average(:latency_ms).transform_values(&:to_f)
     end
 
-    def user_id
-      parsed_tags["user_id"]
+    def self.daily_costs(days: 30)
+      where(tracked_at: days.days.ago..)
+        .group("DATE(tracked_at)")
+        .sum(:total_cost)
+        .transform_keys(&:to_s)
     end
   end
 end

data/lib/llm_cost_tracker/logging.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Logging
+    PREFIX = "[LlmCostTracker]"
+
+    class << self
+      def debug(message)
+        log(:debug, message)
+      end
+
+      def info(message)
+        log(:info, message)
+      end
+
+      def warn(message)
+        log(:warn, message)
+      end
+
+      def log(level, message)
+        message = prefixed(message)
+
+        if rails_logger
+          rails_logger.public_send(level, message)
+        else
+          Kernel.warn(message)
+        end
+      end
+
+      private
+
+      def prefixed(message)
+        message = message.to_s
+        return message if message.start_with?(PREFIX)
+
+        "#{PREFIX} #{message}"
+      end
+
+      def rails_logger
+        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+      end
+    end
+  end
+end