llm_cost_tracker 0.1.2 → 0.1.3

data/lib/llm_cost_tracker/storage/active_record_store.rb

@@ -5,21 +5,21 @@ module LlmCostTracker
     class ActiveRecordStore
       class << self
         def save(event)
-          tags = stringify_tags(event[:tags] || {})
+          tags = stringify_tags(event.tags || {})
 
           attributes = {
-            provider:      event[:provider],
-            model:         event[:model],
-            input_tokens:  event[:input_tokens],
-            output_tokens: event[:output_tokens],
-            total_tokens:  event[:total_tokens],
-            input_cost:    event.dig(:cost, :input_cost),
-            output_cost:   event.dig(:cost, :output_cost),
-            total_cost:    event.dig(:cost, :total_cost),
+            provider:      event.provider,
+            model:         event.model,
+            input_tokens:  event.input_tokens,
+            output_tokens: event.output_tokens,
+            total_tokens:  event.total_tokens,
+            input_cost:    event.cost&.input_cost,
+            output_cost:   event.cost&.output_cost,
+            total_cost:    event.cost&.total_cost,
             tags:          tags_for_storage(tags),
-            tracked_at:    event[:tracked_at]
+            tracked_at:    event.tracked_at
           }
-          attributes[:latency_ms] = event[:latency_ms] if model_class.latency_column?
+          attributes[:latency_ms] = event.latency_ms if model_class.latency_column?
 
           model_class.create!(attributes)
         end

data/lib/llm_cost_tracker/storage/backends.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "log_backend"
+require_relative "active_record_backend"
+require_relative "custom_backend"
+
+module LlmCostTracker
+  module Storage
+    module Backends
+      MAP = {
+        log: LogBackend,
+        active_record: ActiveRecordBackend,
+        custom: CustomBackend
+      }.freeze
+
+      class << self
+        def fetch(name)
+          MAP.fetch(name.to_sym)
+        rescue KeyError
+          raise Error, "Unknown storage_backend: #{name.inspect}. Use one of: #{MAP.keys.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/storage/custom_backend.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Storage
+    module CustomBackend
+      class << self
+        def save(event, config:)
+          result = config.custom_storage&.call(event)
+          return false if result == false
+
+          event
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/storage/log_backend.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../logging"
+
+module LlmCostTracker
+  module Storage
+    module LogBackend
+      class << self
+        def save(event, config:)
+          message = "#{event.provider}/#{event.model} " \
+                    "tokens=#{event.input_tokens}+#{event.output_tokens} " \
+                    "cost=#{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
+
+        private
+
+        def cost_label(event)
+          event.cost ? "$#{format('%.6f', event.cost.total_cost)}" : "unknown"
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/tag_accessors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LlmCostTracker
+  module TagAccessors
+    def parsed_tags
+      return tags.transform_keys(&:to_s) if tags.is_a?(Hash)
+
+      JSON.parse(tags || "{}")
+    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_query.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LlmCostTracker
+  module TagQuery
+    class << self
+      def apply(model, tags)
+        normalized_tags = normalize_tags(tags)
+        return model.all if normalized_tags.empty?
+
+        return json_query(model, normalized_tags) if model.tags_json_column?
+
+        text_query(model, normalized_tags)
+      end
+
+      def normalize_tags(tags)
+        (tags || {}).to_h.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      private
+
+      def json_query(model, tags)
+        model.where("tags @> ?::jsonb", tags.to_json)
+      end
+
+      def text_query(model, tags)
+        tags.reduce(model.all) do |relation, (key, value)|
+          relation.where("tags LIKE ? ESCAPE '\\'", "%#{model.sanitize_sql_like(json_tag_fragment(key, value))}%")
+        end
+      end
+
+      def json_tag_fragment(key, value)
+        JSON.generate(key => value).delete_prefix("{").delete_suffix("}")
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/tags_column.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module TagsColumn
+    def tags_json_column?
+      column = columns_hash["tags"]
+      return false unless column
+
+      %i[json jsonb].include?(column.type) || column.sql_type.to_s.downcase == "jsonb"
+    end
+
+    def latency_column?
+      columns_hash.key?("latency_ms")
+    end
+  end
+end

data/lib/llm_cost_tracker/tracker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "logging"
+
 module LlmCostTracker
   class Tracker
     EVENT_NAME = "llm_request.llm_cost_tracker"
@@ -9,6 +11,15 @@ module LlmCostTracker
         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)
 
@@ -23,20 +34,20 @@ module LlmCostTracker
 
         UnknownPricing.handle!(model) unless cost_data
 
-        event = {
+        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(EventMetadata.tags(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
         stored = store(event)
@@ -49,17 +60,7 @@ 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
-
-        true
+        Storage::Backends.fetch(config.storage_backend).save(event, config: config)
       rescue BudgetExceededError, UnknownPricingError
         raise
       rescue StandardError => e
@@ -67,68 +68,18 @@ module LlmCostTracker
         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 += " latency=#{event[:latency_ms]}ms" if event[:latency_ms]
-        message += " tags=#{event[:tags]}" unless event[:tags].empty?
-
-        case LlmCostTracker.configuration.log_level
-        when :debug
-          Rails.logger.debug(message) if defined?(Rails)
-        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 log_warning(message)
-        message = "[LlmCostTracker] #{message}"
-
-        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-          Rails.logger.warn(message)
-        else
-          warn message
-        end
-      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 handle_storage_error(error)
-        case storage_error_behavior
+        case LlmCostTracker.configuration.storage_error_behavior
         when :ignore
           nil
         when :warn
-          log_warning("Storage failed; tracking event was not persisted: #{error.class}: #{error.message}")
+          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 storage_error_behavior
-        behavior = (LlmCostTracker.configuration.storage_error_behavior || :warn).to_sym
-        return behavior if Configuration::STORAGE_ERROR_BEHAVIORS.include?(behavior)
-
-        raise Error,
-              "Unknown storage_error_behavior: #{behavior.inspect}. " \
-              "Use one of: #{Configuration::STORAGE_ERROR_BEHAVIORS.join(', ')}"
-      end
-
       def normalized_latency_ms(latency_ms)
         return nil if latency_ms.nil?
 

data/lib/llm_cost_tracker/unknown_pricing.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "logging"
+
 module LlmCostTracker
   class UnknownPricing
     class << self
@@ -23,24 +25,15 @@ module LlmCostTracker
       end
 
       def warn_missing(model)
-        message = "[LlmCostTracker] 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."
-
-        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-          Rails.logger.warn(message)
-        else
-          Kernel.warn(message)
-        end
+        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
-        behavior = (LlmCostTracker.configuration.unknown_pricing_behavior || :warn).to_sym
-        return behavior if Configuration::UNKNOWN_PRICING_BEHAVIORS.include?(behavior)
-
-        raise Error,
-              "Unknown unknown_pricing_behavior: #{behavior.inspect}. " \
-              "Use one of: #{Configuration::UNKNOWN_PRICING_BEHAVIORS.join(', ')}"
+        LlmCostTracker.configuration.unknown_pricing_behavior
       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.2"
+  VERSION = "0.1.3"
 end

data/lib/llm_cost_tracker.rb

@@ -6,9 +6,15 @@ 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"
@@ -18,7 +24,14 @@ 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 << self
@@ -30,6 +43,10 @@ module LlmCostTracker
       @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!
@@ -40,7 +57,7 @@ module LlmCostTracker
       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,
@@ -50,6 +67,14 @@ module LlmCostTracker
     #     feature: "chat",
     #     user_id: current_user.id
     #   )
+    #
+    # @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,
@@ -64,20 +89,10 @@ module LlmCostTracker
     private
 
     def warn_for_configuration!
-      return unless (configuration.budget_exceeded_behavior || :notify).to_sym == :block_requests
+      return unless configuration.budget_exceeded_behavior == :block_requests
       return if configuration.active_record?
 
-      log_warning(":block_requests requires storage_backend = :active_record; preflight blocking will be skipped.")
-    end
-
-    def log_warning(message)
-      message = "[LlmCostTracker] #{message}"
-
-      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
-        Rails.logger.warn(message)
-      else
-        warn message
-      end
+      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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Sergii Khomenko
@@ -159,33 +159,52 @@ files:
 - 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: