llm_cost_tracker 0.1.2 → 0.1.4

data/lib/llm_cost_tracker/report.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "report_data"
+require_relative "report_formatter"
+
+module LlmCostTracker
+  class Report
+    DEFAULT_DAYS = ReportData::DEFAULT_DAYS
+
+    class << self
+      # Render a terminal-friendly cost report from ActiveRecord storage.
+      #
+      # @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
+      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)
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/report_data.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "value_object"
+
+module LlmCostTracker
+  TopCall = ValueObject.define(:provider, :model, :total_cost)
+
+  ReportData = ValueObject.define(
+    :days,
+    :from_time,
+    :to_time,
+    :total_cost,
+    :requests_count,
+    :average_latency_ms,
+    :unknown_pricing_count,
+    :cost_by_provider,
+    :cost_by_model,
+    :cost_by_tags,
+    :top_calls
+  )
+
+  ReportData.const_set(:DEFAULT_DAYS, 30)
+  ReportData.const_set(:TOP_LIMIT, 5)
+  ReportData.const_set(:DEFAULT_TAG_BREAKDOWNS, %w[feature].freeze)
+
+  class << ReportData
+    def build(days: ReportData::DEFAULT_DAYS, now: Time.now.utc)
+      require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+
+      days = normalized_days(days)
+      scope = LlmApiCall.where(tracked_at: from_time(days, now)..now)
+
+      new(
+        days: days,
+        from_time: from_time(days, now),
+        to_time: now,
+        total_cost: scope.sum(:total_cost).to_f,
+        requests_count: scope.count,
+        average_latency_ms: average_latency_ms(scope),
+        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_tags: cost_by_tags(scope, ReportData::DEFAULT_TAG_BREAKDOWNS),
+        top_calls: top_calls(scope)
+      )
+    end
+
+    private
+
+    def normalized_days(days)
+      days = days.to_i
+      days.positive? ? days : ReportData::DEFAULT_DAYS
+    end
+
+    def from_time(days, now)
+      now - (days * 86_400)
+    end
+
+    def average_latency_ms(scope)
+      return nil unless LlmApiCall.latency_column?
+
+      scope.average(:latency_ms)&.to_f
+    end
+
+    def cost_by(scope, column)
+      scope.group(column).sum(:total_cost).transform_values(&:to_f).sort_by { |_name, cost| -cost }
+    end
+
+    def cost_by_tags(scope, keys)
+      keys.to_h { |key| [key, scope.cost_by_tag(key).to_a] }
+    end
+
+    def top_calls(scope)
+      scope
+        .where.not(total_cost: nil)
+        .order(total_cost: :desc)
+        .limit(ReportData::TOP_LIMIT)
+        .map { |call| TopCall.new(provider: call.provider, model: call.model, total_cost: call.total_cost.to_f) }
+    end
+  end
+end

data/lib/llm_cost_tracker/report_formatter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  class ReportFormatter
+    TOP_LIMIT = 5
+
+    def initialize(data)
+      @data = data
+    end
+
+    def to_s
+      lines = ["LLM Cost Report (last #{@data.days} days)", ""]
+      append_summary(lines)
+      append_cost_section(lines, "By provider", @data.cost_by_provider)
+      append_cost_section(lines, "By model", @data.cost_by_model)
+      append_tag_sections(lines)
+      append_top_calls(lines)
+      lines.join("\n")
+    end
+
+    private
+
+    def append_summary(lines)
+      lines << "Total cost: #{money(@data.total_cost)}"
+      lines << "Requests: #{@data.requests_count}"
+      lines << "Avg latency: #{average_latency}"
+      lines << "Unknown pricing: #{@data.unknown_pricing_count}"
+    end
+
+    def append_cost_section(lines, title, rows)
+      lines << ""
+      lines << "#{title}:"
+      return lines << "  none" if rows.empty?
+
+      rows.first(TOP_LIMIT).each do |name, cost|
+        lines << "  #{name.to_s.ljust(28)} #{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
+
+    def append_top_calls(lines)
+      lines << ""
+      lines << "Top expensive calls:"
+      return lines << "  none" if @data.top_calls.empty?
+
+      @data.top_calls.first(TOP_LIMIT).each do |call|
+        label = "#{call.provider}/#{call.model}"
+        lines << "  #{label.ljust(32)} #{money(call.total_cost)}"
+      end
+    end
+
+    def average_latency
+      @data.average_latency_ms ? "#{@data.average_latency_ms.round}ms" : "n/a"
+    end
+
+    def money(value)
+      "$#{format('%.6f', value.to_f)}"
+    end
+  end
+end

data/lib/llm_cost_tracker/storage/active_record_backend.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Storage
+    module ActiveRecordBackend
+      class << self
+        def save(event, **_options)
+          require_relative "../llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
+          require_relative "active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
+
+          ActiveRecordStore.save(event)
+          event
+        rescue LoadError => e
+          raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
+        end
+      end
+    end
+  end
+end

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,15 @@
+# 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
+  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 guardrails 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.4"
 end