llm_cost_tracker 0.1.1 → 0.1.3

data/lib/llm_cost_tracker/tracker.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "logging"
+
 module LlmCostTracker
   class Tracker
     EVENT_NAME = "llm_request.llm_cost_tracker"
 
     class << self
-      def record(provider:, model:, input_tokens:, output_tokens:, metadata: {})
-        usage = usage_data(input_tokens, output_tokens, metadata)
+      def enforce_budget!
+        Budget.enforce!
+      end
+
+      # Build, notify, persist, and budget-check a single LLM usage event.
+      #
+      # @param provider [String] Provider name.
+      # @param model [String] Model identifier.
+      # @param input_tokens [Integer] Input token count.
+      # @param output_tokens [Integer] Output token count.
+      # @param metadata [Hash] Attribution tags plus provider-specific usage metadata.
+      # @param latency_ms [Integer, nil] Optional latency in milliseconds.
+      # @return [LlmCostTracker::Event]
+      def record(provider:, model:, input_tokens:, output_tokens:, metadata: {}, latency_ms: nil)
+        usage = EventMetadata.usage_data(input_tokens, output_tokens, metadata)
 
         cost_data = Pricing.cost_for(
           model: model,
@@ -17,25 +32,26 @@ module LlmCostTracker
           cache_creation_input_tokens: usage[:cache_creation_input_tokens]
         )
 
-        event = {
+        UnknownPricing.handle!(model) unless cost_data
+
+        event = Event.new(
           provider: provider,
           model: model,
           input_tokens: usage[:input_tokens],
           output_tokens: usage[:output_tokens],
           total_tokens: usage[:total_tokens],
           cost: cost_data,
-          tags: LlmCostTracker.configuration.default_tags.merge(metadata),
+          tags: LlmCostTracker.configuration.default_tags.merge(EventMetadata.tags(metadata)).freeze,
+          latency_ms: normalized_latency_ms(latency_ms),
           tracked_at: Time.now.utc
-        }
+        )
 
         # Emit ActiveSupport::Notifications event
-        ActiveSupport::Notifications.instrument(EVENT_NAME, event)
+        ActiveSupport::Notifications.instrument(EVENT_NAME, event.to_h)
 
         # Store based on backend
-        store(event)
-
-        # Budget check
-        check_budget(event)
+        stored = store(event)
+        Budget.check!(event) unless stored == false
 
         event
       end
@@ -44,100 +60,30 @@ module LlmCostTracker
 
       def store(event)
         config = LlmCostTracker.configuration
-
-        case config.storage_backend
-        when :log
-          log_event(event)
-        when :active_record
-          store_active_record(event)
-        when :custom
-          config.custom_storage&.call(event)
-        end
+        Storage::Backends.fetch(config.storage_backend).save(event, config: config)
+      rescue BudgetExceededError, UnknownPricingError
+        raise
+      rescue StandardError => e
+        handle_storage_error(e)
+        false
       end
 
-      def log_event(event)
-        cost_str = event[:cost] ? "$#{format('%.6f', event[:cost][:total_cost])}" : "unknown"
-
-        message = "[LlmCostTracker] #{event[:provider]}/#{event[:model]} " \
-                  "tokens=#{event[:input_tokens]}+#{event[:output_tokens]} " \
-                  "cost=#{cost_str}"
-        message += " tags=#{event[:tags]}" unless event[:tags].empty?
-
-        case LlmCostTracker.configuration.log_level
-        when :debug
-          Rails.logger.debug(message) if defined?(Rails)
+      def handle_storage_error(error)
+        case LlmCostTracker.configuration.storage_error_behavior
+        when :ignore
+          nil
         when :warn
-          Rails.logger.warn(message) if defined?(Rails)
-        else
-          Rails.logger.info(message) if defined?(Rails)
-        end
-
-        # Fallback if Rails is not available
-        warn(message) unless defined?(Rails)
-      end
-
-      def store_active_record(event)
-        require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
-        require_relative "storage/active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
-
-        LlmCostTracker::Storage::ActiveRecordStore.save(event)
-      rescue LoadError => e
-        raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
-      end
-
-      def check_budget(event)
-        config = LlmCostTracker.configuration
-        return unless config.monthly_budget && config.on_budget_exceeded
-        return unless event[:cost]
-
-        monthly_total = calculate_monthly_total(event[:cost][:total_cost])
-        return unless monthly_total > config.monthly_budget
-
-        config.on_budget_exceeded.call(
-          monthly_total: monthly_total,
-          budget: config.monthly_budget,
-          last_event: event
-        )
-      end
-
-      def calculate_monthly_total(latest_cost)
-        # For :active_record backend, query the DB
-        if LlmCostTracker.configuration.active_record? &&
-           defined?(LlmCostTracker::Storage::ActiveRecordStore)
-          LlmCostTracker::Storage::ActiveRecordStore.monthly_total
-        else
-          # For other backends, we can only report the latest cost
-          latest_cost
+          Logging.warn("Storage failed; tracking event was not persisted: #{error.class}: #{error.message}")
+        when :raise
+          storage_error = StorageError.new(error)
+          raise storage_error
         end
       end
 
-      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 integer_metadata(metadata, *keys)
-        keys.each do |key|
-          value = metadata[key] || metadata[key.to_s]
-          return value.to_i unless value.nil?
-        end
+      def normalized_latency_ms(latency_ms)
+        return nil if latency_ms.nil?
 
-        0
+        [latency_ms.to_i, 0].max
       end
     end
   end

data/lib/llm_cost_tracker/unknown_pricing.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "logging"
+
+module LlmCostTracker
+  class UnknownPricing
+    class << self
+      def handle!(model)
+        model = normalized_model_name(model)
+
+        case behavior
+        when :ignore
+          nil
+        when :warn
+          warn_missing(model)
+        when :raise
+          raise UnknownPricingError.new(model: model)
+        end
+      end
+
+      private
+
+      def normalized_model_name(model)
+        model.to_s.empty? ? "unknown" : model.to_s
+      end
+
+      def warn_missing(model)
+        Logging.warn(
+          "No pricing configured for model #{model.inspect}. " \
+          "Cost and budget enforcement will be skipped for this event. " \
+          "Add a pricing_overrides entry or set unknown_pricing_behavior."
+        )
+      end
+
+      def behavior
+        LlmCostTracker.configuration.unknown_pricing_behavior
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/value_object.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ValueObject
+    class << self
+      def define(*members, &block)
+        klass = data_class(*members)
+        add_hash_like_readers(klass)
+        klass.class_eval(&block) if block
+        klass
+      end
+
+      private
+
+      def data_class(*members)
+        return Data.define(*members) if defined?(Data)
+
+        Struct.new(*members, keyword_init: true) do
+          def initialize(**kwargs)
+            super
+            freeze
+          end
+        end
+      end
+
+      def add_hash_like_readers(klass)
+        klass.class_eval do
+          def [](key)
+            public_send(key.to_sym)
+          end
+
+          def dig(key, *rest)
+            value = self[key]
+            rest.empty? ? value : value&.dig(*rest)
+          end
+
+          def except(*keys)
+            excluded = keys.map(&:to_sym)
+            to_h.reject { |key, _value| excluded.include?(key.to_sym) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/version.rb

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

data/lib/llm_cost_tracker.rb

@@ -5,34 +5,59 @@ require "active_support/notifications"
 
 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"
+require_relative "llm_cost_tracker/price_registry"
 require_relative "llm_cost_tracker/pricing"
 require_relative "llm_cost_tracker/parsers/base"
+require_relative "llm_cost_tracker/parsers/openai_usage"
 require_relative "llm_cost_tracker/parsers/openai"
+require_relative "llm_cost_tracker/parsers/openai_compatible"
 require_relative "llm_cost_tracker/parsers/anthropic"
 require_relative "llm_cost_tracker/parsers/gemini"
 require_relative "llm_cost_tracker/parsers/registry"
 require_relative "llm_cost_tracker/middleware/faraday"
+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_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"
+require_relative "llm_cost_tracker/report"
 
 module LlmCostTracker
-  class Error < StandardError; end
-
   class << self
+    CONFIGURATION_MUTEX = Mutex.new
+
     attr_writer :configuration
 
     def configuration
-      @configuration ||= Configuration.new
+      @configuration || CONFIGURATION_MUTEX.synchronize { @configuration ||= Configuration.new }
     end
 
+    # Configure the gem once during application boot.
+    #
+    # @yieldparam configuration [LlmCostTracker::Configuration]
+    # @return [void]
     def configure
       yield(configuration)
+      configuration.normalize_openai_compatible_providers!
+      warn_for_configuration!
     end
 
     def reset_configuration!
-      @configuration = Configuration.new
+      CONFIGURATION_MUTEX.synchronize { @configuration = Configuration.new }
     end
 
-    # Manual tracking for non-Faraday clients
+    # Track an LLM request manually for non-Faraday clients.
     #
     #   LlmCostTracker.track(
     #     provider: :openai,
@@ -42,15 +67,33 @@ module LlmCostTracker
     #     feature: "chat",
     #     user_id: current_user.id
     #   )
-    def track(provider:, model:, input_tokens:, output_tokens:, **metadata)
+    #
+    # @param provider [String, Symbol] Provider name, such as :openai or :anthropic.
+    # @param model [String] Provider model identifier.
+    # @param input_tokens [Integer] Billed input token count.
+    # @param output_tokens [Integer] Billed output token count.
+    # @param latency_ms [Integer, nil] Optional request latency in milliseconds.
+    # @param metadata [Hash] Attribution tags and provider-specific usage metadata.
+    # @return [LlmCostTracker::Event] The tracked event.
+    def track(provider:, model:, input_tokens:, output_tokens:, latency_ms: nil, **metadata)
       Tracker.record(
         provider: provider.to_s,
         model: model,
         input_tokens: input_tokens,
         output_tokens: output_tokens,
+        latency_ms: latency_ms,
         metadata: metadata
       )
     end
+
+    private
+
+    def warn_for_configuration!
+      return unless configuration.budget_exceeded_behavior == :block_requests
+      return if configuration.active_record?
+
+      Logging.warn(":block_requests requires storage_backend = :active_record; preflight blocking will be skipped.")
+    end
   end
 end
 

data/lib/tasks/llm_cost_tracker.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :llm_cost_tracker do
+  desc "Print an LLM cost report from ActiveRecord storage"
+  task report: :environment do
+    days = (ENV["DAYS"] || LlmCostTracker::Report::DEFAULT_DAYS).to_i
+    puts LlmCostTracker::Report.generate(days: days)
+  end
+end

data/llm_cost_tracker.gemspec

@@ -8,10 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Sergii Khomenko"]
   spec.email         = ["sergey@mm.st"]
 
-  spec.summary       = "Self-hosted LLM API cost tracking for Ruby and Rails"
-  spec.description   = "Tracks token usage and estimated costs for OpenAI, Anthropic, and Google Gemini calls. " \
+  spec.summary       = "Self-hosted LLM API cost guardrails for Ruby and Rails"
+  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, and budget alerts."
+                       "per-user/per-feature attribution, budget alerts, and budget enforcement."
   spec.homepage      = "https://github.com/sergey-homenko/llm_cost_tracker"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-17 00:00:00.000000000 Z
+date: 2026-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -140,9 +140,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Tracks token usage and estimated costs for OpenAI, Anthropic, and Google
-  Gemini calls. Works as Faraday middleware for Ruby clients, with ActiveRecord storage,
-  per-user/per-feature attribution, and budget alerts.
+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.
 email:
 - sergey@mm.st
 executables: []
@@ -156,22 +157,54 @@ files:
 - README.md
 - Rakefile
 - lib/llm_cost_tracker.rb
+- lib/llm_cost_tracker/budget.rb
 - lib/llm_cost_tracker/configuration.rb
+- lib/llm_cost_tracker/cost.rb
+- lib/llm_cost_tracker/errors.rb
+- lib/llm_cost_tracker/event.rb
+- lib/llm_cost_tracker/event_metadata.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/prices_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_latency_ms_to_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/initializer.rb.erb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/llm_cost_tracker_prices.yml.erb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_llm_api_call_cost_precision.rb.erb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_llm_api_call_tags_to_jsonb.rb.erb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_cost_precision_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_tags_to_jsonb_generator.rb
 - lib/llm_cost_tracker/llm_api_call.rb
+- lib/llm_cost_tracker/logging.rb
 - lib/llm_cost_tracker/middleware/faraday.rb
+- lib/llm_cost_tracker/parsed_usage.rb
 - lib/llm_cost_tracker/parsers/anthropic.rb
 - lib/llm_cost_tracker/parsers/base.rb
 - lib/llm_cost_tracker/parsers/gemini.rb
 - lib/llm_cost_tracker/parsers/openai.rb
+- lib/llm_cost_tracker/parsers/openai_compatible.rb
+- lib/llm_cost_tracker/parsers/openai_usage.rb
 - lib/llm_cost_tracker/parsers/registry.rb
+- lib/llm_cost_tracker/price_registry.rb
+- lib/llm_cost_tracker/prices.json
 - lib/llm_cost_tracker/pricing.rb
 - lib/llm_cost_tracker/railtie.rb
+- lib/llm_cost_tracker/report.rb
+- lib/llm_cost_tracker/report_data.rb
+- lib/llm_cost_tracker/report_formatter.rb
+- lib/llm_cost_tracker/storage/active_record_backend.rb
 - lib/llm_cost_tracker/storage/active_record_store.rb
+- lib/llm_cost_tracker/storage/backends.rb
+- lib/llm_cost_tracker/storage/custom_backend.rb
+- lib/llm_cost_tracker/storage/log_backend.rb
+- lib/llm_cost_tracker/tag_accessors.rb
+- lib/llm_cost_tracker/tag_query.rb
+- lib/llm_cost_tracker/tags_column.rb
 - lib/llm_cost_tracker/tracker.rb
+- lib/llm_cost_tracker/unknown_pricing.rb
+- lib/llm_cost_tracker/value_object.rb
 - lib/llm_cost_tracker/version.rb
+- lib/tasks/llm_cost_tracker.rake
 - llm_cost_tracker.gemspec
 homepage: https://github.com/sergey-homenko/llm_cost_tracker
 licenses:
@@ -198,5 +231,5 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: Self-hosted LLM API cost tracking for Ruby and Rails
+summary: Self-hosted LLM API cost guardrails for Ruby and Rails
 test_files: []