llm_cost_tracker 0.1.3 → 0.2.0.alpha1

data/lib/llm_cost_tracker/price_registry.rb

@@ -11,54 +11,50 @@ module LlmCostTracker
     EMPTY_PRICES = {}.freeze
     PRICE_KEYS = %w[input cached_input output cache_read_input cache_creation_input].freeze
     METADATA_KEYS = %w[_source _updated _notes].freeze
-    FILE_PRICES_MUTEX = Mutex.new
-    NORMALIZE_PRICE_ENTRY = lambda do |price|
-      (price || {}).each_with_object({}) do |(key, value), normalized|
-        key = key.to_s
-        normalized[key.to_sym] = Float(value) if PRICE_KEYS.include?(key)
-      end
-    end
-    NORMALIZE_PRICE_TABLE = lambda do |table|
-      (table || {}).each_with_object({}) do |(model, price), normalized|
-        normalized[model.to_s] = NORMALIZE_PRICE_ENTRY.call(price)
-      end
-    end
-    RAW_REGISTRY = JSON.parse(File.read(DEFAULT_PRICES_PATH)).freeze
-    PRICE_METADATA = RAW_REGISTRY.fetch("metadata", {}).freeze
-    BUILTIN_PRICES = NORMALIZE_PRICE_TABLE.call(RAW_REGISTRY.fetch("models", {})).freeze
-
-    private_constant :FILE_PRICES_MUTEX
 
     class << self
       def builtin_prices
-        BUILTIN_PRICES
+        @builtin_prices ||= normalize_price_table(raw_registry.fetch("models", {})).freeze
       end
 
       def metadata
-        PRICE_METADATA
+        @metadata ||= raw_registry.fetch("metadata", {}).freeze
       end
 
       def normalize_price_table(table)
-        NORMALIZE_PRICE_TABLE.call(table)
+        (table || {}).each_with_object({}) do |(model, price), normalized|
+          normalized[model.to_s] = normalize_price_entry(price)
+        end
       end
 
       def file_prices(path)
         return EMPTY_PRICES unless path
 
         path = path.to_s
-        FILE_PRICES_MUTEX.synchronize do
-          cache_key = [path, File.mtime(path).to_f]
-          return @file_prices if @file_prices_cache_key == cache_key
+        cache_key = [path, File.mtime(path).to_f]
+        cached = @file_prices_cache
+        return cached[:value] if cached && cached[:key] == cache_key
 
-          @file_prices_cache_key = cache_key
-          @file_prices = normalize_file_prices(price_file_models(load_price_file(path)), path: path).freeze
-        end
+        value = normalize_file_prices(price_file_models(load_price_file(path)), path: path).freeze
+        @file_prices_cache = { key: cache_key, value: value }.freeze
+        value
       rescue Errno::ENOENT, JSON::ParserError, Psych::Exception, ArgumentError, TypeError, NoMethodError => e
         raise Error, "Unable to load prices_file #{path.inspect}: #{e.message}"
       end
 
       private
 
+      def raw_registry
+        @raw_registry ||= JSON.parse(File.read(DEFAULT_PRICES_PATH)).freeze
+      end
+
+      def normalize_price_entry(price)
+        (price || {}).each_with_object({}) do |(key, value), normalized|
+          key = key.to_s
+          normalized[key.to_sym] = Float(value) if PRICE_KEYS.include?(key)
+        end
+      end
+
       def normalize_file_prices(table, path:)
         (table || {}).each_with_object({}) do |(model, price), normalized|
           warn_unknown_keys(model, price, path)
@@ -66,10 +62,6 @@ module LlmCostTracker
         end
       end
 
-      def normalize_price_entry(price)
-        NORMALIZE_PRICE_ENTRY.call(price)
-      end
-
       def warn_unknown_keys(model, price, path)
         unknown_keys = price.keys.map(&:to_s) - PRICE_KEYS - METADATA_KEYS
         return if unknown_keys.empty?

data/lib/llm_cost_tracker/pricing.rb

@@ -4,11 +4,6 @@ module LlmCostTracker
   # Calculates costs from price entries expressed in USD per 1M tokens.
   module Pricing
     PRICES = PriceRegistry.builtin_prices
-    PRICES_MUTEX = Mutex.new
-    SORTED_PRICE_KEYS_MUTEX = Mutex.new
-
-    private_constant :PRICES_MUTEX
-    private_constant :SORTED_PRICE_KEYS_MUTEX
 
     class << self
       # Estimate model cost from token counts.
@@ -61,14 +56,12 @@ module LlmCostTracker
         overrides = PriceRegistry.normalize_price_table(LlmCostTracker.configuration.pricing_overrides)
         cache_key = [file_prices.object_id, LlmCostTracker.configuration.pricing_overrides.hash]
 
-        return @prices if @prices_cache_key == cache_key
-
-        PRICES_MUTEX.synchronize do
-          return @prices if @prices_cache_key == cache_key
+        cached = @prices_cache
+        return cached[:value] if cached && cached[:key] == cache_key
 
-          @prices_cache_key = cache_key
-          @prices = PRICES.merge(file_prices).merge(overrides).freeze
-        end
+        value = PRICES.merge(file_prices).merge(overrides).freeze
+        @prices_cache = { key: cache_key, value: value }.freeze
+        value
       end
 
       private
@@ -120,14 +113,12 @@ module LlmCostTracker
       end
 
       def sorted_price_keys(table)
-        return @sorted_price_keys if @sorted_price_keys_table.equal?(table)
+        cached = @sorted_price_keys_cache
+        return cached[:keys] if cached && cached[:table].equal?(table)
 
-        SORTED_PRICE_KEYS_MUTEX.synchronize do
-          return @sorted_price_keys if @sorted_price_keys_table.equal?(table)
-
-          @sorted_price_keys_table = table
-          @sorted_price_keys = table.keys.sort_by { |key| -key.length }
-        end
+        keys = table.keys.sort_by { |key| -key.length }
+        @sorted_price_keys_cache = { table: table, keys: keys }.freeze
+        keys
       end
     end
   end

data/lib/llm_cost_tracker/report.rb

@@ -13,16 +13,16 @@ module LlmCostTracker
       # @param days [Integer] Number of trailing days to include.
       # @param now [Time] Report end time.
       # @return [String]
-      def generate(days: DEFAULT_DAYS, now: Time.now.utc)
-        ReportFormatter.new(data(days: days, now: now)).to_s
+      def generate(days: DEFAULT_DAYS, now: Time.now.utc, tag_breakdowns: nil)
+        ReportFormatter.new(data(days: days, now: now, tag_breakdowns: tag_breakdowns)).to_s
       rescue LoadError => e
         "Unable to build LLM cost report: ActiveRecord storage is unavailable (#{e.message})"
       rescue StandardError => e
         "Unable to build LLM cost report: #{e.class}: #{e.message}"
       end
 
-      def data(days: DEFAULT_DAYS, now: Time.now.utc)
-        ReportData.build(days: days, now: now)
+      def data(days: DEFAULT_DAYS, now: Time.now.utc, tag_breakdowns: nil)
+        ReportData.build(days: days, now: now, tag_breakdowns: tag_breakdowns)
       end
     end
   end

data/lib/llm_cost_tracker/report_data.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "value_object"
+require "active_support/core_ext/integer/time"
 
 module LlmCostTracker
-  TopCall = ValueObject.define(:provider, :model, :total_cost)
+  TopCall = Data.define(:provider, :model, :total_cost)
 
-  ReportData = ValueObject.define(
+  ReportData = Data.define(
     :days,
     :from_time,
     :to_time,
@@ -15,23 +15,25 @@ module LlmCostTracker
     :unknown_pricing_count,
     :cost_by_provider,
     :cost_by_model,
-    :cost_by_feature,
+    :cost_by_tags,
     :top_calls
   )
 
-  ReportData.const_set(:DEFAULT_DAYS, 30)
-  ReportData.const_set(:TOP_LIMIT, 5)
+  class ReportData
+    DEFAULT_DAYS = 30
+    TOP_LIMIT = 5
 
-  class << ReportData
-    def build(days: ReportData::DEFAULT_DAYS, now: Time.now.utc)
+    def self.build(days: DEFAULT_DAYS, now: Time.now.utc, tag_breakdowns: nil)
       require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
 
       days = normalized_days(days)
-      scope = LlmApiCall.where(tracked_at: from_time(days, now)..now)
+      from = now - days.days
+      scope = LlmApiCall.where(tracked_at: from..now)
+      tag_breakdowns ||= LlmCostTracker.configuration.report_tag_breakdowns || []
 
       new(
         days: days,
-        from_time: from_time(days, now),
+        from_time: from,
         to_time: now,
         total_cost: scope.sum(:total_cost).to_f,
         requests_count: scope.count,
@@ -39,46 +41,38 @@ module LlmCostTracker
         unknown_pricing_count: scope.where(total_cost: nil).count,
         cost_by_provider: cost_by(scope, :provider),
         cost_by_model: cost_by(scope, :model),
-        cost_by_feature: cost_by_feature(scope),
+        cost_by_tags: cost_by_tags(scope, tag_breakdowns),
         top_calls: top_calls(scope)
       )
     end
 
-    private
-
-    def normalized_days(days)
+    def self.normalized_days(days)
       days = days.to_i
-      days.positive? ? days : ReportData::DEFAULT_DAYS
-    end
-
-    def from_time(days, now)
-      now - (days * 86_400)
+      days.positive? ? days : DEFAULT_DAYS
     end
 
-    def average_latency_ms(scope)
+    def self.average_latency_ms(scope)
       return nil unless LlmApiCall.latency_column?
 
       scope.average(:latency_ms)&.to_f
     end
 
-    def cost_by(scope, column)
+    def self.cost_by(scope, column)
       scope.group(column).sum(:total_cost).transform_values(&:to_f).sort_by { |_name, cost| -cost }
     end
 
-    def cost_by_feature(scope)
-      costs = Hash.new(0.0)
-      scope.select(:id, :tags, :total_cost).find_each do |call|
-        costs[call.feature || "(untagged)"] += call.total_cost.to_f
-      end
-      costs.sort_by { |_feature, cost| -cost }
+    def self.cost_by_tags(scope, keys)
+      keys.to_h { |key| [key, scope.cost_by_tag(key).to_a] }
     end
 
-    def top_calls(scope)
+    def self.top_calls(scope)
       scope
         .where.not(total_cost: nil)
         .order(total_cost: :desc)
-        .limit(ReportData::TOP_LIMIT)
+        .limit(TOP_LIMIT)
         .map { |call| TopCall.new(provider: call.provider, model: call.model, total_cost: call.total_cost.to_f) }
     end
+
+    private_class_method :normalized_days, :average_latency_ms, :cost_by, :cost_by_tags, :top_calls
   end
 end

data/lib/llm_cost_tracker/report_formatter.rb

@@ -3,6 +3,8 @@
 module LlmCostTracker
   class ReportFormatter
     TOP_LIMIT = 5
+    NAME_COLUMN_WIDTH = 28
+    TOP_CALL_COLUMN_WIDTH = 32
 
     def initialize(data)
       @data = data
@@ -13,7 +15,7 @@ module LlmCostTracker
       append_summary(lines)
       append_cost_section(lines, "By provider", @data.cost_by_provider)
       append_cost_section(lines, "By model", @data.cost_by_model)
-      append_cost_section(lines, "By feature", @data.cost_by_feature)
+      append_tag_sections(lines)
       append_top_calls(lines)
       lines.join("\n")
     end
@@ -33,7 +35,13 @@ module LlmCostTracker
       return lines << "  none" if rows.empty?
 
       rows.first(TOP_LIMIT).each do |name, cost|
-        lines << "  #{name.to_s.ljust(28)} #{money(cost)}"
+        lines << "  #{name.to_s.ljust(NAME_COLUMN_WIDTH)} #{money(cost)}"
+      end
+    end
+
+    def append_tag_sections(lines)
+      @data.cost_by_tags.each do |tag_key, rows|
+        append_cost_section(lines, "By tag (#{tag_key})", rows)
       end
     end
 
@@ -44,7 +52,7 @@ module LlmCostTracker
 
       @data.top_calls.first(TOP_LIMIT).each do |call|
         label = "#{call.provider}/#{call.model}"
-        lines << "  #{label.ljust(32)} #{money(call.total_cost)}"
+        lines << "  #{label.ljust(TOP_CALL_COLUMN_WIDTH)} #{money(call.total_cost)}"
       end
     end
 

data/lib/llm_cost_tracker/storage/active_record_store.rb

@@ -25,10 +25,8 @@ module LlmCostTracker
         end
 
         def monthly_total(time: Time.now.utc)
-          beginning_of_month = Time.new(time.year, time.month, 1, 0, 0, 0, "+00:00")
-
           model_class
-            .where(tracked_at: beginning_of_month..time)
+            .where(tracked_at: time.beginning_of_month..time)
             .sum(:total_cost)
             .to_f
         end

data/lib/llm_cost_tracker/tag_accessors.rb

@@ -11,13 +11,5 @@ module LlmCostTracker
     rescue JSON::ParserError
       {}
     end
-
-    def feature
-      parsed_tags["feature"]
-    end
-
-    def user_id
-      parsed_tags["user_id"]
-    end
   end
 end

data/lib/llm_cost_tracker/tag_key.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module TagKey
+    PATTERN = /\A[\w.-]+\z/
+
+    class << self
+      def validate!(key, error_class: ArgumentError)
+        key = key.to_s
+        return key if key.match?(PATTERN)
+
+        raise error_class, "invalid tag key: #{key.inspect}"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/tracker.rb

@@ -60,7 +60,11 @@ module LlmCostTracker
 
       def store(event)
         config = LlmCostTracker.configuration
-        Storage::Backends.fetch(config.storage_backend).save(event, config: config)
+        case config.storage_backend
+        when :log            then log_event(event, config)
+        when :active_record  then active_record_save(event)
+        when :custom         then custom_save(event, config)
+        end
       rescue BudgetExceededError, UnknownPricingError
         raise
       rescue StandardError => e
@@ -68,6 +72,36 @@ module LlmCostTracker
         false
       end
 
+      def log_event(event, config)
+        message = "#{event.provider}/#{event.model} " \
+                  "tokens=#{event.input_tokens}+#{event.output_tokens} " \
+                  "cost=#{log_cost_label(event)}"
+        message += " latency=#{event.latency_ms}ms" if event.latency_ms
+        message += " tags=#{event.tags}" unless event.tags.empty?
+
+        Logging.log(config.log_level, message)
+        event
+      end
+
+      def log_cost_label(event)
+        event.cost ? "$#{format('%.6f', event.cost.total_cost)}" : "unknown"
+      end
+
+      def active_record_save(event)
+        require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+        require_relative "storage/active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
+
+        Storage::ActiveRecordStore.save(event)
+        event
+      rescue LoadError => e
+        raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
+      end
+
+      def custom_save(event, config)
+        result = config.custom_storage&.call(event)
+        result == false ? false : event
+      end
+
       def handle_storage_error(error)
         case LlmCostTracker.configuration.storage_error_behavior
         when :ignore

data/lib/llm_cost_tracker/unknown_pricing.rb

@@ -27,7 +27,7 @@ module LlmCostTracker
       def warn_missing(model)
         Logging.warn(
           "No pricing configured for model #{model.inspect}. " \
-          "Cost and budget enforcement will be skipped for this event. " \
+          "Cost and budget guardrails will be skipped for this event. " \
           "Add a pricing_overrides entry or set unknown_pricing_behavior."
         )
       end

data/lib/llm_cost_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmCostTracker
-  VERSION = "0.1.3"
+  VERSION = "0.2.0.alpha1"
 end

data/lib/llm_cost_tracker.rb

@@ -7,7 +7,6 @@ require_relative "llm_cost_tracker/version"
 require_relative "llm_cost_tracker/configuration"
 require_relative "llm_cost_tracker/errors"
 require_relative "llm_cost_tracker/logging"
-require_relative "llm_cost_tracker/value_object"
 require_relative "llm_cost_tracker/cost"
 require_relative "llm_cost_tracker/event"
 require_relative "llm_cost_tracker/parsed_usage"
@@ -25,9 +24,9 @@ require_relative "llm_cost_tracker/budget"
 require_relative "llm_cost_tracker/unknown_pricing"
 require_relative "llm_cost_tracker/event_metadata"
 require_relative "llm_cost_tracker/tags_column"
+require_relative "llm_cost_tracker/tag_key"
 require_relative "llm_cost_tracker/tag_query"
 require_relative "llm_cost_tracker/tag_accessors"
-require_relative "llm_cost_tracker/storage/backends"
 require_relative "llm_cost_tracker/tracker"
 require_relative "llm_cost_tracker/report_data"
 require_relative "llm_cost_tracker/report_formatter"
@@ -35,12 +34,10 @@ require_relative "llm_cost_tracker/report"
 
 module LlmCostTracker
   class << self
-    CONFIGURATION_MUTEX = Mutex.new
-
     attr_writer :configuration
 
     def configuration
-      @configuration || CONFIGURATION_MUTEX.synchronize { @configuration ||= Configuration.new }
+      @configuration ||= Configuration.new
     end
 
     # Configure the gem once during application boot.
@@ -54,7 +51,7 @@ module LlmCostTracker
     end
 
     def reset_configuration!
-      CONFIGURATION_MUTEX.synchronize { @configuration = Configuration.new }
+      @configuration = Configuration.new
     end
 
     # Track an LLM request manually for non-Faraday clients.

data/llm_cost_tracker.gemspec

@@ -12,32 +12,36 @@ Gem::Specification.new do |spec|
   spec.description   = "Tracks token usage and estimated costs for OpenAI, Anthropic, Google Gemini, " \
                        "OpenRouter, DeepSeek, and OpenAI-compatible calls. " \
                        "Works as Faraday middleware for Ruby clients, with ActiveRecord storage, " \
-                       "per-user/per-feature attribution, budget alerts, and budget enforcement."
+                       "arbitrary tag-based attribution, and budget guardrails."
   spec.homepage      = "https://github.com/sergey-homenko/llm_cost_tracker"
   spec.license       = "MIT"
 
-  spec.required_ruby_version = ">= 3.1.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
-  spec.metadata["homepage_uri"]  = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?("bin/", "test/", "spec/", ".git", ".github", "Gemfile")
+        f.start_with?("bin/", "test/", "spec/", ".git", ".github", "gemfiles/", ".rubocop", "Gemfile")
     end
   end
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activesupport", ">= 7.0", "< 9.0"
-  spec.add_dependency "faraday", ">= 1.0", "< 3.0"
+  spec.add_dependency "activesupport", ">= 7.1", "< 9.0"
+  spec.add_dependency "csv", ">= 3.0"
+  spec.add_dependency "faraday", ">= 2.0", "< 3.0"
 
-  spec.add_development_dependency "activerecord", ">= 7.0", "< 9.0"
+  spec.add_development_dependency "activerecord", ">= 7.1", "< 9.0"
+  spec.add_development_dependency "railties", ">= 7.1", "< 9.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rubocop", "~> 1.0"
-  spec.add_development_dependency "sqlite3", "~> 2.0"
+  spec.add_development_dependency "sqlite3", ">= 1.4", "< 3.0"
   spec.add_development_dependency "webmock", "~> 3.0"
 end